76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# 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/`.
|