Add shared bandit effect hooks

docs/card-effect-fields.md

@@ -1,88 +1,102 @@
 # Card Effect Fields
 
-`data/cards.json`의 카드 효과를 공용 데이터 필드로 표현하는 기준 문서입니다.
+This file tracks the shared data fields used by `data/cards.json`.
+The goal is to keep card behavior reusable instead of hardcoding one-off card names.
 
-## 피해 수치
+## Damage
 
-- `damage`: 기본 피해
-- `damagePerOtherHandCard`: 손패의 다른 카드 수만큼 피해 증감
-- `damagePerAttackPlayedThisTurn`: 이번 턴에 사용한 공격 카드 수만큼 피해 증감
-- `damagePerDiscardedThisTurn`: 이번 턴에 버린 카드 수만큼 피해 증감
-- `damagePerSkillInHand`: 손패의 스킬 카드 수만큼 피해 증감
-- `otherHandAtLeast`: 손패의 다른 카드가 이 수 이상일 때 조건 충족
-- `bonusHitsWhenOtherHandAtLeast`: 조건 충족 시 추가 적중 수
+- `damage`: base attack damage
+- `damagePerOtherHandCard`: bonus damage per other card in hand
+- `damagePerAttackPlayedThisTurn`: bonus damage per attack played this turn
+- `damagePerDiscardedThisTurn`: bonus damage per card discarded this turn
+- `damagePerSkillInHand`: bonus damage per skill card in hand
+- `damagePerCardDrawnThisCombat`: bonus damage per card drawn this combat
+- `damagePerTurn`: damage applied at turn start
+- `cardPlayedDamage`: damage when the card is played
+- `cardPlayedRandomDamage`: random damage when the card is played
+- `drawDamage`: damage dealt when a card is drawn
+- `shivDamageBonus`: bonus damage for all Shivs
+- `firstShivDamageBonus`: bonus damage for the first Shiv each turn
+- `attackDamageVsWeakMultiplier`: multiplier when the attack hits Weak targets
 
-## 방어/상태
+## Block and utility
 
-- `block`: 방어도 획득
-- `cardPlayedBlock`: 카드를 사용할 때마다 방어도 획득
-- `blockGainMultiplier`: 이번 턴 동안 얻는 방어도 배수
-- `hits`: 다단히트 횟수
-- `aoe`: 모든 적 대상
-- `pierce`: 방어도 무시
-- `draw`: 즉시 드로우
-- `drawUntilHandSize`: 손패가 지정 장수에 도달할 때까지 드로우
-- `heal`: 즉시 회복
-- `gainEnergy`: 즉시 에너지 획득
-- `strength`: 힘 획득
-- `dex`: 민첩 획득
-- `thorns`: 가시 획득
-- `selfVuln`: 자신에게 취약 부여
+- `block`: gain block
+- `cardPlayedBlock`: gain block whenever a card is played
+- `blockGainMultiplier`: multiplier for block gained this turn
+- `hits`: multi-hit count
+- `aoe`: hit all enemies
+- `pierce`: ignore block
+- `draw`: draw cards immediately
+- `drawUntilHandSize`: draw until hand reaches a target size
+- `drawSkillBlock`: gain block for each Skill drawn
+- `drawPoison`: apply poison when a card is drawn
+- `heal`: heal immediately
+- `gainEnergy`: gain energy immediately
+- `strength`: gain Strength
+- `dex`: gain Dexterity
+- `thorns`: gain Thorns
+- `selfVuln`: apply Vulnerable to self
 
-## 상태이상
+## Status
 
-- `weak`: 약화 부여
-- `vuln`: 취약 부여
-- `poison`: 중독 부여
+- `weak`: apply Weak
+- `vuln`: apply Vulnerable
+- `poison`: apply Poison
+- `poisonHits`: apply poison multiple times
+- `poisonRandomTargets`: spread poison applications across random alive enemies
 
-`poison`은 적 턴 시작 시 피해를 주고 1 감소합니다.
+`poison` deals damage at enemy turn start and then decreases by 1.
 
-## 드로우/버리기
+## Shivs and discard
 
-- `discard`: 손패에서 지정 장수 버리기
-- `discardAll`: 손패 전부 버리기
-- `drawPerDiscarded`: 버린 카드 1장당 추가 드로우
-- `addShiv`: 표창 생성
-- `addShivPerDiscard`: 버린 장수만큼 표창 생성
-- `sly`: 버려질 때 교활 발동
-- `retain`: 턴 종료 시 해당 카드 보존
+- `discard`: discard a chosen number of cards from hand
+- `discardAll`: discard the whole hand
+- `drawPerDiscarded`: draw one extra card per discarded card
+- `addShiv`: create Shiv cards
+- `addShivPerDiscard`: create one Shiv per discarded card
+- `shivRetain`: Shiv cards are retained at end of turn
+- `shivAoe`: Shiv cards hit all enemies for the turn
+- `sly`: trigger on discard
+- `retain`: keep the card at end of turn
 
-## 파워/턴 효과
+## Powers and turn effects
 
 - `powerEffect: "strengthPerTurn"`
 - `powerEffect: "energyPerTurn"`
 - `powerEffect: "blockPerTurn"`
+- `powerEffect: "poisonPerTurn"`
+- `powerEffect: "damagePerTurn"`
 - `powerEffect: "retainOne"`
-- `turnStartShiv`: 턴 시작 시 표창 생성
-- `turnStartDraw`: 턴 시작 시 추가 드로우
-- `turnStartDiscard`: 턴 시작 시 카드 버리기
+- `turnStartShiv`: create Shivs at turn start
+- `turnStartDraw`: draw cards at turn start
+- `turnStartDiscard`: discard cards at turn start
 
-## 다음 턴 예약
+## Next turn planning
 
-- `nextTurnBlock`: 다음 턴 시작 시 방어도 획득
-- `nextTurnDraw`: 다음 턴 시작 시 추가 드로우
-- `nextTurnKeepBlock`: 다음 턴 시작 시 기존 방어도 유지
-- `nextTurnAttackMultiplier`: 다음 턴 공격 피해 배수
-- `nextTurnCopies`: 다음 턴에 손패에서 가져올 복사본 수
-- `nextTurnSelectHandCard`: 현재 손패에서 카드 1장 선택
-- `nextTurnSelectPrompt`: 선택 UI 문구
-- `nextSkillRepeatCount`: 다음 스킬 카드의 효과를 추가 횟수만큼 다시 적용
-- `nextSkillCostZero`: 다음 스킬 카드 비용을 0으로 만듦
-- `skillCostReductionThisTurn`: 이번 턴 스킬 카드 비용을 일정량 감소
+- `nextTurnBlock`: gain block next turn
+- `nextTurnDraw`: draw extra cards next turn
+- `nextTurnKeepBlock`: keep block next turn
+- `nextTurnAttackMultiplier`: attack multiplier next turn
+- `nextTurnCopies`: copy a chosen card next turn
+- `nextTurnSelectHandCard`: choose a card from the current hand for next turn copies
+- `nextTurnSelectPrompt`: prompt text for selection UI
+- `nextSkillRepeatCount`: repeat the next Skill's effect
+- `nextSkillCostZero`: make the next Skill cost 0
+- `skillCostReductionThisTurn`: reduce Skill costs this turn
 
-## 기타
+## Misc
 
-- `innate`: 전투 시작 시 첫 손패에 우선 진입
-- `playableWhenDrawPileEmpty`: 뽑을 카드 더미가 비었을 때만 사용 가능
-- `exhaust`: 사용 후 소멸
-- `unplayable`: 사용 불가
-- `curse`: 저주 카드
-- `token`: 토큰 카드
-- `endTurnDamage`: 턴 종료 시 손패에 있으면 피해
+- `innate`: place the card in the opening hand
+- `playableWhenDrawPileEmpty`: only playable when the draw pile is empty
+- `exhaust`: exhaust after use
+- `unplayable`: cannot be played
+- `curse`: curse card
+- `token`: token card
+- `endTurnDamage`: damage if the card remains in hand at end of turn
 
-## 사용 원칙
-
-- 카드 전용 분기보다 공용 필드를 먼저 쓴다.
-- 같은 효과는 같은 필드로 재사용한다.
-- 새 카드가 같은 패턴이면 먼저 공용 필드를 추가한다.
+## Rules
 
+- Prefer shared fields over card-specific branches.
+- Reuse the same field name for the same behavior.
+- Add a new shared field before adding more special-case card logic.