diff --git a/docs/reference.txt b/docs/reference.txt new file mode 100644 index 0000000..95d99be --- /dev/null +++ b/docs/reference.txt @@ -0,0 +1,61 @@ +slaywithfriends quick reference +(text version of board game Reference.png) + +================================ +COMBAT ROUND +================================ + +PLAYER TURN + 1. start of turn + - reset to 3 energy, 0 block + - draw 5 cards + - roll die + - resolve start-of-turn abilities + 2. action phase + - discuss with team + - play cards, use potions + 3. end of turn + - resolve end-of-turn effects + - discard hand + +ENEMY TURN + 1. remove enemy block + 2. enemy actions resolve + 3. advance action cubes + +================================ +ICONS +================================ + + /\ hit - deals damage + () block - prevents damage + /\+1 deal +1 damage on all hits + /\x2 deal 2x damage on all hits in next attack, + then remove one vulnerable token + /\-1 deal -1 damage on all hits, + then remove one weak token + + vulnerable vs weak: + when a vulnerable target is attacked by a weak attacker, + they cancel each other out and one of both tokens is removed + + * area of effect - affects all enemies in a row and the boss. + on enemy actions, it affects all players. + + [gem] energy - used to play cards + colors: red (ironclad), green (silent), + blue (defect), purple (watcher) + + [chest] reveal 3 card rewards. add 1 to your deck or skip. + [star] reveal 3 rare rewards. add 1 to your deck or skip. + +================================ +MAP NODES +================================ + + enemies put a die in each player's row + elite put a cube in the bottom row + event draw a ? + merchant flip this board over + treasure each player gains a relic + campfire [rest] heal 3 hp, or [smith] upgrade a card diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..efe82b8 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,198 @@ +# slaywithfriends roadmap + +overall progress tracker. references existing plans and design docs. + +key docs: +- docs/plans/2026-02-23-single-combat-plan.md (implementation plan) +- docs/plans/2026-02-23-single-combat-design.md (design decisions) +- docs/rules-web-mvp.md (what we're building toward) +- docs/rules-canon.md (board game source of truth) +- docs/rules-web-delta.md (known differences) + +--- + +## phase 0: foundation [done] + +project scaffold, core engine, first playable encounter. + +- [x] bun + biome project setup +- [x] card data module (cards.js, starter deck) +- [x] state module (combat init, draw, play, end turn) +- [x] effect resolver (hit, block, status, draw, lose_hp) +- [x] die roll + enemy action resolver +- [x] combat orchestration (turn flow, win/loss) +- [x] html shell + css layout + dev server +- [x] render module (state to dom) +- [x] main module (event handling, game loop) +- [x] ironclad starter card image mapping + +## phase 1: data pipeline [in progress] + +extract all board game data into structured json. + +branch: data-pipeline-merge-and-assets +- [x] extract ironclad cards from board game sheets +- [x] extract silent cards +- [x] extract defect cards +- [ ] extract watcher cards (in progress - 8/~120 done) +- [x] extract colorless cards +- [x] merge per-character files into unified cards.json (410 cards) +- [x] map card images: ironclad (118), silent (108), defect (106), watcher (8) +- [x] extract enemy data (57 enemies across acts 1-4) +- [x] switch cards.js to load full cards.json +- [x] add data validation tests (cards + enemies schema) +- [ ] 70 cards still missing image paths (28 ironclad, 20 silent, 22 defect) +- [ ] potion data extraction +- [ ] relic data extraction + +## phase 2: multiplayer state model [in progress] + +restructure engine for multiple players and enemies. + +branch: engine-multiplayer-state +- [x] indexed players[] and enemies[] arrays +- [x] backward-compat aliases for single-player code +- [x] getEntity/setEntity abstraction in effects +- [x] per-player draw/play/endTurn +- [x] per-enemy combat resolution +- [x] fix draw effect player index bug +- [x] fix lose_hp semantics (damages caster) +- [x] playersReady duplicate guard +- [x] refactor playCard to options-based API +- [x] enemy instanceId for multi-enemy encounters +- [ ] enemy targeting logic (currently always player 0) +- [ ] turn order for simultaneous play + +## phase 3: board game assets + ui + +use board game visual assets for an authentic feel. + +### icons (manual extraction needed - jared doing this) +the Reference.png has all the game icons. plan: +- [ ] extract individual icons from reference card (jared, manual) +- [ ] try svg versions of icons +- [ ] evaluate emoji as slottable icon alternatives +- [ ] text version of reference card for image-free mode + (see docs/reference.txt) + +### board game art for ui +StS_BG_assets/ has a wealth of material: +- [ ] player boards (Player_Board_Ironclad.png etc) - character select / stats +- [ ] playmats (Playmat.jpg, per-character variants) - combat background +- [ ] boss art (front + back, normal + A9 variants) - encounter screens +- [ ] enemy/elite card sheets - could crop individual enemy art +- [ ] map tiles + tokens - for map navigation screen +- [ ] hp tracker (HP_Tracker.png) - compact tens/ones component +- [ ] status tokens (Token_Vulnerable.png etc) - inline status display +- [ ] potion sheet (Potions.png) - potion inventory +- [ ] relic sheets (Relics_Common.png, Relics_Boss.png) +- [ ] shop image (Shop.png) - merchant screen +- [ ] card back (Cards_Back.png) - draw pile / face-down cards +- [ ] mini character portraits (Mini_Ironclad.png etc) - player indicators + +### card images +- [ ] decide: crop individual cards from sheets vs use video game card images +- [ ] or: combine all into single spritesheet for efficient loading +- [ ] image-free fallback mode (text + icons only) + +## phase 4: full combat + +complete combat mechanics per rules-web-mvp.md. + +- [ ] all keywords: exhaust, ethereal, retain, scry, unplayable +- [ ] area of effect (single row + boss) +- [ ] multi-hit with correct token consumption +- [ ] poison mechanic (max 30 across all enemies) +- [ ] start-of-turn / end-of-turn trigger system +- [ ] status cards (dazed, slime, burn, wound, void) +- [ ] potion system (max 3, use/discard flow) +- [ ] combat log (scrollable history of actions) + +## phase 5: character mechanics + +each character's unique systems. + +- [ ] ironclad: strength interactions, heal 1 hp end of combat +- [ ] silent: shiv generation, poison limits/behavior +- [ ] defect: orb channel/end-of-turn/evoke +- [ ] watcher: neutral/calm/wrath stances + miracle tokens + +## phase 6: map + progression + +between-combat game flow. + +- [ ] map generation (acts 1-3 structure) +- [ ] room types: encounter, elite, event, campfire, treasure, merchant, boss +- [ ] deck building / card reward selection +- [ ] upgraded card rewards, rare rewards +- [ ] campfire: rest (heal) / smith (upgrade) +- [ ] merchant: buy cards, remove cards, buy potions/relics +- [ ] events (act-specific event decks) +- [ ] relic system +- [ ] act transitions +- [ ] neow bonuses (run start) + +## phase 7: multiplayer + +the "with friends" part. + +- [ ] websocket server (bun serve) +- [ ] lobby/room creation +- [ ] simultaneous play during player turn +- [ ] row-based enemy targeting across players +- [ ] shared combat state sync +- [ ] reconnection handling +- [ ] spectator mode + +## phase 8: polish + +- [ ] animations (card play, damage, block, status) +- [ ] sound effects +- [ ] mobile touch optimization +- [ ] save/load (persist run state) +- [ ] ascension levels (A1-A20) +- [ ] act 4 (corrupt heart) +- [ ] daily climb mode + +--- + +## asset inventory (StS_BG_assets/) + +game state / reference: +- Reference.png - combat flow + icon glossary + map nodes +- HP_Tracker.png - tens/ones hp dial +- Ascension_Reference.png - ascension level modifiers +- Kindling.png / Kindling_Back.png - campfire resource + +per-character: +- Player_Board_{character}.png - stats/ability board +- Playmat_{character}.png (+ Playmat.jpg generic) +- Mini_{character}.png - small portrait +- Cards_{character}.png / _Rare.png / _Start.png + upgraded variants + +enemies/bosses: +- Enemies_Act{1-3}.png + _Back.png (+ Act1_First_Back.png) +- Elites_Act{1-3}.png + _Back.png +- Boss_Act{1-4}_{name}.png + variants (A9, Back, Summon) +- Summons_Act{1-3}.png + _Back.png + +map: +- Map.png, Map_Act{1-3}.png +- Map_Token_{type}.png (Back, Camp, Elite, Empty, Encounter, Enemy, Shop) + +tokens: +- Token_Block_5.png, Token_Gold_{1,5}.png +- Token_Poison.png, Token_Poison_{5,10}.png +- Token_Strength.png, Token_Strength_5.png +- Token_Vulnerable.png, Token_Weak.png +- Token_Shield.png, Token_Shiv.png, Token_Miracle.png +- Status_Dazed.png, Status_Slime_Burn.png + +other: +- Cards_Back.png, Cards_Colorless.png + upgraded +- Curse.png, Curse_A5.png +- Events.png, Events_Act{1-3}.png + _Back.png +- Neows_Blessing.png + _Back.png +- Potions.png + _Back.png +- Relics_Common.png, Relics_Boss.png + _Back variants +- Shop.png diff --git a/docs/rules.md b/docs/rules.md index b42a9b0..ce1719e 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -1,7 +1,15 @@ -# rules docs index +# docs index Use these files by intent: +- `docs/roadmap.md` + - Overall project progress tracker. + - References all plans, tracks what's done and what's next. + +- `docs/reference.txt` + - Text version of the board game Reference card. + - Combat flow, icon glossary, map node types. + - `docs/rules-canon.md` - Canonical rules reference based on `STS_KS_Rulebook.pdf`. - Use for correctness decisions. @@ -16,3 +24,9 @@ Use these files by intent: - `docs/rules-legacy.md` - Previous condensed rules writeup kept for historical reference. + +- `docs/plans/2026-02-23-single-combat-plan.md` + - Step-by-step implementation plan for first playable encounter. + +- `docs/plans/2026-02-23-single-combat-design.md` + - Design decisions for single combat slice.