Improve the rule docs

2026-02-23 17:14:53 -05:00 · 2026-02-23 17:14:53 -05:00 · 759779b319
commit 759779b319
parent 26958ac195
4 changed files with 257 additions and 414 deletions
--- a/docs/rules-canon.md
+++ b/docs/rules-canon.md
@ -0,0 +1,64 @@
 # slay the spire board game rules (canonical reference)
 This file is the canonical mechanical reference for this project.
 Source: `STS_KS_Rulebook.pdf`.
 Use this for adjudicating rule disputes and deciding implementation behavior.
 For a smaller implementation spec, see `docs/rules-web-mvp.md`.
 For intentional product deviations, see `docs/rules-web-delta.md`.
 ## Canonical clarifications (high-value)
 These points are called out explicitly because they are commonly simplified or misremembered.
 1. Setup shuffle behavior
 - Do not shuffle Summons, Daze, or Status decks during setup.
 - Keep 1st Encounter cards separate from the main Encounter deck.
 2. Act transition behavior
 - Replace act-specific decks with next-Act versions.
 - Summons also use the next-Act deck and remain unshuffled.
 - Heal to max HP at start of Act II/III (and Act IV when used).
 - Shuffle each player's card rewards deck with skipped cards; do not shuffle rares.
 3. Combat ordering
 - One shared player turn (simultaneous player actions), then enemy turn.
 - Die is rolled once per round and drives all die-based effects that round.
 - Enemy action order: highest row to lowest row, left to right; bosses act last.
 - Enemy Block is removed at start of enemy turn.
 4. Reward and inventory constraints
 - Players may evaluate combat rewards with full knowledge before finalizing choices.
 - Potions are limited; overflow requires skip/pass/use-discard handling.
 - Potions are the only tradeable item type outside combat.
 5. Targeting and damage semantics
 - Player AoE targets one row and always includes boss if present.
 - "ALL enemies" targets every row plus boss.
 - Weak and Vulnerable interact via cancellation rule in canon reference.
 - "Lose HP" is not damage and is not prevented by Block.
 6. Playing copies
 - Copies are free.
 - X-cost copies use original X value.
 - Copies resolve before original card resolves.
 - Only one "play multiple times" effect can apply to a given played card; additional effects wait for next valid card.
 7. Cross-character mechanics
 - Transforming off-class/colorless cards still draws from your own card rewards deck.
 - Golden Ticket revealed from another character uses that character's rare deck.
 - If stances/orbs are gained cross-character, Prismatic Shard rules apply.
 8. Golden rule
 - If card text contradicts general rules, card text takes precedence.
 ## Scope notes
 The official rulebook also includes:
 - FAQ and specific card interactions
 - Unlock progression and Ascension ladder
 - Daily Climb/custom modifiers
 - Act IV keys and quick-start tables
 - Optional modes
 All are canonical unless explicitly listed as product deltas in `docs/rules-web-delta.md`.
