# World format v2 (index)

Status (2026-09-27): design agreed with the owner 2026-09-26; v2 is being built on branch
`world-format-v2` in `v2/` (kernel, systems, clock, weather, NPCs, vehicles, missions, forge,
referee, audio, characters, first pixels; see "What's built"). This index is the contract the
work hangs off: change the design here (or in the area doc) first, then the data contract
`agents/v2-formats.md`, then code. Decisions are in the register below; anything unsettled is
under "Open questions".

Origin: the 2026-09-26 architecture review (brain note
findings/newcastle-game-architecture-review-baseline-2026-09-26) and the owner's follow-ups.
Ideas are the currency here: if a conversation produces one, it lands in an area doc or it is
lost. Condensed from one 1,755-line file on 2026-09-27; what moved where, and what was dropped
and why, is in `agents/v2/_condense-checklist.md`.

## Area docs

| Doc | Covers |
|---|---|
| `agents/v2/world-and-content.md` | layers, versions/ids/lockfiles, catalogue, materials and joints, splat loop, asset pipeline and its licence traps, world-data licensing |
| `agents/v2/systems.md` | principle 7 as proven, electricity, heat, fire, later systems, clock/sun/moon/tide, weather, vegetation and night, water |
| `agents/v2/simulation.md` | tick, determinism and replay (Rapier spike), data-oriented design, relevance tiers, physics, moving frames, destruction, agent tooling |
| `agents/v2/vehicles.md` | handling, drivetrain, damage, classes, Metro rails, interiors, upgrades, vehicle networking and audio, parody brands, models |
| `agents/v2/characters.md` | animation, skeleton, body, face, clothing, bake and ragdoll, safety, motion data and character licences |
| `agents/v2/npcs.md` | NPC components, navmesh, pathfinding and traffic, tiers, schedules, witnesses and police, reactions, NPC networking |
| `agents/v2/missions-and-forge.md` | entity I/O, the forge, missions, dialogue and voice policy, private worlds and mods, Source feature checklist |
| `agents/v2/gameplay.md` | economy, inventory, wanted, combat, police practice, griefing and PvP |
| `agents/v2/networking.md` | who simulates, netcode v2, referee, anti-cheat, persistence tiers and saves |
| `agents/v2/rendering-and-audio.md` | renderer, sensor camera, upscaling, benchmark harness, weather rendering, asset delivery, audio, voice recording, browser compatibility |
| `agents/v2/platform-and-community.md` | accounts and safety, content policy and ratings, contributions and the mod hub, claiming houses, input and UI, web and Steam |
| `agents/v2/gold-dust.md` | borrowed tech: all prior art, grouped |

Related: `agents/v2-formats.md` (schemas and their own decision tables), `agents/v2-roadmap.md`
(briefs a to m), `agents/v2-overnight-goals.md` (goals and progress), `v2/CLAUDE.md` (what is
built, directory by directory).

## The target

- **Look and feel: Source / gmod, not PS1.** Move off uber-low-poly and stiff animation: proper
  player and NPC bodies with GTA-style clothing and customisation, no square heads. The PS1 mode
  survives as a stylised option, not the baseline.
  - Fidelity comes from materials with depth (normal/roughness), baked and bounced light, AO,
    modelled detail (window reveals, sills, cornices, rooflines) and lots of physical props,
    not raw triangle count (v1 already draws 1.5M a frame).
  - The eye catches silhouettes (need geometry), contact (need AO) and repetition (need
    variation). Take detail from where it is forced, put it where it counts.
- **Physics is a feature, not plumbing.** Props you can knock over, carry, stack and weld; cars
  that crumple; buildings that break (gmod, Teardown).
- **Mod-first ecosystem.** The official Newcastle is one mod set among many, built with the same
  tools players get.
- **Humans out of the loop by default.** The pipeline and agents produce and validate content
  unattended; a human can always step in through the forge, but nothing waits for sign-off.

## Principles (decided 2026-09-26)

1. **Decouple first, engine second.** Three layers: world data, simulation, renderer. The seam
   is data, not an abstraction layer over renderers (that drags every engine to the lowest
   common denominator). The simulation emits a plain scene snapshot (entity id, transform,
   state); each renderer reads it however it likes and they share nothing.
2. **Simulation does not know about the camera.** v1's `traffic.update(camera...)` and
   `peds.update(camera...)` only simulate round the viewer, which rules out a server-side world.
   v2 simulates by interest regions the server (or local host) owns; the client camera is one
   interest source.
3. **Everything is an entity:** catalogue id + transform + components (physics body, light,
   door, seat, trigger, mission node, voice line, destructible, claimable). Buildings, props,
   cars, peds, pickups, triggers alike.
