Twungeon/Twungeon_MVP_PRD_Current.md

# Twungeon MVP Product Requirements Document

**Status:** Approved product baseline

**Baseline date:** 2026-08-17

**Implementation design:** [Twungeon MVP Technical Specification](Twungeon_MVP_Technical_Specification.md)

**Execution and verification:** [Twungeon MVP Acceptance-Test and Build Checklist](Twungeon_MVP_Acceptance_Test_and_Build_Checklist.md)

This document remains the source of truth for MVP product scope and acceptance.
The companion specification defines implementation behavior, and the checklist
tracks build sequencing and evidence without replacing these requirements.

## 1. Product Summary

**Twungeon** is a Twitch-controlled cooperative dungeon game in which viewers watch a shared game world on the Twitch stream and control their own characters through a Twitch Extension.

The MVP is intended to prove that the complete interaction loop works at a basic level:

**Twitch viewer -> follower eligibility -> `!spawn` -> character control -> turn-based dungeon play -> combat -> healing -> death -> resurrection or floor advance -> new floor -> run reset**

The MVP is not intended to prove game balance, long-term progression, production presentation, or anti-exploit systems.

---

## 2. MVP Objective

The MVP should demonstrate that multiple Twitch viewers can:

- intentionally join a shared dungeon,
- control individual characters through Twitch,
- take turns using a simple action-point system,
- move through a procedurally varied dungeon floor,
- encounter and fight a basic enemy,
- heal themselves,
- die and remain inactive for the current floor,
- resurrect through a configured Channel Points reward,
- advance the entire party by reaching the exit,
- revive dead players on floor advancement,
- and reset the run when all participating players die.

The MVP succeeds if these systems work together reliably enough to test the core concept with real Twitch viewers.

Balance, difficulty, exploit prevention, and polish are explicitly secondary.

---

## 3. Player Eligibility and Joining

### 3.1 Watching

Any Twitch viewer may:

- enter the channel,
- watch the game,
- and participate in normal Twitch chat.

Watching the channel does not automatically create a game character.

### 3.2 Player Eligibility

Only Twitch followers are eligible to play.

### 3.3 Spawning

A follower joins the game by typing:

`!spawn`

When a valid `!spawn` command is received:

1. The backend verifies the Twitch identity associated with the chat message.
2. The backend verifies that the viewer follows the channel.
3. The backend verifies that the viewer does not already have an active character.
4. The backend verifies that the viewer has not died on the current floor.
5. A character is created in the current floor's spawn room.
6. The game records the Twitch user ID as the authoritative identity for that character.
7. The player's Twitch Extension identity must resolve to the same Twitch user ID before game controls are enabled.
8. The player's Twitch Extension game controls become active.

Only one active character may exist per Twitch user.

A follower who has died on the current floor cannot use `!spawn` to bypass death. That player must wait for either a Channel Points resurrection or advancement to the next floor.

### 3.4 Twitch Identity Binding

The MVP must explicitly associate the identity that issued `!spawn` in Twitch chat with the identity operating the Twitch Extension.

The binding must use Twitch's stable user identity rather than display name alone.

Controls must not be enabled unless:

- the Extension viewer has an authenticated identity,
- that identity maps to the same Twitch user ID that owns the spawned character,
- and that character is currently eligible to act.

This prevents one viewer's Extension controls from operating another viewer's character and closes the chat-to-controller identity gap.

---

## 4. Twitch Extension Controls and Game View

The Twitch Extension acts as the player's controller.

The MVP controller must provide:

- Up
- Down
- Left
- Right
- Attack
- Monster target selection
- Self-heal
- Pass / end unused actions

The shared Twitch stream is the primary game display.

Players do not require a separate conventional game client.

### 4.1 Three-Section MVP Layout

The MVP game view must establish the intended structure of the final Twungeon experience even if the graphics and styling remain temporary.

The view consists of three major sections:

1. **Upper-left control/status area**
   - Smallest of the three areas.
   - Contains the Twitch gameplay controls and basic player status needed for MVP testing.

2. **Upper-right game area**
   - Largest area.
   - Displays the current two-room floor, player characters, Goblin Guard, walls, paths, and exit.

3. **Bottom running text area**
   - Spans beneath both upper sections.
   - Displays a chronological action/system log.

The MVP does not require final retro pixel art or production-quality framing. It does require enough structural presentation that early players can understand the intended game experience.

### 4.2 Action Log

The running action log is part of the MVP.

It must provide clear confirmation of significant game actions and state changes, including at minimum:

- player movement,
- player attacks,
- successful hits,
- misses,
- Goblin attacks,
- damage,
- AutoGuard blocks,
- self-heal use,
- player death,
- Channel Points resurrection,
- Goblin aggro or return behavior when useful,
- floor advancement,
- dormant-state changes,
- and total-party wipe/run reset.

