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 focuses on unlimited
Free Driving, with automatic split-screen for up to four controllers.

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. Start from the main
menu to drive immediately; there is no mode selection or countdown.

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. 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.

For **online Free Driving**, choose **Play public** to drop into an open public
room, or **Private room** to play with friends. **New room** starts a private room
and shows a short code such as `K7Q-4MZ` above the track (**Select code** selects
it for copying); friends choose **Private room**, type the code and **Join room**.
Anyone with the code can join. Rooms hold up to eight players; when every public
room is full a new one opens. Allow peer connections if the host asks. No Nostr
login is needed, and each machine has its own car, chase camera and local physics world.
The first player's asset pack and any custom GLB level define the room. Joining
automatically downloads them when they differ from yours, verifies their hashes,
and loads them before spawning. The files must be available on a Blossom server
accessible to your host. Matching local files can be reused without downloading;
incompatible game versions never meet. Remote cars have coloured name tags (your Nostr profile
name when you are signed in, looked up by other players through the host) and are
visual ghosts without car-to-car collisions. Online play uses only the first
supported controller on each machine; keyboard and touch also work. Offline play
still supports local split-screen.

**Leave online** continues driving offline. Esc returns to the title screen,
where you can join again. A room has no host: it continues while anyone is in it,
including after the player who started it leaves. Changing packs or entering the
Konami code ends the online session before rebuilding. Private rooms need only
WebRTC; public rooms also need the host's CVM room service. See
[the design and verification notes](docs/online-multiplayer.md).

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, free driving, 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).