4. **Generated base, authored overlays.** Pipeline output is never hand-edited. Every change,
   human or agent, is an overlay keyed by a stable id, merged at load/build time, so a rebuild
   never wipes an edit.
5. **Registry ids are the spine.** Building ids (OS grid ref) and face ids (id + compass) from
   `build/registry.py` are what overlays, claims, missions and destruction state key on.
6. **Dogfood.** The official city is built through the forge format. If our own content can't
   be made in the forge, the forge isn't good enough.
7. **We build the rules of the world, not the world.** Systems never call each other: they read
   and write components, fire and receive I/O events, and query shared fields. Emergence (a
   burning car melts the snow round it) comes from simple rules meeting, never from scripting
   the moment. Every system stays swappable on its own. Proven in a prototype and on the kernel;
   the rules that proof produced are in `agents/v2/systems.md`.

## v2 is a new game; v1 stays live (decided 2026-09-27)

- v2 is built alongside v1 in the same repo; the `build/` pipeline, the registry ids and the
  raw inputs are shared data, never shared code. v1 stays live and untouched at
  newcastle.gabrielpenman.com until v2 overtakes it.
- **Pull from v1 where it's good; never hobble v2 to keep v1 behaviour.** v1's low-poly look,
  square-headed characters and GLSL shading are not constraints.
- **Everything imported from v1 is tagged** (`origin: "v1"` on classes, materials and
  placements, `prov.src: "v1"` on fields), so it is always findable and replaceable.
- Carries over: the generated world data and registry ids, facades and the facade pipeline,
  the texture/material library as a start, driving feel (car.js numbers), game rules (wanted,
  police, weapons, seats, wrecks) as design reference, stations and radio, the multiplayer
  protocol ideas. Doesn't: v1 character meshes, the PS1 shading code (`ps1.js`, `post.js`), the
  camera-coupled simulation structure.
- **v1 is preserved:** tag `v1.0` and branch `v1-maintenance` (both `7aa9c4a`, pushed); untracked
  live assets of the time (loading images, `mob.png`) are archived in
  `/home/gabriel/newcastle-data/v1-untracked/`. v1-branch work (the snapshot module, the
  benchmark harness) is kept standalone so v2 adopts it unchanged.

## Decisions register

