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: implemented.

• 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.
• PROVENANCE.json plus npm run provenance hash-gates every tracked distribution artifact, rejects undeclared copied items and remote/bundled fonts, and records original procedural/data lineage.
• npm run licenses enforces the reviewed dependency-license allowlist and registry integrity pins; npm run sbom emits SPDX 2.3 from the lockfile.

Exit gate: a clean clone builds and tests without private services or binary runtime art; every shipped dependency, route, font, and asset has recorded provenance. The only tracked raster art is the two generated social cards in public/, both source-reproducible and SHA-256 pinned in the manifest.

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: implemented and integrated. City actors and office walkers share the same profile-derived appearance and journey identity; anonymous visitors change from crow outdoors to dog indoors, while signed-in members remain humanoid.

• 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

Status: core hosted actor, vehicle, and aircraft presence is implemented. The service uses short-lived rotating grants, exact interest cells, bounded 10 Hz publishing, strict motion validation, reconnect snapshots, and aggregate- only presence UI. Deterministic two-client and bounded-service acceptance tests cover convergence, late join, cell isolation, ownership, revocation, cleanup, and speed-hack rejection.

• 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

Status: implemented and integrated. Signed-in members can start an optional camera face only from the Character dialog; a persistent live indicator and one-click Stop remain visible while active. Capture is tab-ephemeral, audio-free, never recorded or uploaded, follows the humanoid across scene transitions, and is torn down on Stop, track end, revocation, or page exit.

• 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

Status: implemented and integrated for peer-to-peer hosted sharing. Authored Three.js monitors remain dark until an authorized viewer explicitly opts in; presenters choose a tab/window through the browser prompt and have an immediate kill switch. Signaling grants, TURN grants, video textures, late join, reconnect, and revoke lifecycle are bounded and tested. Presenter encoding defaults to 1280×720 at 15 fps and 1.5 Mbps with capability-safe browser fallback.

• MediaSurface records identify office/room/screen, ACL, source, and state.
• WebRTC peer track after authorization and explicit viewer opt-in; Three.js gets a video texture only while subscribed. An SFU is a later scale-out option, not a core requirement for the bounded eight-participant room.
• 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

Status: solo and hosted multiplayer play are implemented. The original procedural electric V-tail has deterministic assisted/manual control, chase camera, California bounds, and an authoritative geographic wire adapter; remote clients render its bank, control surfaces, and fan phase from validated state.

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.