blacktrigram 0.7.2

package/lib/systems/breathing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Breathing Disruption System exports.
+ *
+ * **Korean**: 호흡곤란 시스템 내보내기
+ *
+ * @module systems/breathing
+ * @category Combat Systems
+ */
+export { BreathingDisruptionSystem, BreathingDisruptionLevel, type BreathingDisruptionEffect, } from "./BreathingDisruptionSystem";
+export { causesBreathingDisruption, getBreathingDisruptionLevel, applyBreathingDisruptionFromVitalPoint, applyBreathingDisruptionFromTorsoDamage, updateBreathingDisruption, upgradeLegacyBreathlessness, } from "./integration";
+export { type BreathingIndicatorConfig, type BreathingPostureState, type BreathingAudioEffect, BREATHING_INDICATOR_CONFIGS, BREATHING_POSTURE_STATES, BREATHING_AUDIO_EFFECTS, createBreathingIndicator, getBreathingPosture, getBreathingAudio, } from "./feedback";
+//# sourceMappingURL=index.d.ts.map

package/lib/systems/breathing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/systems/breathing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,sCAAsC,EACtC,uCAAuC,EACvC,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/lib/systems/breathing/index.js

@@ -0,0 +1,3 @@
+import "./BreathingDisruptionSystem.js";
+import "./integration.js";
+import "./feedback.js";

package/lib/systems/breathing/integration.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Integration of Breathing Disruption System with Vital Point System.
+ *
+ * **Korean**: 호흡곤란-급소 통합
+ *
+ * This module bridges the breathing disruption system with the vital point targeting
+ * system, applying appropriate respiratory effects based on which torso vital points
+ * are struck.
+ *
+ * ## Torso Vital Points with Breathing Effects
+ *
+ * - **명치 (Solar Plexus)**: Instant severe disruption (75% penalty, 15s)
+ * - **늑골 (Floating Ribs)**: Moderate disruption (50% penalty, 10s)
+ * - **횡격막 (Diaphragm)**: Severe disruption (75% penalty, 15s)
+ * - **복부 (Abdomen)**: Light disruption (25% penalty, 5s)
+ *
+ * @module systems/breathing/integration
+ * @category Combat Systems
+ * @korean 호흡곤란통합
+ */
+import { VitalPoint } from "../vitalpoint/types";
+import { PlayerState } from "../player";
+import { BreathingDisruptionLevel } from "./BreathingDisruptionSystem";
+/**
+ * Check if a vital point causes breathing disruption.
+ *
+ * @param vitalPointId - ID of the vital point struck
+ * @returns True if this vital point affects breathing
+ */
+export declare function causesBreathingDisruption(vitalPointId: string): boolean;
+/**
+ * Get breathing disruption level for a vital point.
+ *
+ * **Korean**: 급소별 호흡곤란 수준
+ *
+ * @param vitalPointId - ID of the vital point struck
+ * @returns Breathing disruption level, or NONE if not applicable
+ */
+export declare function getBreathingDisruptionLevel(vitalPointId: string): BreathingDisruptionLevel;
+/**
+ * Apply breathing disruption effect from vital point strike.
+ *
+ * **Korean**: 급소 타격으로 호흡곤란 적용
+ *
+ * Creates a breathing disruption effect when a torso vital point is struck.
+ * If player already has breathing disruption, stacks the effects.
+ *
+ * @param player - Player state to modify
+ * @param vitalPoint - Vital point that was struck
+ * @param timestamp - Current game timestamp in milliseconds
+ * @returns Updated player state with breathing disruption effect applied
+ *
+ * @example
+ * ```typescript
+ * // Solar plexus strike causes severe breathing disruption
+ * const updatedPlayer = applyBreathingDisruptionFromVitalPoint(
+ *   player,
+ *   solarPlexusVitalPoint,
+ *   Date.now()
+ * );
+ *
+ * // Player now has 75% stamina regen penalty for 15 seconds
+ * const penalty = BreathingDisruptionSystem.calculateStaminaRegen(
+ *   updatedPlayer,
+ *   10
+ * );
+ * // penalty === 2.5 (25% of normal regen)
+ * ```
+ */
+export declare function applyBreathingDisruptionFromVitalPoint(player: PlayerState, vitalPoint: VitalPoint, timestamp: number): PlayerState;
+/**
+ * Apply breathing disruption from general torso damage.
+ *
+ * **Korean**: 일반 몸통 피해로 호흡곤란 적용
+ *
+ * When torso is hit but no specific vital point is targeted,
+ * calculates appropriate breathing disruption level from damage amount.
+ *
+ * @param player - Current player state
+ * @param damage - Torso damage amount
+ * @param isSolarPlexusArea - Whether strike was near solar plexus
+ * @param timestamp - Current game time
+ * @returns Updated player state with breathing disruption effect
+ *
+ * @example
+ * ```typescript
+ * // Moderate torso strike (15 damage)
+ * const updatedPlayer = applyBreathingDisruptionFromTorsoDamage(
+ *   player,
+ *   15,
+ *   false,
+ *   Date.now()
+ * );
+ *
+ * // Player gets Winded effect (25% penalty for 5s)
+ * ```
+ */
+export declare function applyBreathingDisruptionFromTorsoDamage(player: PlayerState, damage: number, isSolarPlexusArea: boolean, timestamp: number): PlayerState;
+/**
+ * Update breathing disruption effects each frame.
+ *
+ * **Korean**: 호흡곤란 효과 프레임 업데이트
+ *
+ * Handles recovery when torso health > 50% and removes expired effects.
+ * Should be called each game frame (60fps).
+ *
+ * @param player - Current player state
+ * @param deltaTime - Time since last frame (milliseconds)
+ * @param timestamp - Current game time
+ * @returns Updated player state with modified breathing disruption
+ *
+ * @example
+ * ```typescript
+ * // In game loop (60fps)
+ * function gameUpdate(deltaTime: number) {
+ *   player = updateBreathingDisruption(player, deltaTime, Date.now());
+ *
+ *   // Stamina regen now reflects breathing disruption penalty
+ *   const regenRate = BreathingDisruptionSystem.calculateStaminaRegen(
+ *     player,
+ *     BASE_STAMINA_REGEN
+ *   );
+ * }
+ * ```
+ */
+export declare function updateBreathingDisruption(player: PlayerState, deltaTime: number, timestamp: number): PlayerState;
+/**
+ * Replace legacy BREATHLESSNESS effects with new breathing disruption system.
+ *
+ * **Korean**: 구형 호흡곤란 효과를 신규 시스템으로 전환
+ *
+ * Upgrades old-style breathlessness status effects to use the new
+ * breathing disruption system with proper stamina regen penalties.
+ *
+ * @param player - Player state with legacy effects
+ * @param timestamp - Current game time
+ * @returns Player state with upgraded breathing disruption effects
+ */
+export declare function upgradeLegacyBreathlessness(player: PlayerState, timestamp: number): PlayerState;
+//# sourceMappingURL=integration.d.ts.map

