Files
lilygo-t-deck/examples/MiataDrive/README.md
T
Dejvino d542d6ffa7 MiataDrive: flicker-free framebuffer rendering + 80 MHz SPI
Render every frame into a full-frame TFT_eSprite (16 bpp, PSRAM) and push
it to the panel in one continuous SPI stream — direct scattered draw calls
raced the panel scan-out and flickered. renderRoad split into projection
and draw passes: the sky now fills down to the topmost road row (fixes the
stale band at the horizon over crests) and the nearest segment is extended
to the screen bottom (fixes the wobbling stale strip). fillTrap uses
incremental edge interpolation. SPI raised to 80 MHz via build flag
(Setup210 define guarded) so the frame push fits the 33 ms budget.
2026-11-12 23:17:43 +01:00

5.3 KiB
Raw Blame History

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

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