blacktrigram 0.7.2

package/lib/systems/combat/BalanceSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BalanceSystem.js","names":[],"sources":["../../../src/systems/combat/BalanceSystem.ts"],"sourcesContent":["/**\n * Balance System for managing stability and vulnerability windows.\n *\n * **Korean**: 균형 시스템 (Balance System)\n *\n * Implements physical balance and stability mechanics. Loss of balance creates\n * vulnerability windows where damage is increased and defensive options limited.\n * Balance is affected by:\n * - Leg strikes\n * - Throws and sweeps\n * - Heavy impacts\n * - Fatigue (low stamina)\n * - Stance transitions (0.5s vulnerability window)\n * - Body part damage (legs reduce balance)\n * - Rapid stance changes (penalty system)\n *\n * ## Balance States\n *\n * - **Stable**: 80-100 balance - Full mobility and defense\n * - **Unsteady**: 50-79 balance - Reduced evasion, slower movement\n * - **Off-Balance**: 20-49 balance - Vulnerability window, defense penalty\n * - **Falling**: 0-19 balance - Severe vulnerability, possible knockdown\n *\n * ## Fall System Integration\n *\n * When balance falls below 20%, the system can trigger fall animations (낙법).\n * Fall direction is determined by attack vector and player stance.\n *\n * ## Stance Transition Vulnerability\n *\n * Changing stances creates a 0.5s vulnerability window with 1.5x damage multiplier.\n * Rapid stance changes (>2 in 3s) apply additional 20% balance penalty for 2s.\n *\n * @module systems/combat/BalanceSystem\n * @category Combat System\n * @korean 균형시스템\n */\n\nimport { BodyRegion } from \"@/types\";\nimport { TrigramStance } from \"@/types/common\";\nimport {\n  determineFallDirection,\n  determineFallFromStance,\n  getRecoveryConfig,\n  isVulnerableFrame,\n} from \"../animation\";\nimport type {\n  FallType,\n  GroundState,\n  RecoveryAnimationType,\n} from \"../animation/core/types\";\nimport { PlayerState } from \"../player\";\n\n/**\n * Stance transition state tracking.\n *\n * **Korean**: 자세 전환 상태 (Stance Transition State)\n *\n * Tracks when a player is transitioning between stances, creating a\n * 0.5s vulnerability window with increased damage multiplier.\n */\nexport interface TransitionState {\n  /** Whether player is currently transitioning */\n  readonly isTransitioning: boolean;\n  /** Timestamp when transition started (ms) */\n  readonly transitionStartTime: number;\n  /** Damage multiplier during transition (1.5x) */\n  readonly vulnerabilityMultiplier: number;\n  /** Stance transitioning from */\n  readonly fromStance: TrigramStance | null;\n  /** Stance transitioning to */\n  readonly toStance: TrigramStance | null;\n}\n\n/**\n * Stance change history entry.\n *\n * **Korean**: 자세 변경 기록 (Stance Change Record)\n */\ninterface StanceChangeRecord {\n  /** Timestamp of stance change */\n  readonly timestamp: number;\n  /** Stance changed from */\n  readonly fromStance: TrigramStance;\n  /** Stance changed to */\n  readonly toStance: TrigramStance;\n}\n\n/**\n * Extended player state with balance system data.\n *\n * Extends PlayerState with additional balance-specific tracking.\n */\nexport interface BalancePlayerState extends PlayerState {\n  /** Stance transition state */\n  readonly transitionState?: TransitionState;\n  /** Stance change history (last 5 changes) */\n  readonly stanceChangeHistory?: readonly StanceChangeRecord[];\n  /** Rapid change penalty end timestamp */\n  readonly rapidChangePenaltyEnd?: number;\n}\n\n/**\n * Balance levels representing physical stability.\n *\n * **Korean**: 균형 수준\n */\nexport enum BalanceLevel {\n  /** Stable footing (80-100) */\n  STABLE = \"stable\",\n  /** Unsteady but controlled (50-79) */\n  UNSTEADY = \"unsteady\",\n  /** Off-balance, vulnerable (20-49) */\n  OFF_BALANCE = \"off_balance\",\n  /** Falling or knocked down (0-19) */\n  FALLING = \"falling\",\n}\n\n/**\n * Effects of balance on combat performance.\n */\ninterface BalanceEffects {\n  /** Balance value range */\n  readonly range: readonly [number, number];\n  /** Defense multiplier */\n  readonly defenseMultiplier: number;\n  /** Evasion success chance modifier */\n  readonly evasionModifier: number;\n  /** Movement speed multiplier */\n  readonly movementSpeedMultiplier: number;\n  /** Vulnerability to attacks multiplier */\n  readonly vulnerabilityMultiplier: number;\n  /** Can perform evasive actions */\n  readonly canEvade: boolean;\n  /** Risk of knockdown */\n  readonly knockdownRisk: number;\n}\n\n/**\n * Balance System managing stability and vulnerability.\n *\n * Balance represents physical stability and center of gravity control.\n * Low balance creates vulnerability windows where opponents can capitalize\n * with increased damage and reduced defensive options.\n *\n * @example\n * ```typescript\n * const balanceSystem = new BalanceSystem();\n *\n * // Apply balance disruption from leg strike\n * const newPlayer = balanceSystem.disruptBalance(\n *   player,\n *   15,\n *   BodyRegion.LEFT_LEG\n * );\n *\n * // Check if vulnerable\n * const isVulnerable = balanceSystem.isVulnerable(newPlayer);\n *\n * // Apply recovery\n * const recovered = balanceSystem.applyRecovery(newPlayer, 1000);\n * ```\n *\n * @public\n * @korean 균형시스템\n */\nexport class BalanceSystem {\n  /**\n   * Balance level effects and thresholds.\n   */\n  private readonly balanceEffects: Record<BalanceLevel, BalanceEffects> = {\n    [BalanceLevel.STABLE]: {\n      range: [80, 100],\n      defenseMultiplier: 1.0,\n      evasionModifier: 1.0,\n      movementSpeedMultiplier: 1.0,\n      vulnerabilityMultiplier: 1.0,\n      canEvade: true,\n      knockdownRisk: 0.0,\n    },\n    [BalanceLevel.UNSTEADY]: {\n      range: [50, 79],\n      defenseMultiplier: 0.85,\n      evasionModifier: 0.7,\n      movementSpeedMultiplier: 0.85,\n      vulnerabilityMultiplier: 1.15,\n      canEvade: true,\n      knockdownRisk: 0.1,\n    },\n    [BalanceLevel.OFF_BALANCE]: {\n      range: [20, 49],\n      defenseMultiplier: 0.6,\n      evasionModifier: 0.4,\n      movementSpeedMultiplier: 0.6,\n      vulnerabilityMultiplier: 1.5, // 50% more damage taken\n      canEvade: false,\n      knockdownRisk: 0.3,\n    },\n    [BalanceLevel.FALLING]: {\n      range: [0, 19],\n      defenseMultiplier: 0.3,\n      evasionModifier: 0.0,\n      movementSpeedMultiplier: 0.3,\n      vulnerabilityMultiplier: 2.0, // 100% more damage taken\n      canEvade: false,\n      knockdownRisk: 0.8,\n    },\n  };\n\n  /**\n   * Balance disruption multipliers by body region.\n   */\n  private readonly regionMultipliers: Record<string, number> = {\n    [BodyRegion.LEFT_LEG]: 2.5,\n    [BodyRegion.RIGHT_LEG]: 2.5,\n    [BodyRegion.CORE]: 2.0,\n    [BodyRegion.TORSO]: 1.5,\n    [BodyRegion.HEAD]: 1.0,\n    default: 0.5,\n  };\n\n   /**\n   * Base balance recovery rate per second.\n   */\n  private readonly baseRecoveryRate = 8.0; // 8 points per second\n\n  /**\n   * Maximum balance value.\n   */\n  private readonly maxBalance = 100;\n\n  /**\n   * Stance transition constants.\n   */\n  private readonly transitionDuration = 500; // 0.5s in milliseconds\n  private readonly transitionVulnerabilityMultiplier = 1.5; // 1.5x damage during transition\n\n  /**\n   * Rapid stance change penalty constants.\n   */\n  private readonly rapidChangeWindow = 3000; // 3 seconds in milliseconds\n  private readonly rapidChangeThreshold = 2; // >2 changes trigger penalty\n  private readonly rapidChangePenalty = 0.2; // 20% balance reduction\n  private readonly rapidChangePenaltyDuration = 2000; // 2 seconds penalty\n  private readonly stanceChangeHistoryLimit = 5; // Keep last 5 changes\n\n  /**\n   * Disrupts balance from combat impact.\n   *\n   * Calculates balance loss based on damage amount and body region hit.\n   * Leg strikes cause maximum balance disruption.\n   *\n   * Now also considers:\n   * - Body part damage modifier (damaged legs reduce balance more)\n   * - Rapid stance change penalty (20% additional reduction)\n   *\n   * @param player - Current player state\n   * @param impact - Impact force amount\n   * @param region - Body region affected\n   * @param currentTime - Current game time for penalty checks (optional)\n   * @returns Updated player state with reduced balance\n   *\n   * @example\n   * ```typescript\n   * // Leg sweep causes major balance disruption\n   * player = system.disruptBalance(\n   *   player,\n   *   20,\n   *   BodyRegion.RIGHT_LEG,\n   *   Date.now()\n   * );\n   * ```\n   *\n   * @public\n   * @korean 균형파괴\n   */\n  disruptBalance(\n    player: BalancePlayerState,\n    impact: number,\n    region?: BodyRegion,\n    currentTime?: number\n  ): BalancePlayerState {\n    // Get multiplier based on region\n    const multiplier = region\n      ? this.regionMultipliers[region] ?? this.regionMultipliers.default\n      : this.regionMultipliers.default;\n\n    // Calculate base balance loss\n    let balanceLoss = impact * multiplier * 0.6; // 0.6 = balance sensitivity\n\n    // Apply body part damage modifier\n    const bodyModifier = this.calculateBalanceModifier(player);\n    balanceLoss *= 1.0 / bodyModifier; // More damage = more balance loss\n\n    // Apply rapid stance change penalty if time is provided\n    if (currentTime !== undefined && this.isRapidChangePenaltyActive(player, currentTime)) {\n      balanceLoss *= 1.0 + this.rapidChangePenalty; // +20% balance loss\n    }\n\n    // Apply balance loss, clamped to 0\n    const newBalance = Math.max(0, player.balance - balanceLoss);\n\n    return {\n      ...player,\n      balance: newBalance,\n    };\n  }\n\n  /**\n   * Applies balance recovery over time.\n   *\n   * Balance recovers quickly when not being disrupted, allowing\n   * fighters to regain stable footing between exchanges.\n   *\n   * Recovery is affected by:\n   * - Balance level (harder to recover when off-balance)\n   * - Stamina (low stamina = slow recovery)\n   * - Body part damage (leg damage reduces recovery rate)\n   *\n   * @param player - Current player state\n   * @param deltaTime - Time elapsed in milliseconds\n   * @returns Updated player state with recovered balance\n   *\n   * @example\n   * ```typescript\n   * // In game loop\n   * player = system.applyRecovery(player, 16); // ~60fps\n   * ```\n   *\n   * @public\n   * @korean 균형회복\n   */\n  applyRecovery(player: BalancePlayerState, deltaTime: number): BalancePlayerState {\n    // Already at maximum balance\n    if (player.balance >= this.maxBalance) {\n      return player;\n    }\n\n    const deltaSeconds = deltaTime / 1000;\n    const level = this.getBalanceLevel(player.balance);\n\n    // Recovery modifier based on balance level\n    let recoveryModifier = 1.0;\n    if (level === BalanceLevel.OFF_BALANCE) {\n      recoveryModifier = 0.7; // Harder to recover when off-balance\n    } else if (level === BalanceLevel.FALLING) {\n      recoveryModifier = 0.4; // Very hard to recover when falling\n    }\n\n    // Stamina affects recovery rate\n    const staminaFactor = player.stamina / player.maxStamina;\n    \n    // Body part damage affects recovery rate\n    const bodyModifier = this.calculateBalanceModifier(player);\n    \n    const finalModifier = recoveryModifier * (0.5 + staminaFactor * 0.5) * bodyModifier;\n\n    const recovery = this.baseRecoveryRate * deltaSeconds * finalModifier;\n    const newBalance = Math.min(this.maxBalance, player.balance + recovery);\n\n    return {\n      ...player,\n      balance: newBalance,\n    };\n  }\n\n  /**\n   * Determines balance level from balance value.\n   *\n   * @param balance - Balance value (0-100)\n   * @returns Current balance level\n   *\n   * @public\n   * @korean 균형수준확인\n   */\n  getBalanceLevel(balance: number): BalanceLevel {\n    if (balance >= 80) return BalanceLevel.STABLE;\n    if (balance >= 50) return BalanceLevel.UNSTEADY;\n    if (balance >= 20) return BalanceLevel.OFF_BALANCE;\n    return BalanceLevel.FALLING;\n  }\n\n  /**\n   * Gets effects for a specific balance level.\n   *\n   * @param level - Balance level\n   * @returns Effects applied at that level\n   *\n   * @public\n   * @korean 균형효과\n   */\n  getEffects(level: BalanceLevel): BalanceEffects {\n    return this.balanceEffects[level];\n  }\n\n  /**\n   * Applies balance effects to player state.\n   *\n   * Modifies player stats based on current balance level.\n   *\n   * @param player - Current player state\n   * @returns Modified player state with balance effects\n   *\n   * @public\n   * @korean 균형효과적용\n   */\n  applyEffects(player: PlayerState): PlayerState {\n    const level = this.getBalanceLevel(player.balance);\n    const effects = this.getEffects(level);\n\n    return {\n      ...player,\n      defense: Math.floor(player.defense * effects.defenseMultiplier),\n      speed: Math.floor(player.speed * effects.movementSpeedMultiplier),\n    };\n  }\n\n  /**\n   * Checks if player is vulnerable due to balance.\n   *\n   * @param player - Current player state\n   * @returns True if off-balance or falling\n   *\n   * @public\n   * @korean 균형취약확인\n   */\n  isVulnerable(player: PlayerState): boolean {\n    const level = this.getBalanceLevel(player.balance);\n    return level === BalanceLevel.OFF_BALANCE || level === BalanceLevel.FALLING;\n  }\n\n  /**\n   * Calculates damage multiplier for vulnerable balance state.\n   *\n   * @param player - Current player state\n   * @returns Damage multiplier (1.0 = normal, >1.0 = increased damage)\n   *\n   * @public\n   * @korean 취약성배율\n   */\n  getVulnerabilityMultiplier(player: PlayerState): number {\n    const level = this.getBalanceLevel(player.balance);\n    const effects = this.getEffects(level);\n    return effects.vulnerabilityMultiplier;\n  }\n\n  /**\n   * Checks if knockdown should occur, using a provided random function for determinism.\n   *\n   * @param player - Current player state\n   * @param randomFn - Optional random number generator (returns number in [0,1)), defaults to Math.random\n   * @returns True if knockdown should occur\n   *\n   * @public\n   * @korean 넘어짐확인\n   */\n  shouldKnockdown(\n    player: PlayerState,\n    randomFn: () => number = Math.random\n  ): boolean {\n    const level = this.getBalanceLevel(player.balance);\n    const effects = this.getEffects(level);\n    return randomFn() < effects.knockdownRisk;\n  }\n\n  /**\n   * Gets bilingual name for balance level.\n   *\n   * @param level - Balance level\n   * @returns Korean and English level names\n   *\n   * @public\n   * @korean 균형이름\n   */\n  getLevelName(level: BalanceLevel): { korean: string; english: string } {\n    const names: Record<BalanceLevel, { korean: string; english: string }> = {\n      [BalanceLevel.STABLE]: {\n        korean: \"안정\",\n        english: \"Stable\",\n      },\n      [BalanceLevel.UNSTEADY]: {\n        korean: \"불안정\",\n        english: \"Unsteady\",\n      },\n      [BalanceLevel.OFF_BALANCE]: {\n        korean: \"균형상실\",\n        english: \"Off-Balance\",\n      },\n      [BalanceLevel.FALLING]: {\n        korean: \"낙하중\",\n        english: \"Falling\",\n      },\n    };\n\n    return names[level];\n  }\n\n  /**\n   * Gets color indicator for balance level (for UI).\n   *\n   * @param level - Balance level\n   * @returns Hex color code\n   *\n   * @public\n   * @korean 균형색상\n   */\n  getLevelColor(level: BalanceLevel): number {\n    const colors: Record<BalanceLevel, number> = {\n      [BalanceLevel.STABLE]: 0x00ff00, // Green\n      [BalanceLevel.UNSTEADY]: 0xffff00, // Yellow\n      [BalanceLevel.OFF_BALANCE]: 0xff8800, // Orange\n      [BalanceLevel.FALLING]: 0xff0000, // Red\n    };\n\n    return colors[level];\n  }\n\n  /**\n   * Checks if balance is low enough to trigger fall animation.\n   *\n   * Falls occur when balance drops below 20% (FALLING state).\n   * This creates realistic knockdown conditions from balance loss.\n   *\n   * @param player - Current player state\n   * @returns True if fall animation should trigger\n   *\n   * @example\n   * ```typescript\n   * if (balanceSystem.shouldTriggerFall(player)) {\n   *   const fallType = balanceSystem.determineFallType(\n   *     player,\n   *     attackAngle,\n   *     attackHeight\n   *   );\n   *   animationMachine.transitionTo(FALL_TYPE_TO_ANIMATION[fallType]);\n   * }\n   * ```\n   *\n   * @public\n   * @korean 낙법발동확인\n   */\n  shouldTriggerFall(player: PlayerState): boolean {\n    return player.balance < 20; // FALLING threshold\n  }\n\n  /**\n   * Determines which fall animation to play based on attack and stance.\n   *\n   * Calculates fall direction using:\n   * - Attack angle relative to player\n   * - Attack height (high/mid/low)\n   * - Player's current stance bias\n   *\n   * Korean falling techniques (낙법):\n   * - 전방낙법 (Jeonbang Nakbeop): Forward fall\n   * - 후방낙법 (Hubang Nakbeop): Backward fall\n   * - 측방낙법 (Cheukbang Nakbeop): Side fall\n   *\n   * @param player - Current player state\n   * @param attackAngle - Angle of attack in radians (0 = from front)\n   * @param attackHeight - Attack height: 'high', 'mid', or 'low'\n   * @returns Fall type to use for animation\n   *\n   * @example\n   * ```typescript\n   * // Player facing forward (0°), attacked from behind (π)\n   * const fallType = balanceSystem.determineFallType(\n   *   player,\n   *   Math.PI,\n   *   'mid'\n   * );\n   * // Returns: 'forward' (pushed forward by rear attack)\n   *\n   * // Low sweep from right side\n   * const fallType = balanceSystem.determineFallType(\n   *   player,\n   *   Math.PI/2,\n   *   'low'\n   * );\n   * // Returns: 'side_right' (swept to the side)\n   * ```\n   *\n   * @public\n   * @korean 낙법유형결정\n   */\n  determineFallType(\n    _player: PlayerState,\n    attackAngle: number,\n    attackHeight: \"high\" | \"mid\" | \"low\" = \"mid\"\n  ): FallType {\n    // Get player facing angle from position or default to 0\n    const playerFacing = 0; // Default facing forward\n\n    // Use attack direction to determine fall\n    return determineFallDirection(attackAngle, playerFacing, attackHeight);\n  }\n\n  /**\n   * Determines fall type based on player stance when no attack direction available.\n   *\n   * Uses stance bias to determine likely fall direction when balance is lost\n   * without a specific attack (e.g., from fatigue, leg damage accumulation).\n   *\n   * @param stance - Current trigram stance\n   * @returns Fall type based on stance characteristics\n   *\n   * @example\n   * ```typescript\n   * // Player in Heaven stance (aggressive forward)\n   * const fallType = balanceSystem.determineFallTypeFromStance(\n   *   TrigramStance.GEON\n   * );\n   * // Returns: 'forward' (Heaven stance has forward bias)\n   * ```\n   *\n   * @public\n   * @korean 자세낙법결정\n   */\n  determineFallTypeFromStance(stance: TrigramStance): FallType {\n    return determineFallFromStance(stance);\n  }\n\n  /**\n   * Check if player is in a grounded state based on animation state.\n   *\n   * Player is considered grounded when in any ground_* animation state\n   * (ground_prone, ground_supine, ground_side_left, ground_side_right).\n   *\n   * @param animationState - Current animation state from AnimationStateMachine\n   * @returns True if player is on the ground\n   *\n   * @example\n   * ```typescript\n   * const isGrounded = balanceSystem.isGrounded(\"ground_prone\");\n   * // Returns: true\n   *\n   * const notGrounded = balanceSystem.isGrounded(\"idle\");\n   * // Returns: false\n   * ```\n   *\n   * @public\n   * @korean 지면상태확인\n   */\n  isGrounded(animationState: string): boolean {\n    return animationState.startsWith(\"ground_\");\n  }\n\n  /**\n   * Get ground state from animation state.\n   *\n   * Extracts the ground position type from animation state name.\n   * Returns null if not in a ground state.\n   *\n   * @param animationState - Current animation state from AnimationStateMachine\n   * @returns Ground state or null if not grounded\n   *\n   * @example\n   * ```typescript\n   * const state = balanceSystem.getGroundState(\"ground_prone\");\n   * // Returns: \"prone\"\n   *\n   * const none = balanceSystem.getGroundState(\"idle\");\n   * // Returns: null\n   * ```\n   *\n   * @public\n   * @korean 지면자세가져오기\n   */\n  getGroundState(animationState: string): GroundState | null {\n    if (!this.isGrounded(animationState)) {\n      return null;\n    }\n\n    // Extract ground state from animation state name\n    // \"ground_prone\" -> \"prone\"\n    const groundType = animationState.replace(\"ground_\", \"\");\n\n    // Validate that it's a valid ground state\n    if (\n      groundType === \"prone\" ||\n      groundType === \"supine\" ||\n      groundType === \"side_left\" ||\n      groundType === \"side_right\"\n    ) {\n      return groundType as GroundState;\n    }\n\n    return null;\n  }\n\n  /**\n   * Check if player can execute recovery based on stamina.\n   *\n   * Some recovery animations (like roll recovery) require stamina.\n   * This checks if player has sufficient stamina for the recovery type.\n   *\n   * @param player - Current player state\n   * @param recoveryType - Type of recovery animation\n   * @returns True if player has enough stamina\n   *\n   * @example\n   * ```typescript\n   * // Roll recovery costs 20 stamina\n   * const canRoll = balanceSystem.canRecoverWithType(player, \"roll_recovery\");\n   * // Returns: true if player.stamina >= 20\n   *\n   * // Normal recoveries have no cost\n   * const canStand = balanceSystem.canRecoverWithType(player, \"prone_standup\");\n   * // Returns: true (no stamina requirement)\n   * ```\n   *\n   * @public\n   * @korean 회복가능확인\n   */\n  canRecoverWithType(\n    player: PlayerState,\n    recoveryType: RecoveryAnimationType\n  ): boolean {\n    const config = getRecoveryConfig(recoveryType);\n\n    // Check if player has enough stamina\n    return player.stamina >= config.staminaCost;\n  }\n\n  /**\n   * Apply stamina cost for recovery animation.\n   *\n   * Deducts stamina cost from player state for recovery animations\n   * that require stamina (like roll recovery).\n   *\n   * @param player - Current player state\n   * @param recoveryType - Type of recovery animation\n   * @returns Updated player state with stamina deducted\n   *\n   * @example\n   * ```typescript\n   * // Roll recovery costs 20 stamina\n   * const recovered = balanceSystem.applyRecoveryCost(player, \"roll_recovery\");\n   * // recovered.stamina = player.stamina - 20\n   * ```\n   *\n   * @public\n   * @korean 회복비용적용\n   */\n  applyRecoveryCost(\n    player: PlayerState,\n    recoveryType: RecoveryAnimationType\n  ): PlayerState {\n    const config = getRecoveryConfig(recoveryType);\n\n    if (config.staminaCost === 0) {\n      return player;\n    }\n\n    return {\n      ...player,\n      stamina: Math.max(0, player.stamina - config.staminaCost),\n    };\n  }\n\n  /**\n   * Get damage multiplier during recovery animation.\n   *\n   * Some recovery animations (like defensive getup) provide damage reduction.\n   * This returns the multiplier to apply to incoming damage.\n   *\n   * @param recoveryType - Type of recovery animation\n   * @param currentFrame - Current frame in the animation\n   * @returns Damage multiplier (1.0 = normal, 0.5 = 50% reduction)\n   *\n   * @example\n   * ```typescript\n   * // Defensive getup has 50% damage reduction\n   * const multiplier = balanceSystem.getRecoveryDamageMultiplier(\"defensive_getup\", 20);\n   * // Returns: 0.5 (50% damage reduction)\n   *\n   * // Normal recoveries have no reduction\n   * const normal = balanceSystem.getRecoveryDamageMultiplier(\"prone_standup\", 15);\n   * // Returns: 1.0 (full damage)\n   * ```\n   *\n   * @public\n   * @korean 회복피해배율\n   */\n  getRecoveryDamageMultiplier(\n    recoveryType: RecoveryAnimationType,\n    currentFrame: number\n  ): number {\n    const config = getRecoveryConfig(recoveryType);\n\n    // Only apply damage reduction during vulnerable frames\n    if (!isVulnerableFrame(recoveryType, currentFrame)) {\n      return 1.0; // No vulnerability = full damage (or no damage if invulnerable)\n    }\n\n    // Apply damage reduction\n    // damageReduction of 0.5 means 50% reduction, so multiplier is 0.5\n    return 1.0 - config.damageReduction;\n  }\n\n  /**\n   * Start a stance transition, creating vulnerability window.\n   *\n   * When a player changes stance, they become vulnerable for 0.5s with\n   * a 1.5x damage multiplier. This creates tactical depth around stance changes.\n   *\n   * @param player - Current player state\n   * @param newStance - Target stance to transition to\n   * @param currentTime - Current game time in milliseconds\n   * @returns Updated player state with transition tracking\n   *\n   * @example\n   * ```typescript\n   * // Player switches from Heaven to Water stance\n   * const transitioning = balanceSystem.startStanceTransition(\n   *   player,\n   *   TrigramStance.GAM,\n   *   Date.now()\n   * );\n   * // transitioning.transitionState.isTransitioning = true\n   * // transitioning.transitionState.vulnerabilityMultiplier = 1.5\n   * ```\n   *\n   * @public\n   * @korean 자세전환시작\n   */\n  startStanceTransition(\n    player: BalancePlayerState,\n    newStance: TrigramStance,\n    currentTime: number\n  ): BalancePlayerState {\n    // No-op if changing to the same stance (avoid unnecessary transitions)\n    if (newStance === player.currentStance) {\n      return player;\n    }\n\n    // Initialize transition state\n    const transitionState: TransitionState = {\n      isTransitioning: true,\n      transitionStartTime: currentTime,\n      vulnerabilityMultiplier: this.transitionVulnerabilityMultiplier,\n      fromStance: player.currentStance,\n      toStance: newStance,\n    };\n\n    // Add to stance change history\n    const historyEntry: StanceChangeRecord = {\n      timestamp: currentTime,\n      fromStance: player.currentStance,\n      toStance: newStance,\n    };\n\n    const history = player.stanceChangeHistory ?? [];\n    const newHistory = [...history, historyEntry].slice(-this.stanceChangeHistoryLimit);\n\n    // Check for rapid stance changes (inclusive boundary)\n    const recentChanges = newHistory.filter(\n      (entry) => currentTime - entry.timestamp <= this.rapidChangeWindow\n    );\n\n    let rapidChangePenaltyEnd = player.rapidChangePenaltyEnd;\n\n    if (recentChanges.length > this.rapidChangeThreshold) {\n      // Apply rapid change penalty\n      rapidChangePenaltyEnd = currentTime + this.rapidChangePenaltyDuration;\n    }\n\n    return {\n      ...player,\n      currentStance: newStance,\n      lastStanceChangeTime: currentTime,\n      transitionState,\n      stanceChangeHistory: newHistory,\n      rapidChangePenaltyEnd,\n    };\n  }\n\n  /**\n   * Update stance transition state based on time elapsed.\n   *\n   * Transitions last 0.5s. After that, vulnerability window closes.\n   * Called each frame to manage transition timing.\n   *\n   * @param player - Current player state\n   * @param currentTime - Current game time in milliseconds\n   * @returns Updated player state\n   *\n   * @example\n   * ```typescript\n   * // In game loop\n   * player = balanceSystem.updateTransition(player, Date.now());\n   * ```\n   *\n   * @public\n   * @korean 전환상태갱신\n   */\n  updateTransition(\n    player: BalancePlayerState,\n    currentTime: number\n  ): BalancePlayerState {\n    if (!player.transitionState?.isTransitioning) {\n      return player;\n    }\n\n    const elapsed = currentTime - player.transitionState.transitionStartTime;\n\n    // Check if transition window has ended\n    if (elapsed >= this.transitionDuration) {\n      return {\n        ...player,\n        transitionState: {\n          ...player.transitionState,\n          isTransitioning: false,\n          vulnerabilityMultiplier: 1.0,\n        },\n      };\n    }\n\n    return player;\n  }\n\n  /**\n   * Calculate balance modifier based on body part damage.\n   *\n   * Leg damage significantly reduces balance. The leg-specific modifier\n   * scales linearly from 0.7x at 0% leg health to 1.0x at 100% leg health:\n   * - 100% leg health: 1.0x balance (no reduction from legs)\n   * - 70% leg health: ≈0.91x balance (≈9% reduction from legs)\n   * - 30% leg health: ≈0.79x balance (≈21% reduction from legs)\n   * - 0% leg health: 0.7x balance (30% reduction from legs)\n   *\n   * Torso damage also affects balance but to a lesser degree, and the\n   * combined leg/torso modifier is clamped so the final balance modifier\n   * stays within the range 0.5x to 1.0x.\n   *\n   * @param player - Current player state with body part health\n   * @returns Balance modifier (0.5 to 1.0)\n   *\n   * @example\n   * ```typescript\n   * const modifier = balanceSystem.calculateBalanceModifier(player);\n   * const effectiveBalance = player.balance * modifier;\n   * ```\n   *\n   * @public\n   * @korean 균형조정계수계산\n   */\n  calculateBalanceModifier(player: BalancePlayerState): number {\n    if (!player.bodyPartHealth || !player.bodyPartMaxHealth) {\n      return 1.0; // No body part tracking, no modifier\n    }\n\n    // Read leg and torso health ratios from body part health tracking\n    const leftLegHealthRaw =\n      (player.bodyPartHealth.legLeft ?? 0) /\n      (player.bodyPartMaxHealth.legLeft ?? 1);\n    const rightLegHealthRaw =\n      (player.bodyPartHealth.legRight ?? 0) /\n      (player.bodyPartMaxHealth.legRight ?? 1);\n    \n    // Use torsoLower for core balance (lower body)\n    const torsoHealthRaw =\n      (player.bodyPartHealth.torsoLower ?? 0) /\n      (player.bodyPartMaxHealth.torsoLower ?? 1);\n\n    // Clamp health ratios to [0, 1] to prevent out-of-range values\n    const leftLegHealth = Math.max(0, Math.min(1, leftLegHealthRaw));\n    const rightLegHealth = Math.max(0, Math.min(1, rightLegHealthRaw));\n    const torsoHealth = Math.max(0, Math.min(1, torsoHealthRaw));\n\n    // Average leg health (both legs affect balance)\n    const avgLegHealth = (leftLegHealth + rightLegHealth) / 2;\n\n    // Leg damage: 0-30% reduction based on damage\n    const legModifier = 0.7 + avgLegHealth * 0.3; // Range: 0.7 to 1.0\n\n    // Torso damage: 0-10% reduction based on damage\n    const torsoModifier = 0.9 + torsoHealth * 0.1; // Range: 0.9 to 1.0\n\n    // Combine modifiers (multiplicative)\n    const combinedModifier = legModifier * torsoModifier;\n\n    // Clamp to [0.5, 1.0] range as documented\n    return Math.max(0.5, Math.min(1.0, combinedModifier));\n  }\n\n  /**\n   * Calculate knockback resistance based on current stance.\n   *\n   * Different stances provide varying levels of knockback resistance:\n   * - Defensive stances (Mountain, Earth): +50% resistance\n   * - Balanced stances (Water, Wind): normal resistance\n   * - Offensive stances (Heaven, Fire, Thunder): -30% resistance\n   * - Fluid stance (Lake): normal resistance\n   *\n   * @param stance - Current trigram stance\n   * @returns Knockback resistance multiplier (0.7 to 1.5)\n   *\n   * @example\n   * ```typescript\n   * const resistance = balanceSystem.getKnockbackResistance(TrigramStance.GAN);\n   * const effectiveKnockback = baseKnockback * (1.0 / resistance);\n   * ```\n   *\n   * @public\n   * @korean 넉백저항계산\n   */\n  getKnockbackResistance(stance: TrigramStance): number {\n    // Defensive stances: +50% resistance\n    if (stance === TrigramStance.GAN || stance === TrigramStance.GON) {\n      // Mountain, Earth\n      return 1.5;\n    }\n\n    // Offensive stances: -30% resistance\n    if (stance === TrigramStance.GEON || stance === TrigramStance.LI || stance === TrigramStance.JIN) {\n      // Heaven, Fire, Thunder\n      return 0.7;\n    }\n\n    // Balanced/adaptive stances: normal resistance\n    return 1.0; // Water, Wind, Lake\n  }\n\n  /**\n   * Check if rapid stance change penalty is active.\n   *\n   * Penalty applies when player changes stances >2 times in 3 seconds.\n   * Lasts for 2 seconds after the last rapid change.\n   * The penalty increases balance loss by 20% in `disruptBalance()`.\n   *\n   * @param player - Current player state\n   * @param currentTime - Current game time in milliseconds\n   * @returns True if penalty is active\n   *\n   * @example\n   * ```typescript\n   * // The penalty is applied automatically in disruptBalance()\n   * if (balanceSystem.isRapidChangePenaltyActive(player, Date.now())) {\n   *   // Penalty active: balance loss will be increased by 20%\n   *   cy.log(\"Rapid change penalty active\");\n   * }\n   * ```\n   *\n   * @public\n   * @korean 급속변경벌칙확인\n   */\n  isRapidChangePenaltyActive(\n    player: BalancePlayerState,\n    currentTime: number\n  ): boolean {\n    if (!player.rapidChangePenaltyEnd) {\n      return false;\n    }\n    return currentTime < player.rapidChangePenaltyEnd;\n  }\n\n  /**\n   * Get total vulnerability multiplier considering all factors.\n   *\n   * Combines:\n   * - Base balance state vulnerability (1.0 to 2.0)\n   * - Stance transition vulnerability (1.5x during 0.5s window)\n   *\n   * @param player - Current player state\n   * @returns Combined vulnerability multiplier\n   *\n   * @example\n   * ```typescript\n   * const multiplier = balanceSystem.getTotalVulnerabilityMultiplier(player);\n   * const finalDamage = baseDamage * multiplier;\n   * ```\n   *\n   * @public\n   * @korean 총취약성배율\n   */\n  getTotalVulnerabilityMultiplier(player: BalancePlayerState): number {\n    // Get base balance vulnerability\n    const level = this.getBalanceLevel(player.balance);\n    const effects = this.getEffects(level);\n    let multiplier = effects.vulnerabilityMultiplier;\n\n    // Apply transition vulnerability if active\n    if (player.transitionState?.isTransitioning) {\n      multiplier *= player.transitionState.vulnerabilityMultiplier;\n    }\n\n    return multiplier;\n  }\n}\n\nexport default BalanceSystem;\n"],"mappings":"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"}

