Files
lilygo-t-deck/examples/MiataDrive
Dejvino 2ac8706606 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
2026-11-12 22:29:37 +01:00
..

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

Running

On your PC (SDL2 emulator)

cd emulator
make run APP=MiataDrive

Headless smoke test (N frames, dump the last frame as a BMP):

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):

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.

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