Initial public release of PSX Adventure Engine

Browser reference stack for PSX-era third-person adventure: fixed cameras, inventory puzzles, Box3D physics, host-authoritative P2P co-op, and a modular character harness. Ships the Ashgrove Precinct Level 1 investigation demo with a full cast and nine linked rooms.
2026-07-31 06:32:43 -05:00
commit 8a96ede9f2
181 changed files with 25807 additions and 0 deletions
@@ -0,0 +1,156 @@
+# PSX Adventure Engine
+
+Browser-first reference engine and project template for **PSX-era third-person
+adventure** — fixed cameras, inventory puzzles, low-poly atmosphere, and true
+peer-to-peer co-op.
+
+Inspired by classic survival-horror and investigation games of the late ’90s
+(not affiliated with any of those franchises).
+
+| Layer | Stack |
+| --- | --- |
+| Client | Three.js · Solid · Vite · Box3D (`box3d-wasm`) |
+| Server | Hono · WebSocket signalling · optional Neon |
+| Shared | Strict TypeScript types & save schemas |
+| Tools | Code-drawn character creator · procedural clips · optional Grok textures |
+
+**Status:** Milestone 3 — playable multi-room demo, co-op, character harness.
+
+---
+
+## Quick start
+
+**Requirements:** Node 20+, [pnpm](https://pnpm.io) 10+
+
+```bash
+pnpm install
+pnpm dev          # client → http://localhost:5173
+pnpm dev:server   # API / signalling → http://localhost:8787
+```
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Copy [`.env.example`](./.env.example) if you need custom ports or a session
+secret. Defaults work for local solo play without any env file.
+
+---
+
+## Controls
+
+| Key | Action |
+| --- | --- |
+| `W` `A` `S` `D` / arrows | Move (tank: `A`/`D` turn, `W`/`S` walk) |
+| `Shift` | Run |
+| `E` | Interact / talk / examine |
+| `Space` | Quick turn (180°) |
+| `C` | Toggle tank ↔ camera-relative |
+| `Tab` | Inventory |
+| `M` | Co-op lobby |
+| `` ` `` | Debug overlay |
+| `Shift`+`F5` | Save to local storage |
+
+---
+
+## Demo campaign — Ashgrove Precinct (Level 1)
+
+Investigation loop in a fixed-camera building: walk the precinct, **question
+NPCs**, gather evidence, and open locked wings with inventory puzzles.
+
+```
+Lobby (Ellis) ── Witness Lounge (Kane)
+     │
+Squad Hall ── Detective Office (Det. Reyes)
+     │     ── Interview Room (Nora Voss)
+     │
+Corridor ── Records (Dr. Hale)          [repaired crank → valve]
+     │
+Break Room ── Evidence Vault (Marrow)   [brass key → vault key]
+```
+
+**Progression**
+
+1. Talk to people in Lobby, Lounge, Office, Interview
+2. Squad Hall — crank handle + broken shaft → combine into repaired crank
+3. Corridor valve → Records (Hale, brass key, notes)
+4. Break Room (brass key) → vault key
+5. Evidence Vault — journal, badge case, case payoff
+
+Cast GLBs live in `assets/characters/` and are rebuilt with `pnpm cast`.
+
+See [`GDD.md`](./GDD.md) for full design, networking model, and implementation notes.
+
+---
+
+## Character creator
+
+Two base bodies (**male** / **female**) on a Mixamo-compatible canonical skeleton,
+plus swappable hair / clothing / footwear. Recipes in
+`tools/src/creator/presets.ts` export Idle / Walk / Run / QuickTurn / **Slumped**
+clips.
+
+```bash
+pnpm creator -- --list
+pnpm cast                       # all presets → assets/characters/
+pnpm creator -- --id survivor
+pnpm creator -- --id survivor --uv-guide
+pnpm creator -- --id survivor --texture   # needs Grok CLI for albedo paint
+pnpm creator:ui                 # http://localhost:5174
+```
+
+Optional photo path (silhouette measure → code-drawn mesh):
+
+```bash
+pnpm harness -- --image tools/fixtures/survivor-reference.jpg --name Survivor
+```
+
+---
+
+## Co-op
+
+```bash
+pnpm dev:server   # terminal 1
+pnpm dev          # terminal 2
+```
+
+Press `M`, create an account, host, share the five-character room code. Host is
+authoritative; guests send movement intent and reconcile 15 Hz snapshots.
+
+---
+
+## Layout
+
+```
+client/    Runtime — engine, systems, PSX post, rooms, Solid UI
+server/    Hono API + WebSocket signalling (in-memory store by default)
+shared/    Types, skeleton, save / net schemas
+tools/     Character harness + local creator UI
+assets/    Shipped cast GLBs (+ recipes); generated/ is gitignored
+```
+
+---
+
+## Implementation notes
+
+A few design-doc features are unavailable in `box3d-wasm@0.2.0`:
+
+| Design doc | Reality | Workaround |
+| --- | --- | --- |
+| Character mover | Not bound | Capsule collide-and-slide via ray probes |
+| Triangle-mesh rooms | No trimesh | Box + convex-hull compounds |
+| Capsule sweeps | No shape cast | Multi-height `castRayClosest` fan |
+
+The client sets COOP/COEP headers so the threaded physics build can load; the
+debug overlay reports which build you got.
+
+---
+
+## License
+
+[MIT](./LICENSE)
+
+Not affiliated with Capcom, Konami, Square, or any television franchise. The
+demo setting and cast are original fiction.