PROCITY/docs/CITY_SPEC.md

PROCITY — CITY_SPEC (the shared contract)

Every lane reads this first. If a lane needs to change something in here, it changes this file in the same commit and says so loudly in the commit message — this doc is the treaty.

What we are building

A standalone, procedurally generated, fully walkable Australian shopping town — the Vuntra City trick (every building enterable, interiors generated on demand) applied not to cyberpunk towers but to record stores, op shops, toy shops, book barns, video rental, pawnbrokers, milk bars, market stalls. 90s-Australia aesthetic, low-poly + generated texture skins. Content (real item data, lore, economy) plugs in later via the GODVERSE/BaseGod feeds — v1 is the system: plan → streets → facades → doors that open → themed interiors → NPCs walking around.

Engine decision (settled — do not relitigate)

three.js r175, vendored, plain JS ES modules, importmap, zero build step, zero npm. This is the proven house stack (90sDJsim + thriftgod both ship on it), it runs great on Apple Silicon, and it lets us lift working code (fittings kit, rig stack, dig.js) verbatim. Unreal was considered and parked: nothing in v1 needs it, and the asset pipeline (GLB, web-ok licensing, 3GOD depot) is web-native. Serve with cd web && python3 -m http.server 8130.

• three and three/addons/ resolve via importmap to web/vendor/ (copied from 90sDJsim).
• No DRACO requirement (house GLBs ship uncompressed/webp-optimized); DRACOLoader is vendored if needed.
• No external CDNs at runtime. Everything local or from https://digalot.fyi/3god (CORS-enabled).

Units, axes, determinism

• Metres. +Y up. Ground plane is XZ. City origin (0,0) = centre of the main square.
• Right-handed three.js defaults. Buildings face their street; a facade's outward normal points at its street edge. GLB convention: origin at base, facing −Z, real-world scale.
• Seeded everything, Math.random() is banned in generation code. web/js/core/prng.js is the only randomness source:
  • seedFor(citySeed, kind, id) → stable uint32 (xmur3 hash of "seed:kind:id").
  • rng(citySeed, kind, id) → mulberry32 stream.
  • Same citySeed ⇒ byte-identical city, forever. This is the thriftgod/90sDJsim house rule and it's what makes the authored-override layer possible later.

The three-layer architecture

LAYER 1  CityPlan   (pure data, no THREE)   Lane A
LAYER 2  Streetscape (chunked 3D realization) Lane B
LAYER 3  Interiors  (on-demand room scenes)  Lane C
         Citizens   (NPCs over layers 2+3)   Lane D
         Assets     (skins + GLB depot)      Lane E

Layer 1 — CityPlan (JSON-serializable, generated in <100ms)