--- a/docs/rules-web-delta.md
+++ b/docs/rules-web-delta.md
@ -0,0 +1,79 @@
 # slaywithfriends rules delta (canon vs web)
 This file records intentional and current differences between:
 - Canon: `docs/rules-canon.md`
 - Web implementation target: `docs/rules-web-mvp.md`
 Use statuses:
 - `implemented` - enforced in app
 - `planned` - accepted but not yet built
 - `deferred` - intentionally skipped for now
 ## Current deltas
 1. Setup shuffle details for non-combat decks
 status: planned
 canon: Summons, Daze, and Status are not shuffled in setup.
 web: MVP setup may simplify by treating some decks uniformly.
 impact: low if card order is random anyway, but should be corrected for parity.
 2. Act transition deck swapping granularity
 status: planned
 canon: only act-specific decks are replaced; relic/potion/boss-relic handling differs.
 web: MVP may use a simplified deck replacement step.
 impact: medium; affects progression balance and content pools.
 3. Summons transition behavior between Acts
 status: planned
 canon: switch to next Act's Summons deck (not shuffled).
 web: currently documented ambiguously in prior markdown.
 impact: medium; can change encounter difficulty distribution.
 4. Playing Copies edge-case constraints
 status: planned
 canon: X-cost copies use original X; only one multi-play effect can apply per card at a time.
 web: MVP doc currently describes the basic copy model only.
 impact: medium-high for combo correctness.
 5. Cross-character Stance/Orb caveat (Prismatic Shard)
 status: planned
 canon: additional restrictions apply (including Watcher stance caveat).
 web: simplified handling.
 impact: low-medium; niche but rules-visible.
 6. Status card mode specifics
 status: planned
 canon: Status card behavior depends on icon mode from source enemy.
 web: MVP currently treats status at a higher level.
 impact: medium for enemy fidelity.
 7. Potion limit overflow options
 status: planned
 canon: when at potion cap, player must skip/pass/use-discard before gaining.
 web: MVP requires explicit UI decision flow.
 impact: medium UX and correctness.
 8. Act IV key acquisition details
 status: deferred
 canon: includes Burning Elite token replacement, Sapphire reveal/discard flow, and key-specific setup effects.
 web: not required for first playable Act loop.
 impact: low for Act I MVP, high for Act IV parity.
 9. Daily Climb and custom modifiers
 status: deferred
 canon: full positive/negative modifier system.
 web: out of MVP scope.
 impact: none for base mode.
 10. Achievements and full FAQ interactions
 status: deferred
 canon: includes broad edge-case rulings and achievement list.
 web: omitted in MVP.
 impact: none on base gameplay if core engine is correct.
 ## Promotion criteria (move planned -> implemented)
 A delta can be marked `implemented` when:
 - it is represented in rules docs,
 - enforced in engine logic,
 - and covered by at least one deterministic test.
--- a/docs/rules-web-mvp.md
+++ b/docs/rules-web-mvp.md
@ -0,0 +1,101 @@
 # slaywithfriends web rules (MVP)
 This document defines the rules currently enforced by the web app.
 It is intentionally smaller than the full board game rulebook.
 Scope: support a complete multiplayer run through at least Act I with
 correct turn order, combat resolution, rewards, and map progression.
 ## Core loop
 - 1-4 players cooperate through map rooms.
 - If any player reaches 0 HP, the run ends in defeat.
 - Clear the Act boss to complete the Act.
 ## Setup
 1. Each player chooses a character and starts with that character's starter deck.
 2. Each player starts with 3 Energy, 0 Block, and max HP.
 3. Prepare decks needed for the selected Act.
 4. Build/reveal the map and place players in starting rows.
 5. Resolve Neow bonuses.
 6. Start first encounter combat.
 ## Map rooms
 - Encounter
 - Elite
 - Event
 - Campfire (Rest/Smith)
 - Treasure
 - Merchant
 - Boss
 ## Combat flow
 ### Player turn
 1. Reset Energy to 3 and Block to 0.
 2. Draw 5 cards.
 3. Roll die once for round-level enemy/relic effects.
 4. Resolve start-of-turn/start-of-combat/die-trigger effects.
 5. Players act simultaneously: play cards, use potions/items, choose targets.
 6. Resolve end-of-turn effects, then discard hand (except retained cards).
 ### Enemy turn
 1. Remove all enemy Block.
 2. Enemies act by row order, then bosses/acts-last enemies.
 3. Advance cube-action enemies.
 ### End of combat
 1. Resolve end-of-combat triggers.
 2. Grant rewards.
 3. Reset decks/boards/tokens according to combat cleanup rules.
 4. Allow row switching before next combat room.
 ## Keywords required for MVP
 - Energy (max 6)
 - Block (player max 20)
 - Strength (max 8)
 - Vulnerable (max 3)
 - Weak (max 3)
 - Poison (max 30 across all enemies)
 - Exhaust
 - Ethereal
 - Retain
 - Scry
 - Unplayable
 - Area of Effect (single row + boss)
 - All Enemies
 - Multi-hit
 ## Reward handling required for MVP
 - Card Reward, Upgraded Card Reward, Rare Reward
 - Potion (max 3) and potion use/discard rules
 - Relic, Boss Relic
 - Gold
 - Remove, Upgrade, Transform
 - Golden Ticket behavior
 ## Character mechanics required for MVP
 - Ironclad: Strength interactions
 - Silent: Shiv + Poison limits/behavior
 - Defect: Orb channel/end-of-turn/evoke behavior
 - Watcher: Neutral/Calm/Wrath + Miracle behavior
 ## Explicitly out of MVP scope
 - Daily Climb mode
 - Achievement tracking
 - Full unlock tree UX
 - Complete FAQ card-by-card interaction coverage
 ## Source of truth
 - Canonical rules: `docs/rules-canon.md`
 - Product deltas: `docs/rules-web-delta.md`
