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; repeatable California and office browser performance-budget instrumentation is implemented.

• 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

Run npm run build && npm run performance. The harness serves the production bundle locally, uses system Chrome (real GPU when available, SwiftShader as the headless fallback), warms each scene, and writes /tmp/tera-performance-budget.json. Budgets live in scripts/performance-budgets.json; a threshold, console error, insufficient sample, or anonymous private endpoint request makes the command non-zero. Use --output, --budgets, --warmup-ms, --sample-ms, or --software for explicit CI/diagnostic runs. The named matrix is California and Office at 1440×900 desktop and 390×844 mobile viewports. Frame comparisons allow only 0.1 ms for Chrome's rAF timestamp quantization; the declared and reported budgets are not raised.

• 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.