Merge pull request #4 from andydixon/rust-port

Add the contents of disk 1: palettes, Camaro, caravan, sounds, music, title

README.md

@@ -3,14 +3,17 @@
 A cross-platform (Windows, macOS, Linux) engine written in Rust that plays
 *Super Skidmarks* (Acid Software, 1995) on the original Amiga data.
 
-The game's data was converted from the original ADF disk images (disks 2–6
+The game's data was converted from the six original ADF disk images into
-of the six-disk set) into editable files in [`assets/`](assets/README.md).
+editable files in [`assets/`](assets/README.md). The images themselves
-The images themselves are no longer kept in this repository.
+aren't kept in this repository.
 
 - **Each track:** a 16-colour PNG (the PNG's palette is the track's
   palette), plus a text file with the lap gates and height map.
-- **Each car:** a PNG sprite sheet, plus a text file with its name and
+- **Each car:** a PNG sprite sheet and menu picture, plus a text file with
-  handling.
+  its name, driver and handling.
+- **Sounds:** WAV files.
+- **Music:** the tune, as an OctaMED module.
+- **Pictures:** the title picture and a few other images, as PNGs.
 
 Edit them with any image editor or text editor. The build embeds the
 `assets/` folder, so the finished program is a single self-contained file.
@@ -24,36 +27,33 @@ give either to also gets the game data.
 
 ## What works
 
-- All 24 tracks across the four track files. Each has its isometric height
+- All 24 tracks across the four track files, in their original palettes.
-  map and lap gates.
+  Each has its isometric height map and lap gates.
-- All 8 vehicles (Mini, Beetle, Porsche, Formula 1, Midget, Truck, Police,
+- All 9 cars (Mini, Beetle, Porsche, Formula 1, Midget, Truck, Police,
-  Cow), with 32 headings and 25 body-tilt frames for hills.
+  Cow, Camaro) with their drivers' names, each with 32 headings and 25
+  body-tilt frames for hills.
+- The caravan: turn on **Caravans** in the menu and every car tows one.
+- The original sound effects, and the original tune played by a built-in
+  OctaMED player. The menu has a **Music** option: menus, always, or off.
+- The original title picture.
 - 1 or 2 players (split screen) plus up to 7 computer drivers.
 - Power-slide handling, slopes, car-to-car bumping, and skid marks burnt
   into the track.
 - Lap and position tracking, lap times, and a results table.
-- Procedural engine, tyre and crash sound.
+- Engine note pitched with revs, tyre screech, crashes, backfires, a horn
+  and start beeps, all from the original samples.
 
 ## What's reconstructed
 
-Disk 1 of the six-disk set is missing from this archive. It held the
+The executable is on disk 1, but its game logic, a compiled Blitz Basic 2
-executable, palettes, sound and music. As a result:
+program, hasn't been decoded. So the **handling, computer drivers and race
+rules** are new code written to feel like the original, not a translation
+of it.
 
-- **Handling, AI and race rules** are new code written to feel like the
+Each car's original settings file has eleven handling numbers whose
-  original, not a translation of the original 68000 code.
+meaning lives in that code. They're kept in the car's settings asset for
-- **Colours** come from a reconstructed palette, built around how the
+when it is decoded. [docs/FORMATS.md](docs/FORMATS.md) covers everything
-  tracks use their 16 colour indices. If you have the real palettes, put
+reverse engineered so far.
-  them in a `palettes/` folder next to the disks as `.pal` files (16 lines
-  of `RRGGBB`):
-  - `track1-3.pal` for one track
-  - `track1.pal` for all six tracks in a file
-  - `default.pal` for everything
-- **Sound** is synthesised.
-
-If you find disk 1, drop it in with the others. Anything it contains under
-`track/` or `vehicles/` is picked up automatically. The format notes in
-[docs/FORMATS.md](docs/FORMATS.md) cover everything reverse engineered so
-far.
 
 ## Running
 
@@ -76,6 +76,7 @@ exists both as an asset and on disk, the asset wins.
 | Accelerate  | ↑ (or W in one-player games)          | W        |
 | Brake / reverse | ↓ (or S)                          | S        |
 | Steer       | ← → (or A D)                          | A D      |
+| Horn        | Right Shift                           | Left Shift |
 | Pause       | P                                     |          |
 | Leave race  | Esc                                   |          |
 
@@ -89,6 +90,8 @@ skids extract --data ADFS [--out assets]  # convert original disks into editable
 skids bench   --data DIR --seconds 120    # race CPU cars on every track: laps and time on road
 skids trace   --data DIR --track 11 --out t.png   # plot CPU racing lines
 skids render  --data DIR --track 3 --out shot.png # headless screenshot