package/lib/systems/combat/BreakingStatusEffects.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Breaking Technique Status Effect Constants
+ *
+ * **Korean**: 파쇄기술 상태효과 상수
+ *
+ * Defines status effect IDs used by the limb exposure and breaking technique system.
+ * These effects are applied when joints/bones are broken during counter-attacks.
+ *
+ * @module systems/combat/BreakingStatusEffects
+ * @korean 파쇄상태효과
+ */
+/**
+ * Status effect IDs for breaking techniques.
+ *
+ * These IDs are used when creating StatusEffect objects after successful
+ * breaking technique execution. Each ID should eventually have a corresponding
+ * StatusEffect implementation in the game's effect system.
+ *
+ * **Korean**: 파쇄 상태효과 ID
+ *
+ * @public
+ * @korean 파쇄상태효과ID
+ */
+export declare const BREAKING_STATUS_EFFECT_IDS: {
+    /**
+     * General pain effect applied on all successful breaks.
+     * Maps to existing VitalPointEffectType.PAIN.
+     * @korean 고통
+     */
+    readonly PAIN: "pain";
+    /**
+     * Severe injury from high-severity breaks (severity > 0.8).
+     * Indicates major trauma requiring immediate attention.
+     * @korean 심각한부상
+     */
+    readonly SEVERE_INJURY: "severe_injury";
+    /**
+     * Limb is completely disabled and cannot be used.
+     * Applied to broken joints/bones preventing limb function.
+     * @korean 사지불능
+     */
+    readonly DISABLED_LIMB: "disabled_limb";
+    /**
+     * Moderate limb injury (severity 0.5-0.8).
+     * Limb can be used but with reduced effectiveness.
+     * @korean 사지부상
+     */
+    readonly INJURED_LIMB: "injured_limb";
+    /**
+     * Minor joint sprain or strain (severity < 0.5).
+     * Causes discomfort but doesn't prevent use.
+     * @korean 관절염좌
+     */
+    readonly SPRAINED_JOINT: "sprained_joint";
+    /**
+     * Movement speed reduction from leg/ankle breaks.
+     * Applied when ankle or knee is broken.
+     * @korean 이동력감소
+     */
+    readonly IMPAIRED_MOBILITY: "impaired_mobility";
+    /**
+     * Bleeding from severe bone breaks (severity > 0.6).
+     * Causes continuous health drain.
+     * @korean 출혈
+     */
+    readonly BLEEDING: "bleeding";
+};
+/**
+ * Type representing valid breaking status effect IDs.
+ * Use this type when referencing breaking effect IDs to ensure type safety.
+ *
+ * @public
+ * @korean 파쇄상태효과ID타입
+ */
+export type BreakingStatusEffectId = (typeof BREAKING_STATUS_EFFECT_IDS)[keyof typeof BREAKING_STATUS_EFFECT_IDS];
+/**
+ * Helper function to validate if a string is a valid breaking status effect ID.
+ *
+ * @param id - The ID to validate
+ * @returns true if the ID is a valid breaking status effect
+ *
+ * @public
+ * @korean 파쇄상태효과ID검증
+ */
+export declare function isBreakingStatusEffectId(id: string): id is BreakingStatusEffectId;
+/**
+ * Get all breaking status effect IDs as an array.
+ *
+ * @returns Array of all breaking status effect ID strings
+ *
+ * @public
+ * @korean 모든파쇄상태효과ID
+ */
+export declare function getAllBreakingStatusEffectIds(): readonly string[];
+export default BREAKING_STATUS_EFFECT_IDS;
+//# sourceMappingURL=BreakingStatusEffects.d.ts.map

