blacktrigram 0.7.2

package/lib/systems/animation/systems/FallAnimations.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Fall Animation System for Black Trigram
+ *
+ * Implements realistic fall down animations for knockdowns, leg sweeps,
+ * and loss of consciousness events. Based on Korean martial arts falling
+ * techniques (낙법 - Nakbeop).
+ *
+ * @module systems/animation/FallAnimations
+ * @category Animation
+ * @korean 낙법애니메이션
+ */
+import { TrigramStance } from "../../../types/common";
+import type { FallType } from "../core/types";
+/**
+ * Fall animation impact frame numbers
+ *
+ * Defines which frame in each fall animation represents ground impact.
+ * Used to trigger camera shake, audio, and particle effects.
+ *
+ * @korean 낙법충격프레임
+ */
+export declare const FALL_IMPACT_FRAMES: Record<FallType, number>;
+/**
+ * Determines fall direction from attack vector and player facing
+ *
+ * Calculates which direction the player should fall based on:
+ * - Attack vector (direction of incoming force)
+ * - Player facing direction (from stance)
+ * - Attack impact point (high/low)
+ *
+ * Korean terminology:
+ * - 전방낙법 (Jeonbang Nakbeop): Forward fall from rear attacks
+ * - 후방낙법 (Hubang Nakbeop): Backward fall from frontal attacks
+ * - 측방낙법 (Cheukbang Nakbeop): Side fall from lateral attacks
+ *
+ * @param attackAngle - Angle of attack in radians (0 = from front)
+ * @param playerFacing - Player facing angle in radians
+ * @param attackHeight - Attack height: 'high', 'mid', or 'low'
+ * @returns Fall type to use for animation
+ *
+ * @example
+ * ```typescript
+ * // Attack from behind while facing forward
+ * const fallType = determineFallDirection(Math.PI, 0, 'mid');
+ * // Returns: 'forward' (pushed forward)
+ *
+ * // Attack from front while facing forward
+ * const fallType = determineFallDirection(0, 0, 'mid');
+ * // Returns: 'backward' (pushed backward)
+ *
+ * // Attack from left side
+ * const fallType = determineFallDirection(-Math.PI/2, 0, 'mid');
+ * // Returns: 'side_left'
+ * ```
+ *
+ * @public
+ * @korean 낙법방향결정
+ */
+export declare function determineFallDirection(attackAngle: number, playerFacing: number, attackHeight?: "high" | "mid" | "low"): FallType;
+/**
+ * Determines fall direction from current trigram stance
+ *
+ * Some stances have inherent instability in certain directions.
+ * This function returns likely fall directions when balance is lost.
+ *
+ * Korean stances and fall tendencies:
+ * - 건 (Heaven): Forward bias - aggressive stance
+ * - 태 (Lake): Backward bias - fluid retreating
+ * - 리 (Fire): Forward bias - aggressive advance
+ * - 진 (Thunder): Backward bias - explosive preparation
+ * - 손 (Wind): Side bias - lateral movement
+ * - 감 (Water): Backward bias - defensive flow
+ * - 간 (Mountain): Backward bias - solid defense
+ * - 곤 (Earth): Forward bias - grounding takedowns
+ *
+ * @param stance - Current trigram stance
+ * @param defaultFall - Default fall type if stance doesn't suggest direction
+ * @returns Likely fall direction for the stance
+ *
+ * @public
+ * @korean 자세낙법방향
+ */
+export declare function determineFallFromStance(stance: TrigramStance, defaultFall?: FallType): FallType;
+/**
+ * Fall animation keyframe data structure
+ *
+ * Defines key poses during fall animations for skeletal rendering.
+ * Each keyframe specifies body positions at critical moments.
+ *
+ * @korean 낙법키프레임
+ */
+export interface FallKeyframe {
+    /** Frame number (0-indexed) */
+    readonly frame: number;
+    /** Torso rotation (radians) */
+    readonly torsoRotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Center of mass vertical position (0-1, 1=standing, 0=ground) */
+    readonly centerOfMassHeight: number;
+    /** Description of this keyframe */
+    readonly description: {
+        readonly korean: string;
+        readonly english: string;
+    };
+}
+/**
+ * Forward fall keyframes (전방낙법)
+ *
+ * 24 frames (400ms) sequence:
+ * - Frames 0-8: Forward stumble, losing balance
+ * - Frames 9-15: Knee collapse, forward momentum
+ * - Frames 16-20: Hands extend to brace fall
+ * - Frames 21-23: Impact and settle face-down
+ *
+ * @korean 전방낙법키프레임
+ */
+export declare const FALL_FORWARD_KEYFRAMES: readonly FallKeyframe[];
+/**
+ * Backward fall keyframes (후방낙법)
+ *
+ * 30 frames (500ms) sequence:
+ * - Frames 0-10: Backward stumble, balance loss
+ * - Frames 11-18: Sitting motion begins
+ * - Frames 19-25: Back impact preparation
+ * - Frames 26-29: Full supine position
+ *
+ * @korean 후방낙법키프레임
+ */
+export declare const FALL_BACKWARD_KEYFRAMES: readonly FallKeyframe[];
+/**
+ * Side fall keyframes (측방낙법)
+ *
+ * 27 frames (450ms) sequence:
+ * - Frames 0-9: Side rotation begins
+ * - Frames 10-16: Shoulder roll motion
+ * - Frames 17-22: Hip impact
+ * - Frames 23-26: Side sprawl position
+ *
+ * @korean 측방낙법키프레임
+ */
+export declare const FALL_SIDE_KEYFRAMES: readonly FallKeyframe[];
+/**
+ * Side fall keyframes - RIGHT side (우측 낙법)
+ *
+ * Mirrored version of FALL_SIDE_KEYFRAMES with negated Y and Z rotations
+ * so the character falls to the opposite side.
+ *
+ * @korean 우측낙법키프레임
+ */
+export declare const FALL_SIDE_RIGHT_KEYFRAMES: readonly FallKeyframe[];
+/**
+ * Get keyframes for a specific fall type
+ *
+ * @param fallType - Type of fall animation
+ * @returns Array of keyframes for that fall type
+ *
+ * @public
+ * @korean 낙법키프레임가져오기
+ */
+export declare function getFallKeyframes(fallType: FallType): readonly FallKeyframe[];
+/**
+ * Get impact frame number for fall type
+ *
+ * @param fallType - Type of fall animation
+ * @returns Frame number when ground impact occurs
+ *
+ * @public
+ * @korean 충격프레임가져오기
+ */
+export declare function getImpactFrame(fallType: FallType): number;
+//# sourceMappingURL=FallAnimations.d.ts.map

