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.
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.
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_eSpriteframebuffer 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, dropSPI_FREQUENCYto 40000000 inplatformio.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
SpriteIdenum insprites.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 |