package/lib/systems/combat/BreakingStatusEffects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BreakingStatusEffects.d.ts","sourceRoot":"","sources":["../../../src/systems/combat/BreakingStatusEffects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;IACrC;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;CAEK,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,sBAAsB,CAI9B;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,MAAM,EAAE,CAEjE;AAED,eAAe,0BAA0B,CAAC"}

package/lib/systems/combat/BreakingStatusEffects.js

@@ -0,0 +1,60 @@
+//#region src/systems/combat/BreakingStatusEffects.ts
+/**
+* Breaking Technique Status Effect Constants
+*
+* **Korean**: 파쇄기술 상태효과 상수
+*
+* Defines status effect IDs used by the limb exposure and breaking technique system.
+* These effects are applied when joints/bones are broken during counter-attacks.
+*
+* @module systems/combat/BreakingStatusEffects
+* @korean 파쇄상태효과
+*/
+/**
+* Status effect IDs for breaking techniques.
+*
+* These IDs are used when creating StatusEffect objects after successful
+* breaking technique execution. Each ID should eventually have a corresponding
+* StatusEffect implementation in the game's effect system.
+*
+* **Korean**: 파쇄 상태효과 ID
+*
+* @public
+* @korean 파쇄상태효과ID
+*/
+var BREAKING_STATUS_EFFECT_IDS = {
+	PAIN: "pain",
+	SEVERE_INJURY: "severe_injury",
+	DISABLED_LIMB: "disabled_limb",
+	INJURED_LIMB: "injured_limb",
+	SPRAINED_JOINT: "sprained_joint",
+	IMPAIRED_MOBILITY: "impaired_mobility",
+	BLEEDING: "bleeding"
+};
+/**
+* Helper function to validate if a string is a valid breaking status effect ID.
+*
+* @param id - The ID to validate
+* @returns true if the ID is a valid breaking status effect
+*
+* @public
+* @korean 파쇄상태효과ID검증
+*/
+function isBreakingStatusEffectId(id) {
+	return Object.values(BREAKING_STATUS_EFFECT_IDS).includes(id);
+}
+/**
+* Get all breaking status effect IDs as an array.
+*
+* @returns Array of all breaking status effect ID strings
+*
+* @public
+* @korean 모든파쇄상태효과ID
+*/
+function getAllBreakingStatusEffectIds() {
+	return Object.values(BREAKING_STATUS_EFFECT_IDS);
+}
+//#endregion
+export { BREAKING_STATUS_EFFECT_IDS as default, getAllBreakingStatusEffectIds, isBreakingStatusEffectId };
+
+//# sourceMappingURL=BreakingStatusEffects.js.map

