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

125 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |