# 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). - **Rendering**: on hardware the whole frame is composed in a PSRAM-backed `TFT_eSprite` framebuffer and pushed to the panel in one continuous SPI stream at 80 MHz — no half-drawn frames (flicker) and a stable ~30 fps. If your panel shows artifacts at 80 MHz, drop `SPI_FREQUENCY` to 40000000 in `platformio.ini`. 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 |