package/lib/systems/combat/BreakingStatusEffects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BreakingStatusEffects.js","names":[],"sources":["../../../src/systems/combat/BreakingStatusEffects.ts"],"sourcesContent":["/**\n * Breaking Technique Status Effect Constants\n *\n * **Korean**: 파쇄기술 상태효과 상수\n *\n * Defines status effect IDs used by the limb exposure and breaking technique system.\n * These effects are applied when joints/bones are broken during counter-attacks.\n *\n * @module systems/combat/BreakingStatusEffects\n * @korean 파쇄상태효과\n */\n\n/**\n * Status effect IDs for breaking techniques.\n *\n * These IDs are used when creating StatusEffect objects after successful\n * breaking technique execution. Each ID should eventually have a corresponding\n * StatusEffect implementation in the game's effect system.\n *\n * **Korean**: 파쇄 상태효과 ID\n *\n * @public\n * @korean 파쇄상태효과ID\n */\nexport const BREAKING_STATUS_EFFECT_IDS = {\n  /**\n   * General pain effect applied on all successful breaks.\n   * Maps to existing VitalPointEffectType.PAIN.\n   * @korean 고통\n   */\n  PAIN: \"pain\" as const,\n\n  /**\n   * Severe injury from high-severity breaks (severity > 0.8).\n   * Indicates major trauma requiring immediate attention.\n   * @korean 심각한부상\n   */\n  SEVERE_INJURY: \"severe_injury\" as const,\n\n  /**\n   * Limb is completely disabled and cannot be used.\n   * Applied to broken joints/bones preventing limb function.\n   * @korean 사지불능\n   */\n  DISABLED_LIMB: \"disabled_limb\" as const,\n\n  /**\n   * Moderate limb injury (severity 0.5-0.8).\n   * Limb can be used but with reduced effectiveness.\n   * @korean 사지부상\n   */\n  INJURED_LIMB: \"injured_limb\" as const,\n\n  /**\n   * Minor joint sprain or strain (severity < 0.5).\n   * Causes discomfort but doesn't prevent use.\n   * @korean 관절염좌\n   */\n  SPRAINED_JOINT: \"sprained_joint\" as const,\n\n  /**\n   * Movement speed reduction from leg/ankle breaks.\n   * Applied when ankle or knee is broken.\n   * @korean 이동력감소\n   */\n  IMPAIRED_MOBILITY: \"impaired_mobility\" as const,\n\n  /**\n   * Bleeding from severe bone breaks (severity > 0.6).\n   * Causes continuous health drain.\n   * @korean 출혈\n   */\n  BLEEDING: \"bleeding\" as const,\n} as const;\n\n/**\n * Type representing valid breaking status effect IDs.\n * Use this type when referencing breaking effect IDs to ensure type safety.\n *\n * @public\n * @korean 파쇄상태효과ID타입\n */\nexport type BreakingStatusEffectId =\n  (typeof BREAKING_STATUS_EFFECT_IDS)[keyof typeof BREAKING_STATUS_EFFECT_IDS];\n\n/**\n * Helper function to validate if a string is a valid breaking status effect ID.\n *\n * @param id - The ID to validate\n * @returns true if the ID is a valid breaking status effect\n *\n * @public\n * @korean 파쇄상태효과ID검증\n */\nexport function isBreakingStatusEffectId(\n  id: string\n): id is BreakingStatusEffectId {\n  return Object.values(BREAKING_STATUS_EFFECT_IDS).includes(\n    id as BreakingStatusEffectId\n  );\n}\n\n/**\n * Get all breaking status effect IDs as an array.\n *\n * @returns Array of all breaking status effect ID strings\n *\n * @public\n * @korean 모든파쇄상태효과ID\n */\nexport function getAllBreakingStatusEffectIds(): readonly string[] {\n  return Object.values(BREAKING_STATUS_EFFECT_IDS);\n}\n\nexport default BREAKING_STATUS_EFFECT_IDS;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAa,6BAA6B;CAMxC,MAAM;CAON,eAAe;CAOf,eAAe;CAOf,cAAc;CAOd,gBAAgB;CAOhB,mBAAmB;CAOnB,UAAU;CACX;;;;;;;;;;AAqBD,SAAgB,yBACd,IAC8B;AAC9B,QAAO,OAAO,OAAO,2BAA2B,CAAC,SAC/C,GACD;;;;;;;;;;AAWH,SAAgB,gCAAmD;AACjE,QAAO,OAAO,OAAO,2BAA2B"}

