modbison/docs/checkpoints/PC3.md

# Package Checkpoint 3 (PC3)

> **Status: partial.** PC3's planned scope was M4-avatars + M5-multiplayer +
> Foundation Hardening + M6–M10 (see `docs/build-plan-v1.md`). As of
> 2026-09-05, **M4, M5, and most of Foundation Hardening are done and
> checkpoint-verified**; M6–M10 have not been started. This doc records what
> is real. Whether to call this "PC3" (redefined scope, M6–M10 → PC4) or keep
> PC3 open is a user decision.

Built by Claude directly (fleet offline), branch `pc3` → `main`.

## What's real and verified (`scripts/run_checkpoint_tests.py`, all green)

| Check | Result |
|---|---|
| Alembic migrations, fresh DB | PASS |
| Backend `pytest` | 77/77 PASS (hermetic — auto-starts an ephemeral Postgres) |
| Godot smoke tests (~16 files) | ALL PASS |
| `smoke_test_network_client` (real dedicated server) | 4/4 PASS |
| 2-player multiplayer (`run_multiplayer_2p_test.sh`) | PASS |
| Fresh-clone boot (`verify_fresh_clone.sh`) | PASS |
| Linux + Windows exports | Build as real ELF64 / PE32+ binaries |

### M4 — Avatars in the game

- Placeholder avatar pack (14 GLBs, rigged 24-bone base body + attachments)
  generated by `scripts/tools/gen_placeholder_avatars.gd`. Real art is a
  content swap — catalog paths are stable.
- The avatar **loader was fixed** — it had never run against a real skeleton
  (`Skeleton3D.has_bone()` isn't a Godot 4 method; the bone-copy dropped the
  skin binding; attachments were parsed then discarded).
- `avatar_visualizer.gd` **rewritten** — the old one referenced a loader API
  that never existed and didn't compile.
- Persistence: `avatar_loadouts` table + `GET/PUT /api/avatar/loadout`
  (loadout stored as one JSON doc; server validates the envelope only).
- Wired into gameplay: the in-world player renders as the assembled avatar
  (not a capsule); the loadout is fetched at login; "Customize Avatar" from
  the main menu saves through to the backend.
- **Follow-up:** camera is still first-person, so the local player doesn't
  see their own avatar much (third-person is a polish item); remote players'
  avatar appearance is not replicated yet (they show as labelled capsules).

### M5 — Real multiplayer

- `server.gd` **actually runs a sim now** — loads the world level, spawns a
  server player per peer, processes each peer's input queue in seq order at a
  fixed 30 Hz, broadcasts full snapshots with a per-peer `last_seq`. (The
  input queue was a no-op before.)
- `network_client.gd` reconciliation **replays in-flight inputs** from the
  authoritative state (drops acked ones), snaps only on real drift.
- **Server orchestration** (`backend/app/services/game_servers.py`): one
  headless Godot dedicated-server process per world, spawned on demand by
  `POST /api/worlds/{id}/join`, port-allocated, with a status-file idle
  reaper. Off by default; the playtest launcher (`checkpoint_ops.py`)
  enables it.
- **Client play path**: world browser → `/join` → `Session` → `game.tscn`
  connects → local player predicts with collision, input forwarded, server
  position is a drift backstop, remote players render from snapshots,
  disconnect returns to the world list. Falls back to local single-player
  when the backend has no orchestration.
- **Verified**: two real client processes each `register → /join → play`,
  hosted on an orchestrated server, see and move relative to each other
  (`run_game_multiplayer_test.sh`).

### Foundation Hardening

- **Hermetic backend tests** — `cd backend && pytest` works from a clean
  checkout (auto ephemeral Postgres + migrations, torn down after); skips
  cleanly with a message if there's no Docker.
- **Fresh-clone boot check** — `verify_fresh_clone.sh` exports a pristine
  tree, imports from scratch, boots headless, fails on any script error.
  Also fixed the root cause: a stale `.godot/global_script_class_cache.cfg`
  was committed to the repo.
- **Real age verification** — `/register` takes a date of birth (not a
  checkbox), server computes age, 403 under 18. Still self-attested; the
  limitation and the ID-check hook are documented
  (`content_moderation.md` 5.2).
- **Auth rate limiting** — 10 attempts / min / IP on `/register` + `/login`.
- **CI workflow** — `.forgejo/workflows/checkpoint.yml` written, **not
  running yet**: needs the operator to enable Forgejo Actions + register a
  `host` runner (one-time; see `docs/ci.md`). Interim gate is
  `run_checkpoint_tests.py` by hand / the dashboard.

## Not in PC3 (planned but not started)

- **M2** server-side world persistence
- **M6** scripting sandbox
- **M7** in-game editor
- **M8** social / chat
- **M9** economy
- **M10** discovery

## Playtest

Same as PC2 — grab the exe from the dashboard's `/checkpoints`, backend
pointed at it. New: with multiple people in the same world you now actually
see each other move.