Rename Lotus3 to MiataDrive; original-graphics title screen
- examples/Lotus3 -> examples/MiataDrive, sketch MiataDrive.ino, emulator target APP=MiataDrive, platformio src_dir updated - drop the borrowed photo title background (title_bg.h): the title screen now renders the game's own start line under the arch with the selected car parked on the road; color picker labels sit over the horizon, showcase car doubles as the live preview - add dedicated README (controls, features, sprite pipeline, gallery) - commit in-progress work the game now depends on: sound engine events (engine hum, crash noise) plus the 4-line SDL audio shim in the emulator host
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# 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).
|
||||
|
||||
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 |
|
||||
Reference in New Issue
Block a user