package/lib/systems/combat/CombatStateSystem.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Combat State System for managing Ready/Shaken/Vulnerable/Helpless states.
+ *
+ * **Korean**: 전투 상태 시스템 (Combat State System)
+ *
+ * Implements the combat readiness state machine based on cumulative damage,
+ * pain, consciousness, and balance. Each state affects player capabilities
+ * with specific multipliers.
+ *
+ * ## Combat States
+ *
+ * - **🟢 READY**: 100% capability - perfect combat condition
+ * - **🟡 SHAKEN**: 80% capability - slightly compromised, -20% accuracy
+ * - **🟠 VULNERABLE**: 60% capability - significantly exposed, -40% defense
+ * - **🔴 HELPLESS**: 20% capability - near incapacitation, cannot block
+ *
+ * @module systems/combat/CombatStateSystem
+ * @category Combat System
+ * @korean 전투상태시스템
+ */
+import { PlayerState } from "../player";
+/**
+ * Combat readiness states representing player combat effectiveness.
+ *
+ * **Korean**: 전투 준비 상태
+ */
+export declare enum CombatReadinessState {
+    /** 🟢 Ready - Full combat capability (100%) */
+    READY = "ready",
+    /** 🟡 Shaken - Reduced effectiveness (80%) */
+    SHAKEN = "shaken",
+    /** 🟠 Vulnerable - Significantly impaired (60%) */
+    VULNERABLE = "vulnerable",
+    /** 🔴 Helpless - Near incapacitation (20%) */
+    HELPLESS = "helpless"
+}
+/**
+ * State capability modifiers for each combat state.
+ *
+ * **Korean**: 상태 능력 배율
+ */
+interface StateCapability {
+    /** Overall capability percentage */
+    readonly capability: number;
+    /** Accuracy modifier (affects hit chance and damage output) */
+    readonly accuracyModifier: number;
+    /** Defense modifier (affects damage reduction) */
+    readonly defenseModifier: number;
+    /** Damage modifier (affects outgoing damage) */
+    readonly damageModifier: number;
+    /** Damage taken multiplier (affects incoming damage) */
+    readonly damageTakenMultiplier: number;
+    /** Movement speed modifier */
+    readonly speedModifier: number;
+    /** Can perform blocking actions */
+    readonly canBlock: boolean;
+    /** Can execute techniques */
+    readonly canExecuteTechniques: boolean;
+}
+/**
+ * Combat State System managing readiness state transitions.
+ *
+ * Evaluates player condition and determines current combat readiness state.
+ * States degrade based on:
+ * - Cumulative damage (health loss)
+ * - Pain overload
+ * - Consciousness reduction
+ * - Balance disruption
+ *
+ * @example
+ * ```typescript
+ * const combatStateSystem = new CombatStateSystem();
+ *
+ * // Determine current state
+ * const state = combatStateSystem.determineState(player);
+ *
+ * // Get capability modifiers
+ * const capability = combatStateSystem.getCapability(state);
+ * console.log(`Capability: ${capability.capability}%`);
+ *
+ * // Apply modifiers to damage calculation
+ * const modifiedDamage = baseDamage * capability.accuracyModifier;
+ * ```
+ *
+ * @public
+ * @korean 전투상태시스템
+ */
+export declare class CombatStateSystem {
+    /**
+     * State capability definitions with modifiers per state.
+     *
+     * Based on acceptance criteria:
+     * - READY: 100% capability (baseline)
+     * - SHAKEN: -15% accuracy, -10% damage
+     * - VULNERABLE: -30% accuracy, -25% damage, +50% damage taken
+     * - HELPLESS: Cannot attack, cannot block, +100% damage taken
+     */
+    private readonly stateCapabilities;
+    /**
+     * Determines the current combat readiness state based on player condition.
+     *
+     * Evaluates health, pain, consciousness, balance, and recent hits to determine
+     * the most appropriate combat state. State transitions follow acceptance criteria:
+     * - READY → SHAKEN: After taking 2-3 hits or significant vital point strike
+     * - SHAKEN → VULNERABLE: After additional 2 hits or loss of 30% body part health
+     * - VULNERABLE → HELPLESS: After head trauma, pain >80, or knock-down
+     * - Recovery: HELPLESS → READY over 5 seconds if no additional hits
+     *
+     * @param player - Current player state
+     * @param currentTime - Current timestamp in milliseconds
+     * @returns Current combat readiness state
+     *
+     * @example
+     * ```typescript
+     * const state = combatStateSystem.determineState(player, Date.now());
+     * if (state === CombatReadinessState.HELPLESS) {
+     *   console.log("Player is near incapacitation!");
+     * }
+     * ```
+     *
+     * @public
+     * @korean 상태결정
+     */
+    determineState(player: PlayerState, currentTime?: number): CombatReadinessState;
+    /**
+     * Gets the capability modifiers for a specific combat state.
+     *
+     * Returns all modifiers that should be applied to player actions
+     * based on their current combat readiness.
+     *
+     * @param state - Combat readiness state
+     * @returns Capability modifiers for the state
+     *
+     * @example
+     * ```typescript
+     * const capability = combatStateSystem.getCapability(
+     *   CombatReadinessState.SHAKEN
+     * );
+     *
+     * // Apply to damage calculation
+     * const finalDamage = baseDamage * capability.accuracyModifier;
+     *
+     * // Check if can block
+     * if (!capability.canBlock) {
+     *   console.log("Cannot block in this state!");
+     * }
+     * ```
+     *
+     * @public
+     * @korean 능력조회
+     */
+    getCapability(state: CombatReadinessState): StateCapability;
+    /**
+     * Applies combat state modifiers to a player state.
+     *
+     * Creates a modified player state with capability reductions
+     * based on current combat readiness.
+     *
+     * @param player - Current player state
+     * @param state - Combat readiness state to apply
+     * @returns Modified player state with applied modifiers
+     *
+     * @example
+     * ```typescript
+     * const state = combatStateSystem.determineState(player);
+     * const modifiedPlayer = combatStateSystem.applyStateModifiers(
+     *   player,
+     *   state
+     * );
+     * ```
+     *
+     * @public
+     * @korean 상태적용
+     */
+    applyStateModifiers(player: PlayerState, state: CombatReadinessState): PlayerState;
+    /**
+     * Gets bilingual name for combat state.
+     *
+     * @param state - Combat readiness state
+     * @returns Korean and English state names
+     *
+     * @public
+     * @korean 상태이름
+     */
+    getStateName(state: CombatReadinessState): {
+        korean: string;
+        english: string;
+    };
+    /**
+     * Gets emoji indicator for combat state.
+     *
+     * @param state - Combat readiness state
+     * @returns Emoji representing the state
+     *
+     * @public
+     * @korean 상태아이콘
+     */
+    getStateEmoji(state: CombatReadinessState): string;
+    /**
+     * Counts recent hits within a time window.
+     *
+     * @param player - Current player state
+     * @param currentTime - Current timestamp (milliseconds)
+     * @param timeWindow - Time window to check in milliseconds
+     * @returns Number of hits within the time window
+     *
+     * @private
+     * @korean 최근타격횟수
+     */
+    private countRecentHits;
+    /**
+     * Checks if any body part has lost more than the specified percentage of health.
+     *
+     * @param player - Current player state
+     * @param lossThreshold - Health loss threshold (0.0 to 1.0)
+     * @returns True if any body part has lost more than the threshold
+     *
+     * @private
+     * @korean 신체부위손상확인
+     */
+    private checkBodyPartHealthLoss;
+    /**
+     * Records a hit on the player and updates recent hit tracking.
+     *
+     * Should be called by combat system when player takes a hit.
+     * Maintains a rolling window of the last 10 hit timestamps.
+     *
+     * @param player - Current player state
+     * @param currentTime - Timestamp of the hit
+     * @returns Updated player state with recorded hit
+     *
+     * @public
+     * @korean 타격기록
+     */
+    recordHit(player: PlayerState, currentTime: number): PlayerState;
+    /**
+     * Updates player when entering HELPLESS state.
+     *
+     * Records the timestamp for recovery tracking.
+     *
+     * @param player - Current player state
+     * @param currentTime - Timestamp when entering helpless state
+     * @returns Updated player state
+     *
+     * @public
+     * @korean 무력상태기록
+     */
+    enterHelplessState(player: PlayerState, currentTime: number): PlayerState;
+    /**
+     * Checks if player can recover from HELPLESS state.
+     *
+     * Recovery occurs after 5 seconds with no additional hits.
+     *
+     * @param player - Current player state
+     * @param currentTime - Current timestamp
+     * @returns True if recovery is possible
+     *
+     * @public
+     * @korean 회복가능확인
+     */
+    canRecoverFromHelpless(player: PlayerState, currentTime: number): boolean;
+}
+export default CombatStateSystem;
+//# sourceMappingURL=CombatStateSystem.d.ts.map

package/lib/systems/combat/CombatStateSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatStateSystem.d.ts","sourceRoot":"","sources":["../../../src/systems/combat/CombatStateSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;GAIG;AACH,oBAAY,oBAAoB;IAC9B,+CAA+C;IAC/C,KAAK,UAAU;IACf,8CAA8C;IAC9C,MAAM,WAAW;IACjB,mDAAmD;IACnD,UAAU,eAAe;IACzB,8CAA8C;IAC9C,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,UAAU,eAAe;IACvB,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,8BAA8B;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAyChC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,oBAAoB;IAoF/E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,aAAa,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe;IAI3D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,mBAAmB,CACjB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,oBAAoB,GAC1B,WAAW;IAad;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAuB9E;;;;;;;;OAQG;IACH,aAAa,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM;IAWlD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAevB;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAiC/B;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW;IAahE;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW;IAOzE;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;CAU1E;AAED,eAAe,iBAAiB,CAAC"}