Example messages include:

- `Chris moves east.`
- `Chris attacks Goblin and hits for 1 point of damage.`
- `Goblin attacks Chris and misses.`
- `Chris casts Heal on self and returns to full HP.`
- `Chris blocks Goblin's attack with AutoGuard.`
- `Chris dies.`
- `Chris is resurrected.`
- `Floor 3 begins.`

Player-to-player in-game chat and `!say` remain outside the MVP.

---

## 5. Dormant State: No Active Players

If there are no active players currently in the dungeon, the game enters a dormant state.

While dormant:

- the current floor remains loaded,
- no Player Phase timer runs,
- no Enemy Phase occurs,
- the Goblin does not act,
- and the dungeon does not reset simply because no players are active.

The stream must display a visible banner:

**Type `!spawn` to spawn in the Twungeon!**

Any eligible follower who has not died on the current floor may type `!spawn` to enter.

The new player spawns in the current floor's spawn room.

When the first eligible player spawns:

1. the dormant-state banner disappears,
2. the game resumes,
3. and a fresh Player Phase begins.

A player who already died on the current floor remains dead and cannot use `!spawn` to re-enter.

Zero active players is not considered a total-party wipe.

The MVP maintains only one active floor at a time. No previous-floor simulation or multi-floor concurrent state is required.

---

## 6. Turn Structure

Twungeon is turn-based.

Each round consists of:

1. Player Phase
2. Enemy Phase

Players always have initiative.

---

## 7. Player Phase

At the beginning of each Player Phase, every living player receives:

**2 Action Points (AP)**

Each of the following costs 1 AP:

- Move one tile
- Attack
- Cast self-heal
- Pass

Players may spend their AP in any valid combination.

Examples:

- Move + Move
- Move + Attack
- Attack + Move
- Attack + Attack
- Heal + Move
- Move + Heal
- Pass + Move
- Pass + Pass

Players do not need to act in a fixed sequential order. Valid player commands may be processed during the shared Player Phase.

### 7.1 Player Phase Timer

The Player Phase timer scales with the number of living players:

**25 seconds per living player**

The timer is capped at:

**120 seconds maximum**

Examples:

- 1 living player: 25 seconds
- 2 living players: 50 seconds
- 3 living players: 75 seconds
- 4 living players: 100 seconds
- 5 or more living players: 120 seconds

The Player Phase ends when either:

- all living players have spent or passed their available AP, or
- the timer expires.

Unused AP is handled through AutoGuard.

---

## 8. AutoGuard

Any AP remaining when the Player Phase ends becomes Guard for the immediately following Enemy Phase.

**1 unused AP = 1 blocked successful hit**

Examples:

- 0 AP remaining = 0 Guard
- 1 AP remaining = block 1 successful hit
- 2 AP remaining = block 2 successful hits

This applies even when a player is inactive or AFK.

Therefore, a completely inactive player who spends no AP receives 2 Guard during each Enemy Phase.

For the MVP, any resulting exploits or indefinite defensive behavior are acceptable.

Guard is reset when the next Player Phase begins.

---

## 9. Player Character

All MVP players use the same basic character type.

### 9.1 Player Stats

- HP: **3**
- AP per Player Phase: **2**
- Movement: **1 tile per AP**
- Attack cost: **1 AP**
- Attack damage: **1 HP**
- Attack hit chance against Goblin: **65%**

A player dies when HP reaches 0.

---

## 10. Self-Heal

Every player has one self-heal available per floor.

### Heal Rules

- Cost: **1 AP**
- Target: **self only**
- Effect: restore HP to full **3/3**
- Uses: **once per floor**

The heal refreshes when a new floor begins.

There is no healing of other players in the MVP.

---

## 11. Enemy: Goblin Guard

Each floor contains exactly one enemy:

**Goblin Guard**

### 11.1 Goblin Stats

- HP: **2**
- AP per Enemy Phase: **2**
- Movement: **1 tile per AP**
- Attack cost: **1 AP**
- Attack damage: **1 HP**
- Attack hit chance against players: **50%**

---

## 12. Goblin Behavior

The Goblin operates using a minimal state model.

### 12.1 Guarding

At the beginning of a floor:

- the Goblin is positioned near or directly in front of the exit door,
- the Goblin is passive,
- the Goblin does not move,
- and the Goblin does not attack unless attacked first.

### 12.2 Aggro

When a player attacks the Goblin:

- the Goblin becomes hostile,
- the attacking player becomes its pursuit target,
- and the Goblin begins acting during Enemy Phases.

The Goblin may spend its 2 AP on:

- movement,
- attacks,
- or a combination of both.

### 12.3 Pursuit