package/lib/systems/breathing/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../../src/systems/breathing/integration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAEL,wBAAwB,EAEzB,MAAM,6BAA6B,CAAC;AA8BrC;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,GACnB,wBAAwB,CAK1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,GAChB,WAAW,CA6Cb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uCAAuC,CACrD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,OAAO,EAC1B,SAAS,EAAE,MAAM,GAChB,WAAW,CAgDb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,WAAW,CAuDb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,GAChB,WAAW,CAgDb"}

package/lib/systems/breathing/integration.js

@@ -0,0 +1,194 @@
+import "../../types/index.js";
+import { BreathingDisruptionLevel, BreathingDisruptionSystem } from "./BreathingDisruptionSystem.js";
+//#region src/systems/breathing/integration.ts
+/**
+* Torso vital point IDs that cause breathing disruption.
+* 
+* Maps vital point IDs to their corresponding breathing disruption levels.
+*/
+var BREATHING_DISRUPTION_VITAL_POINTS = {
+	torso_solar_plexus: BreathingDisruptionLevel.SEVERELY_WINDED,
+	torso_floating_ribs: BreathingDisruptionLevel.GASPING,
+	torso_rib_left: BreathingDisruptionLevel.GASPING,
+	torso_rib_right: BreathingDisruptionLevel.GASPING,
+	torso_diaphragm: BreathingDisruptionLevel.SEVERELY_WINDED,
+	torso_abdomen: BreathingDisruptionLevel.WINDED,
+	torso_liver: BreathingDisruptionLevel.WINDED,
+	torso_kidney_left: BreathingDisruptionLevel.WINDED,
+	torso_kidney_right: BreathingDisruptionLevel.WINDED
+};
+/**
+* Check if a vital point causes breathing disruption.
+* 
+* @param vitalPointId - ID of the vital point struck
+* @returns True if this vital point affects breathing
+*/
+function causesBreathingDisruption(vitalPointId) {
+	return vitalPointId in BREATHING_DISRUPTION_VITAL_POINTS;
+}
+/**
+* Get breathing disruption level for a vital point.
+* 
+* **Korean**: 급소별 호흡곤란 수준
+* 
+* @param vitalPointId - ID of the vital point struck
+* @returns Breathing disruption level, or NONE if not applicable
+*/
+function getBreathingDisruptionLevel(vitalPointId) {
+	return BREATHING_DISRUPTION_VITAL_POINTS[vitalPointId] ?? BreathingDisruptionLevel.NONE;
+}
+/**
+* Apply breathing disruption effect from vital point strike.
+* 
+* **Korean**: 급소 타격으로 호흡곤란 적용
+* 
+* Creates a breathing disruption effect when a torso vital point is struck.
+* If player already has breathing disruption, stacks the effects.
+* 
+* @param player - Player state to modify
+* @param vitalPoint - Vital point that was struck
+* @param timestamp - Current game timestamp in milliseconds
+* @returns Updated player state with breathing disruption effect applied
+* 
+* @example
+* ```typescript
+* // Solar plexus strike causes severe breathing disruption
+* const updatedPlayer = applyBreathingDisruptionFromVitalPoint(
+*   player,
+*   solarPlexusVitalPoint,
+*   Date.now()
+* );
+* 
+* // Player now has 75% stamina regen penalty for 15 seconds
+* const penalty = BreathingDisruptionSystem.calculateStaminaRegen(
+*   updatedPlayer,
+*   10
+* );
+* // penalty === 2.5 (25% of normal regen)
+* ```
+*/
+function applyBreathingDisruptionFromVitalPoint(player, vitalPoint, timestamp) {
+	const level = getBreathingDisruptionLevel(vitalPoint.id);
+	if (level === BreathingDisruptionLevel.NONE) return player;
+	const existingEffect = BreathingDisruptionSystem.getActiveEffect(player);
+	let newEffect;
+	if (existingEffect) {
+		newEffect = BreathingDisruptionSystem.stackEffect(existingEffect, level, `${vitalPoint.names.korean} (${vitalPoint.names.english})`, timestamp);
+		const otherEffects = player.statusEffects.filter((effect) => effect.id !== existingEffect.id);
+		return {
+			...player,
+			statusEffects: [...otherEffects, newEffect]
+		};
+	} else {
+		newEffect = BreathingDisruptionSystem.createEffect(level, `${vitalPoint.names.korean} (${vitalPoint.names.english})`, timestamp);
+		return {
+			...player,
+			statusEffects: [...player.statusEffects, newEffect]
+		};
+	}
+}
+/**
+* Apply breathing disruption from general torso damage.
+* 
+* **Korean**: 일반 몸통 피해로 호흡곤란 적용
+* 
+* When torso is hit but no specific vital point is targeted,
+* calculates appropriate breathing disruption level from damage amount.
+* 
+* @param player - Current player state
+* @param damage - Torso damage amount
+* @param isSolarPlexusArea - Whether strike was near solar plexus
+* @param timestamp - Current game time
+* @returns Updated player state with breathing disruption effect
+* 
+* @example
+* ```typescript
+* // Moderate torso strike (15 damage)
+* const updatedPlayer = applyBreathingDisruptionFromTorsoDamage(
+*   player,
+*   15,
+*   false,
+*   Date.now()
+* );
+* 
+* // Player gets Winded effect (25% penalty for 5s)
+* ```
+*/
+function applyBreathingDisruptionFromTorsoDamage(player, damage, isSolarPlexusArea, timestamp) {
+	const level = BreathingDisruptionSystem.calculateLevelFromDamage(damage, isSolarPlexusArea);
+	if (level === BreathingDisruptionLevel.NONE) return player;
+	const existingEffect = BreathingDisruptionSystem.getActiveEffect(player);
+	let newEffect;
+	if (existingEffect) {
+		newEffect = BreathingDisruptionSystem.stackEffect(existingEffect, level, "Torso Strike", timestamp);
+		const otherEffects = player.statusEffects.filter((effect) => effect.id !== existingEffect.id);
+		return {
+			...player,
+			statusEffects: [...otherEffects, newEffect]
+		};
+	} else {
+		newEffect = BreathingDisruptionSystem.createEffect(level, "Torso Strike", timestamp);
+		return {
+			...player,
+			statusEffects: [...player.statusEffects, newEffect]
+		};
+	}
+}
+/**
+* Update breathing disruption effects each frame.
+* 
+* **Korean**: 호흡곤란 효과 프레임 업데이트
+* 
+* Handles recovery when torso health > 50% and removes expired effects.
+* Should be called each game frame (60fps).
+* 
+* @param player - Current player state
+* @param deltaTime - Time since last frame (milliseconds)
+* @param timestamp - Current game time
+* @returns Updated player state with modified breathing disruption
+* 
+* @example
+* ```typescript
+* // In game loop (60fps)
+* function gameUpdate(deltaTime: number) {
+*   player = updateBreathingDisruption(player, deltaTime, Date.now());
+*   
+*   // Stamina regen now reflects breathing disruption penalty
+*   const regenRate = BreathingDisruptionSystem.calculateStaminaRegen(
+*     player,
+*     BASE_STAMINA_REGEN
+*   );
+* }
+* ```
+*/
+function updateBreathingDisruption(player, deltaTime, timestamp) {
+	const activeEffect = BreathingDisruptionSystem.getActiveEffect(player);
+	if (!activeEffect) return player;
+	if (timestamp >= activeEffect.endTime) {
+		const remainingEffects = player.statusEffects.filter((effect) => effect.id !== activeEffect.id);
+		return {
+			...player,
+			statusEffects: remainingEffects
+		};
+	}
+	if (BreathingDisruptionSystem.canRecover(player)) {
+		const recoveredEffect = BreathingDisruptionSystem.applyGradualRecovery(activeEffect, deltaTime, timestamp);
+		if (!recoveredEffect) {
+			const remainingEffects = player.statusEffects.filter((effect) => effect.id !== activeEffect.id);
+			return {
+				...player,
+				statusEffects: remainingEffects
+			};
+		}
+		const otherEffects = player.statusEffects.filter((effect) => effect.id !== activeEffect.id);
+		return {
+			...player,
+			statusEffects: [...otherEffects, recoveredEffect]
+		};
+	}
+	return player;
+}
+//#endregion
+export { applyBreathingDisruptionFromTorsoDamage, applyBreathingDisruptionFromVitalPoint, causesBreathingDisruption, getBreathingDisruptionLevel, updateBreathingDisruption };
+
+//# sourceMappingURL=integration.js.map

