tera/BUILD_PLAN.md

# Tera / Spaces build plan

This is the execution order for the California world. It is intentionally a
dependency plan rather than a feature wish list: each milestone leaves behind a
tested substrate the next one can safely use.

## North star

One continuous California world at three nested scales:

1. **State / corridor** — Los Angeles to San Francisco, route traffic, flyover.
2. **City / exterior** — detailed Bay Area and Southern California boards,
   office buildings as real destinations.
3. **Office / metre scale** — walkable interiors, people, rooms, and screens.

Every scale supports **Observe**. Selected actors and vehicles additionally
support **Play**. Public geometry and ambient simulation work from a static
clone; identity, private presence, realtime state, webcam faces, and shared
screens are hosted capabilities layered on top.

## Work lanes

| Lane | Owns | Can run in parallel with |
| --- | --- | --- |
| World + simulation | transport packs, cells, origin rebasing, controllers | assets, UI, service contracts |
| Asset craft | vehicles, humanoids, dog, crow, buildings, animation | every milestone once interfaces are frozen |
| Product + camera | chapters, follow/chase/walk cameras, input, accessibility | simulation and assets |
| Realtime + media | session authority, interest zones, ACLs, WebRTC surfaces | solo play after state contracts exist |
| Quality | deterministic replays, browser captures, performance budgets, provenance | continuous; never a final cleanup phase |

The critical path is world coordinates → deterministic control → walkable actor
contract → authoritative sessions → private media. Art can stay one milestone
ahead; realtime/media must not jump ahead of the actor and access contracts.

## M0 — contracts and provenance

Status: **in progress**.

- Tera/Spaces is the renderer; `lumbridgecorp` is the control plane.
- Apache-2.0 remains the outbound code license.
- Every copied asset/data item gets a pinned source, license, hash, and intake
  note. Original procedural assets record their design lineage.
- Add an automated asset-manifest gate, dependency license allowlist, and SBOM.

Exit gate: a clean clone builds and tests without private services or binary
art; every shipped dependency, route, font, and asset has recorded provenance.

## M1 — California roads and passive Model X traffic

Status: **implemented and rendered on desktop and mobile; performance-budget
instrumentation remains**.

- Coarse California board plus detailed Bay Area and SoCal boards.
- Serializable US-101 and I-5/I-580/I-80 route graphs.
- Procedural black Model X with follow and corridor detail tiers.
- Fixed-step deterministic traffic, both carriageways, instanced background
  vehicles, and a chase/follow camera selected from route chapters.

Exit gate: one hero completes either route on the road; the same seed and frame
sequence reproduce the same poses; route switching leaks no GPU resources; the
declared desktop/mobile frame budgets pass in browser capture.

## M2 — solo playable driving

Status: **deterministic control core plus keyboard, standard gamepad, touch,
chase, and driver-height camera integration implemented and rendered on desktop
and mobile**. The vehicle owns a controller state separate from its render rig.

- Keyboard, gamepad, and touch input through one normalized action map.
- Chase and driver-height cameras.
- Assisted route following as a state machine; manual input takes over and can
  hand back cleanly.
- Route guardrails, recovery/reset, pause and background-tab recovery.
- Fixed input traces for deterministic replay tests.

Exit gate: finish both routes manually or assisted; no NaNs, ordinary-speed
tunneling, or tab-resume jumps; a recorded input trace replays identically.

## M3 — walkable offices and actors

Status: **collision/controller foundation and procedural actor assets
implemented; office camera/input integration and identity handoff pending**.

- First-/third-person walker against the existing `Plan.blocked` wall segments.
- Door traversal and city ↔ office identity handoff.
- Customizable procedural humanoid for signed-in members.
- Anonymous office visitor is a dog; anonymous Tera visitor is a crow.
- Profiles begin as generated materials and parameters, not uploaded binaries.

Exit gate: every room reachable through doors but never through walls; identity
survives scene changes; anonymous clients receive no private presence; 30-minute
soak produces no stuck or out-of-bounds actor.

## M4 — authoritative multiplayer

- Dedicated realtime session service; do not merge it into the control plane.
- Server-authoritative actor/vehicle poses, input validation, interpolation,
  reconnect, and interest zones keyed by Tera cell / Office / Floor / Room.
- `lumbridgecorp` issues short-lived launch grants and revalidates membership.
- Delta snapshots around 10–15 Hz for nearby dynamic actors; media never rides
  on this socket.

Exit gate: two browsers converge within the declared latency; reconnect restores
the right cell; revocation ejects promptly; malformed and speed-hack state is
rejected; selected cell concurrency passes a repeatable load test.

## M5 — profile and webcam faces

- Generated profile face is the default.
- Webcam face is opt-in and ephemeral: explicit contextual permission, active
  indicator, one-click stop, no recording/storage by default.
- Server-enforced visibility capabilities; unauthorized clients never receive
  the private object or track.

Exit gate: revocation and tab close stop every track; anonymous/unapproved peers
cannot subscribe; the full product works without a camera.

## M6 — office media surfaces

- `MediaSurface` records identify office/room/screen, ACL, source, and state.
- WebRTC SFU track after authorization and explicit viewer opt-in; Three.js gets
  a video texture only while subscribed.
- Share tab/window by default, muted viewer autoplay, visible broadcast state,
  presenter kill switch, late join and reconnect.

Exit gate: no unauthorized subscription; revoke ends tracks and disposes GPU
textures; bandwidth adaptation and safe public placeholders work.

## M7 — playable aircraft

Keep today's aircraft ambient until vehicle, actor, camera, and network
abstractions are proven. A later `PlayableAircraft` reuses flight-source data for
the world but owns a separate controller and authority model.

Exit gate: route/altitude bounds, camera and control handoff, multiplayer
validation, and no regression to ambient live ADS-B rendering.

## Performance gates

- Named benchmark scenes: p95 frame at or below 16.7 ms desktop and 33.3 ms on
  the selected supported mobile tier.
- Hard budgets per scale for resident cells, triangles, draw calls, dynamic
  actors, GPU memory, and media textures.
- Fixed simulation tick separated from rendering; instancing, LOD, pooling,
  frustum/distance culling, and explicit resource disposal.
- Degrade shadows, traffic density, and far detail before input, access control,
  identity, or privacy enforcement.

## Immediate parallel build

The California driving vertical slice now proves the transport, vehicle,
controller, input, camera, and responsive UI contracts. Continue in these lanes:

1. **World:** corridor cell streaming, origin rebasing, city/office destination
   transitions, and deterministic route-completion scenarios.
2. **Office:** integrate the walker with first-/third-person cameras, doors,
   actor possession, and identity-preserving city ↔ office transitions.
3. **Assets:** add driver-view interior hints and animation/state adapters for
   the existing humanoid, dog, and crow rigs; keep the code-only asset pipeline.
4. **Platform:** define versioned launch-grant, session, interest-zone, actor,
   vehicle, and media-capability schemas plus their threat model—without coupling
   the renderer to a hosted service.
5. **Quality:** add repeatable frame-time/draw-call budgets, screenshot baselines,
   long-route and office soak tests, asset-manifest CI, and cross-browser input
   coverage.