Made of little things.

# Making a custom asset pack

An asset pack (`.ssrcpack`) holds everything the game draws and plays: the track,
the car, the props, the screen art and the sounds. The game code never changes
between packs, so a new pack can give the game a new track, a new car or just new
sounds. Players load a pack from **Asset pack…** on the title screen.

Never build a pack from the original 2004 game's files for anyone but yourself.
Those assets are copyrighted.

## 1. Start from the shipped pack

The pack every build ships, "Bedroom Grand Prix", is the folder
`src/game/assets-custom/`. Copy it to start your own:

```sh
cp -r src/game/assets-custom my-pack
```

## 2. Change what you want

### Sounds and screen art (no code)

Add files to your folder. Anything the pack leaves out falls back to a default:
sounds the pack lacks are synthesized, and screens without art use plain HTML.
Names are matched without case or extension, so `sounds/CarLoop.ogg` works as
well as `sounds/carloop.wav`. Supported formats are `.wav`, `.mp3`, `.ogg`,
`.png`, `.jpg` and `.webp`.

| File | Used for |
| --- | --- |
| `sounds/CarStart`, `CarLoop`, `CarEnd` | Engine start, loop (pitched with speed) and stop |
| `sounds/CarTurnLeft01`…`03`, `CarTurnRight01`…`03` | Tyre noise when turning |
| `sounds/Crash1`, `Crash2`, `crash3`…`crash8`, `Crash1_glass`…`Crash3_glass` | Crashes |
| `sounds/Alarm`, `StingWin`, `StingCheckpoint`, `StingLoseLoop`, `StingHiddenTreasure` | Game events |
| `sounds/buttonclick` | Menu clicks |
| `sounds/SSRMusicSplashScreen`, `musicloop1`…`musicloop5` | Music |
| `ui/Title-v8` | Title screen, the full 640×480 stage |
| `ui/Help-v5` | Controls screen, 640×480 |
| `ui/Background` | Mode select background, 640×480 |
| `ui/Free`, `Checkpoint`, `Stunt`, `Scavenger`, `Supersonic` | Mode buttons, 291×56 or 291×57 (exact sizes in `BUTTON_RECTS`, `src/game/ui/screens.ts`). Add `Over`, `Down` and `Gray` (locked) variants, such as `ui/FreeOver` |
| `ui/carshadow` | The blob shadow under the car |

### Models

`car.glb`, `star.glb` (checkpoints), `prize.glb` and `arrow2.glb` are ordinary
glTF binaries. Use Z-up and inches. The car file needs a node named `Car`, with
its wheels as child nodes. Copy the node names and placement of the shipped
`car.glb`, which `tools/assets/props.ts` builds.

### A new track

The track is `level.glb`, a single file exported from Blender with the SSRC
add-on. It holds the drawn objects, the collision shapes, the start,
checkpoints and prizes, and any baked lighting. See
[level-editing.md](level-editing.md). Start from
`src/game/assets-custom/level.blend` (copied with the folder) or the add-on's template, export over
`level.glb` in your folder, and delete any `collision.json`, `raymesh.bin` and
`markers.json` the folder still has from older packs.

You can also skip the pack and load a level `.glb` directly from
**Asset pack…**; it then plays with the current pack's car, props and sounds.

## 3. Try it

Drive your track without a browser:

```sh
SIM_LEVEL=my-pack node tools/sim/drive.mjs "u:6,ul:2"
```

To play the pack, start `soyli dev`, pack your folder (next step), and load the
file from **Asset pack…** on the title screen.

## 4. Pack and share it

```sh
pnpm assets:pack my-pack my-pack.ssrcpack --title "My Track"
```

The title is shown when the pack loads. A pack can be at most 10 MiB.

To share it, upload the `.ssrcpack` file to any Blossom server and send the
link. Players paste the link, or just its SHA-256 hash, into **Asset pack…**.
The game finds the file on the server named in the link and checks its hash.
A pack that fails to load is refused, and the game keeps the pack it had.

A napplet that lists or hosts packs can also hand one to the game directly: a
NAP-INTENT `play` request for the `supersonicrc` archetype with
`{ url: "<the Blossom link>" }` as its payload opens the game with that pack
(see the README).

## 5. The original assets

Entering the classic code (↑ ↑ ↓ ↓ ← → ← → B A) on any menu screen — keyboard
or controller — loads the original 2004 game's assets, replacing whatever pack
is playing. The download is `ORIGINAL_PACK_LINK` in `src/game/assets.ts`: the
byte-deterministic `ref-out/SuperSonicRC-original.ssrcpack` from
`tools/build-original-assets.sh`, named by SHA-256 with the Blossom servers
that carry it. The napplet never bundles or uploads those bytes; the link only
resolves where a listed server has the blob, and everywhere else the player
sees a clean "not available" notice. Rebuilding the pack from the game files
changes the hash, so update the link (and the servers hosting it) together.

Those assets are copyrighted ([the README's warning](../README.md) applies):
keep the "local use only" rule when you build the pack yourself.

Publishing the game itself with a different built-in pack is a separate step;
see `tools/assets/README.md`.