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