# 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