# Vibegame — AI context

Multiplayer 2D platformer (Ultimate Chicken Horse-style): alternating build/play
phases, server-authoritative, deterministic shared simulation.

**Starting fresh? Read [docs/HANDOFF.md](docs/HANDOFF.md) first** — current state,
mental model, file map, invariants, toolchain traps, verify recipes. Then:
[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (how it works),
[docs/ROADMAP.md](docs/ROADMAP.md) (supported vs planned vs debt),
[docs/adr/](docs/adr/) (why the stack is what it is).

## Commands

```bash
pnpm dev          # web (localhost:3200) + game server (ws://localhost:3001) via turbo
pnpm test         # Vitest across all workspaces (~1s, run it often)
pnpm build        # next build + tsup server build + typechecks
pnpm lint         # eslint (root config for packages/server, next config for web)
pnpm typecheck    # tsc --noEmit everywhere
pnpm --filter @vibegame/server exec tsx scripts/smoke.ts   # E2E vs running server
```

## Layout

- `packages/shared` — deterministic sim core + zod protocol. Runs on client AND server.
- `apps/server` — ws rooms; `GameRoom` is transport-agnostic (tests use fake connections).
- `apps/web` — game code in `src/game/` (non-React); React is menus/HUD only, bridged
  via the Zustand store in `src/game/store.ts`.
- `packages/db` — repository interfaces (in-memory now; Prisma/MySQL stub prepared).

## Hard rules

1. **Simulation determinism**: nothing in `packages/shared/src/sim|physics|modes|maps|
   characters|placeables` may use `Math.random` (use `sim.rng`), `Date`, timers, or I/O.
   Iterate players via `sim.getPlayers()` (sorted). The determinism test will catch
   violations — keep it passing.
2. **Never trust the client**: clients send inputs/intents; the server validates
   everything (`validatePlacement`, `mode.canPlace`, zod schemas). New messages get zod
   schemas in `shared/src/protocol/messages.ts` and are parsed with them on both ends.
3. **World units**: 1 unit = 1 block cell, y grows downward, 60 Hz fixed tick
   (`TICK_DT`). Don't mix pixels into shared code — pixels exist only in the renderer.
4. **Extending content** (mode/map/modifier/character/placeable): implement the
   interface + register it — see the table in ARCHITECTURE.md. Don't special-case core
   code for specific content.
5. **Milestone hygiene**: keep `docs/ROADMAP.md` current when adding features or
   discovering debt; significant decisions get an ADR.
6. **No commits or pushes without explicit user approval**: pushing to `main`
   triggers the publish workflow (`.github/workflows/main.yml`), so every commit
   and push deploys. Never run `git commit` or `git push` unless the user asks.

## Conventions

- TypeScript strict, ESM everywhere, single quotes, 100-col prettier.
- Tests colocate per package in `tests/`; shared test fixtures in `tests/helpers.ts`.
- Art style: Clean Vector Flat, procedural Pixi Graphics + procedural shaders
  (ADR 008); no image/audio assets ever.
  Palette: coral `#FF6B57`, teal `#1B4353`, cream `#FFF3E0`, gold `#FFC24B`.