package/lib/systems/animation/systems/FallAnimations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FallAnimations.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/systems/FallAnimations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAKvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,YAAY,GAAE,MAAM,GAAG,KAAK,GAAG,KAAa,GAC3C,QAAQ,CAmDV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,WAAW,GAAE,QAAqB,GACjC,QAAQ,CAaV;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,QAAQ,CAAC,aAAa,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE5D,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EA8ChD,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,YAAY,EA8CjD,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EA8C7C,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,YAAY,EA8CnD,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,YAAY,EAAE,CAa5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEzD"}

package/lib/systems/animation/systems/FallAnimations.js

@@ -0,0 +1,104 @@
+import { TrigramStance } from "../../../types/common.js";
+//#region src/systems/animation/systems/FallAnimations.ts
+/**
+* Fall Animation System for Black Trigram
+*
+* Implements realistic fall down animations for knockdowns, leg sweeps,
+* and loss of consciousness events. Based on Korean martial arts falling
+* techniques (낙법 - Nakbeop).
+*
+* @module systems/animation/FallAnimations
+* @category Animation
+* @korean 낙법애니메이션
+*/
+/**
+* Determines fall direction from attack vector and player facing
+*
+* Calculates which direction the player should fall based on:
+* - Attack vector (direction of incoming force)
+* - Player facing direction (from stance)
+* - Attack impact point (high/low)
+*
+* Korean terminology:
+* - 전방낙법 (Jeonbang Nakbeop): Forward fall from rear attacks
+* - 후방낙법 (Hubang Nakbeop): Backward fall from frontal attacks
+* - 측방낙법 (Cheukbang Nakbeop): Side fall from lateral attacks
+*
+* @param attackAngle - Angle of attack in radians (0 = from front)
+* @param playerFacing - Player facing angle in radians
+* @param attackHeight - Attack height: 'high', 'mid', or 'low'
+* @returns Fall type to use for animation
+*
+* @example
+* ```typescript
+* // Attack from behind while facing forward
+* const fallType = determineFallDirection(Math.PI, 0, 'mid');
+* // Returns: 'forward' (pushed forward)
+*
+* // Attack from front while facing forward
+* const fallType = determineFallDirection(0, 0, 'mid');
+* // Returns: 'backward' (pushed backward)
+*
+* // Attack from left side
+* const fallType = determineFallDirection(-Math.PI/2, 0, 'mid');
+* // Returns: 'side_left'
+* ```
+*
+* @public
+* @korean 낙법방향결정
+*/
+function determineFallDirection(attackAngle, playerFacing, attackHeight = "mid") {
+	let relativeAngle = attackAngle - playerFacing;
+	while (relativeAngle > Math.PI) relativeAngle -= 2 * Math.PI;
+	while (relativeAngle < -Math.PI) relativeAngle += 2 * Math.PI;
+	const absAngle = Math.abs(relativeAngle);
+	if (attackHeight === "low") {
+		if (Math.abs(relativeAngle) < .01) return "side_right";
+		if (relativeAngle < 0) return "side_left";
+		else return "side_right";
+	}
+	if (attackHeight === "high" && absAngle < Math.PI / 3) return "backward";
+	if (absAngle < Math.PI / 4) return "backward";
+	if (absAngle > 3 * Math.PI / 4) return "forward";
+	if (relativeAngle < 0) return "side_left";
+	else return "side_right";
+}
+/**
+* Determines fall direction from current trigram stance
+*
+* Some stances have inherent instability in certain directions.
+* This function returns likely fall directions when balance is lost.
+*
+* Korean stances and fall tendencies:
+* - 건 (Heaven): Forward bias - aggressive stance
+* - 태 (Lake): Backward bias - fluid retreating
+* - 리 (Fire): Forward bias - aggressive advance
+* - 진 (Thunder): Backward bias - explosive preparation
+* - 손 (Wind): Side bias - lateral movement
+* - 감 (Water): Backward bias - defensive flow
+* - 간 (Mountain): Backward bias - solid defense
+* - 곤 (Earth): Forward bias - grounding takedowns
+*
+* @param stance - Current trigram stance
+* @param defaultFall - Default fall type if stance doesn't suggest direction
+* @returns Likely fall direction for the stance
+*
+* @public
+* @korean 자세낙법방향
+*/
+function determineFallFromStance(stance, defaultFall = "backward") {
+	return {
+		[TrigramStance.GEON]: "forward",
+		[TrigramStance.TAE]: "backward",
+		[TrigramStance.LI]: "forward",
+		[TrigramStance.JIN]: "backward",
+		[TrigramStance.SON]: "side_left",
+		[TrigramStance.GAM]: "backward",
+		[TrigramStance.GAN]: "backward",
+		[TrigramStance.GON]: "forward"
+	}[stance] ?? defaultFall;
+}
+//#endregion
+export { determineFallDirection, determineFallFromStance };
+
+//# sourceMappingURL=FallAnimations.js.map

