# Twungeon

Twungeon is a Twitch-controlled cooperative dungeon game in which viewers watch
a shared world on stream, join through Twitch chat, and control individual
characters with a Twitch Extension.

## Project status

Twungeon now has a runnable MVP proof of concept. It includes an authoritative
TypeScript game core, deterministic two-room dungeon generation, HTTP and
WebSocket APIs, a shared broadcast/Extension UI, synthetic local Twitch events,
and a Twurple production boundary for chat, followers, Channel Points, and
Extension identity. Live Twitch acceptance still requires operator credentials, an
approved Extension configuration, and real-viewer evidence.

Each floor has four first-come, first-served party slots with fixed Blue, Green,
Red, and Yellow identities. Reaching the exit clears the party and opens the
next floor for a complete reparty. Player phases use a rolling five-second
deadline that each living player may reset once with their first accepted
action. The same Twitch Extension provides compact desktop controls and a
touch-oriented mobile layout backed by the same authoritative game instance.

## Quick start

Requirements: Node.js 22 or newer and npm.

```bash
npm install
npm run dev
```

Open `http://localhost:3000`. Expand **Local viewer login**, then choose
**Spawn & bind** to exercise the complete local controller loop without Twitch.
The production Twitch viewer is the transparent Video Overlay at
`http://localhost:3000/extension`; use
`http://localhost:3000/extension?dev=1&debug=1` to exercise its shared controls
and view alignment boundaries locally.

Quality gates:

```bash
npm run lint
npm run typecheck
npm test
npm run test:integration
npm run build
```

Production startup uses `npm run build` followed by `npm start`. Configuration
is described in [.env.example](.env.example) and [docs/twitch-setup.md](docs/twitch-setup.md).
The optional private operator console is documented in
[docs/admin-panel.md](docs/admin-panel.md).

## Planning documents

- [MVP Product Requirements Document](Twungeon_MVP_PRD_Current.md) — defines the
  product boundary and 33 success criteria.
- [MVP Technical Specification](Twungeon_MVP_Technical_Specification.md) —
  defines the approved architecture, authoritative state, rules, contracts, and
  failure behavior.
- [MVP Acceptance-Test and Build Checklist](Twungeon_MVP_Acceptance_Test_and_Build_Checklist.md)
  — sequences implementation and defines the evidence required for each success
  criterion.

The PRD is authoritative for product scope. The specification and checklist
must be updated alongside any approved requirement change.

## Initial technical direction

The implementation uses TypeScript and Twurple, with game rules isolated from
framework and service adapters. The current RPGJS package is an authority-free
render-model adapter; adopting RPGJS engine rendering remains a presentation
integration task and cannot move rules out of the domain package.

Public project and development-log records are maintained under `.labyricorn/`.