PROCITY/docs/RESEARCH.md

# RESEARCH — what the parent repos already solved (port, don't reinvent)

*Condensed technical briefs from full sweeps of both repos (2026-07-14). Exact paths verified.
Read the section for your lane before writing code; open the referenced files and lift patterns.*

## 90sDJsim (`/Users/jing/Documents/90sDJsim`)

- three.js r175 **vendored** at `web/world/vendor/` (copied into PROCITY `web/vendor/`), importmap
  in `web/world/index.html`. No build, no npm. Backend = single stdlib-Python `server.py` :8123.
- Docs: `CLAUDE.md`, `DEVMANUAL.md` (single source of truth), `TOWNMAP.md`, `ECONOMY_SPEC.md`.
- **World**: `web/world/index.html` (~3400 lines, all inline). One scene, one `room` Group
  swapped per mode. `AREAS` data table (~line 711) declares streets as shop rows; `buildStrip()`
  (~740) realizes them: `BoxGeometry(4.8,h,4)` shell + facade JPEG on a `PlaneGeometry(4.7,2.4)`
  + awning box + `textPlane()` canvas signs, seeded per building with `mulberry32(i*77+5)`.
  `buildHome()` ~963, `buildVenue()` ~1094. Day/night = 6-segment `applyLighting(segIdx)`.
- **Facade skins**: `web/world/tex/facade_{record,opshop,pawn,pub,video,dept,milkbar}.jpg` —
  Cloudflare Flux, committed 2026-07-10 (commit `e31e605`), cropped below the sign band. Mapped
  by `FACADE` table (~line 276). Copied into PROCITY as `facade-djsim-*.jpg`.
- **NPC stack (the crown jewel — port for Lane D)**, `web/world/index.html` ~258–393:
  - `models/peds/` = 17 normal + 2 comical rigged GLBs (~2MB each) + clip-only `walk.glb`/`idle.glb`.
  - `spawnRig(rig,target,x,z,ry,clipName,height,extClip)`: SkeletonUtils.clone → height-normalize
    off the **head bone** → plant feet by min bone Y → mixer.clipAction().play() with random
    start offset to desync.
  - `_canon = s => s.replace(/mixamorig\d+/g,'mixamorig')` — one clip binds to any character.
  - `_rotOnly` strips position tracks + Hips.quaternion from shared clips (prevents scale blowups).
  - `upgradeStreetPeople()` — world builds instantly with primitive figures, rigs hot-swap in
    when ~40MB of GLBs arrive. Venue crowd: rigged front rows, bobbing box-figures behind.
- **`web/world/fittings.js`** — standalone parametric shop-fitting kit (racks, bins, shelves,
  counters, pegboards, canvas-texture garments). Takes THREE as arg, returns placeable Groups.
  Written to theme "any shop, any count". Port for Lane C.
- **`web/world/dig.js`** — self-contained crate-riffle minigame (own scene/camera, callback API
  `onBuy/getCash/spawnClerk/spawnFittings`). Already ported across 3 games. Content phase.