The Goblin follows its target until one of the following occurs:

- the Goblin dies,
- the pursued player dies,
- or the floor ends.

### 12.4 Target Death

If the pursued player dies:

1. The Goblin stops pursuing that player.
2. The Goblin begins returning toward its original guard position.
3. Once it reaches its guard position, it resumes its passive guarding behavior.

### 12.5 Player Escape

The Goblin does not have to be killed to complete the floor.

A pursued player may flee from the Goblin and reach the exit.

If a living player enters the exit while the Goblin is still alive:

- the floor ends,
- the Goblin remains behind,
- and the Goblin does not follow to the new floor.

A new Goblin is created on the next floor.

---

## 13. Enemy Phase

The Enemy Phase begins after:

- all living players have completed their Player Phase actions, or
- the Player Phase timer expires.

During the Enemy Phase:

- the Goblin receives 2 AP,
- performs valid behavior according to its current state,
- then ends its turn.

After the Enemy Phase completes, a new Player Phase begins.

---

## 14. Dungeon Floor Generation

Each floor is intentionally simple.

Every floor must contain exactly:

- one spawn room,
- one exit room,
- a navigable connection between the rooms,
- one exit door,
- and one Goblin Guard associated with that exit.

### 14.1 Procedural Variation

Between floors:

- room sizes may change,
- room positions may change,
- and the connecting path or corridor may change.

The generator does not need to create a sophisticated dungeon.

The MVP only needs to reliably produce varied two-room floors.

---

## 15. Floor Progression

The objective of each floor is:

**Reach and enter the exit door while alive.**

Killing the Goblin is optional.

When any living player enters the exit:

1. The current floor ends immediately.
2. The floor counter increases.
3. A new two-room floor is generated.
4. A new Goblin Guard is created.
5. All participating players are placed in the new spawn room.
6. All players are restored to full HP.
7. All dead players are resurrected.
8. Every player's self-heal is refreshed.

The dungeon may continue generating floors indefinitely for the MVP.

---

## 16. Player Death

A player dies when their HP reaches 0.

While dead:

- the player cannot move,
- attack,
- heal,
- or otherwise take game actions.

There is no timed automatic resurrection.

A dead player returns to play only through:

1. immediate Channel Points resurrection, or
2. another living player reaching the next floor.

---

## 17. Channel Points Resurrection

A dead player may redeem the configured Twitch Channel Points custom reward to resurrect immediately during the current floor.

Upon successful Channel Points redemption:

- the player's dead state is removed,
- the player returns to active play on the current floor,
- and the player may participate in subsequent Player Phases.

The broadcaster configures the reward cost in Twitch. Twungeon identifies the reward by its stable reward ID and does not duplicate or override its cost in domain code.

Bits and Cheers are outside the MVP and must not trigger game-state changes.

---

## 18. Total Party Wipe

If every active participating player is dead before any player reaches the exit:

**The run resets.**

On reset:

1. The floor counter returns to Floor 1.
2. A new starting floor is generated.
3. All participating players return alive.
4. Player HP returns to full.
5. Player self-heals refresh.
6. A new Goblin Guard is generated.

---

## 19. Minimal Player State

The MVP must maintain enough authoritative player state to support:

- Twitch user ID,
- Twitch chat identity,
- Twitch Extension identity,
- verified chat-to-Extension identity binding,
- follower eligibility,
- one character per Twitch user,
- current HP,
- alive/dead state,
- current AP,
- AutoGuard,
- self-heal availability,
- current floor participation,
- and reconnect/refresh handling.

A browser refresh or temporary connection interruption must not create duplicate characters.

The authoritative game account for a character must remain tied to the same Twitch user ID across chat commands, Extension controls, reconnects, and resurrection events.

---

## 20. Twitch Integration Setup and Documentation

A documented Twitch integration setup is an explicit MVP deliverable.

A developer/operator starting from a clean Twungeon checkout must be able to connect the MVP to a Twitch channel using the repository documentation without relying on undocumented knowledge from the original developer.

The setup documentation must cover at minimum:

- required software and dependencies,
- creating and configuring the Twitch developer application,
- creating and configuring the Twitch Extension,
- required authentication and authorization configuration,
- required Twitch scopes,
- Twurple configuration,
- EventSub/chat integration used by the MVP,
- broadcaster/channel identifiers,
- environment variables and configuration files,
- backend and Extension URLs,
- callback/webhook or WebSocket configuration as applicable,
- HTTPS or public endpoint requirements where applicable,
- follower eligibility verification,
- receiving and processing `!spawn`,
- chat-to-Extension Twitch identity binding,
- Channel Points custom reward and redemption EventSub setup,
- separation and protection of secrets,
- local/development testing,
- live-channel testing,
- startup procedure,
- verification that Twitch events are reaching Twungeon,
- and troubleshooting common authentication, EventSub, Extension, identity-binding, and configuration failures.

