sprite_tool.py gains a 'clean' subcommand that tidies the sheet in place: drops specks (<=4px) and 1px sliver lines left over from the original checker-keyed extractions, and re-centers every sprite in its cell (bottom-anchored, 2px margin) so nothing touches the cell edges. Tree trunks / palm fronds are protected from thin-line removal. Run on the sheet: 489 junk pixels removed; re-import crops tightened (e.g. car_white_turn 108x60 -> 92x54, car_yellow_turn 86x60 -> 80x56).
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).
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 |