The whole town as lightweight data, generated up front from citySeed, dumpable to JSON. Schema v1 (Lane A owns it; extend, don't break):

{
  version: 1,
  citySeed: 20261990,           // uint32
  name: "…",                    // generated town name
  size: { w: 1024, d: 1024 },   // metres, city core v1 = 1km²
  districts: [ { id, kind, cx, cz } ],
      // kind: 'mainstreet' | 'arcade' | 'backstreets' | 'warehouse' | 'residential' | 'market'
  streets: {
    nodes: [ { id, x, z } ],
    edges: [ { id, a, b, width, kind } ]   // kind: 'main' | 'side' | 'lane' | 'arcade'
  },
  blocks: [ { id, district, kind, poly: [[x,z],…] } ],
      // district = district ID (index into districts[]); kind = that district's kind string, denormalized
      // onto the block so consumers can theme it without a lookup (Lane A extension, non-breaking).
  lots:   [ { id, block, x, z, w, d, ry, frontEdge, use } ],
      // use: 'shop' | 'anchor' | 'house' | 'yard' | 'stall' | 'infill'
      // ry: Y-rotation (radians) so a GLB modelled facing −Z ends up with its facade's OUTWARD normal
      //     pointing at frontEdge. World facing = (−sin ry, −cos ry). Lane B rotates the shell by ry.
      // frontEdge: id of the street edge this lot fronts (guaranteed to exist and be geometrically adjacent).
  shops:  [ { id, lot, type, name, sign, seed, facadeSkin, storeys, hours: [open, close], openLate? } ]
      // type: see SHOP TYPES below.  hours: [open, close], 24h integers, 0 ≤ open < close ≤ 23.
      // storeys: integer in [registryMin, permittedMax] where permittedMax = registryMax≥2 ? min(registryMax+1,3)
      //   : registryMax. The "+1 (cap 3)" is the CITY_SPEC "occasional 3-storey corner anchor" — it fires ONLY
      //   for tall-capable types (registry max ≥ 2); single-storey types (video/milkbar/stall, [1,1]) are NEVER
      //   boosted. So `storeys > registryMax` on a corner anchor is EXPECTED, not plan↔registry drift.
      // openLate: present and `true` on EXACTLY ONE shop per town — the designated late-night landmark
      //   (closes ≥ 22:00; a naturally-late type, video rental or milk bar, never a market stall). Absent
      //   on every other shop. Lane B lights it after dark; Lane F's night gate keys off this field
      //   (`plan.shops.find(s => s.openLate)`), NOT a magic hours threshold.
}

Field-type contract (Lane A is the source of truth; consumer fixtures must match this, not the reverse). Every id and every reference to one — lot.block, lot.frontEdge, edge.a/b, block.district, shop.lot — is an integer, not a string. facadeSkin, and every entry in a registry facades pool, is a full filename under web/assets/gen/ (e.g. "facade-fibro-blue.jpg") — load it verbatim; do not prepend facade- or append an extension (the shop-types table below abbreviates skin names for readability only). The same rule holds for Lane E's ground/awning/sky/wall/ interior skins: store the file exactly as the manifest names it, never re-derive a key from it.

Layer-1 invariants Lane A guarantees (enforced by web/js/citygen/selfcheck.js): fully deterministic per citySeed (with a committed golden fingerprint guarding against drift); every frontEdge/block/district/lot reference resolves; every lot faces its frontEdge; no two building lots (shop/anchor/house/stall) overlap, within OR across blocks; exactly one shop carries openLate (the late-night landmark); chunkIndex covers every lot and lists every edge in every chunk its road corridor (road + verge, centreline ± width/2) touches — so verge-placed street furniture never resolves to a chunk that omits its edge; strictly JSON round-trippable (all finite numbers, no stray keys).

Plan sources. A CityPlan can come from two producers behind this one contract, chosen via generatePlanFor(seed, source, { town }) (web/js/citygen/index.js) — the shell selects with ?plansrc= (+ &town= for osm):

• 'synthetic' (default) — generatePlan(seed), the procedural town. Byte-identical, golden 0x3fa36874.
• 'osm' — generatePlanOSM(seed, town), a real-data import from a checked-in fixture (osm_fixture.js → OSM_TOWNS; real AU shops from thriftgod's OSM cache; zero network). Towns: melbourne (default, golden 0x34cfdec0), katoomba (0x0f652510). osmTownKeys() lists them.

An 'osm' plan sets source:'osm', reports its real bounding-box size (not 1024²), and contains only real retail types — no synthetic market square, arcade, dept anchor, milk bars, or stalls. All structural invariants above hold identically. Consumers that assume a synthetic-only feature (dept/market/milkbar/stall) must guard on source. The invariant suite runs on every (source, town). Full frozen v2 producer contract below (§"CityPlan v2 — frozen producer contract").

Chunk key: cx = floor(x/64), cz = floor(z/64). Chunk size 64m. Lane A ships a chunkIndex(plan) helper: chunk key → { lots, shops, edges } touching it. Edges are bucketed across the full road corridor (centreline ± width/2), so anything placed in the verge (street furniture, footpath NPCs) resolves to a chunk whose edges list includes its edge.

CityPlan v2 — frozen producer contract

FROZEN at v2.0 (round 9). This is the authoritative Layer-1 contract — the v3 epoch (editor / override layer) reads THIS. It matches the code as shipped; web/js/citygen/selfcheck.js enforces every law here. Changes are a CITY_SPEC amendment in the same commit + a golden re-pin, never a silent drift. Import everything from web/js/citygen/index.js (the barrel) — internals (plan.js, plan_osm.js, osm_fixture.js, names.js) may move behind it.

Producer API (all from web/js/citygen/index.js):

• generatePlanFor(seed, source = 'synthetic', { town } = {}) → CityPlan — the selector the shell uses.
• generatePlan(seed) → CityPlan — synthetic producer (unchanged, byte-identical).
• generatePlanOSM(seed, town = 'melbourne', { report } = {}) → CityPlan — osm producer; pass a report object to receive the normalization log (below). osmTownKeys() → string[].
• chunkIndex(plan, chunkSize = 64) → { chunkSize, chunks }; CHUNK = 64; chunkKey(cx, cz).
• Geometry helpers (shared with the harness): lotCorners(lot), obbOverlap(a, b).

Determinism & goldens. Same inputs ⇒ byte-identical plan, forever. The determinism gate keys on (seed, plansrc, town). Committed goldens (xmur3(JSON.stringify(plan)) at seed 20261990):

source / town	golden
synthetic	0x3fa36874
osm / melbourne	0x34cfdec0
osm / katoomba	0x0f652510

Adding a town is mechanical (recipe in docs/LANES/LANE_A_NOTES.md): append to OSM_TOWNS, run selfcheck, paste the printed fingerprint into OSM_GOLDENS, tell Lane F the new hash.

Trading-hours law. shop.hours = [open, close], 24h integers, 0 ≤ open < close ≤ 23. Openness is half-open: isOpen(shop, h) ⟺ open ≤ h < close (a shop closing at 17 is shut at 17:00 exactly). Both the shell (index.html) and the NPC sim (citizens/sim.js _openAt) use this identical predicate.

openLate law. Exactly one shop per town is the late-night landmark. It is the sole shop that closes ≥ 22:00 (LATE_HOUR), so the field and the threshold are equivalent: {s: s.openLate} ≡ {s: s.hours[1] ≥ 22} (a singleton). It is the video rental (a town with no video falls back to another non-stall type, logged). Every other shop closes by 21:00 — so after ~21:00 the streets thin to that one lit destination.

Storeys law. shop.storeys ∈ [registryMin, permittedMax], permittedMax = registryMax ≥ 2 ? min(registryMax + 1, 3) : registryMax. The occasional 3-storey corner anchor adds ≤1 storey (tall types only); single-storey types (video/milkbar/stall, [1,1]) are never boosted.

OSM normalization rules (the importer bends the data to the contract, never the contract; each change is logged into report): unknown OSM shop= kind → opshop (report.typesRemapped); any shop closing ≥ 22:00 → clamped to 21:00 so only the one openLate landmark is late (report.hoursClamped); the openLate landmark prefers a video, else a fallback non-stall type (report.openLate). Shop names are the real OSM names; sign is derived. osm plans carry source:'osm', a real bbox size, and no synthetic dept/market/milkbar/stall/arcade.

Closing-time occupant ruling (Lane A, round 9 — ratifies Lane D's sim.js). When a shop closes:

1. No new entry. Patronage only ever routes a ped into an open shop (_nearestOpenShop gates on _openAt); the player likewise gets a CLOSED plate/toast and cannot enter (index.html).
2. Occupants drain, they don't pop. A ped already inside when the shop closes finishes its current bounded visit (seeded 5–20s dwell) and re-emerges through the door normally — it is never teleported out or culled at the close instant. Occupancy therefore drains to 0 within one dwell window; sim.occupancyOf(shopId) falls to 0 on its own. Any browser-rig presence (Lane D/F) tracks occupancy, so it clears with the same drain — no orphaned rigs in a shut shop.
3. The player is never force-ejected. Closing locks the door to entry only; a player already inside stays until they choose to leave (leaving restores the street where they stood, as always).
4. The openLate video shop is the one place still filling after ~21:00 (the night crowd); at its own close (22:00/23:00) it drains identically. Determinism holds: entry/dwell/emerge are seeded + clock driven, so same (seed, time) ⇒ same occupancy.

Layer 2 — Streetscape (Lane B)

Realizes CityPlan chunks around the player. Hard requirements the two parent games skipped:

• Contiguous geometry — no teleport seams; you can walk the whole core.
• Chunk streaming — build/dispose chunk Groups at radius ~2–3; never rebuild the world.
• InstancedMesh from day one for: building shells, awning boxes, verandah posts, street furniture, trees, streetlights. Canvas signage batched into a sign atlas texture per chunk (one CanvasTexture, many UV-mapped planes) — not one canvas per sign.
• Facade formula (proven in both games): instanced box shell + front PlaneGeometry with a facade-*.jpg skin + parametric awning/verandah + sign band + door + window planes. Skins are generated with blank signboards — the game overlays the shop name.

Layer 3 — Interiors (Lane C)

Interiors are not street geometry. Walking into a doorway triggers enterShop(shop) → separate room Group built from shop.seed (thriftgod archetypes + the 90sDJsim fittings.js parametric kit), themed by shop.type. Leaving restores the street exactly where you stood. Street windows show a cheap fake (tinted glass + emissive warm glow at night in v1; interior-mapping shader is a stretch goal).

CityPlan v3 — gig layer (?gigs=1) — THE DISTRICT

FROZEN at v3.0 (round 14). The authoritative Layer-1 gig-layer contract — venues, the week's schedule, posters, the gigKey map, the corridor law, and the runtime surface. web/js/citygen/selfcheck.js enforces every law here, including the round-14 400-seed district invariant sweep + an osm graceful-placement case. Changes are a CITY_SPEC amendment in the same commit + a gig-golden re-pin, never silent drift. One edit is still pending and lands with Lane F's alias-retirement commit (R13 debt #1): the R12 single-venue compat alias in the runtime block below retires; everything else here is final for the v3.0 tag.

(Recorded amendment — ROUND15, ledger #1: the frontage poster was flipped to the +Z street facade (it had been on the −Z back, invisible from the street); this moved plan.posters, so the gig golden re-pinned 0x1f636349 → 0x4f4a549d in the same commit under the amendment law above. The synthetic golden 0x3fa36874 did not move — this is the round's one sanctioned gig-golden move.)

Prime flag law. The gig layer is a post-hoc augmentation applied by the selector only when ?gigs=1. With the flag OFF, generatePlanFor(seed, src) returns the byte-identical v2 base plan — all v2 goldens stay frozen. So this section adds fields that exist only on gig-on plans; it does not touch the v2 contract above. Deterministic from (citySeed, customBands); works on synthetic AND osm towns. Node-pure (no THREE, no runtime fetch — the shell loads the band drop-in and passes it in).

(v3.0-alpha was one pub, one genre, one night's posters. ROUND13 → v3.0-beta, the district: 2–4 venues of three kinds, a full week's schedule across town, town-wide posters. Same flag, same laws.)

Turning it on (Lane F): generatePlanFor(seed, source, { gigs:true, customBands }) → plan with the gig fields below (else the base plan, untouched). generatePlanFor stays synchronous — F fetches custom_bands.json in the bootstrap and passes the array. withGigs(plan, seed, opts) is also exported.

The venues (2–4 per town — a seeded count). Three registry venue kinds — pub, band_room, rsl — each with no district weights (never auto-placed). The layer converts that many plain shops in place (keeps each lot id + geometry ⇒ enterable, no overlap), tags them shop.venue === true, shop.venueKind, shop.genreKey, and never takes the openLate landmark (the town keeps exactly one openLate shop). Kinds are added in the order pub, band_room, rsl, pub (a 4-venue town gets a second pub at the far end of the spine). Placement rules (each degrades to "any remaining plain shop" so osm towns still get venues):

kind	genreKey → gigKey	placement	hours	reads as
pub	pubrock → gig-pubrock	spine end/corner (main edge, farthest)	[17,23]	≥2-storey corner hotel
band_room	grunge → gig-grunge	warehouse-district fringe	[18,23]	single-storey tin shed
rsl	covers → gig-covers	off-spine (not main, not warehouse)	[16,23]	carpet-and-bistro club

Venue hours all close 23 (open through DUSK+NIGHT so the gig runs and D's surge fills the room; drains at close per the closing-time ruling above). Venues are the only gig-plan shops allowed to close ≥22 besides the openLate video (selfcheck exempts them). genreKey is set from the registry kind→genre map (SHOP_TYPES[kind].genre, mirrored by genreForVenueKind(kind)); John may re-flavour the two new genres (names only — E synthesises to order).

The gigKey contract (ROUND13 debt #1 — one key, zero mapping). The audio-manifest bed key for a genre IS the gigKey, and it is always gig-<genreKey>. There is no mapping table anywhere: A emits shop.genreKey + gig.genreKey, C sets audio.gigKey = 'gig-'+genreKey, E names the manifest bed identically, B's spill reads it and F resolves it — all through the single exported helper gigKeyFor(genreKey) => 'gig-'+genreKey (web/js/citygen/gigs.js, re-exported from the barrel). Import it rather than building the string; R12 lost a bed to a private rename (gig-pubrock vs pubrock-live) and, because audio fails soft, the band just mimed.

plan.gigs — the week's schedule across the whole district (present only on gig-on plans):

gigs: [ { gigId, venueShopId, bandName, genreKey, night, startSeg, endSeg, cover } ]

• 7 nights × every venue, but not every venue plays every night: each venue takes a seeded 4–6 of the 7 and goes dark the rest (dark nights read true). gigId unique town-wide; night = 0-based, F selects tonight's (night 0) per venue. venueShopId → the venue shop id; genreKey ≡ that venue's genre.
• startSeg = 5 (NIGHT / 22:00), endSeg = 5. F's state machine (now per venue): quiet → doors (startSeg−1 = DUSK) → on → done. (Day-segment→hour map is lighting.js: 0 DAWN … 5 NIGHT.) Runtime surface F publishes on window.PROCITY.gigs (B's venue.js/audio.js and D's setGig read it): .byVenue → { [venueShopId]: 'quiet'|'doors'|'on'|'done' } plus per-venue getters stateOf/onOf/openOf/gigOf/coverOf/bandNameOf/paidOf(id) + markPaidOf(id) and .venueShopIds. The R12 single-venue alias (.state/.on/.open/.venueShopId/.cover/.paid/… → the primary venue = gigs[0]'s) is kept for one round so mid-round single-venue callers don't break; it retires next round.
• cover — integer in {0} ∪ [2,10], ~half free town-wide, skewed by kind: pub 50% free / $2–10, RSL 45% free / $2–5 (cheap — the bistro pays the bills), band_room 70% free / $2–6 (a hat on a milk crate). F debits the wallet per venue at each door; a night at two venues is two covers.
• No band plays two venues on one night (≤1 slot per name per night across town): custom names are deduped and used at most once; a generated name that would clash tonight advances its stream until it doesn't (deterministic — the generator index only moves forward).

plan.posters — town-wide gig advertising (Lane B renders): posters: [ { id, gigId, x, z, ry } ]. Only tonight's (night 0) playing venues are advertised. Each such venue gets one poster on its own frontage — seated on the +Z street facade (B's canon: buildings.js facade + venue.js door/queue/ camera are all +Z; position lot + (sin ry, cos ry)·(d/2+ε)), turned to read from the street (ry = lot.ry + π so its printed face points +Z at the queue-side camera — ROUND15 ledger #1; before R15 it was on the −Z back and invisible from the street). Plus a seeded run along the spine — 2 per main edge, at t ∈ [0.2,0.8] of the block, on either verge. Different venues' posters share the same pole runs — that IS the district reading. ry follows the house convention (a poster's printed face = (−sin ry, −cos ry), so atan2 of the away-from-viewer normal); B places E's poster skin at (x, z) rotated ry; F wires "poster → that venue's tonight-gig".

The street-corridor law (ROUND13 debt #5 — published as functions, not plan data). edge.width is the full corridor (carriageway + verge/footpath, centreline ± width/2), never the carriageway alone — so a naive node.x + 2 seats furniture mid-bitumen. web/js/core/registry.js now exports the split as pure functions over an edge (no plan fields change ⇒ base goldens stay frozen), re-exported from the barrel: roadWidth(edge) (full carriageway width — main 10 m, side 6–8, lane = all, arcade 0; the kerb sits at roadWidth/2 from the centreline), vergeBand(edge) → [inner,outer] (where footpath furniture lives), poleOffset(edge) (where a pole/poster seats — just behind the kerb). Poles, verandah posts and spine posters belong in the verge band; the selfcheck asserts no spine poster stands within roadWidth/2 of any edge centreline. A frontage poster is exempt — it is bound to its venue building (the +Z facade B draws), so at a corner venue whose facade abuts a crossing street it may legitimately sit near that street's kerb (B's building geometry, not a mid-road defect).

Band names + the drop-in. bandName(seed) generates 90s-Aussie pub-rock names from wordlists. web/assets/custom_bands.json is an OPTIONAL editable drop-in (schema { "bands": ["The Feral Galahs", …] }, Lane-A-owned per ROUND12): present → those names get priority, deduped and shuffled by seed, spread night-major across the whole week's slots town-wide (not one venue's residency); absent → pure generator, zero errors, zero fetch (the ?noassets=1 path). Deterministic given (seed, file contents). John edits the file and reloads.

Closing-time law as code (v2 debt paid). isOpen(shopOrHours, hour) is exported from the barrel — the canonical half-open predicate (open ≤ hour < close) for D's gig-night patronage surge and everyone else.

Gig golden (guards gig-layer drift; pure-generator path, no custom file), seed 20261990 synthetic: 0x4f4a549d (ROUND15 re-pin — the frontage-poster +Z flip, ledger #1, moved plan.posters; was 0x1f636349 the R13 district, 0xa6ae5a5e the R12 alpha). Asserted by selfcheck.js alongside the frozen v2 goldens; changing gig output re-pins it.

Shop types v1 (registry lives in web/js/core/registry.js, Lane A writes it, all lanes read)

web/js/core/registry.js is the machine-readable source of truth — import SHOP_TYPES for the exact facade pools, sign hints, interior archetype, fittings, storeys, hours and district weights. This table mirrors it. (Lane A amendment 2026-07-14: added a variety facade to toy/book/pawn and rounded out the fittings mixes — a counter to shops that sell over one, a freezer to milkbar, a glass_case+counter to dept — so this table matches the registry lanes actually consume. Non-breaking; all facades exist in web/assets/gen/.)

(Lane A amendment 2026-07-14 · round 2, responding to B/E/F integration notes: gave stall a 2nd facade facade-corrugated.jpg (a market-shed backdrop, matching Lane E's manifest facade→type map, so every type now has ≥ 2 facades per Lane E's validator). Replaced the old per-shop 6% "open late" dice — which yielded 0…many late shops and often none past 22:00 — with exactly one deterministic openLate landmark per town (see the schema note above). Widened chunkIndex edge coverage to the full road corridor. All non-breaking; self-check green at 1283/1283; golden fingerprint refreshed to 0x098eec2b.)

type	facade pool	interior archetype	fittings mix
record	timber-teal, arcade-tile, djsim-record	crates + bins	record bins, crates, counter, listening corner
opshop	weatherboard, fibro-blue, djsim-opshop	racks + shelves	clothes racks, bric-a-brac shelving, book wall, counter
toy	stucco-pink, deco-pastel, boutique	shelves + glass case	cube shelves, display tables, glass case, counter
book	federation, sandstone, redbrick	halls of shelves	bookshelves, spinner racks, armchair, counter
video	stripmall, djsim-video	aisle shelves	VHS shelving, returns slot, poster wall, counter
pawn	besser, grimy, djsim-pawn, corrugated	counter-forward	glass cabinets, wall hooks, barred window, counter
milkbar	djsim-milkbar, brickveneer	counter + freezer	counter, fridge, magazine rack, freezer
dept (anchor)	terrazzo, djsim-dept	grand hall	mixed sections, escalator prop, glass case, counter
stall (market)	market, corrugated	open stall	trestle tables, crates
pub (v3 venue)	djsim-pub, federation	pub	bar counter, stage, PA stack, tables, stools
band_room (v3 venue)	warehouse-tin, besser, corrugated	band_room	bar counter, stage, PA stack, stools
rsl (v3 venue)	brickveneer, redbrick	rsl	bar counter, stage, PA stack, bistro tables, stools

NPC contract (Lane D)

• Fleet rule (house law): 2 rigged base meshes + shared clip bank. Canonical rigs: ~/Documents/character_kit/ (female grandma_game.glb route, male hum_character.glb) plus the 19 peds in 90sDJsim/web/world/models/peds/. Game-local copies are byte-identical builds — copy from character_kit / 90sDJsim, never edit locally.
• Distance tiers: near <25m = rigged SkeletonUtils.clone + AnimationMixer; mid = billboard impostor (pre-rendered sprite, instanced); far = culled. Walkers path along street-edge footpath lanes from the CityPlan graph.
• Licensing: 🟢 web-ok only (Mixamo, CC0/CC-BY, CGTrader RF). No ActorCore in web builds.

Performance budget (M-series laptop, 60fps)

• ≤ 300 draw calls in street mode, ≤ 200k tris in a typical view.
• renderer.setPixelRatio(min(devicePixelRatio, 2)).
• Textures: skins ≤ 1024px, sign atlases 2048px, total GPU texture < 512MB.
• Chunk build must not hitch: budget 4ms/frame (build incrementally or in idle callbacks).
• Adopt 90sDJsim's GFX_TIERS idea later if needed; don't gold-plate now.

Modes & shell (Lane B owns the shell)

MODE ∈ { map, street, interior } — one renderer, one state machine, same as both parent games. map = 2D canvas town directory (Lane A's debug view grows into it). Save/load = localStorage v1.

File ownership (parallel-safety treaty)

path	owner
web/js/core/* (prng, loaders, canvas)	scaffold (frozen — propose changes via CITY_SPEC PR)
web/js/core/registry.js	Lane A
web/js/citygen/*, web/map.html	Lane A
web/index.html, web/js/world/*	Lane B
web/js/interiors/*, web/interior_test.html	Lane C
web/js/citizens/*, web/citizens_test.html, web/models/*	Lane D
pipeline/*, web/assets/* + web/assets/manifest.json	Lane E
web/assets/custom_bands.json	Lane A (v3 band drop-in — carve-out from web/assets/*, per ROUND12)
web/package.json	scaffold/shared — {"type":"module"} only, added by Lane A
docs/*	everyone, additively

Each lane also ships its own standalone test page so it can be verified without the others. Never edit another lane's files. Integration (Lane F) happens after A–E land.

web/package.json (added by Lane A) contains only {"type":"module"} so node runs the pure web/js/** ES modules directly (e.g. node web/js/citygen/selfcheck.js, an acceptance criterion). Browsers and python3 -m http.server ignore it; no deps, no build step. It changes Node's module interpretation for every lane's web/js/** — which is what we want (all lanes can node-test their pure modules) — so it's flagged here as shared scope, not silently added.

Infrastructure map

• This mac — dev box, Blender + Unreal installed, Apple Silicon (no CUDA — all gen is cloud-API or tailnet).
• ultra ssh johnking@100.91.239.7 (key auth works, always-on M1 Ultra): MESHGOD Blender scripts (~/Documents/MESHGOD/scripts/finish_glb.py, render_glb.py, media_primitive.py), sorted model library ~/Documents/3D=models/ (shop-fittings / street-furniture / furniture — see its MANIFEST.md + CH_MAPPING.md), character_kit/, mixamo-fetch/out/ clip bank (34 clips — never re-download an existing clip). Caveats: no GNU coreutils/timeout/setsid, system python 3.9, Homebrew at /opt/homebrew.
• m3ultra http://100.89.131.57:11434 — Ollama (qwen3:235b/32b/8b, gemma3:4b vision, gemma4). Free local LLM for name generation, lore, cataloguing. Use it before any paid API.
• 3GOD depot https://digalot.fyi/3god — POST /api/upload?name=<f>.glb, GET /a/<f>, GET /api/list (CORS on). The shared GLB CDN all sibling games use.
• MeshGod https://digalot.fyi/meshgod — image→GLB generation (~30¢/solid; check the DealGod canon-3D cache first; media/books use the free parametric skinner).
• Image gen — house flow is prompt packs (see ~/Documents/FLOW_PROMPTS.md format) + thriftgod's gen_assets.py batch pipeline (OpenRouter google/gemini-3.1-flash-image, ~$0.004/img, style-bible prefix, resumable) and 90sDJsim's Cloudflare Flux scripts (creds in ~/Documents/backnforth/.env).

Style lock (visual)

Low-poly chunky geometry, flat-ish shading, muted 90s Australian palette, warm cinematic light — the 90sDJsim POLY lock — skinned with the thriftgod generated-texture kit (69 skins already in web/assets/gen/). Facade prompt template (blank signboards!) is in thriftgod gen_assets.py:69-86 — reuse it for new skins so everything matches.

House patterns to keep (both games proved these)

• Promise-cached loaders; missing asset ⇒ placeholder box, never a crash. The game must run with zero assets.
• CanvasTexture text planes for ALL signage/text — no font files.
• SkeletonUtils.clone for anything skinned; canonicalize mixamorig\d+ → mixamorig so one clip drives every character; strip position tracks from shared clips (_rotOnly).
• Height-normalize rigs off the head bone; plant feet by min bone Y.
• Seeded flat-colour fallbacks under every texture.
• A shot() fixed-camera screenshot harness for visual regression (90sDJsim tools/shots.py).