psxbase/README.md

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 10+

pnpm install
pnpm dev          # client → http://localhost:5173
pnpm dev:server   # API / signalling → http://localhost:8787

pnpm typecheck
pnpm test
pnpm build

Copy .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 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.

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):

pnpm harness -- --image tools/fixtures/survivor-reference.jpg --name Survivor

---

Co-op

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

Not affiliated with Capcom, Konami, Square, or any television franchise. The demo setting and cast are original fiction.