- Loaders: `loadGLB`/`loadRig`/`loadProp`/`loadTex` promise-cached, fail→null→placeholder stays.
- Perf: **zero instancing/LOD/atlases** (small scenes got away with it — we can't). Tricks worth
  keeping: `GFX_TIERS` era-tiered graphics (~line 167), bloom threshold 0.9, single 2048 shadow
  map on street only, additive light-cones, `tools/shots.py` screenshot regression harness.
- Gear/prop gen: MeshGod manifests (`MESHGOD/manifests/djsim_home.json` pattern), webp-optimized
  ~1MB GLBs, **no Draco**. Gotcha: thin wires/flat discs reconstruct badly — do those as
  in-engine primitives.

## thriftgod (`/Users/jing/Documents/thriftgod`)

- three.js 0.175 from unpkg importmap in `web/index.html` (2,061 lines = whole game). Backend
  `server.py` (1,616 lines, stdlib + psycopg2) :8777; reads `dealgod` DB (1.77M real listings).
- **Real-world city**: `build_city()` (`server.py:433`) — Overpass query for all named AU
  secondhand/charity/music/antiques/books/toys shops → `city_source.json` cache → dedupe →
  nearest-capital assignment → suburb inference → parody names → seeded hours. ~2,918 shops.
  The recipe for later swapping PROCITY's synthetic plan for real geography.
- **Seed + override architecture (the big idea)**: every shop interior is deterministic from
  `shop.seed` via mulberry32 (`web/index.html:1063`); Postgres `layout_shop`/`layout_area`/
  `layout_asset` tables hold optional hand-authored overrides; NULL = procedural fallback.
  In-game editor (E1–E4) writes overrides. See `EDITOR_PLAN.md`.
- **Street**: `buildStreet()` (`index.html:1441-1515`) — 4.4×3.4×0.4 box per shop, facade skin
  on front face, canvas name sign, OPEN/CLOSED plate, `SphereGeometry(70)` BackSide sky dome
  (seasonal `pickSky`), landmark billboard, textured ground planes.
- **Interior**: `buildShop()` (`index.html:1109+`) — 5 archetypes `SHOP_SHAPES`
  (cosy/gallery/wide/hall/pokey), seeded wallpaper/carpet/art, shuffled wall-slot system so
  decor never overlaps, record bins, shelves with product thumbnails, floor piles, counter+till,
  glass case. Port for Lane C.
- **Generated assets**: 557 JPGs in `web/assets/gen/` from `gen_assets.py` (OpenRouter
  `google/gemini-3.1-flash-image`, ~$0.004/img, resumable `.genraw/`, style-bible prefix
  *"1990s Australian op-shop aesthetic, slightly faded and worn…"*). Facade prompts generate
  **blank signboards** (template at `gen_assets.py:69-86`). 69 relevant skins copied into
  PROCITY. CORS enabled on live `/assets/*`.
- **3GOD depot loading** (`index.html:1072-1249`): `DEPOT='https://digalot.fyi/3god'`,
  `GLB_CACHE[file] ||= loadAsync`, SkeletonUtils.clone, bbox floor-plant, auto-play `/idle/i`
  clip. Editor palette from `/api/list`.
- Movement: PointerLockControls + AABB clamps + rotated-rect divider collision (`hitsDivider`,
  `index.html:1994`). `/img` caching proxy with SSRF guard (`server.py:1362`) for CORS-free
  WebGL textures.
- Item economy (content phase): `mint()` `server.py:792-858` — per-shop-type profiles, gem
  bands, curation axis (CBD distance), isolation multiplier, `TABLESAMPLE` over real listings,
  rarity from live supply. `dig.js` riffle with real physical sleeve thicknesses.

## Everything else

- **character_kit** (`~/Documents/character_kit/`, also on ultra): female + male canonical rigs,
  props (hats/boombox/camera/thermos), `scripts/finish_rig.py`, `export_for_mixamo.py`.
  House law: edit here, copy into games, never edit game-local.
- **mixamo-fetch** (`~/Documents/mixamo-fetch/`): `fetch.cjs` drives Mixamo's REST API (token
  from logged-in Brave via CDP :9222). 34 clips in `out/`. Search first; never re-download.
  Bespoke clips (crate-riffle, DJ) don't exist there — hand-author.
- **ultra 3D=models library** (`johnking@100.91.239.7:~/Documents/3D=models/`):
  `shop-fittings/` (record_crate_plastic_01, clothes_rack_01, shelf_metal_wire_01,
  garage_shelves_metal_v2, bookshelves, cube_bookcase, wardrobes, many tables, balcao counter…),
  `street-furniture/` (bench, longbench, park_bench_01, market_stall_01, food_cart_bakso_01,
  **building_shell_01.glb**), `furniture/`, `props-scenes/` (dj_room, turntable), `characters/`,
  `animations/`. `MANIFEST.md` + `CH_MAPPING.md` + `_thumbnails/` exist — read them on ultra.
- **GODVERSE brain** (`~/Documents/dealgod/GODVERSE.md`, `docs/GODVERSE_3D_BRIEF.md`): recordgod/
  toygod/bookgod/mediagod data feeds, 44k solid-object 3D candidates, 185k vinyl w/ images —
  this is the content firehose for later. Not v1.
- **Vuntra City reference** (YouTube devlogs): 20×20km UE5 city, every building enterable,
  interiors generated at runtime, million-NPC layered simulation (detailed near / abstract far),
  faked GI. We steal the *ideas* at hamlet scale: on-demand interiors, LOD'd simulation,
  cheap lighting.