Every decision in the design, one line each. "Owner" = the owner decided; "orch." = the
orchestrator under the owner's delegation (`agents/v2-roadmap.md`); "build" = settled by what
was built. Items the old spec left undated are marked 09-26, the day of the original review.
Schema-level decisions live in `agents/v2-formats.md` ("Decisions taken here", "Resolved in
v1.1/v1.2").

**The must-decide-now list (from the 2026-09-26 gap review):**
1. **Authority model: hybrid** (owner, 2026-09-26): server authoritative for shared systems
   (traffic spine, police and wanted, missions and leases, fire, persistent damage, money);
   peers own local physics detail and exchange it peer to peer. `agents/v2/networking.md`.
2. **Renderer: three.js WebGPURenderer (TSL)** (owner, 2026-09-26); our own renderer (e.g. wgpu)
   deferred indefinitely; a Steam build wraps the web build. `agents/v2/rendering-and-audio.md`.
3. **v2 is a new game; v1 stays live** (owner, 2026-09-27). Above.
4. **Versioning and id stability** (proposed 09-26; built in the formats and registry aliases).
   `agents/v2/world-and-content.md`.
5. **Tick, determinism and replay** (proposed 09-26; tick fixed at 60 Hz by the build).
   `agents/v2/simulation.md`.
6. **Agent tooling** (proposed 09-26). `agents/v2/simulation.md`.

**Owner decisions, 2026-09-27:**
- **Peer-to-peer: yes**, mesh on by default with a relay-only privacy setting. `agents/v2/networking.md`.
- **Canonical world is PEGI 18** (`rules18`); kids and schools get `rules12` worlds.
  `agents/v2/platform-and-community.md`.
- **Adult bodies only.** `agents/v2/characters.md`.
- **Limb detach is a world rule**: on in canonical (18), off in 12-rated worlds. `agents/v2/characters.md`.
- **Quaternius: use it**, only inside official `ncl` content (QAL forbids redistribution).
  `agents/v2/characters.md`.

**Orchestrator decisions (delegated, 2026-09-27):**
- **The `look` record hashes wire-rounded values** (taken in the characters build; challenge
  if wrong). `agents/v2/characters.md`.
- Tick phases `input, environment, systems, physics, post`; formats v1.2 matches. `agents/v2/systems.md`.
- State hash in ascending entity-id order (kernel format 2). `agents/v2/simulation.md`.
- Car handling target: today's v1 after the 2026-09-24 braking pass, re-measured. `agents/v2/vehicles.md`.
- Under-18 accounts are forced relay-only. `agents/v2/networking.md`.
- Welding is an overlay entry, specified in the formats first (formats v1.3). `agents/v2/missions-and-forge.md`.

**Settled by the build (2026-09-27):**
- Physics runs on rapier3d-deterministic-compat 0.20.0 (not the SIMD build). `agents/v2/simulation.md`.
- Deterministic maths (`dmath.mjs`) everywhere in the sim; no JS `Math` transcendentals. `agents/v2/simulation.md`.
- Rust port layout: **recommendation only** (brief m / goal 11 plan): custom sparse sets, hecs
  as prior art; no toolchain installed, needs the owner's OK. `agents/v2/simulation.md`.
- Open-Meteo data is CC BY 4.0 (the free API is non-commercial). `agents/v2/systems.md`.
- No TURN server: failed ICE uses the server path. `agents/v2/networking.md`.

**Design decisions (09-26 unless dated):**
- Layers: personal / proposed / canonical over session, overlays and the generated base. `agents/v2/world-and-content.md`.
- Catalogue placements only (GTA-style); AI attribute pass fills physics. `agents/v2/world-and-content.md`.
- Splat loop: capture, decompose, rebuild-and-compare as the gate; splats not shipped. `agents/v2/world-and-content.md`.
- Clean asset stack only; non-commercial tools behind a research flag (09-27). `agents/v2/world-and-content.md`.
- World data published under the ODbL; assets kept separate. `agents/v2/world-and-content.md`.
- Electricity first, heat second; fire as a rule on heat, capped and server-authoritative. `agents/v2/systems.md`.
- Fire for play: >= 1 mm/h of rain stops catching; ~12 mm/h or a hose puts it out (09-27). `agents/v2/systems.md`.
- Environment as pure fields; nobody reads the clock; golden hashes are world format (09-27). `agents/v2/systems.md`.
- Weather: simulated by default, real mode optional; default sky overcast; white LED streetlights. `agents/v2/systems.md`.
- Big water never fluid-simulated; buoyancy by pontoons; local shallow water near players. `agents/v2/systems.md`.
- Rapier stays; destruction is ours; moving reference frames are a decided want. `agents/v2/simulation.md`.
- Destruction in the format from the start, voxel lean, must not look like voxels. `agents/v2/simulation.md`.
- One relevance tier policy for every system. `agents/v2/simulation.md`.
- A recording = seed + lockfile + input log; systems marked deterministic / authoritative / cosmetic. `agents/v2/simulation.md`.
- Entity I/O is Hammer's model; I/O stays the default over scripts. `agents/v2/missions-and-forge.md`.
- The forge is the game client in edit mode; every wire visible, readable, undoable. `agents/v2/missions-and-forge.md`.
- AI assistant is ops-only with preview; no raw code execution. `agents/v2/missions-and-forge.md`.
- Missions: private is the safe default, shared a bonus; leases; pressure valve. `agents/v2/missions-and-forge.md`.
- Voice lines by real Geordies; no runtime LLM in shared worlds or for under-18s (09-27). `agents/v2/missions-and-forge.md`.
- Mod code sandboxed; tiers I/O, Python-flavoured, Rust/WASM. `agents/v2/missions-and-forge.md`.
- NPCs: no witness, no heat; schedule, utility, small FSMs, no GOAP at launch; `where(seed, t)` (09-27). `agents/v2/npcs.md`.
- Vehicles: own tyres and drivetrain; v1-arcade as CI regression; parody brands only (09-27). `agents/v2/vehicles.md`.
- Characters: VRM 1.0 skeleton on MPFB2, hide masks, per-character bake, same body for ragdoll (09-27). `agents/v2/characters.md`.
- Netcode: server star + capped mesh K = 8, leases with epochs, quantise before stepping (09-27). `agents/v2/networking.md`.
- Anti-cheat: never trust a client about anything that matters; referee not optional. `agents/v2/networking.md`.
- Persistence tiers T0-T4; SQLite + Litestream; canonical event-sourced (09-27). `agents/v2/networking.md`.
- Clean renderer first; stylised looks are passes; benchmark harness. `agents/v2/rendering-and-audio.md`.
- KTX2 ETC1S, raster terrain, content-addressed immutable payloads (09-27). `agents/v2/rendering-and-audio.md`.
- Audio is a consumer; mixer in an AudioWorklet; radio synced by the world clock (09-27). `agents/v2/rendering-and-audio.md`.
- Cross-origin isolation with `require-corp`; WebGL2 is a real fallback (09-27). `agents/v2/rendering-and-audio.md`.
- Police follow UK practice; canonical PvP opt-in; money only via the server ledger. `agents/v2/gameplay.md`.
- Contributors never touch git; licence not assignment, CC BY 4.0 default; parent accounts for under-18s (09-27). `agents/v2/platform-and-community.md`.
- No creator payouts in v2; no credits on claimed houses (09-27). `agents/v2/platform-and-community.md`.
- Accounts from day one; claims never imply residence; telemetry off for children. `agents/v2/platform-and-community.md`.
- Web first, Steam later by wrapping the web build; platform services behind thin interfaces. `agents/v2/platform-and-community.md`.

## What's built

Directory by directory in `v2/CLAUDE.md`; `bash v2/test.sh` runs every suite and must be green
before anything merges into `world-format-v2`. Progress per goal: `agents/v2-overnight-goals.md`.
In short: the kernel (`v2/sim/core/`), systems (`v2/sim/systems/`), clock and weather,
dialogue, navmesh prototype (`v2/nav/`), missions, chunk converter (`v2/build/chunks/`), voice
recorder and batch, the Heaton slice (`v2/sim/scenarios/`), NPCs v0, physics and road vehicles
v0, first pixels (`v2/client/`), referee v0 (`v2/net/`), audio v0 (`v2/audio/`), conformance
fixtures (`v2/conformance/`), forge MVP stage 1 (`v2/forge/`), characters milestone. Off the v2
line by design: `v2-bench` and `v2-snapshot` (they hook v1's live runtime). Prototypes:
`tools/systems-sandbox/`, `tools/determinism/`.

**Still to build** (from the original order of work and the goals): split the ~1,100-line root
`CLAUDE.md` into per-directory docs; the catalogue pilot's community contribution (a Minecraft
build via Mineways, or a hand-modelled pub); the destruction prototype on one building; the
WebGPU renderer beyond first pixels (brief e stages 2-5); the Rust core (brief m); the gaps from
the Heaton slice (dialogue pack and lawns in the lockfile, recording keyframes, stand-in systems
for spawning, routes, trigger volumes and barks); the chunk converter's material array texture;
the referee's remaining list (`agents/v2/networking.md`).

## Open questions

- **Mod sandbox:** WASM (capability-limited, CPU-metered, runs in browser and server) is the
  lean. Open: how the Python-flavoured tier runs inside it, and how close we get to s&box's
  instant hotload with a compile step in the loop.
- **Rapier determinism on ARM** (gates lockstep bubbles and the native check): holds across
  engines on x86; ARM unproven. Details in `agents/v2/simulation.md`.
- **Per-player capacity budgets** (entities, bandwidth, owned bodies) and the per-system budget
  table: to be measured by the harness before multiplayer opens.
- **Destructible representation:** voxels (Teardown) vs pre-fractured meshes, and whether the
  lighting voxels are the same volume.
- **Where private worlds are hosted and who pays.**
- **Claim rules for real addresses:** one claim per address? verify anything?
- **System order within a phase:** formats section 14 orders by `after` then id, the kernel by
  declared order; decide in JS (changes hashes).
- Unverified figures awaiting a source are listed in their area docs (tide range and lag,
  rainfall and kittiwake counts, crate maturity, AX-class cost, Safari Opus decode).

## For the owner (can't be done by agents)

- **M3 runs:** the bench (`v2-bench`, add `&sync=1`) and the renderer pages in Chrome and Safari;
  open `v2/client/` on the M3. Nothing about speed is decided on this box (SwiftShader).
- **ARM determinism check:** `node tools/determinism/serve.mjs`, `/?build=det` on Apple Silicon
  Safari and an iPhone; expect `a3e6aacdec0f0161`.
- **Splat pilot:** `agents/v2-f-splat-pilot.md`.
- **RTT** from Newcastle ISPs to Nuremberg/Helsinki and between two home lines (tunes K and the
  tier rates).
- **Legal reads:** CMU mocap in a free mod SDK; contracts with under-18 contributors
  (solicitor); which Esri terms govern the imagery endpoint; publishing extracted map data
  (ODbL); Open-Meteo's terms before real-weather mode ships (the free API is
  non-commercial); the OSA illegal-content and children's access assessments before public upload opens.
- **Content:** pick and edit the AI-drafted Geordie barks; the navmesh road-crossing cost; the
  Rust toolchain OK.