+skids music   --out tune.wav --seconds 60     # render the tune to WAV
+skids unpack  disk.adf --out files/           # extract a disk or LHA archive as-is
 ```
 
 ## Building
@@ -114,11 +117,12 @@ GitHub Actions builds all three platforms on every push
 ```
 assets/        the game data as editable PNG and text files
 build.rs       embeds assets/ into the executable
-src/formats/   ADF (OFS/FFS), LHA and CrunchMania readers
+src/formats/   ADF (OFS/FFS), LHA (incl. -lh5-), CrunchMania, IFF 8SVX/ILBM, OctaMED
 src/data/      track, vehicle and palette decoding; locating the game files
 src/game/      physics, AI and race rules
 src/render/    software renderer at 320×256 (PAL low-res) and a bitmap font
-src/audio.rs   synthesised sound (cpal)
+src/audio.rs   sample mixer and sound effects (cpal)
+src/music.rs   OctaMED player
 src/app.rs     menus, race screens and results
 ```
 

assets/README.md

@@ -42,10 +42,19 @@ Plain text; lines starting with `#` are comments.
 - **`height`:** 64 rows of 64 numbers giving ground height × 256. Each
   number covers a 16 × 8 pixel cell of the picture. Slopes push cars
   downhill and tilt the car sprites.
+- **`set`:** the name of the set of tracks this one belongs to, shown under
+  the menu thumbnail.
 - **`start`, `flags`:** values from the original data that the game
   doesn't use.
 
-To add a track, make a new folder with both files. Tracks are listed in
+### `thumb.png` (optional)
+
+The track's 123 × 32 thumbnail from the original track-select screen, in
+the track's palette. It's drawn at double height in the menu, because the
+original's pixels are half-width. Without one, the menu shows a shrunken
+`track.png`.
+
+To add a track, make a new folder with `track.png` and `track.txt`. Tracks are listed in
 name order.
 
 ## Vehicles: `vehicles/<id>.png` and `<id>.txt`
@@ -68,12 +77,21 @@ A 2048 × 800 sprite sheet: 32 headings across by 25 tilts down, each cell
 - **Tilts:** row = roll × 5 + pitch (each 0–4), so row 12 is the car on
   flat ground.
 
+### `<id>-menu.png` (optional)
+
+The car's 64 × 32 picture from the original select screen, in the same
+four colours as the sprite sheet.
+
 ### `<id>.txt`
 
-The display name and handling:
+The display name, driver and handling:
 
 | Setting   | Meaning |
 |-----------|---------|
+| `name`    | name shown in the menu |
+| `driver`  | driver's name, shown next to it |
+| `trailer` | `yes` for something towed behind cars (the caravan) rather than driven |
+| `original`| the 16 values from the original `.set` file, kept for reference; the game doesn't use them yet |
 | `top`     | top speed on tarmac |
 | `accel`   | acceleration |
 | `brake`   | braking |
@@ -82,7 +100,44 @@ The display name and handling:
 | `mass`    | weight in collisions |
 | `offroad` | speed and grip multiplier on scenery |
 
-To add a car, add a new `<id>.png` / `<id>.txt` pair.
+The handling values are a reconstruction, so tune them freely. To add a
+car, add a new `<id>.png` / `<id>.txt` pair.
+
+## Sounds: `sounds/*.wav`
+
+8-bit mono WAV files at the original Amiga sample rates. A loop point,
+stored in the WAV's `smpl` chunk, makes a sound repeat from there; most
+sample editors keep it. The game uses these names:
+
+| Sound | Use |
+|-------|-----|
+| `motor3` | engine, pitched up and down with revs (falls back to `motor`, then `engine`) |
+| `screech2` | tyres sliding (falls back to `screech3`, then `screech`) |
+| `crash1`, `crash2`, `crash3` | collisions, picked at random |
+| `backfire` | lifting off at high revs |
+| `horn` | Right Shift (player 1) or Left Shift (player 2) |
+| `beep`, `beep2` | countdown, then lights out |
+
+Missing sounds fall back to synthesised ones. Any other WAV files are kept
+but not used.
+
+## Music: `music/*.med`
+
+The tune, an OctaMED module. Edit it in a tracker that reads MED files,
+such as OpenMPT. The game's player supports plain sample instruments (no
+synth sounds) and the commands listed in `docs/FORMATS.md`. Preview it
+with `skids music --data assets --out tune.wav`. If there are several
+files, the first in name order plays.
+
+## Pictures: `gfx/*.png`
+
+Indexed PNGs. `skidtoon.png` is the title picture at the top of the menu,
+shown at half size. The others aren't used:
+
+- `ball.png`: 64 frames of a spinning ball with the Acid logo, 16 frames
+  across, each 32 × 33. Its real colours aren't known, so it has a grey
+  palette.
+- `chat2.png`, `mouse.png`, `sign.png`: small odds and ends.
 
 ## Palettes: `palettes/*.pal` (optional)
 

