diff --git a/docs/rules-canon.md b/docs/rules-canon.md new file mode 100644 index 0000000..34e7e50 --- /dev/null +++ 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`. diff --git a/docs/rules-web-delta.md b/docs/rules-web-delta.md new file mode 100644 index 0000000..e193a7e --- /dev/null +++ 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. diff --git a/docs/rules-web-mvp.md b/docs/rules-web-mvp.md new file mode 100644 index 0000000..be3c7e7 --- /dev/null +++ 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` diff --git a/docs/rules.md b/docs/rules.md index 5e4ef6d..b42a9b0 100644 --- 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. -players win by defeating the final boss. if any player hits 0 HP, everyone loses. +Use these files by intent: ---- +- `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 - by adding/removing/upgrading cards throughout the run -- the party travels up a map, hitting encounters, events, merchants, campfires, - 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 +- `docs/rules-web-delta.md` + - Explicit differences between canon and web behavior. + - Use to track planned/deferred parity work. -## characters - -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. +- `docs/rules-legacy.md` + - Previous condensed rules writeup kept for historical reference.