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.
125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# 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)
|
||
|
||
```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 |
|