package/lib/systems/animation/systems/FallAnimations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FallAnimations.js","names":[],"sources":["../../../../src/systems/animation/systems/FallAnimations.ts"],"sourcesContent":["/**\n * Fall Animation System for Black Trigram\n *\n * Implements realistic fall down animations for knockdowns, leg sweeps,\n * and loss of consciousness events. Based on Korean martial arts falling\n * techniques (낙법 - Nakbeop).\n *\n * @module systems/animation/FallAnimations\n * @category Animation\n * @korean 낙법애니메이션\n */\n\nimport { TrigramStance } from \"@/types/common\";\nimport type { FallType } from \"../core/types\";\n\n/**\n * Fall animation impact frame numbers\n *\n * Defines which frame in each fall animation represents ground impact.\n * Used to trigger camera shake, audio, and particle effects.\n *\n * @korean 낙법충격프레임\n */\nexport const FALL_IMPACT_FRAMES: Record<FallType, number> = {\n  forward: 18, // Frame 18 of 24 - hands hit ground\n  backward: 22, // Frame 22 of 30 - back impacts\n  side_left: 20, // Frame 20 of 27 - shoulder/side impacts\n  side_right: 20, // Frame 20 of 27 - shoulder/side impacts\n};\n\n/**\n * Determines fall direction from attack vector and player facing\n *\n * Calculates which direction the player should fall based on:\n * - Attack vector (direction of incoming force)\n * - Player facing direction (from stance)\n * - Attack impact point (high/low)\n *\n * Korean terminology:\n * - 전방낙법 (Jeonbang Nakbeop): Forward fall from rear attacks\n * - 후방낙법 (Hubang Nakbeop): Backward fall from frontal attacks\n * - 측방낙법 (Cheukbang Nakbeop): Side fall from lateral attacks\n *\n * @param attackAngle - Angle of attack in radians (0 = from front)\n * @param playerFacing - Player facing angle in radians\n * @param attackHeight - Attack height: 'high', 'mid', or 'low'\n * @returns Fall type to use for animation\n *\n * @example\n * ```typescript\n * // Attack from behind while facing forward\n * const fallType = determineFallDirection(Math.PI, 0, 'mid');\n * // Returns: 'forward' (pushed forward)\n *\n * // Attack from front while facing forward\n * const fallType = determineFallDirection(0, 0, 'mid');\n * // Returns: 'backward' (pushed backward)\n *\n * // Attack from left side\n * const fallType = determineFallDirection(-Math.PI/2, 0, 'mid');\n * // Returns: 'side_left'\n * ```\n *\n * @public\n * @korean 낙법방향결정\n */\nexport function determineFallDirection(\n  attackAngle: number,\n  playerFacing: number,\n  attackHeight: \"high\" | \"mid\" | \"low\" = \"mid\",\n): FallType {\n  // Calculate relative attack angle (attack direction relative to player facing)\n  let relativeAngle = attackAngle - playerFacing;\n\n  // Normalize to -π to π range\n  while (relativeAngle > Math.PI) relativeAngle -= 2 * Math.PI;\n  while (relativeAngle < -Math.PI) relativeAngle += 2 * Math.PI;\n\n  const absAngle = Math.abs(relativeAngle);\n\n  // Leg sweeps always cause side falls (more realistic for sweeps)\n  if (attackHeight === \"low\") {\n    // Determine which side based on angle\n    // Use a small threshold to avoid edge case at exactly 0\n    // Threshold represents the angle within which we consider the sweep \"frontal\"\n    // 0.01 radians ≈ 0.57 degrees - small enough to only catch near-perfect frontal sweeps\n    // while still allowing accurate left/right determination for most angles\n    const SWEEP_ANGLE_THRESHOLD = 0.01;\n    if (Math.abs(relativeAngle) < SWEEP_ANGLE_THRESHOLD) {\n      // For perfectly frontal sweeps, default to right side fall\n      return \"side_right\";\n    }\n    if (relativeAngle < 0) {\n      return \"side_left\";\n    } else {\n      return \"side_right\";\n    }\n  }\n\n  // High attacks to head often cause backward falls\n  if (attackHeight === \"high\" && absAngle < Math.PI / 3) {\n    return \"backward\";\n  }\n\n  // Determine fall direction based on attack angle\n  // Front quadrant (±45°): Backward fall\n  if (absAngle < Math.PI / 4) {\n    return \"backward\";\n  }\n\n  // Rear quadrant (±45° from back): Forward fall\n  if (absAngle > (3 * Math.PI) / 4) {\n    return \"forward\";\n  }\n\n  // Side quadrants: Side falls\n  if (relativeAngle < 0) {\n    return \"side_left\";\n  } else {\n    return \"side_right\";\n  }\n}\n\n/**\n * Determines fall direction from current trigram stance\n *\n * Some stances have inherent instability in certain directions.\n * This function returns likely fall directions when balance is lost.\n *\n * Korean stances and fall tendencies:\n * - 건 (Heaven): Forward bias - aggressive stance\n * - 태 (Lake): Backward bias - fluid retreating\n * - 리 (Fire): Forward bias - aggressive advance\n * - 진 (Thunder): Backward bias - explosive preparation\n * - 손 (Wind): Side bias - lateral movement\n * - 감 (Water): Backward bias - defensive flow\n * - 간 (Mountain): Backward bias - solid defense\n * - 곤 (Earth): Forward bias - grounding takedowns\n *\n * @param stance - Current trigram stance\n * @param defaultFall - Default fall type if stance doesn't suggest direction\n * @returns Likely fall direction for the stance\n *\n * @public\n * @korean 자세낙법방향\n */\nexport function determineFallFromStance(\n  stance: TrigramStance,\n  defaultFall: FallType = \"backward\",\n): FallType {\n  const stanceFallBias: Record<TrigramStance, FallType> = {\n    [TrigramStance.GEON]: \"forward\", // Heaven - aggressive forward\n    [TrigramStance.TAE]: \"backward\", // Lake - fluid retreat\n    [TrigramStance.LI]: \"forward\", // Fire - aggressive strike\n    [TrigramStance.JIN]: \"backward\", // Thunder - explosive back\n    [TrigramStance.SON]: \"side_left\", // Wind - lateral pressure\n    [TrigramStance.GAM]: \"backward\", // Water - flowing back\n    [TrigramStance.GAN]: \"backward\", // Mountain - defensive back\n    [TrigramStance.GON]: \"forward\", // Earth - forward throws\n  };\n\n  return stanceFallBias[stance] ?? defaultFall;\n}\n\n/**\n * Fall animation keyframe data structure\n *\n * Defines key poses during fall animations for skeletal rendering.\n * Each keyframe specifies body positions at critical moments.\n *\n * @korean 낙법키프레임\n */\nexport interface FallKeyframe {\n  /** Frame number (0-indexed) */\n  readonly frame: number;\n\n  /** Torso rotation (radians) */\n  readonly torsoRotation: { x: number; y: number; z: number };\n\n  /** Center of mass vertical position (0-1, 1=standing, 0=ground) */\n  readonly centerOfMassHeight: number;\n\n  /** Description of this keyframe */\n  readonly description: {\n    readonly korean: string;\n    readonly english: string;\n  };\n}\n\n/**\n * Forward fall keyframes (전방낙법)\n *\n * 24 frames (400ms) sequence:\n * - Frames 0-8: Forward stumble, losing balance\n * - Frames 9-15: Knee collapse, forward momentum\n * - Frames 16-20: Hands extend to brace fall\n * - Frames 21-23: Impact and settle face-down\n *\n * @korean 전방낙법키프레임\n */\nexport const FALL_FORWARD_KEYFRAMES: readonly FallKeyframe[] = [\n  {\n    frame: 0,\n    torsoRotation: { x: 0, y: 0, z: 0 },\n    centerOfMassHeight: 0.9,\n    description: {\n      korean: \"초기 자세\",\n      english: \"Initial stance\",\n    },\n  },\n  {\n    frame: 8,\n    torsoRotation: { x: 0.3, y: 0, z: 0 }, // Leaning forward\n    centerOfMassHeight: 0.75,\n    description: {\n      korean: \"전방으로 비틀거림\",\n      english: \"Forward stumble\",\n    },\n  },\n  {\n    frame: 15,\n    torsoRotation: { x: 0.7, y: 0, z: 0 }, // Falling forward\n    centerOfMassHeight: 0.4,\n    description: {\n      korean: \"무릎 붕괴\",\n      english: \"Knee collapse\",\n    },\n  },\n  {\n    frame: 18,\n    torsoRotation: { x: 1.2, y: 0, z: 0 }, // Hands extending\n    centerOfMassHeight: 0.15,\n    description: {\n      korean: \"손으로 지면 충격 완화\",\n      english: \"Hands brace impact\",\n    },\n  },\n  {\n    frame: 23,\n    torsoRotation: { x: 1.57, y: 0, z: 0 }, // Face down (90° forward)\n    centerOfMassHeight: 0.05,\n    description: {\n      korean: \"엎드려 정지\",\n      english: \"Face-down prone\",\n    },\n  },\n] as const;\n\n/**\n * Backward fall keyframes (후방낙법)\n *\n * 30 frames (500ms) sequence:\n * - Frames 0-10: Backward stumble, balance loss\n * - Frames 11-18: Sitting motion begins\n * - Frames 19-25: Back impact preparation\n * - Frames 26-29: Full supine position\n *\n * @korean 후방낙법키프레임\n */\nexport const FALL_BACKWARD_KEYFRAMES: readonly FallKeyframe[] = [\n  {\n    frame: 0,\n    torsoRotation: { x: 0, y: 0, z: 0 },\n    centerOfMassHeight: 0.9,\n    description: {\n      korean: \"초기 자세\",\n      english: \"Initial stance\",\n    },\n  },\n  {\n    frame: 10,\n    torsoRotation: { x: -0.2, y: 0, z: 0 }, // Leaning back\n    centerOfMassHeight: 0.8,\n    description: {\n      korean: \"후방으로 비틀거림\",\n      english: \"Backward stumble\",\n    },\n  },\n  {\n    frame: 18,\n    torsoRotation: { x: -0.6, y: 0, z: 0 }, // Sitting motion\n    centerOfMassHeight: 0.45,\n    description: {\n      korean: \"앉는 동작\",\n      english: \"Sitting motion\",\n    },\n  },\n  {\n    frame: 22,\n    torsoRotation: { x: -1.2, y: 0, z: 0 }, // Back impact\n    centerOfMassHeight: 0.2,\n    description: {\n      korean: \"등 충격\",\n      english: \"Back impact\",\n    },\n  },\n  {\n    frame: 29,\n    torsoRotation: { x: -1.57, y: 0, z: 0 }, // Face up (90° back)\n    centerOfMassHeight: 0.05,\n    description: {\n      korean: \"누워 정지\",\n      english: \"Supine position\",\n    },\n  },\n] as const;\n\n/**\n * Side fall keyframes (측방낙법)\n *\n * 27 frames (450ms) sequence:\n * - Frames 0-9: Side rotation begins\n * - Frames 10-16: Shoulder roll motion\n * - Frames 17-22: Hip impact\n * - Frames 23-26: Side sprawl position\n *\n * @korean 측방낙법키프레임\n */\nexport const FALL_SIDE_KEYFRAMES: readonly FallKeyframe[] = [\n  {\n    frame: 0,\n    torsoRotation: { x: 0, y: 0, z: 0 },\n    centerOfMassHeight: 0.9,\n    description: {\n      korean: \"초기 자세\",\n      english: \"Initial stance\",\n    },\n  },\n  {\n    frame: 9,\n    torsoRotation: { x: 0, y: 0.3, z: 0.4 }, // Side rotation\n    centerOfMassHeight: 0.7,\n    description: {\n      korean: \"측면 회전 시작\",\n      english: \"Side rotation begins\",\n    },\n  },\n  {\n    frame: 16,\n    torsoRotation: { x: 0.2, y: 0.8, z: 0.9 }, // Shoulder roll\n    centerOfMassHeight: 0.4,\n    description: {\n      korean: \"어깨 구르기\",\n      english: \"Shoulder roll\",\n    },\n  },\n  {\n    frame: 20,\n    torsoRotation: { x: 0.3, y: 1.2, z: 1.3 }, // Hip impact\n    centerOfMassHeight: 0.2,\n    description: {\n      korean: \"엉덩이 충격\",\n      english: \"Hip impact\",\n    },\n  },\n  {\n    frame: 26,\n    torsoRotation: { x: 0, y: 1.57, z: 1.57 }, // Side position (90° roll)\n    centerOfMassHeight: 0.05,\n    description: {\n      korean: \"측면 정지\",\n      english: \"Side sprawl\",\n    },\n  },\n] as const;\n\n/**\n * Side fall keyframes - RIGHT side (우측 낙법)\n *\n * Mirrored version of FALL_SIDE_KEYFRAMES with negated Y and Z rotations\n * so the character falls to the opposite side.\n *\n * @korean 우측낙법키프레임\n */\nexport const FALL_SIDE_RIGHT_KEYFRAMES: readonly FallKeyframe[] = [\n  {\n    frame: 0,\n    torsoRotation: { x: 0, y: 0, z: 0 },\n    centerOfMassHeight: 0.9,\n    description: {\n      korean: \"초기 자세\",\n      english: \"Initial stance\",\n    },\n  },\n  {\n    frame: 9,\n    torsoRotation: { x: 0, y: -0.3, z: -0.4 }, // Opposite side rotation\n    centerOfMassHeight: 0.7,\n    description: {\n      korean: \"우측 회전 시작\",\n      english: \"Right side rotation begins\",\n    },\n  },\n  {\n    frame: 16,\n    torsoRotation: { x: 0.2, y: -0.8, z: -0.9 }, // Opposite shoulder roll\n    centerOfMassHeight: 0.4,\n    description: {\n      korean: \"우측 어깨 구르기\",\n      english: \"Right shoulder roll\",\n    },\n  },\n  {\n    frame: 20,\n    torsoRotation: { x: 0.3, y: -1.2, z: -1.3 }, // Opposite hip impact\n    centerOfMassHeight: 0.2,\n    description: {\n      korean: \"우측 엉덩이 충격\",\n      english: \"Right hip impact\",\n    },\n  },\n  {\n    frame: 26,\n    torsoRotation: { x: 0, y: -1.57, z: -1.57 }, // Right side position (-90° roll)\n    centerOfMassHeight: 0.05,\n    description: {\n      korean: \"우측 정지\",\n      english: \"Right side sprawl\",\n    },\n  },\n] as const;\n\n/**\n * Get keyframes for a specific fall type\n *\n * @param fallType - Type of fall animation\n * @returns Array of keyframes for that fall type\n *\n * @public\n * @korean 낙법키프레임가져오기\n */\nexport function getFallKeyframes(fallType: FallType): readonly FallKeyframe[] {\n  switch (fallType) {\n    case \"forward\":\n      return FALL_FORWARD_KEYFRAMES;\n    case \"backward\":\n      return FALL_BACKWARD_KEYFRAMES;\n    case \"side_left\":\n      return FALL_SIDE_KEYFRAMES;\n    case \"side_right\":\n      return FALL_SIDE_RIGHT_KEYFRAMES;\n    default:\n      return FALL_BACKWARD_KEYFRAMES;\n  }\n}\n\n/**\n * Get impact frame number for fall type\n *\n * @param fallType - Type of fall animation\n * @returns Frame number when ground impact occurs\n *\n * @public\n * @korean 충격프레임가져오기\n */\nexport function getImpactFrame(fallType: FallType): number {\n  return FALL_IMPACT_FRAMES[fallType];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,SAAgB,uBACd,aACA,cACA,eAAuC,OAC7B;CAEV,IAAI,gBAAgB,cAAc;AAGlC,QAAO,gBAAgB,KAAK,GAAI,kBAAiB,IAAI,KAAK;AAC1D,QAAO,gBAAgB,CAAC,KAAK,GAAI,kBAAiB,IAAI,KAAK;CAE3D,MAAM,WAAW,KAAK,IAAI,cAAc;AAGxC,KAAI,iBAAiB,OAAO;AAO1B,MAAI,KAAK,IAAI,cAAc,GADG,IAG5B,QAAO;AAET,MAAI,gBAAgB,EAClB,QAAO;MAEP,QAAO;;AAKX,KAAI,iBAAiB,UAAU,WAAW,KAAK,KAAK,EAClD,QAAO;AAKT,KAAI,WAAW,KAAK,KAAK,EACvB,QAAO;AAIT,KAAI,WAAY,IAAI,KAAK,KAAM,EAC7B,QAAO;AAIT,KAAI,gBAAgB,EAClB,QAAO;KAEP,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA2BX,SAAgB,wBACd,QACA,cAAwB,YACd;AAYV,QAXwD;GACrD,cAAc,OAAO;GACrB,cAAc,MAAM;GACpB,cAAc,KAAK;GACnB,cAAc,MAAM;GACpB,cAAc,MAAM;GACpB,cAAc,MAAM;GACpB,cAAc,MAAM;GACpB,cAAc,MAAM;EACtB,CAEqB,WAAW"}

