Made of little things.

# Supersonic RC Revive

A faithful remake of the 2004 Shockwave RC-car game SuperSonic RC, rebuilt with
three.js and Rapier as a [NIP-5D](docs/nip-5d.md) napplet. The car handling is
ported line by line from the original Lingo scripts. The game includes all five
modes: Free Driving, Checkpoint Chase, Stunt Rally, Scavenger Hunt and the
Supersonic Challenge.

The original game is preserved on the Internet Archive:
[LEGO Super Sonic RC](https://archive.org/details/lego-super-sonic-rc).

## Playing

Drive with the arrow keys or WASD, a controller, or the on-screen touch controls.
Space brakes hard, Esc quits to the menu and M toggles sound. Unlocked modes are
saved through the host's storage, when the host provides it.

A controller with the standard layout (an Xbox pad, for example) runs the whole
game, menus included:

| Button | In a race | In menus |
| --- | --- | --- |
| A | accelerate | press the highlighted button |
| X | brake / reverse | |
| B | hard brake | back (closes the asset pack panel) |
| Left stick | steer, as far as you lean it | move the highlight |
| D-pad | steer (full lock, like the arrow keys) | move the highlight |
| Menu (≡) | quit to the menu | press the highlighted button |

The buttons and D-pad act like keys, so the car handles exactly as it does on the
keyboard. The stick turns the wheels part of the way when half pushed, at the same
rate the keys turn them. If the controller does nothing, click the game first: the browser only
passes controller input to the focused frame.

In **Free Driving**, connecting a second supported controller automatically
switches to split screen while driving. You can also choose **Local Multiplayer · 1–4**
on the challenge screen to start directly in shared free roaming. Detected standard
controllers automatically add players, including during
play; disconnecting removes their car and view. Two players split top and bottom;
three or four use a 2×2 grid with a separate chase camera for each car.
Up to four can drive at once.
Remaining cars and P1–P4 labels stay assigned; a new controller fills the first
vacant label. Some browsers need a button press before exposing a newly plugged-in
controller. Single-player keeps keyboard and touch driving.

Local play uses the same A/X/B/stick controls. Menu (≡), Esc or the on-screen Menu
button pauses everyone; Resume continues, and Return to menu ends the session.
Focus loss also pauses. D-pad and A operate the pause menu. Cars collide, and each
has its own engine/effect channels with shared music. Local play has no timer,
collectibles or progression unlocks yet.

The published game ships a recreated asset pack, "Bedroom Grand Prix". To play
with a different pack, choose **Asset pack…** on the title screen and either
paste the pack's Blossom link or hash, or choose a `.ssrcpack` file. The same
button takes a level exported from Blender as a `.glb` file, which is played
with the current pack's car, props and sounds. To share a pack or a level,
upload it to any Blossom server and send the link.
[docs/custom-asset-packs.md](docs/custom-asset-packs.md) explains how to make one.

Other napplets can open the game straight into a pack with a NAP-INTENT `play`
request for the `supersonicrc` archetype:

```ts
import { intent } from '@napplet/sdk';

await intent.invoke({
  archetype: 'supersonicrc',
  action: 'play',
  convention: 'napplet:supersonicrc/play',
  payload: { url: 'https://blossom.example.com/<sha256>.ssrcpack' },
});
```

The payload's `url` (or `uri`) takes anything the link field does: a Blossom
blob URL, a `blossom:` URI or a bare SHA-256, of an asset pack or a level
`.glb`. The game downloads it and returns to the title screen with it;
mid-race it waits for the race to end.
The host delivers the request as an INC event on `napplet:supersonicrc/play`.

## Development

```bash
soyli setup
soyli dev          # hosted preview; stop it when you are done
pnpm verify        # guidance test + type-check + build
pnpm test:conformance
```

Read [docs/napplet-space.md](docs/napplet-space.md) for the soyli commands and
host capabilities.

Levels are edited in Blender: [docs/level-editing.md](docs/level-editing.md)
covers the add-on (`tools/blender/ssrc_level.py`), the shipped level's source
(`src/game/assets-custom/level.blend`), extra levels in `levels/` that are
registered as soyli assets and offered in the game, and converting the original
level locally.

| Path | Contents |
| --- | --- |
| `src/game/lingo/` | The ported game logic: car, wheels, modes, scoring |
| `src/game/physics/` | The Havok stand-in on Rapier |
| `src/game/render/`, `src/game/ui/` | three.js scene, HUD and screens |
| `src/game/assets-custom/` | The recreated asset pack; `level.blend` is the source of its `level.glb` |
| `tools/blender/` | The SSRC Blender add-on and command-line level tool |
| `tools/assets/` | The asset pack generator and pack tools ([README](tools/assets/README.md)) |
| `tools/` | Extraction tools for the original game, for local reference only ([README](tools/README.md)) |
| `docs/original-game-spec.md` | What the original game does, recovered from its scripts |
| `docs/physics-calibration.md` | How the physics port was checked against the original |

The original game's assets are copyrighted. The extraction tools keep them in
gitignored folders (`ref/`, `ref-out/`); never commit, publish or upload them.

## License

MIT. See [LICENSE](LICENSE).