### 20.1 Setup Acceptance Criterion

The Twitch integration documentation passes the MVP requirement when:

> A clean installation can be connected to a Twitch channel by following the documented procedure without requiring configuration knowledge that exists only in the developer's head.

---

## 21. MVP Technical Direction

The initial proof of concept is expected to use:

- **RPGJS** for the prototype game environment,
- **Twurple** for Twitch integration,
- and a **Twitch Extension** as the player controller.

These technologies are implementation choices for the prototype rather than permanent product requirements.

The MVP should avoid unnecessarily coupling unique Twungeon game logic to RPGJS so that the game system can later be replaced with a custom implementation if the concept is validated.

---

## 22. Explicit MVP Non-Goals

The following are intentionally deferred beyond the MVP:

- Subscriber perks
- Production-quality retro pixel art
- Old-school RPG stream framing
- In-game chat
- `!say`
- Speech bubbles
- Ray-cast vision
- Fog of war
- Multiple player classes
- Healing other players
- Multiple enemy types
- Advanced enemy AI
- Inventory
- Loot
- Equipment
- Character progression
- Experience points
- Skills or skill trees
- Bosses
- Complex procedural dungeon generation
- Difficulty balancing
- Anti-exploit systems
- Competitive balancing
- Sophisticated moderation systems
- Long-term persistence
- Leaderboards
- Achievements
- Guilds or parties
- Economy systems

These features may be considered for version 1.0 or later only after the MVP validates the core experience.


The three-section structural layout and running action log are MVP requirements. Final art direction, production styling, and player-to-player in-game chat are not.

---

## 23. MVP Success Criteria

The MVP is successful if it demonstrates that:

1. Twungeon can be installed from a clean checkout using documented dependencies and startup instructions.
2. Twitch credentials, identifiers, URLs, and secrets are externalized and not hard-coded into source.
3. A clean Twungeon installation can be connected to a Twitch channel using the documented setup procedure.
4. Twungeon successfully receives the Twitch events and chat activity required by the MVP.
5. The Twitch Extension loads and communicates with the Twungeon backend.
6. The stream-facing game view presents the three-section MVP layout: control/status area, main game area, and running action log.
7. With zero active players, the dungeon enters dormant mode, stops advancing turns, and displays the `Type !spawn to spawn in the Twungeon!` banner.
8. A Twitch follower can intentionally join with `!spawn`.
9. A non-follower cannot spawn a player character.
10. Duplicate spawning for the same Twitch user is prevented.
11. The Twitch identity that issues `!spawn` is correctly bound to the same authenticated Twitch identity operating the Extension controls.
12. Extension controls cannot operate another viewer's character.
13. Multiple viewers can control separate characters in the same dungeon.
14. Twitch Extension commands reliably control movement and actions.
15. The Player Phase / Enemy Phase cycle functions correctly.
16. The Player Phase timer scales at 25 seconds per living player and caps at 120 seconds.
17. The Player Phase ends early when all living players finish.
18. AP, AutoGuard, attacks, healing, HP, and death interact correctly.
19. The action log accurately reports significant game actions and state changes.
20. The Goblin can guard, aggro, pursue, attack, return, and remain behind on floor transition.
21. Two-room floors can be generated repeatedly with varying room sizes, positions, and navigable connections.
22. A surviving player can reach the exit without necessarily killing the Goblin and advance the entire group.
23. Dead players return when the floor advances.
24. A player who died on the current floor cannot bypass death by using `!spawn`.
25. The configured Channel Points reward can resurrect the correct dead player during the current floor.
26. A total-party wipe resets the run to Floor 1.
27. Zero active players is distinguished from a total-party wipe.
28. An eligible follower who has not died on the current floor can `!spawn` into an otherwise empty current floor.
29. Refreshes and temporary disconnects do not create duplicate characters or corrupt critical identity/game state.
30. The complete loop can repeat across multiple floors without breaking Twitch integration, turns, player state, Goblin state, floor generation, or the action log.
31. A real Twitch viewer can arrive knowing nothing, watch first, follow, type `!spawn`, discover the controls, and participate without developer intervention.
32. The setup documentation includes sufficient troubleshooting to diagnose common Twitch authentication, EventSub, Extension, identity-binding, and configuration failures.
33. The end-to-end prototype provides enough real viewer feedback to determine whether the Twitch-controlled shared dungeon concept is worth expanding.

The MVP does not need to be balanced, production-polished, visually final, or resistant to every exploit.

The primary question is:

> **Does the Twitch-controlled shared dungeon loop work well enough to justify building Twungeon into a full game?**