assets/tracks/track1-1/track.txt

@@ -27,6 +27,9 @@ gate 600.6875 768.8125 488.4375 696.3125
 gate 599.25 904.75 487.75 759.25
 gate 456.75 935 408.5 776.75
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 458 107
 flags 1

assets/tracks/track1-2/track.txt

@@ -36,6 +36,9 @@ gate 253.125 618.375 144.34375 626.03125
 gate 311.4375 676.8125 239.25 719.28125
 gate 357.25 723.75 333.1875 815.5625
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 461 295
 flags 0

assets/tracks/track1-3/track.txt

@@ -31,6 +31,9 @@ gate 487.75 549.25 491.5 648.5
 gate 708 556 686.5 649.5
 gate 766.5 529.5 861 616.5
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 608 305
 flags 0

assets/tracks/track1-4/track.txt

@@ -31,6 +31,9 @@ gate 761 667 688.5 575.5
 gate 645 675 623 573
 gate 550.4375 729.8125 495.75 655.25
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 608 305
 flags 0

assets/tracks/track1-5/track.txt

@@ -32,6 +32,9 @@ gate 381.40625 687.25 449.78125 749.875
 gate 472.28125 690.78125 551.53125 741.53125
 gate 468.5625 611.34375 549.5625 610.34375
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 301 79
 flags 0

assets/tracks/track1-6/track.txt

@@ -48,6 +48,9 @@ gate 535.65625 389.6875 437.78125 406.5625
 gate 576.625 424.75 529.125 502.25
 gate 646.96875 425.4375 648.46875 504.4375
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Racing In The Name Of
+
 # As stored in the original data; not used by the game.
 start 434 354
 flags 1

assets/tracks/track2-1/track.txt

@@ -28,6 +28,9 @@ gate 360.5 837.5 380 756
 gate 222.9375 708.375 281.25 659.65625
 gate 80.25 559.03125 229.5625 610.21875
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 474 167
 flags 1

assets/tracks/track2-2/track.txt

@@ -33,6 +33,9 @@ gate 622.375 910.5 544.6875 822.6875
 gate 508.6875 934.5 481.71875 820.71875
 gate 418 903.5 421.75 805.75
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 339 117
 flags 1

assets/tracks/track2-3/track.txt

@@ -40,6 +40,9 @@ gate 610 280 715.5 340.5
 gate 627.25 212.75 703.5 208.5
 gate 565.5 156.5 587 89
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 420 97
 flags 0

assets/tracks/track2-4/track.txt

@@ -47,6 +47,9 @@ gate 551.3125 264.84375 488.125 183.375
 gate 504.84375 311.25 424.9375 247.21875
 gate 465.90625 350.15625 376.78125 298.09375
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 689 201
 flags 1

assets/tracks/track2-5/track.txt

@@ -51,6 +51,9 @@ gate 598.9375 295.90625 581.4375 233.40625
 gate 486.375 293.34375 450.375 235.34375
 gate 350.8125 298.75 320.0625 235.5
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 353 47
 flags 0

assets/tracks/track2-6/track.txt

@@ -54,6 +54,9 @@ gate 722.125 791.0625 640.125 753.0625
 gate 659.5 864.25 598.5 787.25
 gate 556.375 884.4375 560.75 793.5625
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Even Flow
+
 # As stored in the original data; not used by the game.
 start 353 47
 flags 0

assets/tracks/track3-1/track.txt

@@ -44,6 +44,9 @@ gate 307.5 604.875 307.6875 694.3125
 gate 358.5 603.5 386 696
 gate 437.34375 599.28125 412.75 695.25
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 641 315
 flags 0

assets/tracks/track3-2/track.txt

@@ -30,6 +30,9 @@ gate 498.8125 807.25 578.75 940.28125
 gate 566.5 820.5 690.75 890.25
 gate 597.75 790.3125 707.8125 768.96875
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 475 288
 flags 0

assets/tracks/track3-3/track.txt

@@ -38,6 +38,9 @@ gate 635 363 636.75 487.25
 gate 689.25 419.75 707.625 558.375
 gate 741.4375 471.8125 785.84375 638.65625
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 809 244
 flags 0

