Document Twungeon MVP and initialize Labyricorn publishing

2026-08-17 00:16:57 -07:00
commit d67d9fc523
5 changed files with 798 additions and 0 deletions
@@ -0,0 +1,11 @@
 # Labyricorn project publishing
 This repository owns the public project page and development log for Twungeon.
 - `.labyricorn/project/contents.lr` is the project exhibition record.
 - `.labyricorn/devlog/contents.lr` is the development-log index.
 - Each directory below `.labyricorn/devlog/` is one chronological entry.
 The project is currently in pre-development. The PRD and MVP definition are
 complete; future work should add dated devlog entries as the project moves
 through planning, implementation, testing, release, and maintenance.
@@ -0,0 +1,8 @@
 _model: devlog
 ---
 schema_version: 1
 ---
 title: Twungeon development log
 ---
 summary: The public record of Twungeon from pre-development through MVP delivery and beyond.
@@ -0,0 +1,51 @@
 _model: devlog-entry
 ---
 schema_version: 1
 ---
 title: Twungeon begins with a shared design conversation
 ---
 date: 2026-08-17
 ---
 author: ChatGPT 5.6 Sol High Reasoning and Christopher Chambers
 ---
 summary: An extensive design conversation between ChatGPT 5.6 Sol High Reasoning and Labyricorn (Christopher Chambers) shaped the Twungeon concept, narrowed its MVP, and produced the current product requirements document.
 ---
 tags: pre-development, PRD, MVP, planning, documentation, game design, Twitch, architecture
 ---
 body:
 Twungeon's first phase was an extensive design conversation between ChatGPT 5.6
 Sol High Reasoning and Labyricorn (Christopher Chambers). The conversation
 turned an early game idea into a testable product boundary: a shared dungeon
 where Twitch viewers watch the stream, join with `!spawn`, and control their
 own characters through a Twitch Extension.
 The resulting MVP is intentionally a proof of the social interaction loop. A
 party of viewers receives two action points per player phase and can move,
 attack, heal, or pass. One Goblin Guard protects the exit on a small,
 procedurally varied two-room floor. Players may fight it or run past it. Death
 matters for the current floor, Bits can provide an immediate resurrection, and
 reaching the exit brings the party forward while a total-party wipe resets the
 run.
 Several design decisions protect the experiment from premature complexity. The
 game remains dormant rather than resetting when no players are active. Twitch
 chat identity and Extension identity must resolve to the same stable Twitch
 user ID. The stream view needs only a temporary but understandable three-part
 layout, including a chronological action log. Balance, production art,
 progression, multiple classes, advanced enemies, anti-exploit systems, and
 long-term persistence are explicitly deferred.
 The conversation also made operator readiness part of the MVP. A clean checkout
 must be connectable to a Twitch channel using documented dependencies,
 credentials, Extension configuration, EventSub/chat setup, follower checks,
 identity binding, Bits events, startup steps, and troubleshooting guidance.
 The technical direction is RPGJS, Twurple, and a Twitch Extension, while the
 game rules should remain portable enough to survive a later engine change.
 The complete boundary and its 33 success criteria are recorded in the
 [current Twungeon MVP PRD](https://git.labyricorn.com/Labyricorn/Twungeon/blob/main/Twungeon_MVP_PRD_Current.md).
 This entry marks the end of product definition, not the beginning of
 implementation. Future devlog entries will record technical planning, build
 phases, validation evidence, scope changes, and what is learned from real
 viewers.
@@ -0,0 +1,52 @@
 _model: project
 ---
 schema_version: 1
 ---
 project_id: twungeon
 ---
 title: Twungeon
 ---
 summary: A Twitch-controlled cooperative dungeon game where viewers share a live world, control individual characters, and discover whether the core loop is worth building into a full game.
 ---
 status: active
 ---
 started: 2026-08-17
 ---
 author: Christopher Chambers
 ---
 repository_url: https://git.labyricorn.com/Labyricorn/Twungeon
 ---
 default_branch: main
 ---
 tags: Twitch, Twitch Extension, RPGJS, Twurple, TypeScript, game design, pre-development, PRD, MVP, planning, architecture, documentation
 ---
 body:
 Twungeon is a Twitch-controlled cooperative dungeon game. Viewers watch a
 shared dungeon on the stream while controlling their own characters through a
 Twitch Extension. Followers join intentionally with `!spawn`, take turns using
 simple action points, fight or evade a Goblin Guard, and cooperate to reach the
 exit.
 The MVP is designed to prove the complete interaction loop with real Twitch
 viewers: eligibility, identity binding, spawning, movement, combat, healing,
 death, Bits resurrection, floor advancement, and total-party reset. It uses a
 deliberately small two-room floor with one Goblin Guard so the project can test
 the social game idea before investing in balance, polish, progression, or
 production art.
 The stream-facing experience has three required regions: a compact
 control/status area, the shared game view, and a running action log. When no
 players are active, the current floor remains loaded in a dormant state and
 invites an eligible follower to type `!spawn`.
 The initial technical direction is RPGJS for the prototype game environment,
 Twurple for Twitch integration, and a Twitch Extension for player controls.
 The design keeps Twungeon's game rules separate from RPGJS where practical so
 the prototype can be replaced without discarding the validated concept.
 The current source of truth is the
 [Twungeon MVP Product Requirements Document](https://git.labyricorn.com/Labyricorn/Twungeon/blob/main/Twungeon_MVP_PRD_Current.md).
 The project is in pre-development: the PRD and MVP definition are complete,
 and this repository will document the transition through technical planning,
 implementation, testing, release preparation, and maintenance.
@@ -0,0 +1,676 @@
 # Twungeon MVP Product Requirements Document
 ## 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 Bits,
 - 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 Bits 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,
 - Bits 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 Bits resurrection, or
 2. another living player reaching the next floor.
 ---
 ## 17. Bits Resurrection
 A dead player may use the Twitch Bits mechanism to resurrect immediately during the current floor.
 Upon successful Bits resurrection:
 - 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 exact Bits price is not required to be finalized before implementation of the core MVP.
 ---
 ## 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,
 - Bits resurrection event 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. Bits 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?**