Made of little things.

# Pocket Circuit

A miniature 3D racing napplet: three-lap races, up to six human players,
AI opponents, four cars and a live track workshop. Original procedural artwork;
inspired by tabletop toy racers.

## Play locally

The workspace is already installed. Run `soyli dev` and open the URL it prints.
Stop the owning process with Ctrl+C after testing. `pnpm dev` alone has no napplet
host and is not the supported game preview. See [host tooling](docs/napplet-space.md).

- **Garage:** choose Comet, Bumble, Bruiser or Mantis and one of seven circuits.
  Select a two-, four- or six-car grid and race AI.
- **Drive:** W/Up accelerates, S/Down reverses, A/D or Left/Right steer,
  Space brakes/drifts, R recovers. Touch controls support simultaneous steering
  and acceleration. Local races pause on focus loss; online races continue.
- **Rooms:** enter a driver name, host a six- or four-player room, or join a listed
  room/by code. Guests ready up; the host starts. Empty seats become AI. The host
  supplies the track and judges collisions, laps and results. If the host leaves,
  the race ends; departed guests become AI. Late arrivals watch the current race.
- **Workshop:** draw a loop, drag its points, change each point's Z height and
  width. Width blends smoothly between points. **Add point** is a placement tool:
  click where the new point should go (Esc returns to editing). **Sections** lets
  you click the stretch between two points and toggle its walls or set their
  thickness. Walls have solid tops, ends and matching car collisions.
  The plan and 3D preview update together. Save/load keeps one personal draft
  through the host, including automatic upgrades of earlier saved drafts; room participants receive the current course at race start.
- Toggle engine audio with the music button. Rotate/zoom the preview; use
  Overview/Follow during a race.

Minimum game frame: 280×240. Smaller frames show a resize notice and retain state.

The visual direction is a colorful toy-box Grand Prix: illustrated car cards,
chunky racing lettering, striped car liveries and a miniature playset with flags,
flowers, pools and a checkerboard start gantry. The seven presets have distinct
palettes. A midnight-violet UI with warm cream text keeps its own racing colors
through host theme changes. Roads are 30% wider, including earlier saved drafts;
point widths can reach 20.8 m. Both typefaces are embedded; see [font credits](src/fonts/README.md).

## Build and verification

```sh
pnpm verify                 # guidance, physics/geometry tests, types, single-file build
pnpm test:conformance        # reference-shell checks (read passed/skipped separately)
soyli check                 # target-host artifact validation
pnpm test:ui                # exact-size themes, editing, save/reload and touch tests
pnpm test:multiplayer       # six independent clients with latency and jitter
```

Some VPN/local ICE configurations cannot connect browser peers directly. To test
through an isolated TURN relay using an installed coturn binary:

```sh
soyli multiplayer tests/multiplayer.mjs --players 6 --latency 50 --jitter 15 \
  --timeout 120 --turn-binary /path/to/turnserver
```

The same scenario also runs with `--players 4` or `--players 2`.
See [verification notes](docs/verification.md) for measured coverage and gaps.
Use `soyli publish` to release the committed build, selected cover and preview clip
under the currently selected creator account.

## Architecture

- `src/art.ts`: shared racing palette, course art direction and car portraits.
- `src/track.ts`: versioned closed cubic spline, road sampling and nearest surface.
- `src/physics.ts`: fixed 60 Hz simulation, grip, damped height suspension, gravity,
  mass-based collisions, ordered lap gates, AI pursuit and recovery.
- `src/render.ts`: bundled WebGL renderer and procedural low-poly geometry.
- `src/editor.ts`: pointer-based plan editing and drawing.
- `src/network.ts`: validated Soy rooms, explicit host authority, star WebRTC
  sessions, bounded sending, roster/ready/start/leave lifecycle.
- `src/main.ts`: UI, local input, simulation scheduling, sequenced guest prediction,
  host acknowledgements, reconciliation and remote snapshot interpolation.

This is arcade physics with physical foundations, not a full vehicle simulator.
Contact uses planar disc proxies with vertical separation, rather than tire-by-tire
rigid-body simulation. Power-ups, boost pickups, public track galleries, host migration
and competitive anti-cheat are future work.

The game has no external assets or rendering dependencies. The final artifact is one
self-contained HTML file. Optional host capabilities: `storage`, `config`,
`cvm`, `webrtc`. Missing online/persistence capabilities leave local racing and editing
available. There are no direct network calls, signer access, or relay escape hatches.

The backend provider is pinned in `napplet.json`. `soyli backend init` generates the
public namespace/provider context. Before builds, `scripts/sync-backend.mjs` copies
only that public context into `src/backend-context.json`; private soyLI state remains
ignored. The source-safe copy is needed because this CLI rejects tracked files under
`.napplet-space`. On remix, use soyLI to regenerate the creator's namespace before
building; do not manually substitute an author or provider.

For other environments, upstream skills are installed with
`npx skills add napplet/napplet`. This workspace already has them; do not reinstall
or re-scaffold. The build contract is in [docs/game-design.md](docs/game-design.md).