assets/tracks/track3-4/track.txt

@@ -39,6 +39,9 @@ gate 573.59375 394.84375 716.59375 427.84375
 gate 483.625 301.96875 614.125 331.46875
 gate 450.3125 217.03125 589.3125 298.03125
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 796 294
 flags 0

assets/tracks/track3-5/track.txt

@@ -36,6 +36,9 @@ gate 304.5 269.5 405 337
 gate 335.75 207.5 415.75 287.5
 gate 386.125 161.5 465.375 240.25
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 744 137
 flags 0

assets/tracks/track3-6/track.txt

@@ -47,6 +47,9 @@ gate 796.78125 544.59375 896.84375 523.4375
 gate 760.125 503.53125 816.78125 446.34375
 gate 658.5 417.5 705.75 366.25
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Surf 'n' Slam
+
 # As stored in the original data; not used by the game.
 start 356 188
 flags 0

assets/tracks/track4-1/track.txt

@@ -37,6 +37,9 @@ gate 402 504 402 378
 gate 342.53125 501.71875 264 374.5
 gate 316.5625 513.03125 192.25 387
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 213 275
 flags 1

assets/tracks/track4-2/track.txt

@@ -47,6 +47,9 @@ gate 715.375 842.65625 586.40625 755
 gate 701.84375 891.1875 585.65625 814.03125
 gate 663.3125 939.1875 581.0625 837.78125
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 122 216
 flags 0

assets/tracks/track4-3/track.txt

@@ -40,6 +40,9 @@ gate 372.1875 581.84375 301.1875 652.34375
 gate 402.625 626.75 392.625 759.25
 gate 435.0625 628.59375 502.1875 772.34375
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 672 360
 flags 0

assets/tracks/track4-4/track.txt

@@ -43,6 +43,9 @@ gate 293.90625 281.8125 414.1875 352
 gate 347.40625 233.625 448.21875 353.125
 gate 423.4375 212.9375 488.71875 377.71875
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 800 350
 flags 0

assets/tracks/track4-5/track.txt

@@ -47,6 +47,9 @@ gate 265.75 441.875 165.75 375.875
 gate 247.84375 489.21875 133.09375 438.96875
 gate 259.9375 536.59375 154.9375 525.59375
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 362 264
 flags 0

assets/tracks/track4-6/track.txt

@@ -42,6 +42,9 @@ gate 506.1875 355.09375 607.4375 450.84375
 gate 628.3125 300 668.3125 426
 gate 841.875 457.5 766.875 502.5
 
+# Name of the set of tracks this one belongs to, shown in the menu.
+set Sounf Of Speed
+
 # As stored in the original data; not used by the game.
 start 501 153
 flags 0

assets/vehicles/camaro.txt

@@ -0,0 +1,23 @@
+# Skids vehicle settings. Lines starting with # are comments.
+# The sprite sheet is camaro.png: 32 headings across, 25 tilts down.
+name CAMARO
+driver ROD
+# yes = towed behind cars (Caravans option) instead of driven
+trailer no
+# The 16 values from the original .set file. Their meaning is not
+# decoded yet, so the game does not use them; the handling below is
+# a reconstruction.
+original 54 35 32 8 7 22 22 16 49 14 53 0 0 0 0 0
+# top speed on tarmac, world pixels per second
+top 200
+# acceleration and braking, world pixels per second squared
+accel 170
+brake 320
+# sideways grip (higher = less sliding)
+grip 5
+# steering rate, radians per second
+turn 3.6
+# weight in collisions
+mass 1
+# speed and grip multiplier off the road
+offroad 0.55

assets/vehicles/caravan.txt

@@ -0,0 +1,23 @@
+# Skids vehicle settings. Lines starting with # are comments.
+# The sprite sheet is caravan.png: 32 headings across, 25 tilts down.
+name CARAVAN
+driver SIMON
+# yes = towed behind cars (Caravans option) instead of driven
+trailer yes
+# The 16 values from the original .set file. Their meaning is not
+# decoded yet, so the game does not use them; the handling below is
+# a reconstruction.
+original 2 65532 65532 1 12 10 16 14 0 0 0 0 0 0 0 0
+# top speed on tarmac, world pixels per second
+top 200
+# acceleration and braking, world pixels per second squared
+accel 170
+brake 320
+# sideways grip (higher = less sliding)
+grip 5
+# steering rate, radians per second
+turn 3.6
+# weight in collisions
+mass 1
+# speed and grip multiplier off the road
+offroad 0.55