package/lib/systems/breathing/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","names":[],"sources":["../../../src/systems/breathing/integration.ts"],"sourcesContent":["/**\n * Integration of Breathing Disruption System with Vital Point System.\n * \n * **Korean**: 호흡곤란-급소 통합\n * \n * This module bridges the breathing disruption system with the vital point targeting\n * system, applying appropriate respiratory effects based on which torso vital points\n * are struck.\n * \n * ## Torso Vital Points with Breathing Effects\n * \n * - **명치 (Solar Plexus)**: Instant severe disruption (75% penalty, 15s)\n * - **늑골 (Floating Ribs)**: Moderate disruption (50% penalty, 10s)\n * - **횡격막 (Diaphragm)**: Severe disruption (75% penalty, 15s)\n * - **복부 (Abdomen)**: Light disruption (25% penalty, 5s)\n * \n * @module systems/breathing/integration\n * @category Combat Systems\n * @korean 호흡곤란통합\n */\n\nimport { VitalPoint } from \"../vitalpoint/types\";\nimport { PlayerState } from \"../player\";\nimport { StatusEffect } from \"../types\";\nimport {\n  BreathingDisruptionSystem,\n  BreathingDisruptionLevel,\n  BreathingDisruptionEffect,\n} from \"./BreathingDisruptionSystem\";\nimport { VitalPointEffectType } from \"@/types\";\n\n/**\n * Torso vital point IDs that cause breathing disruption.\n * \n * Maps vital point IDs to their corresponding breathing disruption levels.\n */\nconst BREATHING_DISRUPTION_VITAL_POINTS: Record<\n  string,\n  BreathingDisruptionLevel\n> = {\n  // Solar plexus - instant severe disruption\n  torso_solar_plexus: BreathingDisruptionLevel.SEVERELY_WINDED,\n  \n  // Floating ribs - moderate disruption\n  torso_floating_ribs: BreathingDisruptionLevel.GASPING,\n  torso_rib_left: BreathingDisruptionLevel.GASPING,\n  torso_rib_right: BreathingDisruptionLevel.GASPING,\n  \n  // Diaphragm - severe disruption\n  torso_diaphragm: BreathingDisruptionLevel.SEVERELY_WINDED,\n  \n  // Lower torso - light disruption\n  torso_abdomen: BreathingDisruptionLevel.WINDED,\n  torso_liver: BreathingDisruptionLevel.WINDED,\n  torso_kidney_left: BreathingDisruptionLevel.WINDED,\n  torso_kidney_right: BreathingDisruptionLevel.WINDED,\n};\n\n/**\n * Check if a vital point causes breathing disruption.\n * \n * @param vitalPointId - ID of the vital point struck\n * @returns True if this vital point affects breathing\n */\nexport function causesBreathingDisruption(vitalPointId: string): boolean {\n  return vitalPointId in BREATHING_DISRUPTION_VITAL_POINTS;\n}\n\n/**\n * Get breathing disruption level for a vital point.\n * \n * **Korean**: 급소별 호흡곤란 수준\n * \n * @param vitalPointId - ID of the vital point struck\n * @returns Breathing disruption level, or NONE if not applicable\n */\nexport function getBreathingDisruptionLevel(\n  vitalPointId: string\n): BreathingDisruptionLevel {\n  return (\n    BREATHING_DISRUPTION_VITAL_POINTS[vitalPointId] ??\n    BreathingDisruptionLevel.NONE\n  );\n}\n\n/**\n * Apply breathing disruption effect from vital point strike.\n * \n * **Korean**: 급소 타격으로 호흡곤란 적용\n * \n * Creates a breathing disruption effect when a torso vital point is struck.\n * If player already has breathing disruption, stacks the effects.\n * \n * @param player - Player state to modify\n * @param vitalPoint - Vital point that was struck\n * @param timestamp - Current game timestamp in milliseconds\n * @returns Updated player state with breathing disruption effect applied\n * \n * @example\n * ```typescript\n * // Solar plexus strike causes severe breathing disruption\n * const updatedPlayer = applyBreathingDisruptionFromVitalPoint(\n *   player,\n *   solarPlexusVitalPoint,\n *   Date.now()\n * );\n * \n * // Player now has 75% stamina regen penalty for 15 seconds\n * const penalty = BreathingDisruptionSystem.calculateStaminaRegen(\n *   updatedPlayer,\n *   10\n * );\n * // penalty === 2.5 (25% of normal regen)\n * ```\n */\nexport function applyBreathingDisruptionFromVitalPoint(\n  player: PlayerState,\n  vitalPoint: VitalPoint,\n  timestamp: number\n): PlayerState {\n  // Check if this vital point causes breathing disruption\n  const level = getBreathingDisruptionLevel(vitalPoint.id);\n  \n  if (level === BreathingDisruptionLevel.NONE) {\n    // No breathing effect from this vital point\n    return player;\n  }\n\n  // Check for existing breathing disruption\n  const existingEffect = BreathingDisruptionSystem.getActiveEffect(player);\n  \n  let newEffect: BreathingDisruptionEffect;\n  \n  if (existingEffect) {\n    // Stack with existing effect\n    newEffect = BreathingDisruptionSystem.stackEffect(\n      existingEffect,\n      level,\n      `${vitalPoint.names.korean} (${vitalPoint.names.english})`,\n      timestamp\n    );\n    \n    // Remove old effect and add stacked effect\n    const otherEffects = player.statusEffects.filter(\n      (effect) => effect.id !== existingEffect.id\n    );\n    \n    return {\n      ...player,\n      statusEffects: [...otherEffects, newEffect],\n    };\n  } else {\n    // Create new breathing disruption effect\n    newEffect = BreathingDisruptionSystem.createEffect(\n      level,\n      `${vitalPoint.names.korean} (${vitalPoint.names.english})`,\n      timestamp\n    );\n    \n    return {\n      ...player,\n      statusEffects: [...player.statusEffects, newEffect],\n    };\n  }\n}\n\n/**\n * Apply breathing disruption from general torso damage.\n * \n * **Korean**: 일반 몸통 피해로 호흡곤란 적용\n * \n * When torso is hit but no specific vital point is targeted,\n * calculates appropriate breathing disruption level from damage amount.\n * \n * @param player - Current player state\n * @param damage - Torso damage amount\n * @param isSolarPlexusArea - Whether strike was near solar plexus\n * @param timestamp - Current game time\n * @returns Updated player state with breathing disruption effect\n * \n * @example\n * ```typescript\n * // Moderate torso strike (15 damage)\n * const updatedPlayer = applyBreathingDisruptionFromTorsoDamage(\n *   player,\n *   15,\n *   false,\n *   Date.now()\n * );\n * \n * // Player gets Winded effect (25% penalty for 5s)\n * ```\n */\nexport function applyBreathingDisruptionFromTorsoDamage(\n  player: PlayerState,\n  damage: number,\n  isSolarPlexusArea: boolean,\n  timestamp: number\n): PlayerState {\n  // Calculate disruption level from damage\n  const level = BreathingDisruptionSystem.calculateLevelFromDamage(\n    damage,\n    isSolarPlexusArea\n  );\n  \n  if (level === BreathingDisruptionLevel.NONE) {\n    // Damage too low to cause breathing disruption\n    return player;\n  }\n\n  // Check for existing breathing disruption\n  const existingEffect = BreathingDisruptionSystem.getActiveEffect(player);\n  \n  let newEffect: BreathingDisruptionEffect;\n  \n  if (existingEffect) {\n    // Stack with existing effect\n    newEffect = BreathingDisruptionSystem.stackEffect(\n      existingEffect,\n      level,\n      \"Torso Strike\",\n      timestamp\n    );\n    \n    // Remove old effect and add stacked effect\n    const otherEffects = player.statusEffects.filter(\n      (effect) => effect.id !== existingEffect.id\n    );\n    \n    return {\n      ...player,\n      statusEffects: [...otherEffects, newEffect],\n    };\n  } else {\n    // Create new breathing disruption effect\n    newEffect = BreathingDisruptionSystem.createEffect(\n      level,\n      \"Torso Strike\",\n      timestamp\n    );\n    \n    return {\n      ...player,\n      statusEffects: [...player.statusEffects, newEffect],\n    };\n  }\n}\n\n/**\n * Update breathing disruption effects each frame.\n * \n * **Korean**: 호흡곤란 효과 프레임 업데이트\n * \n * Handles recovery when torso health > 50% and removes expired effects.\n * Should be called each game frame (60fps).\n * \n * @param player - Current player state\n * @param deltaTime - Time since last frame (milliseconds)\n * @param timestamp - Current game time\n * @returns Updated player state with modified breathing disruption\n * \n * @example\n * ```typescript\n * // In game loop (60fps)\n * function gameUpdate(deltaTime: number) {\n *   player = updateBreathingDisruption(player, deltaTime, Date.now());\n *   \n *   // Stamina regen now reflects breathing disruption penalty\n *   const regenRate = BreathingDisruptionSystem.calculateStaminaRegen(\n *     player,\n *     BASE_STAMINA_REGEN\n *   );\n * }\n * ```\n */\nexport function updateBreathingDisruption(\n  player: PlayerState,\n  deltaTime: number,\n  timestamp: number\n): PlayerState {\n  const activeEffect = BreathingDisruptionSystem.getActiveEffect(player);\n  \n  if (!activeEffect) {\n    // No breathing disruption to update\n    return player;\n  }\n\n  // Check if effect has expired\n  if (timestamp >= activeEffect.endTime) {\n    // Remove expired effect\n    const remainingEffects = player.statusEffects.filter(\n      (effect) => effect.id !== activeEffect.id\n    );\n    \n    return {\n      ...player,\n      statusEffects: remainingEffects,\n    };\n  }\n\n  // Check if player can recover (torso health > 50%)\n  if (BreathingDisruptionSystem.canRecover(player)) {\n    // Apply gradual recovery\n    const recoveredEffect = BreathingDisruptionSystem.applyGradualRecovery(\n      activeEffect,\n      deltaTime,\n      timestamp\n    );\n    \n    if (!recoveredEffect) {\n      // Fully recovered\n      const remainingEffects = player.statusEffects.filter(\n        (effect) => effect.id !== activeEffect.id\n      );\n      \n      return {\n        ...player,\n        statusEffects: remainingEffects,\n      };\n    }\n    \n    // Replace with recovered effect\n    const otherEffects = player.statusEffects.filter(\n      (effect) => effect.id !== activeEffect.id\n    );\n    \n    return {\n      ...player,\n      statusEffects: [...otherEffects, recoveredEffect],\n    };\n  }\n\n  // No recovery, effect continues normally\n  return player;\n}\n\n/**\n * Replace legacy BREATHLESSNESS effects with new breathing disruption system.\n * \n * **Korean**: 구형 호흡곤란 효과를 신규 시스템으로 전환\n * \n * Upgrades old-style breathlessness status effects to use the new\n * breathing disruption system with proper stamina regen penalties.\n * \n * @param player - Player state with legacy effects\n * @param timestamp - Current game time\n * @returns Player state with upgraded breathing disruption effects\n */\nexport function upgradeLegacyBreathlessness(\n  player: PlayerState,\n  timestamp: number\n): PlayerState {\n  // Find legacy breathlessness effects (without breathing disruption level)\n  const legacyEffects = player.statusEffects.filter(\n    (effect): effect is StatusEffect =>\n      effect.type === VitalPointEffectType.BREATHLESSNESS &&\n      !(\"level\" in effect)\n  );\n  \n  if (legacyEffects.length === 0) {\n    return player;\n  }\n\n  // Remove legacy effects\n  const nonLegacyEffects = player.statusEffects.filter(\n    (effect) =>\n      effect.type !== VitalPointEffectType.BREATHLESSNESS ||\n      \"level\" in effect\n  );\n  \n  // Create new breathing disruption effect based on legacy effect intensity\n  const legacyEffect = legacyEffects[0]; // Use first/strongest effect\n  let level: BreathingDisruptionLevel;\n  \n  // Map legacy intensity to new disruption levels\n  switch (legacyEffect.intensity) {\n    case \"high\":\n    case \"severe\":\n    case \"critical\":\n      level = BreathingDisruptionLevel.SEVERELY_WINDED;\n      break;\n    case \"medium\":\n    case \"moderate\":\n      level = BreathingDisruptionLevel.GASPING;\n      break;\n    default:\n      level = BreathingDisruptionLevel.WINDED;\n  }\n  \n  const newEffect = BreathingDisruptionSystem.createEffect(\n    level,\n    legacyEffect.source || \"Legacy Effect\",\n    timestamp\n  );\n  \n  return {\n    ...player,\n    statusEffects: [...nonLegacyEffects, newEffect],\n  };\n}\n"],"mappings":";;;;;;;;AAoCA,IAAM,oCAGF;CAEF,oBAAoB,yBAAyB;CAG7C,qBAAqB,yBAAyB;CAC9C,gBAAgB,yBAAyB;CACzC,iBAAiB,yBAAyB;CAG1C,iBAAiB,yBAAyB;CAG1C,eAAe,yBAAyB;CACxC,aAAa,yBAAyB;CACtC,mBAAmB,yBAAyB;CAC5C,oBAAoB,yBAAyB;CAC9C;;;;;;;AAQD,SAAgB,0BAA0B,cAA+B;AACvE,QAAO,gBAAgB;;;;;;;;;;AAWzB,SAAgB,4BACd,cAC0B;AAC1B,QACE,kCAAkC,iBAClC,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkC7B,SAAgB,uCACd,QACA,YACA,WACa;CAEb,MAAM,QAAQ,4BAA4B,WAAW,GAAG;AAExD,KAAI,UAAU,yBAAyB,KAErC,QAAO;CAIT,MAAM,iBAAiB,0BAA0B,gBAAgB,OAAO;CAExE,IAAI;AAEJ,KAAI,gBAAgB;AAElB,cAAY,0BAA0B,YACpC,gBACA,OACA,GAAG,WAAW,MAAM,OAAO,IAAI,WAAW,MAAM,QAAQ,IACxD,UACD;EAGD,MAAM,eAAe,OAAO,cAAc,QACvC,WAAW,OAAO,OAAO,eAAe,GAC1C;AAED,SAAO;GACL,GAAG;GACH,eAAe,CAAC,GAAG,cAAc,UAAU;GAC5C;QACI;AAEL,cAAY,0BAA0B,aACpC,OACA,GAAG,WAAW,MAAM,OAAO,IAAI,WAAW,MAAM,QAAQ,IACxD,UACD;AAED,SAAO;GACL,GAAG;GACH,eAAe,CAAC,GAAG,OAAO,eAAe,UAAU;GACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BL,SAAgB,wCACd,QACA,QACA,mBACA,WACa;CAEb,MAAM,QAAQ,0BAA0B,yBACtC,QACA,kBACD;AAED,KAAI,UAAU,yBAAyB,KAErC,QAAO;CAIT,MAAM,iBAAiB,0BAA0B,gBAAgB,OAAO;CAExE,IAAI;AAEJ,KAAI,gBAAgB;AAElB,cAAY,0BAA0B,YACpC,gBACA,OACA,gBACA,UACD;EAGD,MAAM,eAAe,OAAO,cAAc,QACvC,WAAW,OAAO,OAAO,eAAe,GAC1C;AAED,SAAO;GACL,GAAG;GACH,eAAe,CAAC,GAAG,cAAc,UAAU;GAC5C;QACI;AAEL,cAAY,0BAA0B,aACpC,OACA,gBACA,UACD;AAED,SAAO;GACL,GAAG;GACH,eAAe,CAAC,GAAG,OAAO,eAAe,UAAU;GACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BL,SAAgB,0BACd,QACA,WACA,WACa;CACb,MAAM,eAAe,0BAA0B,gBAAgB,OAAO;AAEtE,KAAI,CAAC,aAEH,QAAO;AAIT,KAAI,aAAa,aAAa,SAAS;EAErC,MAAM,mBAAmB,OAAO,cAAc,QAC3C,WAAW,OAAO,OAAO,aAAa,GACxC;AAED,SAAO;GACL,GAAG;GACH,eAAe;GAChB;;AAIH,KAAI,0BAA0B,WAAW,OAAO,EAAE;EAEhD,MAAM,kBAAkB,0BAA0B,qBAChD,cACA,WACA,UACD;AAED,MAAI,CAAC,iBAAiB;GAEpB,MAAM,mBAAmB,OAAO,cAAc,QAC3C,WAAW,OAAO,OAAO,aAAa,GACxC;AAED,UAAO;IACL,GAAG;IACH,eAAe;IAChB;;EAIH,MAAM,eAAe,OAAO,cAAc,QACvC,WAAW,OAAO,OAAO,aAAa,GACxC;AAED,SAAO;GACL,GAAG;GACH,eAAe,CAAC,GAAG,cAAc,gBAAgB;GAClD;;AAIH,QAAO"}

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