package/lib/systems/animation/systems/HeadMovements.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Head movement animations for combat reactions
+ *
+ * Provides realistic head movement animations:
+ * - Recoil from strikes
+ * - Nods during attacks
+ * - Head shakes when stunned
+ * - Tilts to avoid hits
+ * - Tracking opponent position
+ *
+ * @module systems/animation/HeadMovements
+ * @category Animation System
+ * @korean 머리움직임애니메이션
+ */
+import * as THREE from "three";
+import { HeadMovementType, type HeadMovementKeyframes } from "../../../types/facial";
+/**
+ * Generate head recoil animation from hit
+ *
+ * Creates keyframes for head snapping back when struck.
+ * Intensity based on hit strength.
+ *
+ * @param hitStrength - Strength of hit (0-1)
+ * @param hitDirection - Direction vector of hit (normalized)
+ * @returns Head movement keyframes for recoil animation
+ *
+ * @example
+ * ```typescript
+ * const recoil = createHeadRecoilAnimation(0.8, new THREE.Vector3(1, 0, 0));
+ * // Creates strong recoil animation to the right
+ * ```
+ *
+ * @public
+ * @korean 머리반동애니메이션생성
+ */
+export declare const createHeadRecoilAnimation: (hitStrength: number, hitDirection?: THREE.Vector3) => HeadMovementKeyframes;
+/**
+ * Generate head nod animation for attacks
+ *
+ * Creates subtle forward nod during attack commitment.
+ * Represents weight shift and attack intention.
+ *
+ * @param intensity - Nod intensity (0-1)
+ * @returns Head movement keyframes for nod animation
+ *
+ * @public
+ * @korean 머리끄덕임애니메이션생성
+ */
+export declare const createHeadNodAnimation: (intensity?: number) => HeadMovementKeyframes;
+/**
+ * Generate head shake animation for stun/disorientation
+ *
+ * Creates side-to-side head shake when stunned or disoriented.
+ *
+ * @param intensity - Shake intensity (0-1)
+ * @returns Head movement keyframes for shake animation
+ *
+ * @public
+ * @korean 머리흔들기애니메이션생성
+ */
+export declare const createHeadShakeAnimation: (intensity?: number) => HeadMovementKeyframes;
+/**
+ * Generate head tilt animation for dodging
+ *
+ * Creates quick head tilt to avoid incoming strike.
+ *
+ * @param direction - Tilt direction ("left" or "right")
+ * @param intensity - Tilt intensity (0-1)
+ * @returns Head movement keyframes for tilt animation
+ *
+ * @public
+ * @korean 머리기울임애니메이션생성
+ */
+export declare const createHeadTiltAnimation: (direction: "left" | "right", intensity?: number) => HeadMovementKeyframes;
+/**
+ * Generate head turn animation for opponent tracking
+ *
+ * Creates smooth head turn to face opponent.
+ *
+ * @param targetAngle - Target yaw angle in radians
+ * @param currentAngle - Current yaw angle in radians
+ * @returns Head movement keyframes for turn animation
+ *
+ * @public
+ * @korean 머리돌리기애니메이션생성
+ */
+export declare const createHeadTurnAnimation: (targetAngle: number, currentAngle?: number) => HeadMovementKeyframes;
+/**
+ * Generate head drop animation for knockout
+ *
+ * Creates head dropping forward when fighter is knocked out.
+ *
+ * @returns Head movement keyframes for drop animation
+ *
+ * @public
+ * @korean 머리떨어짐애니메이션생성
+ */
+export declare const createHeadDropAnimation: () => HeadMovementKeyframes;
+/**
+ * Calculate smooth head rotation toward target
+ *
+ * Uses linear interpolation (lerp) for smooth head turning.
+ * Each Euler angle component is interpolated independently.
+ *
+ * @param currentRotation - Current head rotation
+ * @param targetPosition - Position to look at
+ * @param headPosition - Current head position in world space
+ * @param smoothing - Smoothing factor (0-1, lower = smoother)
+ * @returns New head rotation
+ *
+ * @public
+ * @korean 부드러운머리회전계산
+ */
+export declare const calculateSmoothHeadRotation: (currentRotation: THREE.Euler, targetPosition: THREE.Vector3, headPosition: THREE.Vector3, smoothing?: number) => THREE.Euler;
+/**
+ * Apply head movement keyframe at given time
+ *
+ * Interpolates between keyframes for smooth animation.
+ *
+ * @param animation - Head movement keyframes
+ * @param currentTime - Current animation time (seconds)
+ * @returns Interpolated head rotation
+ *
+ * @public
+ * @korean 머리움직임키프레임적용
+ */
+export declare const applyHeadMovementKeyframe: (animation: HeadMovementKeyframes, currentTime: number) => THREE.Euler;
+/**
+ * Check if head movement animation is complete
+ *
+ * @param animation - Head movement keyframes
+ * @param currentTime - Current animation time (seconds)
+ * @returns True if animation is complete
+ *
+ * @public
+ * @korean 머리움직임완료확인
+ */
+export declare const isHeadMovementComplete: (animation: HeadMovementKeyframes, currentTime: number) => boolean;
+/**
+ * Get head movement animation by type
+ *
+ * Convenience function to create animation by type with default parameters.
+ *
+ * @param type - Type of head movement
+ * @param intensity - Animation intensity (0-1)
+ * @returns Head movement keyframes
+ *
+ * @public
+ * @korean 타입별머리움직임가져오기
+ */
+export declare const getHeadMovementByType: (type: HeadMovementType, intensity?: number) => HeadMovementKeyframes;
+//# sourceMappingURL=HeadMovements.d.ts.map

