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.

Quick start

Requirements: Node.js 22 or newer and npm.

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:

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 and docs/twitch-setup.md. The optional private operator console is documented in docs/admin-panel.md.

Planning documents

MVP Product Requirements Document — defines the product boundary and 33 success criteria.
MVP Technical Specification — defines the approved architecture, authoritative state, rules, contracts, and failure behavior.
MVP Acceptance-Test and Build Checklist — 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/.