@@ -0,0 +1,223 @@
+/**
+ * AI Counter-Attack Integration Example
+ *
+ * **Korean**: AI 반격 통합 예제 (AI Banggyeok Tonghap Yeje)
+ *
+ * Demonstrates how the AI DecisionTree can integrate with LimbExposureSystem
+ * to intelligently detect and exploit opponent vulnerabilities during combat.
+ *
+ * This serves as both documentation and a template for implementing
+ * counter-attack awareness in the AI system.
+ *
+ * @module systems/combat/AICounterAttackIntegration
+ * @korean AI반격통합
+ */
+import type { KoreanTechnique } from "../vitalpoint/types";
+import type { PlayerState } from "../player";
+import type { CounterOpportunity } from "../../types/physics";
+/**
+ * Extended combat context with limb exposure awareness.
+ *
+ * **Korean**: 사지 노출 인식 전투 상황
+ *
+ * Extends the existing CombatContext type with information about
+ * opponent's exposed limbs and counter-attack opportunities.
+ */
+export interface CounterAwareCombatContext {
+    /** Player executing technique */
+    readonly player: PlayerState;
+    /** Opponent state */
+    readonly opponent: PlayerState;
+    /** Distance between combatants (meters) */
+    readonly distance: number;
+    /** Opponent's current technique (if executing) */
+    readonly opponentTechnique?: KoreanTechnique;
+    /** Time elapsed in opponent's technique execution (ms) */
+    readonly opponentTechniqueTime?: number;
+    /** Detected counter opportunity (if any) */
+    readonly counterOpportunity?: CounterOpportunity;
+    /** Opponent's current vulnerability multiplier */
+    readonly opponentVulnerability: number;
+}
+/**
+ * Analyze combat context for counter-attack opportunities.
+ *
+ * **Korean**: 반격 기회 분석
+ *
+ * Evaluates the current combat situation to detect if the opponent
+ * has exposed limbs that can be exploited for counter-attacks.
+ *
+ * **TEMPLATE/EXAMPLE IMPLEMENTATION**: This function demonstrates the
+ * integration pattern but requires PlayerState to track currentTechnique
+ * and techniqueElapsedTime fields before it can be fully functional.
+ *
+ * @param player - The AI-controlled player
+ * @param opponent - The opponent player
+ * @param distance - Distance between combatants
+ * @returns Enhanced combat context with counter-attack data
+ *
+ * @remarks
+ * TODO: PlayerState needs to be extended with:
+ * - currentTechnique?: KoreanTechnique
+ * - techniqueElapsedTime?: number
+ * Once these fields exist, remove the undefined assignments and use actual data.
+ *
+ * @example
+ * ```typescript
+ * const context = analyzeCounterOpportunity(aiPlayer, humanPlayer, 0.8);
+ * if (context.counterOpportunity?.allowsBreaking) {
+ *   // AI can execute breaking technique!
+ *   const breakingTechnique = selectBreakingTechnique(context);
+ *   executeTechnique(aiPlayer, breakingTechnique);
+ * }
+ * ```
+ */
+export declare function analyzeCounterOpportunity(player: PlayerState, opponent: PlayerState, distance: number): CounterAwareCombatContext;
+/**
+ * AI decision priorities for counter-attack scenarios.
+ *
+ * **Korean**: AI 반격 우선순위
+ */
+export declare enum CounterAttackPriority {
+    /** Ignore counter, continue offense */
+    IGNORE = 0,
+    /** Low priority, only if perfect opportunity */
+    LOW = 1,
+    /** Medium priority, consider if favorable */
+    MEDIUM = 2,
+    /** High priority, strongly favor counter */
+    HIGH = 3,
+    /** Maximum priority, always counter */
+    CRITICAL = 4
+}
+/**
+ * Determine AI's priority for executing a counter-attack.
+ *
+ * **Korean**: 반격 우선순위 결정
+ *
+ * Calculates how strongly the AI should favor a counter-attack
+ * based on archetype, personality, and opportunity quality.
+ *
+ * @param context - Combat context with counter opportunity
+ * @param aiArchetype - AI's player archetype
+ * @param aiPersonality - AI personality traits
+ * @returns Priority level for counter-attack
+ */
+export declare function calculateCounterPriority(context: CounterAwareCombatContext, aiArchetype: string, aiPersonality: {
+    defensiveness: number;
+    aggression: number;
+}): CounterAttackPriority;
+/**
+ * Select the best counter-technique for the opportunity.
+ *
+ * **Korean**: 최적 반격 기술 선택
+ *
+ * Chooses an appropriate counter-technique from the AI's available
+ * techniques based on the exposed limb and opportunity window.
+ *
+ * @param context - Combat context with counter opportunity
+ * @param availableTechniques - AI's available techniques
+ * @returns Selected counter technique, or undefined if none suitable
+ */
+export declare function selectCounterTechnique(context: CounterAwareCombatContext, availableTechniques: readonly KoreanTechnique[]): KoreanTechnique | undefined;
+/**
+ * Example AI decision flow integrating counter-attacks.
+ *
+ * **Korean**: AI 반격 의사결정 흐름 예제
+ *
+ * Demonstrates a complete decision cycle for an AI combatant
+ * that can recognize and exploit counter-attack opportunities.
+ *
+ * @example
+ * ```typescript
+ * // In AI combat loop:
+ * const context = analyzeCounterOpportunity(ai, human, distance);
+ * const decision = aiDecisionWithCounters(context, ai.techniques);
+ *
+ * if (decision.action === "counter") {
+ *   executeTechnique(ai, decision.technique!);
+ * }
+ * ```
+ */
+export declare function aiDecisionWithCounters(context: CounterAwareCombatContext, availableTechniques: readonly KoreanTechnique[]): {
+    action: "counter" | "attack" | "defend" | "reposition";
+    technique?: KoreanTechnique;
+    reason: string;
+};
+/**
+ * Integration points for existing AI DecisionTree.
+ *
+ * **Korean**: 기존 AI 의사결정 트리 통합 지점
+ */
+export declare const AI_INTEGRATION_POINTS: {
+    /**
+     * 1. CombatContext Enhancement
+     * Extend the existing CombatContext interface with limb exposure data.
+     * Location: src/systems/ai/types.ts
+     */
+    readonly ENHANCE_COMBAT_CONTEXT: "Add counterOpportunity and opponentVulnerability fields";
+    /**
+     * 2. Decision Tree Evaluation
+     * Add counter-attack evaluation before standard action selection.
+     * Location: src/systems/ai/DecisionTree.ts - makeDecision()
+     */
+    readonly EVALUATE_COUNTERS_FIRST: "Call analyzeCounterOpportunity() at decision start";
+    /**
+     * 3. Action Selection Priority
+     * Integrate counter priority with existing action selection logic.
+     * Location: src/systems/ai/DecisionTree.ts - selectAction()
+     */
+    readonly PRIORITIZE_COUNTERS: "Check counter priority before attack/defend decisions";
+    /**
+     * 4. Technique Filtering
+     * Filter available techniques to include counter-specific moves.
+     * Location: src/systems/ai/DecisionTree.ts - selectTechnique()
+     */
+    readonly INCLUDE_COUNTER_TECHNIQUES: "Add breaking techniques to available moves";
+    /**
+     * 5. Personality Tuning
+     * Adjust AI personality traits to influence counter behavior.
+     * Location: src/systems/ai/AIPersonality.ts
+     */
+    readonly TUNE_DEFENSIVENESS: "Defensive archetypes should favor counters";
+};
+declare const _default: {
+    analyzeCounterOpportunity: typeof analyzeCounterOpportunity;
+    calculateCounterPriority: typeof calculateCounterPriority;
+    selectCounterTechnique: typeof selectCounterTechnique;
+    aiDecisionWithCounters: typeof aiDecisionWithCounters;
+    AI_INTEGRATION_POINTS: {
+        /**
+         * 1. CombatContext Enhancement
+         * Extend the existing CombatContext interface with limb exposure data.
+         * Location: src/systems/ai/types.ts
+         */
+        readonly ENHANCE_COMBAT_CONTEXT: "Add counterOpportunity and opponentVulnerability fields";
+        /**
+         * 2. Decision Tree Evaluation
+         * Add counter-attack evaluation before standard action selection.
+         * Location: src/systems/ai/DecisionTree.ts - makeDecision()
+         */
+        readonly EVALUATE_COUNTERS_FIRST: "Call analyzeCounterOpportunity() at decision start";
+        /**
+         * 3. Action Selection Priority
+         * Integrate counter priority with existing action selection logic.
+         * Location: src/systems/ai/DecisionTree.ts - selectAction()
+         */
+        readonly PRIORITIZE_COUNTERS: "Check counter priority before attack/defend decisions";
+        /**
+         * 4. Technique Filtering
+         * Filter available techniques to include counter-specific moves.
+         * Location: src/systems/ai/DecisionTree.ts - selectTechnique()
+         */
+        readonly INCLUDE_COUNTER_TECHNIQUES: "Add breaking techniques to available moves";
+        /**
+         * 5. Personality Tuning
+         * Adjust AI personality traits to influence counter behavior.
+         * Location: src/systems/ai/AIPersonality.ts
+         */
+        readonly TUNE_DEFENSIVENESS: "Defensive archetypes should favor counters";
+    };
+};
+export default _default;
+//# sourceMappingURL=AICounterAttackIntegration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AICounterAttackIntegration.d.ts","sourceRoot":"","sources":["../../../src/systems/combat/AICounterAttackIntegration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQ9D;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC;IAE7C,0DAA0D;IAC1D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAExC,4CAA4C;IAC5C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAEjD,kDAAkD;IAClD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE,MAAM,GACf,yBAAyB,CAgC3B;AAED;;;;GAIG;AACH,oBAAY,qBAAqB;IAC/B,uCAAuC;IACvC,MAAM,IAAI;IAEV,gDAAgD;IAChD,GAAG,IAAI;IAEP,6CAA6C;IAC7C,MAAM,IAAI;IAEV,4CAA4C;IAC5C,IAAI,IAAI;IAER,uCAAuC;IACvC,QAAQ,IAAI;CACb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,EAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3D,qBAAqB,CAkDvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,mBAAmB,EAAE,SAAS,eAAe,EAAE,GAC9C,eAAe,GAAG,SAAS,CAgD7B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,mBAAmB,EAAE,SAAS,eAAe,EAAE,GAC9C;IACD,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;IACvD,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAqDA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;CAEK,CAAC;;;;;;;QAlCT;;;;WAIG;;QAGH;;;;WAIG;;QAGH;;;;WAIG;;QAGH;;;;WAIG;;QAGH;;;;WAIG;;;;AAIL,wBAME"}