# v2: world and content

Layers, versions and ids, the catalogue, materials, the asset pipeline and the licensing of
world data. Index: `agents/world-format-v2.md`. Schemas: `agents/v2-formats.md` (sections 1-3,
5, 9, 10). Built so far: `v2/content/` and the validator (`v2/CLAUDE.md`).

## Layers of the world

```
 canonical  ─┐   shared Newcastle everyone sees (curated, agent-validated)
 proposed   ─┤   public-world edits waiting to be merged
 personal   ─┤   your house, your flat, your private world; instant, invite-only
 session    ─┤   transient: a mission's props, debris, a player's placed bench
 overlays   ─┤   authored/agent-derived: facades, catalogue placements, terrain stamps
 generated  ─┘   OSM + LIDAR + imagery pipeline output (never hand-edited)
```
The diagram is not a precedence order; merge order is explicit (formats section 3).

- **Generated base:** today's `public/world/` plus refetchable raw inputs (OSM, EA LIDAR,
  Historic England, Esri Wayback release pinned to 26334), reproducible from the pinned
  sources (brief b, merged).
- **Overlays:** one folder per contributor/source so edits can't collide; merge order is
  explicit; CI validates that ids resolve and nothing overlaps illegally. Kinds: building
  overrides (a glTF model or a facade spec for a registry id); catalogue placements (catalogue
  id + transform + props); **terrain stamps** (height deltas and material paints over the
  generated earth, saved as modifications, so the ground is editable without touching the
  LIDAR base). Hand-built meshes replace procedural decks where those fail (overpasses).
- **Personal / proposed / canonical (decided 2026-09-26):** personal is instant and private,
  proposed is a public edit submitted for merge, canonical is the shared city. Kids get total
  freedom in personal straight away; canonical stays clean, which also carries most of the
  Online Safety Act load (see `platform-and-community.md`).

## Versions, ids and packaging (proposed, and built in the formats)

- **Every file carries `format: N`** (world, overlay, mod manifest, save, lockfile), with
  migration functions N to N+1 run in CI (Minecraft's DataFixerUpper, Factorio's migrations folder).
- **Registry ids across refetches:** `build/registry.py` carries ids across rebuilds (2 m / 25%
  area matching). Footprints that **split or merge** after an OSM refetch go through an
  **alias and tombstone table** (old id to new id(s)); overlays whose id no longer resolves go
  to a **quarantine report**, never silently dropped. A kid's claimed house must survive a
  refetch. Built: branch `v2-registry-alias`, formats section 9.
- **Mod namespacing:** ids are `modid:prop/bin`. The manifest has `depends` (semver),
  `conflicts` and `loadAfter`, sorted into a deterministic topological order; the forge shows
  a per-registry-id conflict report (Factorio `info.json`, LOOT, Fabric).
- **Lockfiles:** every world ships a lockfile (exact mod versions and content hashes). Joining
  a world means matching it; packages are content-addressed and fetched on demand (Cargo.lock).
  Built: `v2/content/world.lock.json`, written by `node v2/tools/validate.mjs --write`.

## Prop and material catalogue

GTA-style: the world never contains a bin model, only placements of `ncl:prop/bin-wheelie-ncc-green`.
- Entry: id, variants, LODs, collision shape (convex hulls), mass, material refs, destructible
  profile, optional components (a lamp's light, a bench's seats). One mesh drawn 10,000 times
  is one instanced draw.
- The pipeline already detects parked cars, back-lane bins and telegraph poles; it places
  catalogue instances and overlays override them.
- **AI attribute pass:** agents fill in the physical attributes of every entry and material in
  a cheap batch pass (mass, strength, flammability, ignition point, heat capacity, heating and
  cooling rate, conductivity, power draw, buoyancy). Rough is fine; the rules do the rest. As
  built, every value carries a `prov` entry (`ai` with `conf`, or `derived`) and authored or
  measured values beat AI ones (`v2/CLAUDE.md`).
- **Materials** (`build/texlib.json` grown up) are defined once and assigned everywhere
  ("Newcastle sandstone").

