177 lines
8.7 KiB
Markdown
177 lines
8.7 KiB
Markdown
# 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.
|