Rename Lotus3 to MiataDrive; original-graphics title screen

- examples/Lotus3 -> examples/MiataDrive, sketch MiataDrive.ino,
  emulator target APP=MiataDrive, platformio src_dir updated
- drop the borrowed photo title background (title_bg.h): the title
  screen now renders the game's own start line under the arch with the
  selected car parked on the road; color picker labels sit over the
  horizon, showcase car doubles as the live preview
- add dedicated README (controls, features, sprite pipeline, gallery)
- commit in-progress work the game now depends on: sound engine events
  (engine hum, crash noise) plus the 4-line SDL audio shim in the
  emulator host
This commit is contained in:
Dejvino
2026-11-12 22:29:37 +01:00
parent 3c56f834c2
commit 2ac8706606
12 changed files with 653 additions and 4846 deletions
+119
View File
@@ -0,0 +1,119 @@
# MiataDrive
A Lotus Turbo Challenge–style pseudo-3D racing game for the LilyGo T-Deck
(ESP32-S3, 320×240). Drive a Mazda MX-5 through a 3-lap circuit against
traffic before the clock runs out.
![screenshot](sprites_sheet.png)
## Running
### On your PC (SDL2 emulator)
```sh
cd emulator
make run APP=MiataDrive
```
Headless smoke test (N frames, dump the last frame as a BMP):
```sh
make smoke APP=MiataDrive
```
### On the T-Deck
`platformio.ini` has `src_dir = examples/MiataDrive`; build and flash with
PlatformIO as usual.
## Controls
| Input | Action |
|--------------------------|-----------------------------------------|
| Trackball / arrow keys | steer left/right, gas (up), brake (down)|
| `W` / `S` | gas on / brake pulse |
| `A` / `D` | steer left / right |
| `1` `2` `3` `4` (title) | pick car color: red / blue / white / yellow |
| Enter / click / tap | start / restart |
| `P` | toggle the auto-play demo driver |
| `T` | sprite test gallery |
Manual driving is the default; the demo AI (`P`) steers toward the racing
line, dodges traffic and eases off in sharp corners — handy when tuning
graphics.
## Game features
- **Segment-based pseudo-3D road** (the classic "2.5D" technique): the track
is a list of `(curve, hill)` segments projected with perspective. Road,
rumble strips and lane dashes are drawn near→far with hill crest clipping;
distance fog fades the far road into the sky.
- **Centrifugal force** pulls you wide in corners; deep off-road excursions
trigger a **rollover crash**: the car slides off, kicks up dust, the camera
jolts, and the body tumbles through its sprite views (rear → slight → turn
→ side) before you rejoin the tarmac.
- **Traffic** (blue / white / yellow cars from the sprite sheet) drive slower
lanes; rear-ending one costs speed and jolts the camera. Cars lean into
corners with their turning sprite, mirrored on right-hand bends.
- **Scoring / laps**: 3 laps, 75 s + 45 s per lap, −300 for a crash.
- **Sound**: engine + event blips via `sound_engine.*` (I2S on device).
All graphics — including the title screen, which renders the start line
under the arch with your selected car parked on the road — come from the
game's own sprites. There are no external image assets.
## Sprite pipeline (hand-editable assets)
All sprites live in **one editable image** — `sprites_sheet.png` — tracked in
git. The converter is `sprite_tool.py` (needs Pillow):
```sh
python3 sprite_tool.py export # sprites.h -> sprites_sheet.png
# ... edit the PNG by hand (paint magenta = transparent) ...
python3 sprite_tool.py import # sprites_sheet.png -> sprites.h
```
Sheet layout (fixed, the cutter never guesses):
- 1120×560: 7×4 grid of 160×140 cells; the top 14px of each cell is a label
strip the cutter ignores; content area is 160×126 (largest sprite: arch,
140×109).
- Background is pure magenta (255,0,255) = transparent. Pink anti-aliasing
fringes are cut (magenta excess > 35) or despilled automatically, so soft
edges don't leave a purple halo.
- Cell order is fixed and matches the `SpriteId` enum in `sprites.h`:
0–15 player cars (red/blue/white/yellow × rear/slight/turn/side),
16–21 scenery (palm, pine, bush, billboard, arch, tires),
22–27 traffic (blue/white/yellow, rear + turning view).
- The sharp-turn views are mirrored at extraction time so rear → slight →
turn all face the same way; the game flips sprites for right-hand
steering/curves.
Round-tripping is lossless (565→888 uses bit replication) and each import
re-trims crops to content, so stray background pixels at sprite edges get
cleaned up automatically.
## Sprite test gallery
Press `T` from the title screen: paginated view of every sprite at native
size on a checkerboard, labeled with index and crop size. `A`/`D` flips the
displayed sprite horizontally (to check turn-view alignment), page keys
cycle through car colors / scenery / traffic, `T` returns.
## Tuning
Key constants live at the top of `MiataDrive.ino`: segment length/road
width/camera (`SEG_LEN`, `ROAD_W`, `CAM_H`, `CAM_D`, `DRAW_DIST`), speeds
(`MAX_SPEED`, `ACCEL`, `BRAKE`, `OFF_DECEL`), physics (`CENTRIFUGAL`), and
race format (`LAPS`, `LAP_TIME`).
## Files
| File | Purpose |
|----------------------|------------------------------------------------|
| `MiataDrive.ino` | the game |
| `sprites.h` | generated sprite data (do not edit by hand) |
| `sprites_sheet.png` | editable sprite sheet (source of truth) |
| `sprite_tool.py` | sheet ⇄ sprites.h converter |
| `sound_engine.*` | I2S sound effects |
| `utilities.h` | T-Deck board pins |