### Materials and joints: how things break
A bin is **texture + physical material + parts + joints**:
- **Surface material** (the look): albedo, normal, roughness, AO.
- **Physical material** (Source's surfaceprops): density, friction, bounciness, strength,
  impact, scrape and break sounds, bullet decal and `absorb` (formats: `absorbJm`), the particle
  it spits (dust, splinters, sparks, glass) and how it fails: glass shatters, timber splinters,
  sandstone crumbles, sheet steel dents then tears.
- **Parts and joints:** composite objects (a bin and its lid, a lamppost and its head, a bus
  shelter's panes) are parts on fixed, hinge, ball, slider or rope joints with break forces.
  Joints are what make failure feel physical.

## Splat loop (capture to catalogue, no human sign-off)

Decided shape (2026-09-26): (1) capture a Gaussian splat (a bin, a shelter, a street, a
facade); (2) agents decompose it into meshes, PBR textures and catalogue objects, segmented and
placed; (3) **rebuild and compare**: render our objects from the capture viewpoints and score
them against the splat per view; that score is the gate, not a person; (4) pass: assets into
the catalogue, placements into the location overlay; fail: iterate or flag.
- Splats are a capture source, not shipped geometry (baked capture-day lighting, heavy),
  except maybe hero landmarks.
- The same compare loop grades existing facade pipes against the photo or splat.
- Pilot plan (owner): `agents/v2-f-splat-pilot.md`.

## Asset generation pipeline (research 2026-09-27)

**Licence trap:** 2DGS, PGSR and the original 3DGS code are non-commercial research licences,
as is nvdiffrec (which TRELLIS.2 installs). Fine for a not-for-profit hobby, fatal for a paid
Steam release or taking money. **Use the clean stack:** gsplat's 2DGS mode (Apache-2.0, CUDA only) + Open3D
TSDF meshing, GLOMAP/COLMAP poses, SAM 2 masks, Brush (Apache-2.0, runs on the M3) for
previews; reimplement PGSR's multi-view consistency loss ourselves as the gate.
Non-commercial tools only behind a "research" flag.

1. **Capture:** raw phone video (frames are ours, no app terms), ~2 fps extraction, GLOMAP
   poses, a gsplat 2DGS splat, SAM 2 masks per view.
2. **Mesh, two routes, whichever passes the gate:** (A) gsplat 2DGS + TSDF mesh (true shape,
   baked light); (B) TRELLIS.2 image-to-3D from the best crop (clean closed PBR mesh, invented
   shape), checked against A's geometry.
3. **PBR:** TRELLIS.2's texturing conditioned on the photos for props; MatFuse /
   StableMaterials / Material Palette (MatE to try) for tileable shared materials into
   `build/texlib.json`, never per-prop copies.
4. **Retopo, LOD, UV:** generators output triangle soup, so remesh (Instant Meshes /
   QuadriFlow), LOD with meshoptimizer, unwrap with xatlas, bake detail to normal and AO maps
   in headless Blender. Thin street furniture: primitive fitting often beats remeshing.
5. **Collision:** CoACD with a hull cap (V-HACD is end of life); boxes and capsules first.
6. **Catalogue entry:** the AI attribute pass fills physics (mass = volume x density, ...).
7. **Gate:** LPIPS plus masked SSIM per view, silhouette IoU, depth and real-world scale,
   triangle/texture budgets, manifold check, hull containment (>= 97%) and hull count. Image
   metrics alone can be gamed by a texture over wrong geometry. Fail: other route, then flag.

- **Cost:** self-hosted on a rented 24-48 GB GPU ~1-2 cents per asset; APIs (Meshy, Tripo,
  Rodin) ~10-70 cents. Self-hosting wins on licence clarity and reproducible reruns.
- **Licence traps:** TRELLIS.2 is MIT but its rasteriser **nvdiffrast is non-commercial**:
  swap it (PyTorch3D, Blender bake, headless three.js) before any Steam or commercial use.
  **Hunyuan3D's licence excludes the UK: never use it.** Paid-API output ownership depends on
  plan: check before using.
- **Newcastle props:** generators don't know NCC green bins, Nexus shelters or Metro livery.
  **Never trust generated lettering or logos:** rebuild signage as mesh plus decal. The Metro
  "M" and Nexus branding are trademarks (invented-equivalent layer, `platform-and-community.md`).
- **Facades:** no tool makes game-ready facades from photos; parse windows and doors into our
  parametric facade spec and gate against the photo or splat.
- Character assets have their own route and traps: `characters.md`.

## Licensing of world data

- **World data is published under the ODbL**, OSM's share-alike licence: our built world
  database is very likely a derivative database of OSM, so publish it rather than fight that.
- **Assets are separate:** meshes, textures and catalogue entries from our own captures,
  photos and modelling are ours (or the contributor's), under their own licence. Keep the line
  clean in the file layout: never mix ODbL-derived data into asset files.
- Esri World Imagery's item terms permit tracing into vector data, but Esri's general terms
  disclaim derivative works: confirm which terms govern the endpoint we used. EA LIDAR and
  Historic England are OGL (attribution only). Get real legal advice before publishing
  extracted map data (owner task).
- Google photorealistic 3D tiles: ruled out (their licence forbids caching and baking).