package/lib/systems/animation/systems/HeadMovements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeadMovements.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/systems/HeadMovements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,GACpC,aAAa,MAAM,EACnB,eAAe,KAAK,CAAC,OAAO,KAC3B,qBA2BF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,kBAAe,KACd,qBAiBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GACnC,kBAAe,KACd,qBAqBF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,WAAW,MAAM,GAAG,OAAO,EAC3B,kBAAe,KACd,qBAiBF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,aAAa,MAAM,EACnB,qBAAgB,KACf,qBAyBF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,QAAO,qBAiB1C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,GACtC,iBAAiB,KAAK,CAAC,KAAK,EAC5B,gBAAgB,KAAK,CAAC,OAAO,EAC7B,cAAc,KAAK,CAAC,OAAO,EAC3B,kBAAe,KACd,KAAK,CAAC,KAyBR,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GACpC,WAAW,qBAAqB,EAChC,aAAa,MAAM,KAClB,KAAK,CAAC,KAsCR,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GACjC,WAAW,qBAAqB,EAChC,aAAa,MAAM,KAClB,OAEF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,gBAAgB,EACtB,kBAAe,KACd,qBAiBF,CAAC"}

package/lib/systems/animation/systems/HeadMovements.js

@@ -0,0 +1,2 @@
+import "../../../types/facial.js";
+import "three";