--- a/docs/rules.md
+++ b/docs/rules.md
@ -1,419 +1,18 @@
-# slay the spire: board game rules
+# rules docs index
-cooperative rogue-like deckbuilder for 1-4 players. each act takes 60-90 min.
+Use these files by intent:
 players win by defeating the final boss. if any player hits 0 HP, everyone loses.
---
+- `docs/rules-canon.md`
  - Canonical rules reference based on `STS_KS_Rulebook.pdf`.
  - Use for correctness decisions.
-## overview
+- `docs/rules-web-mvp.md`
  - Implementation rules for first playable web version.
  - Use for current scope and task planning.
- each player picks a character, starts with a simple deck, and improves it
+- `docs/rules-web-delta.md`
-  by adding/removing/upgrading cards throughout the run
+  - Explicit differences between canon and web behavior.
- the party travels up a map, hitting encounters, events, merchants, campfires,
+  - Use to track planned/deferred parity work.
  elites, and a boss at the top
 - the game is divided into acts (I, II, III, optionally IV). you can stop after
  any act and save your progress
-## characters
+- `docs/rules-legacy.md`
-
+  - Previous condensed rules writeup kept for historical reference.
 each character has a unique starter deck, player board, and mechanics.
 **ironclad** (red, easiest) - strength-based fighter with exhaust synergies.
 starts with the most HP. strength (max 8) adds +1 damage per hit.
 **silent** (green, easy) - poison and shiv specialist.
 poison (max 30 across all enemies) deals 1 HP loss per token at end of turn,
 ignoring block. shivs (max 5) are tokens that deal 1 damage each, usable
 anytime you could play a card.
 **defect** (blue, hard) - orb channeler. uses lightning, frost, and dark orbs
 placed in slots on the player board. orbs trigger end-of-turn effects and can
 be evoked for stronger effects. any orb can go in any slot.
 **watcher** (purple, hardest) - stance-based fighter with miracles.
 stances: neutral (no effect), calm (gain 2 energy when leaving), wrath (+1
 damage on all hits, but take 1 damage at end of turn). miracles (max 5)
 are tokens that give 1 energy each, usable anytime.
 ## setup
 1. each player picks a character, takes their player board, starter deck,
   card rewards deck, and rare rewards deck. shuffle the decks.
 2. player board: energy cube at 3, block cube at 0, HP cube at max
 3. prepare shared decks: encounters, elites, summons, events, relics,
   potions, boss relics, daze, status, curses. shuffle each (except summons).
   keep "1st encounter" cards separate from the encounter deck.
 4. randomly choose an act I map board. place it on the table.
 5. shuffle map tokens face-down. dark tokens on dark spaces, light on light.
   flip them all face-up.
 6. place character figures on the lowest open space of the map.
 7. randomly choose an act I boss. place it face-down at the top of the map.
 8. place boot meeple at bottom of map next to the first encounter.
 9. neow's blessing: each player draws 1 neow's blessing card. gain the red
   reward, then choose 1 of the 3 blue rewards.
 10. set up the 1st encounter and start combat.
 ### setup for acts II and III
 - swap all card decks (encounters, elites, events, etc.) for the next act's
  versions. shuffle them. summons deck carries over.
 - new map board, new boss.
 - all players heal to max HP.
 - shuffle your card rewards deck (include any skipped cards). don't shuffle rares.
 ## the map
 move the boot meeple up the map after finishing each room. follow the paths -
 you choose which fork to take. room types:
 **encounter** - fight monsters. 1st encounter uses special "1st encounter"
 cards (one per player row). other encounters draw 1 card per player from the
 encounter deck.
 **elite** - harder fight. 1 elite in the bottom row, with summons in each
 player's row if the elite has them.
 **event** - draw from event deck. options in [yellow brackets] are choices -
 each player picks one independently. "pay" or "give" options require you to
 already have the thing.
 **campfire** - each player independently chooses: rest (heal 3 HP) or smith
 (upgrade a card).
 **treasure** - each player gains a relic.
 **merchant** - place 3 relics and 3 potions on the merchant board. each player
 reveals top 3 of their card rewards. players can buy:
 - items (relics/potions) for their gold cost. top-left relic is on sale (-1 gold).
 - cards: common 2g, uncommon 3g, rare 6g
 - card remove: 3g, once per merchant per player
 - you can spend your gold on another player's purchase.
 **boss** - fight the act boss at the top of the map. beat it to clear the act.
 ## your deck
 ### card types
 - **attack** - deals damage to enemies
 - **skill** - blocks damage and other utility effects
 - **power** - stays in play for the rest of combat (not discarded after playing)
 - **curse** - bad cards added to your deck. can't be transformed.
 - **status / daze** - bad cards added by enemies. removed from your deck at
  end of combat.
 ### card rarity (banner color)
 - starter (gray border) - your starting cards
 - common (gray banner) - 2 copies of each exist
 - uncommon (blue banner)
 - rare (yellow banner)
 ### energy
 energy is used to play cards. pay the cost in the top-left corner.
 max 6 energy. resets to 3 at the start of each turn.
 x-cost cards: spend any amount of energy (including 0), effect scales with
 amount spent.
 ### card piles
 - **draw pile** - shuffle your deck at the start of combat. draw from here.
 - **discard pile** - played cards go here. when draw pile is empty, shuffle
  discard into a new draw pile.
 - **exhaust pile** - exhausted cards go here. can't be used again this combat.
  returned to your deck at end of combat.
 ## combat
 ### combat setup
 **encounters** - 1 enemy per player row.
 **elites** - 1 elite in bottom row. summons (if any) in each player's row,
 to the right of the elite.
 **bosses** - treated as being in ALL rows. placed to the right of the board.
 boss HP scales with player count (listed on boss card).
 enemy HP: put a cube on the starting HP number (yellow outline). enemies
 with 11+ HP use 2 cubes on the HP board.
 ### combat round
 rounds repeat until combat ends. each round = player turn, then enemy turn.
 all players act simultaneously during the player turn.
 #### player turn
 **1. start of turn**
 - reset energy to 3, block to 0
 - draw 5 cards (no max hand size)
 - roll the die (determines enemy actions and relic triggers for this round)
 - resolve start-of-turn abilities (relics, powers, die triggers)
 - start-of-combat abilities trigger only on turn 1
 **2. play phase**
 - play cards, use potions, activate abilities in any order
 - discuss strategy openly (encouraged!)
 - to play a card: pay energy, choose targets, resolve effects top to bottom,
  then discard (or exhaust, or place as power)
 - effects with the area-of-effect symbol hit all enemies in one row AND
  the boss (if present)
 - players can target any enemy, not just ones in their row
 **3. end of turn**
 - end-of-turn abilities trigger
 - discard all remaining cards in hand
 #### enemy turn
 **1. remove enemy block** - all enemies lose their block tokens
 **2. enemy actions** - enemies act row by row, top to bottom, left to right
 within each row. bosses always act last. each enemy takes one action:
 - *single action* - same action every turn
 - *die action* - action depends on the die result rolled during player turn
 - *cube action* - tracks progress down a list. cube slides down each round.
  gray actions at the bottom don't repeat.
 enemies target the player in their row. area-of-effect enemy actions hit
 all players.
 **3. move cube actions** - slide cubes down for any cube-action enemies
 ### end of combat
 triggers when all monsters are dead (unless an on-death ability summons more).
 1. end-of-combat abilities trigger
 2. gain rewards from the enemy card (encounters: from your row's enemy.
   elites/bosses: all players gain rewards)
 3. reset your deck: return powers, discard pile, exhaust pile to your deck.
   remove status/daze cards back to their decks.
 4. reset player board: block and energy to 0. lose all tokens except gold.
   defect removes orbs. watcher enters neutral stance.
 5. clear enemies back to their decks. summons return to summons deck.
 6. players may switch rows before next combat.
 ## rewards
 gain rewards in any order. you may skip any reward. you can look at all
 rewards before making final decisions.
 **card reward** - reveal top 3 of your card rewards deck. add 1 to your deck
 or skip. return unchosen cards to the bottom.
 - golden ticket: when revealed, also reveal top card of your rare rewards.
  add that as an option. return golden ticket to bottom of card rewards.
 **upgraded card reward** - same as card reward but the chosen card is
 immediately upgraded.
 **rare reward** - reveal 3 from your rare rewards deck. add 1 or skip.
 **potion** - draw 1 from potion deck. keep (face-up, in front of you) or skip.
 max 3 potions. single-use items. some potions can be used outside combat.
 **relic** - draw 1 from relic deck. keep (face-up) or skip.
 **boss relic** - reveal 1 per player + 1 (or 3 if solo). each player may
 take one.
 **gold** - gain gold tokens equal to the value shown. spend at merchants or
 events. you can pay for other players' purchases.
 **trading** - potions can be given to other players outside combat.
 nothing else can be traded.
 ## remove, upgrade, transform
 **remove** - take a card out of your deck permanently. keep it in a removed pile.
 **upgrade** - flip a card to its upgraded side (green text). cards are
 double-sided: normal on one side, upgraded on the other.
 **transform** - remove a non-curse card from your deck, then add the top card
 of your card rewards to your deck. if it's a golden ticket, add the top rare
 instead and return the golden ticket to the bottom.
 ## items
 items are small cards kept in front of you.
 **relics** - persistent effects. some have die-triggered abilities.
 some are "once per combat" or "once per room" (flip face-down when used,
 flip back after).
 **boss relics** - same as relics but from the boss relic deck.
 **potions** - single-use. max 3 at a time. some usable outside combat.
 ## keywords and abilities
 **area of effect (AoE)** - affects all enemies in one row, always includes
 the boss.
 **ALL enemies** - targets every enemy in every row, including boss.
 **block (max 20 for players)** - prevents 1 damage per point.
 player block resets at start of player turn. enemy block resets at start
 of enemy turn. does NOT prevent "lose X HP" effects.
 **daze** - bad card placed on top of your draw pile. returns to daze deck
 when exhausted.
 **energy (max 6)** - resource for playing cards. all character energy symbols
 are equivalent.
 **ethereal** - if still in hand at end of turn, it's exhausted.
 **exhaust** - card is removed from play for this combat. goes to exhaust pile.
 returns to your deck at end of combat.
 **hit** - damage icon on cards. hits are affected by vulnerable, weak, and
 strength. "damage" effects (like "lose HP") are NOT hits.
 **multi-hit** - multiple hit icons on one card/action. all hits target the
 same enemy (unless stated otherwise). all are affected equally by strength,
 vulnerable, weak. remove vuln/weak token only after the full multi-hit
 resolves.
 **retain** - card is not discarded at end of turn. cards "forget" they were
 retained once they leave your hand.
 **scry X** - look at top X cards of your draw pile. discard any of them.
 put the rest back on top in the same order.
 **strength (max 8)** - +1 damage on each hit per strength token. enemies
 can also gain strength.
 **unplayable** - can't be played. if an effect tries to play it, discard it
 instead.
 **vulnerable (max 3 per target)** - when attacked, damage from each hit is
 doubled. token removed after the attack resolves. add strength before doubling.
 **weak (max 3 per target)** - each hit in the attack deals -1 damage.
 token removed after the attack. for AoE or multi-hit attacks, only 1 weak
 token is consumed.
 **weak vs vulnerable** - if attacker is weak AND target is vulnerable, the
 effects cancel out. attack is unaffected. remove 1 weak from attacker and
 1 vulnerable from all affected targets.
 **poison (max 30 total across all enemies)** - at end of turn, enemies lose
 1 HP per poison token. ignores block. poison stays until the enemy dies.
 ## triggered abilities
 **on death** - triggers when the enemy with this ability dies.
 **start of turn** - triggers at start of player turn.
 **start of combat** - like start of turn, but only on turn 1.
 **start of next round** - triggers during next player turn's start-of-turn.
 **end of turn** - triggers at end of player turn (not enemy turn).
 **end of combat** - triggers when combat ends.
 **once per combat** - usable once during any player turn. flip item face-down
 when used.
 **once per room** - usable once per combat or event. can affect die results.
 **die relic abilities** - trigger on specific die results at start of turn.
 found on relics and boss relics only.
 ## cards from other characters
 if you get cards from another character:
 - use their tokens the same way (shared token limits)
 - transform: new card comes from YOUR card rewards deck
 - golden tickets from other characters' rewards: rare comes from THAT
  character's rare deck
 - stances and orbs from other characters: gain the prismatic shard special
  relic. start each combat in neutral stance. defect doesn't gain extra orb
  slots this way.
 ## playing copies
 when a card is played multiple times (by an effect), copies are free to play.
 copies can have different targets. copies are affected separately by
 vulnerable, weak, and single-use bonuses. copies can't be copied.
 copies resolve first, then the original goes to discard.
 ## golden rule
 when a card's text contradicts the rules, the card wins.
 ## optional rules
 **the last stand** - if a player dies during a boss fight, other players can
 keep fighting. enemies in the dead player's row target the nearest player
 below (or above if none below). if at least 1 player survives the boss,
 the party wins. if a player dies, you can't continue to the next act.
 **sequential turns** - if simultaneous play doesn't work for your group,
 take turns in order starting from bottom lane (lane 1), going left. die is
 only rolled on the first player's turn. your abilities/triggers only happen
 on your turn.
 **choose your relic** - when gaining relics from elites or treasure in
 multiplayer, reveal relics equal to player count. each player picks one.
 ## act IV (unlockable)
 requires collecting 3 keys during act III:
 - **ruby key** - all players skip actions at a campfire room
 - **sapphire key** - all players skip a relic at an elite or treasure room
 - **emerald key** - defeat a burning elite (replaces one encounter on the map)
 act IV has its own map (on the back of the boss card) and boss.
 ## ascension (difficulty scaling)
 unlocked after beating act II boss (or act III solo). each level adds a
 modifier that stacks with all previous levels:
 1. harder elites (replace with ascension elites)
 2. -1 max HP
 3. harder events (add ascension events)
 4. potion limit reduced to 2
 5. start with ascender's bane curse
 6. heal only 4 HP (not full) after boss in acts II+
 7. harder encounters (replace with ascension encounters + summons)
 8. card removes cost 4g at merchant
 9. lose 1 HP at game start
 10. harder bosses (use ascension boss deck)
 11. harder act IV boss + ascension elites in act IV
 12. even harder elites (replace with ascension 12 elites)
 13. double act III boss (fight a second random boss after the first)
 ## daily climb (optional mode)
 roll die twice, gain one random modifier from each group:
 **positive modifiers:** all star (5 random colorless cards), shiny (5 random
 rares), heirloom (random boss relic), transformed (all card rewards become
 transforms), vintage (encounter card rewards become upgraded card rewards),
 prismatic shard (start with prismatic shard, card rewards pull from
 different characters' decks)
 **negative modifiers:** terminal (lose 1 HP end of combat), insanity
 (transform a random card end of combat), uncertain future (map tokens
 hidden until you land on them), cursed (start with 2 random curses),
 deadly events (lose 2 HP after each event), night terrors (can't rest)
 ## quick start (joining late / starting at act II+)
 use the quick start table to catch up players joining at later acts.
 gives scaling amounts of gold, card rewards, transforms, relics, potions,
 upgrades, and a merchant visit based on starting act.
 ## achievements
 tracked across runs. examples: hit strength limit (8), hit poison limit (30),
 play 7 shivs in one turn, have 7 powers in play, beat act III with each
 character, beat a boss on turn 1, beat act III with a 5-card deck.