92 lines
5 KiB
Markdown
92 lines
5 KiB
Markdown
# Space Taxi level .dat format (STL2)
|
|
|
|
A small custom binary format that `stLevelLoad()` reads at scene
|
|
boot. Output files land in `examples/spacetaxi/generated/levels/`
|
|
(from `romToLevel.py` for the 24 canonical C64 levels, or from
|
|
`mkstlevel` for hand-authored levels in `assets/levels/*.txt`). The
|
|
build copies them under `DATA/levels/levelNN.dat` in the runtime
|
|
asset bundle. All multi-byte fields are little-endian. No
|
|
compression; ~2 KB per level.
|
|
|
|
| Offset | Type | Field |
|
|
|-------:|:----------|:-----------------------------------------------|
|
|
| 0 | 4 bytes | magic `S T L 2` |
|
|
| 4 | u8 | nameLen (0..23) |
|
|
| 5 | char[N] | name (no NUL; max 23 chars) |
|
|
| 5+N | u8 | tileBankId |
|
|
| ... | u8 | musicId (UNUSED -- C64 gameplay is silent; see VERIFIED.md) |
|
|
| ... | u8 | bgColor (palette slot) |
|
|
| ... | u8 | borderColor (palette slot, also HUD-band fill) |
|
|
| ... | u8 | taxiSpawnTileX |
|
|
| ... | u8 | taxiSpawnTileY |
|
|
| ... | u8 | xAccel (horizontal thrust magnitude / frame) |
|
|
| ... | u8 | yAccel (vertical thrust magnitude / frame) |
|
|
| ... | i8 | xGrav (constant horizontal accel; side-wind on levels P, U) |
|
|
| ... | i8 | yGrav (constant vertical accel; anti-gravity on level K = -7) |
|
|
| ... | u8 | bgColor1 ($D022, VIC multicolor -- UNUSED) |
|
|
| ... | u8 | bgColor2 ($D023, VIC multicolor -- UNUSED) |
|
|
| ... | u8 | bgColor3 ($D024, VIC multicolor -- UNUSED) |
|
|
| ... | u8 | spriteMc0 ($D025, sprite multicolor -- UNUSED) |
|
|
| ... | u8 | spriteMc1 ($D026, sprite multicolor -- UNUSED) |
|
|
| ... | u8 | sprite0Color ($D027, cab fallback color) |
|
|
| ... | u8 | sprite1Color ($D028, flame fallback color) |
|
|
| ... | u8 | padCount (0..10) |
|
|
| ... | pad[] | padCount * 4 bytes: letter, tileX, tileY, tileW |
|
|
| ... | u8 | fareCount (0..16) |
|
|
| ... | fare[] | fareCount * 2 bytes: spawnPad, destPad |
|
|
| ... | u8[40*25] | tilemap (row-major, full 25 rows) |
|
|
| ... | u8[40*25] | colormap (row-major, palette slot per cell) |
|
|
|
|
Notes:
|
|
|
|
- `xAccel/yAccel/xGrav/yGrav` mirror the C64 per-level templates at
|
|
`$7D8F-$7D96`. Side-wind levels P (`xGrav = +4`) and U (`+2`); the
|
|
anti-gravity level K (`yGrav = -7`) makes the cab drift upward
|
|
without input. See `VERIFIED.md` for the emulator-traced extracts.
|
|
- `musicId` is preserved for format symmetry only; the C64 original
|
|
has no gameplay music (only title/score-screen jingles).
|
|
- The five VIC multicolor fields are preserved so the .dat is a
|
|
faithful byte-for-byte capture of the C64 `$7D00-$7D08` block. The
|
|
port renders in single-color mode and ignores them at runtime.
|
|
- Pads are 4 bytes (letter + 3 tile coords); there is no patience
|
|
byte on fares -- Space Taxi proper has no patience timeout, and the
|
|
emulator trace at `$71CE/$7213` confirmed the only gating is the
|
|
player-selectable fare target at the title screen.
|
|
|
|
## Tile-index conventions (in the tilemap byte)
|
|
|
|
Indexes 0..255 reference the level's active tile bank. Reserved
|
|
ranges:
|
|
|
|
| Range | Meaning |
|
|
|----------|---------------------------------------------------------|
|
|
| 0 | empty (sky / interior space; non-solid) |
|
|
| 1..63 | solid (walls, ceilings, support structures) |
|
|
| 64..127 | landing-pad surfaces (also solid; pad collisions live here) |
|
|
| 128..255 | decorative non-solid (lights, signs, animation frames) |
|
|
|
|
The engine's `isSolidAt()` uses this convention. If you redesign a
|
|
tile bank, keep the indexing consistent so the physics keeps working
|
|
without changes.
|
|
|
|
## Authoring pipeline
|
|
|
|
1. Author a 256-tile (or smaller) tile sheet as an indexed PNG. Each
|
|
tile is 8x8 px. Arrange in a grid; the bank loader assumes row-
|
|
major, tile-index = `ty * tilesPerRow + tx`. Drop the PNG at
|
|
`examples/spacetaxi/assets/tiles/tbank<N>.png`.
|
|
2. The Makefile bakes per-target via `tools/assetbake/assetbake.py
|
|
--type tile --target <port> tbank<N>.png tbank<N>.tbk`. Output
|
|
lands in `examples/spacetaxi/generated/<port>/tiles/` and is
|
|
staged into the runtime tree at `build/<port>/.../DATA/tiles/`.
|
|
3. Author each level layout in a text editor or grid tool, save as a
|
|
.dat per this spec. The helper `examples/spacetaxi/mkstlevel`
|
|
converts from a human-readable text grid to .dat. The 24 canonical
|
|
C64 levels are emitted by `stuff/spacetaxi/romToLevel.py` directly
|
|
from a raw VICE dump of the original .prg.
|
|
|
|
## Naming
|
|
|
|
Use the original game's level names as the `name` field (uppercase
|
|
ASCII, max 23 chars). The HUD displays this at the bottom-right of
|
|
the screen.
|