package/lib/systems/animation/systems/MuscleActivation.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Muscle activation system for realistic combat physiology
+ *
+ * Maps Korean martial arts techniques to anatomically accurate muscle activation patterns.
+ * Manages dynamic muscle tension, stamina effects, and smooth relaxation transitions.
+ * Includes stance-specific leg muscle tension for isometric holds and weight-bearing.
+ *
+ * @module systems/animation/MuscleActivation
+ * @category Combat Animation
+ * @korean 근육활성화시스템
+ */
+import type { TrigramStance } from "../../../types/common";
+import type { MuscleActivationMap, MuscleActivationState, MuscleGroupName, MuscleSystemConfig } from "../../../types/muscle";
+/**
+ * Get leg muscle tension for a specific trigram stance
+ *
+ * Calculates realistic leg muscle activation based on stance biomechanics:
+ * - Weight distribution (체중부하) - Which leg bears more load
+ * - Knee flexion angles (무릎굽힘각도) - Deep stances require more tension
+ * - Isometric contraction (등척성수축) - Holding positions activates muscles
+ *
+ * Based on authentic Korean martial arts stance mechanics:
+ * - Deep stances (Jin 90°, Gon 80°) = High quad/calf tension
+ * - Front-weighted (Geon 60/40) = Front leg emphasis
+ * - Back-weighted (Tae 10/90, Gam 30/70) = Back leg emphasis
+ *
+ * @param stance - Trigram stance (e.g., TrigramStance.GEON)
+ * @returns Map of leg muscle groups to tension levels (0-1)
+ *
+ * @example
+ * ```typescript
+ * const jinMuscles = getMuscleTensionForStance(TrigramStance.JIN);
+ * // Returns: Map {
+ * //   "QUAD_L" => 0.90,  // Deep 90° knee bend
+ * //   "QUAD_R" => 0.90,  // Equal weight distribution
+ * //   "CALF_L" => 0.85,  // Isometric hold
+ * //   "CALF_R" => 0.85,
+ * //   "HAMSTRING_L" => 0.45,
+ * //   "HAMSTRING_R" => 0.45,
+ * //   "GLUTE_L" => 0.40,
+ * //   "GLUTE_R" => 0.40
+ * // }
+ * ```
+ *
+ * @korean 자세다리근육긴장도
+ */
+export declare const getMuscleTensionForStance: (stance: TrigramStance) => MuscleActivationMap;
+/**
+ * Get muscle activation mapping for a specific Korean martial arts technique
+ *
+ * Maps technique names to muscle groups with tension levels (0-1 scale).
+ * Based on authentic Korean martial arts (Taekwondo, Hapkido, Taekyon).
+ *
+ * @param technique - Technique name (e.g., "jab", "cross", "front_kick", "block")
+ * @returns Map of muscle groups to target tension levels
+ *
+ * @example
+ * ```typescript
+ * const jabMuscles = getMuscleActivationForTechnique("jab");
+ * // Returns: Map {
+ * //   "SHOULDER_R" => 0.7,
+ * //   "BICEP_R" => 1.0,
+ * //   "TRICEP_R" => 0.8,
+ * //   "CORE" => 0.5
+ * // }
+ * ```
+ *
+ * @korean 기법근육활성화가져오기
+ */
+export declare const getMuscleActivationForTechnique: (technique: string) => MuscleActivationMap;
+/**
+ * Muscle activation manager for real-time combat physiology
+ *
+ * Manages 60fps muscle tension updates, stamina effects, and smooth transitions.
+ * Optimized for performance with ref-based updates to avoid React re-renders.
+ *
+ * @korean 근육활성화관리자
+ */
+export declare class MuscleActivationManager {
+    private activations;
+    private config;
+    private scratchMap;
+    /**
+     * Create a new muscle activation manager
+     *
+     * @param config - Optional configuration (uses defaults if not provided)
+     * @korean 생성자
+     */
+    constructor(config?: Partial<MuscleSystemConfig>);
+    /**
+     * Update muscle activations for a technique at 60fps
+     *
+     * @param technique - Technique name
+     * @param stamina - Current stamina (0-100)
+     * @param delta - Time since last frame in seconds
+     *
+     * @korean 업데이트
+     */
+    update(technique: string, stamina: number, delta: number): void;
+    /**
+     * Gradually relax all muscles to idle state
+     *
+     * Used after technique completion with configurable delay.
+     *
+     * @param delta - Time since last frame in seconds
+     *
+     * @korean 근육이완
+     */
+    relaxAllMuscles(delta: number): void;
+    /**
+     * Get current tension for a specific muscle group
+     *
+     * @param muscleGroup - Muscle group name
+     * @returns Current tension (0-1) or 0 if not found
+     *
+     * @korean 긴장도가져오기
+     */
+    getTension(muscleGroup: MuscleGroupName): number;
+    /**
+     * Get shaking state for a specific muscle group
+     *
+     * @param muscleGroup - Muscle group name
+     * @returns Whether muscle is shaking
+     *
+     * @korean 흔들림상태가져오기
+     */
+    isShaking(muscleGroup: MuscleGroupName): boolean;
+    /**
+     * Get all current muscle activations
+     *
+     * @returns Map of muscle groups to current states
+     *
+     * @korean 모든활성화가져오기
+     */
+    getAllActivations(): ReadonlyMap<MuscleGroupName, MuscleActivationState>;
+    /**
+     * Get reusable scratch map with current tension values for state sync
+     *
+     * Populates and returns a reusable Map to avoid allocations during state sync.
+     * This map is cleared and repopulated on each call.
+     *
+     * @returns Reusable Map with current tension values
+     *
+     * @korean 상태동기화맵가져오기
+     */
+    getScratchMapForSync(): Map<string, number>;
+    /**
+     * Reset all muscles to relaxed state immediately
+     *
+     * @korean 즉시이완
+     */
+    reset(): void;
+    /**
+     * Dispose of the muscle activation system
+     *
+     * Clears all internal state and references to prevent memory leaks.
+     * Should be called when the system is no longer needed (e.g., component unmount).
+     *
+     * @korean 근육시스템해제
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=MuscleActivation.d.ts.map

package/lib/systems/animation/systems/MuscleActivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MuscleActivation.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/systems/MuscleActivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAsBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,aAAa,KACpB,mBAuGF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,+BAA+B,GAC1C,WAAW,MAAM,KAChB,mBAoKF,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAsB;IAExC;;;;;OAKG;gBACS,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAoDpD;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAgC/D;;;;;;;;OAQG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAiBpC;;;;;;;OAOG;IACH,UAAU,CAAC,WAAW,EAAE,eAAe,GAAG,MAAM;IAIhD;;;;;;;OAOG;IACH,SAAS,CAAC,WAAW,EAAE,eAAe,GAAG,OAAO;IAIhD;;;;;;OAMG;IACH,iBAAiB,IAAI,WAAW,CAAC,eAAe,EAAE,qBAAqB,CAAC;IAIxE;;;;;;;;;OASG;IACH,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ3C;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAIhB"}