190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# 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):
|
||
|
||
```js
|
||
{
|
||
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, poly: [[x,z],…] } ],
|
||
lots: [ { id, block, x, z, w, d, ry, frontEdge, use } ],
|
||
// use: 'shop' | 'anchor' | 'house' | 'yard' | 'stall' | 'infill'
|
||
shops: [ { id, lot, type, name, sign, seed, facadeSkin, storeys, hours: [open, close] } ]
|
||
// type: see SHOP TYPES below
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
### 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).
|
||
|
||
## Shop types v1 (registry lives in `web/js/core/registry.js`, Lane A writes it, all lanes read)
|
||
|
||
| 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 |
|
||
| `toy` | stucco-pink, deco-pastel | shelves + glass case | cube shelves, display tables, glass case |
|
||
| `book` | federation, sandstone | halls of shelves | bookshelves, spinner racks, armchair |
|
||
| `video` | stripmall, djsim-video | aisle shelves | VHS shelving, returns slot, poster wall |
|
||
| `pawn` | besser, grimy, djsim-pawn | counter-forward | glass cabinets, wall hooks, barred window |
|
||
| `milkbar` | djsim-milkbar, brickveneer | counter + freezer | counter, fridge, magazine rack |
|
||
| `dept` (anchor) | terrazzo, djsim-dept | grand hall | mixed sections, escalator prop |
|
||
| `stall` (market) | facade-market | open stall | trestle tables, crates |
|
||
|
||
## 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 |
|
||
| `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.
|
||
|
||
## 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`).
|