182 lines
5.1 KiB
Markdown
182 lines
5.1 KiB
Markdown
# single combat encounter - design doc
|
|
|
|
first playable slice of slaywithfriends. one ironclad player vs one
|
|
enemy. proves the core card engine works.
|
|
|
|
## decisions
|
|
|
|
- rendering: html/css with card images (no canvas)
|
|
- framework: none. vanilla js, es modules, bun serve
|
|
- networking: client-only. all state in browser
|
|
- character: ironclad (simplest mechanics)
|
|
- interaction: two-tap (select card, tap target)
|
|
- mobile: design for 375px baseline, scales up naturally
|
|
|
|
## state model
|
|
|
|
single object drives everything. pure functions produce new state.
|
|
nothing mutates directly.
|
|
|
|
state = {
|
|
player: {
|
|
hp, maxHp,
|
|
energy, maxEnergy,
|
|
block,
|
|
strength,
|
|
drawPile: [...cardIds],
|
|
hand: [...cardIds],
|
|
discardPile: [...cardIds],
|
|
exhaustPile: [...cardIds],
|
|
powers: [...cardIds],
|
|
},
|
|
enemy: {
|
|
id, name, hp, maxHp, block,
|
|
strength, vulnerable, weak,
|
|
action,
|
|
actionTrack: [...],
|
|
trackPosition,
|
|
},
|
|
combat: {
|
|
turn,
|
|
phase: 'player_turn' | 'enemy_turn' | 'rewards' | 'ended',
|
|
dieResult,
|
|
selectedCard,
|
|
log: [...],
|
|
}
|
|
}
|
|
|
|
## card data schema
|
|
|
|
cards are json entries keyed by id. effects are typed arrays.
|
|
|
|
{
|
|
"strike_r": {
|
|
"name": "Strike",
|
|
"cost": 1,
|
|
"type": "attack",
|
|
"effects": [{"type": "hit", "value": 6}],
|
|
"image": "assets/images/ironclad/starter/0.png",
|
|
"keywords": [],
|
|
"description": "Deal 6 damage.",
|
|
"upgraded": "strike_r+"
|
|
}
|
|
}
|
|
|
|
effect types for first slice: hit, block, draw, strength, vulnerable,
|
|
weak, exhaust, lose_hp.
|
|
|
|
## enemy data schema
|
|
|
|
{
|
|
"jaw_worm": {
|
|
"name": "Jaw Worm",
|
|
"hp": 6,
|
|
"actionType": "die",
|
|
"actions": {
|
|
"1": {"intent": "attack", "effects": [{"type": "hit", "value": 3}]},
|
|
...
|
|
}
|
|
}
|
|
}
|
|
|
|
three action types: single (same every turn), die (keyed to die roll),
|
|
cube (ordered list with advancing pointer, gray actions don't repeat).
|
|
|
|
## rendering layout
|
|
|
|
three vertical zones:
|
|
|
|
enemy zone (~40%) enemy art, hp bar, block, status tokens, intent
|
|
info bar (fixed) energy pips, hp bar, block shield, strength, pile counts
|
|
hand (~35%) cards fan out, overlap if many, selected card lifts
|
|
|
|
pile overlays: tap draw/discard count to see scrollable card grid.
|
|
|
|
## two-tap interaction
|
|
|
|
1. tap card in hand - it lifts and highlights
|
|
2. enemy zone becomes valid target (highlighted border)
|
|
3. skills that don't need a target auto-play
|
|
4. tap enemy - card plays, effects resolve, card animates to discard
|
|
5. not enough energy - card shakes and drops back
|
|
6. tap selected card again to deselect
|
|
|
|
## combat loop
|
|
|
|
player turn:
|
|
1. reset energy to 3, block to 0
|
|
2. draw 5 cards (shuffle discard into draw if needed)
|
|
3. roll die (1-6), determines enemy intent
|
|
4. resolve start-of-turn triggers
|
|
5. play phase - player acts freely
|
|
6. "end turn" button ends play phase
|
|
7. end-of-turn triggers, discard remaining hand
|
|
|
|
enemy turn (auto-resolves):
|
|
1. remove enemy block
|
|
2. enemy executes action
|
|
3. advance cube-action pointer if applicable
|
|
4. brief pause (~1s) for player to read
|
|
|
|
combat ends when enemy hp hits 0 (victory) or player hp hits 0 (defeat).
|
|
|
|
## damage formula
|
|
|
|
1. start with base hit value
|
|
2. add attacker strength (+1 per token)
|
|
3. if target vulnerable, double result
|
|
4. if attacker weak, subtract 1
|
|
5. weak AND vulnerable cancel out - skip both
|
|
6. subtract target block, remainder hits hp
|
|
7. consume 1 vulnerable from target after attack
|
|
8. consume 1 weak from attacker after attack
|
|
9. multi-hit: loop N times, consume tokens only after all hits
|
|
10. aoe/multi-hit: only 1 weak consumed total
|
|
|
|
## enemy ai
|
|
|
|
data-driven. each enemy's action is an effects array resolved the
|
|
same way as card effects. intent displayed as icon + number after
|
|
die roll so player can plan.
|
|
|
|
## project structure
|
|
|
|
slaywithfriends/
|
|
index.html
|
|
style.css
|
|
src/
|
|
main.js entry point, init, render loop
|
|
state.js state creation, pure action functions
|
|
effects.js effect resolver
|
|
combat.js turn flow orchestration
|
|
enemy-ai.js resolve enemy actions
|
|
render.js state to dom
|
|
cards.js load/query card data
|
|
enemies.js load/query enemy data
|
|
die.js die roll
|
|
data/
|
|
cards.json card database
|
|
enemies.json enemy database
|
|
potions.json potion database
|
|
relics.json relic database
|
|
assets/ video game card images
|
|
StS_BG_assets/ board game assets
|
|
docs/ rules and plans
|
|
|
|
## out of scope
|
|
|
|
- map / room navigation
|
|
- deck building / rewards / card selection
|
|
- merchant / campfire / events
|
|
- potions and relics
|
|
- multiplayer / networking
|
|
- persistent state / save / load
|
|
- sound
|
|
- ironclad passive (heal 1 hp end of combat)
|
|
- tutorial
|
|
|
|
## data pipeline
|
|
|
|
board game card sheet images being extracted to json by agent.
|
|
video game wiki data (wiki.gg Module:Cards/data) available as
|
|
secondary reference. board game values are source of truth.
|