ryanfitzpatrickio
8a96ede9f2
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.
157 lines
4.3 KiB
Markdown
157 lines
4.3 KiB
Markdown
# 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.
|