Mike0021/agua-seca-western-world

Agua Seca — a realistic 3D western frontier town (1886)

An explorable, historically grounded 3D western railroad town that runs entirely in the browser. Agua Seca, New Mexico Territory, July 1886, 6:40 PM — an AT&SF-style water stop, cattle-shipping point, and mining-supply stop on the high-desert bench (1,610 m), one wide dirt main street of staggered false fronts running from a church knoll in the north to the rail depot in the south, ringed by red-rock mesas.

Built by a Kimi K3 lead orchestrator through Claude Code: an ARCHITECT subagent researched and froze the town plan, 15 specialist subagents built the assets against that contract, two QA subagents audited history and rendering, and the lead integrated, reviewed, and verified everything. The full process is documented in TOWN_PLAN.md, SUBAGENT_LEDGER.md, ASSET_MANIFEST.md, and QA_REPORT.md.

Run it

Any static file server from the repo root works — no build step:

npm run serve          # tiny built-in server → http://127.0.0.1:8080
# or: python3 -m http.server 8080

Then open http://127.0.0.1:8080 in a WebGL2-capable browser.

Controls

H fades the help card. Modes also switch from the top-right bar.

What's in the town

20 planned lots per the frozen plan: La Estrella Saloon (two-storey, balcony, batwing doors, warm interior), Exchange Hotel (full two-storey porch + exterior stair), brick Agua Seca Bank, general store + U.S. Post Office + telegraph, Territorial sheriff & jail (wanted posters, barred cells), assay office and rooming house (the two pre-rail adobes), barber, gunsmith, doctor, livery barn + corral, blacksmith (open forge bay, brick chimney), Union Church + belfry/spire + cemetery, District 7 school + yard, rail depot (bay-window ticket office, chalkboard, platform), freight platform, water tower (raised spout over the main line), stockyard pens + loading chute + windmill — plus boardwalks with step blocks, plank crossings, alleys, a service lane of privies/wood ricks/refuse, three wagons, 60+ barrels, hitched horses with idle motion, cattle, chickens, a dog, circling vultures, rolling tumbleweeds, chimney smoke, golden-hour dust, and a monsoon thunderhead with virga over the mesa.

Tech

• —Three.js r178 (MIT), vendored locally in vendor/three/ — the only runtime dependency. ES modules + import map; static-host compatible, no bundler.
• —Fully procedural: every mesh is generated code; every texture is a canvas generated at boot by the material registry (src/assets/materials.js, 25 keys). No external models/images/fonts. Deterministic: one master seed (1886) drives all randomness via a namespaced mulberry32 (src/ctx.js) — two boots are pixel-identical.
• —Real-world scale (1 unit = 1 m) and a frozen coordinate/lot contract (TOWN_PLAN.md §3/§5, src/TOWN.js).
• —Performance: merged static geometry per building, instancing for ties/barrels/ crates/fence posts/vegetation/rocks, 313 draw calls / ~536 k triangles at high quality (budget 1000 / 1.2 M), low-quality mode for mobile (278 calls / ~295 k tris).
• —Atmosphere: physically coherent golden-hour sun (az 252°, el 14°), PCFSoft shadow map, FogExp2 haze, gradient sky dome with sun lobes, cumulus + virga, GPU chimney/train smoke, dust motes, gaussian contact-shadow decals, ACES tone mapping.
• —Walk physics: eye at 1.68 m, capsule-vs-AABB collision against 233 registered collider boxes, walkable decks (boardwalks, porches, balconies, platforms), auto-step 0.25 m / Space-assist 0.55 m, terrain grounding via the analytic heightfield.

Verification

node test/probe-terrain.mjs   # 53 heightfield assertions (TOWN_PLAN §2.1)
node test/lotcheck.mjs src/assets/saloon.js   # per-asset validator (any module)
node test/veg-census.mjs      # vegetation census: reject zones, species caps, determinism
node test/smoke.mjs           # 18-gate browser smoke test → writes test/output/final-qa.png
node test/shot.mjs --out=/tmp/x.png --cam=0,1.68,108 --look=0,3,-60   # deterministic screenshot
node test/ashot.mjs --specfile=test/output/reconciliation/spec-integrated.json  # batch capture

Current state (unified build, post-reconciliation 2026-07-26): all 18 smoke gates pass, zero page/console errors, desktop + mobile boots clean, determinism proven (byte-identical double-boot frames), 53/53 heightfield probes, 20/20 modules lotcheck high+low, vegetation census PASS.

Artifacts

• —TOWN_PLAN.md — researched, frozen town plan (Agua Seca, 1886) + lead amendments A1–A27
• —ASSET_MANIFEST.md — every module, owner, budget, ratified deviation, licenses
• —SUBAGENT_LEDGER.md — every subagent launch, verdict, defect, retry
• —QA_REPORT.md — defect lists, both QA verdicts, visual QA passes, acceptance checklist
• —TERRAIN_UPGRADE_PLAN.md / TERRAIN_UPGRADE_REPORT.md — AAA terrain overhaul mission (broken-ring landforms, far ranges, 5-tier rocks, vegetation ecology, atmosphere retune)
• —ASSET_POLISH_PLAN.md / ASSET_POLISH_REPORT.md — exhaustive non-terrain asset perfection pass (9 specialist waves over all 18 lots + street/props/life/rail)
• —RECONCILIATION_REPORT.md — merge of the two missions into this unified build: strategy, conflicts, verification, metrics, evidence
• —test/output/intermediate-preview.png / test/output/final-qa.png — before/after evidence
• —test/output/terrain-upgrade/ / test/output/asset-polish/ — mission evidence sets
• —test/output/reconciliation/ — unified-build evidence (overview/player/commercial/ rail/terrain/mobile + two QA passes)

License

Project code: MIT. three.js: MIT (see vendor/three/LICENSE). All textures/models are procedurally generated for this project.