blacktrigram 0.7.2

package/lib/systems/animation/core/RecoveryPhaseEnhancer.js

@@ -0,0 +1,122 @@
+import * as THREE from "three";
+//#region src/systems/animation/core/RecoveryPhaseEnhancer.ts
+/**
+* Recovery Phase Enhancement for Black Trigram Animations
+*
+* Implements realistic recovery animations following Korean martial arts principles:
+* - 균형회복 (Gyunhyeong Hoebog) - Balance restoration
+* - 자세복귀 (Jase Bokgwi) - Stance return
+* - 호흡조절 (Hoheup Jojoel) - Breath control during recovery
+* - 근육이완 (Geunryuk Ihwan) - Muscle relaxation after tension
+*
+* @module systems/animation/RecoveryPhaseEnhancer
+* @category Animation System
+* @korean 복귀애니메이션강화
+*/
+/**
+* Default recovery phase configuration
+* Based on Korean martial arts recovery principles
+*
+* **Korean**: 기본 복귀 설정
+*/
+var DEFAULT_RECOVERY_CONFIG = {
+	duration: .22,
+	intermediateReturnPercent: .8,
+	peakMuscleTension: 1,
+	intermediateMuscleTension: .4,
+	finalMuscleTension: .1,
+	useEaseOut: true
+};
+/**
+* Add realistic recovery phase to technique animation
+*
+* **Korean**: 기술 애니메이션에 복귀 단계 추가
+*
+* Enhances technique animations with proper recovery phases following
+* Korean martial arts principles of 복귀 (Bokgwi - recovery/return).
+*
+* The recovery phase consists of two keyframes:
+* 1. **Intermediate recovery** (60% of recovery duration):
+*    - Returns 80% toward neutral position
+*    - Reduces muscle tension to 40%
+*    - Uses ease-out for gradual deceleration
+*
+* 2. **Final recovery** (100% of recovery duration):
+*    - Fully returns to neutral stance
+*    - Relaxes muscle tension to 10%
+*    - Completes breath cycle
+*
+* @param animation - Base technique animation
+* @param config - Recovery phase configuration options
+* @returns Enhanced animation with recovery phase
+*
+* @example
+* ```typescript
+* // Add default 220ms recovery to front kick
+* const kickWithRecovery = addRecoveryPhase(FRONT_KICK_ANIMATION);
+*
+* // Add custom 180ms recovery with faster muscle release
+* const quickRecovery = addRecoveryPhase(JAB_ANIMATION, {
+*   duration: 0.18,
+*   intermediateMuscleTension: 0.3,
+*   finalMuscleTension: 0.05,
+* });
+* ```
+*
+* @korean 복귀단계추가
+*/
+function addRecoveryPhase(animation, config = {}) {
+	const finalConfig = {
+		...DEFAULT_RECOVERY_CONFIG,
+		...config
+	};
+	if (animation.keyframes.length < 2) {
+		if (process.env.NODE_ENV !== "test") console.warn(`Animation "${animation.name}" has fewer than 2 keyframes. Recovery phase not added.`);
+		return animation;
+	}
+	const lastKeyframe = animation.keyframes[animation.keyframes.length - 1];
+	const peakKeyframe = animation.keyframes[animation.keyframes.length - 2];
+	const recoveryStartTime = lastKeyframe.time;
+	const intermediateTime = recoveryStartTime + finalConfig.duration * .6;
+	const finalTime = recoveryStartTime + finalConfig.duration;
+	const intermediateFrame = {
+		time: intermediateTime,
+		easing: finalConfig.useEaseOut ? "ease-out" : "linear",
+		boneRotations: /* @__PURE__ */ new Map(),
+		bonePositions: /* @__PURE__ */ new Map()
+	};
+	peakKeyframe.boneRotations.forEach((rotation, bone) => {
+		const intermediate = new THREE.Euler(rotation.x * (1 - finalConfig.intermediateReturnPercent), rotation.y * (1 - finalConfig.intermediateReturnPercent), rotation.z * (1 - finalConfig.intermediateReturnPercent), rotation.order);
+		intermediateFrame.boneRotations.set(bone, intermediate);
+	});
+	if (peakKeyframe.bonePositions) peakKeyframe.bonePositions.forEach((position, bone) => {
+		const returnPercent = finalConfig.intermediateReturnPercent;
+		const intermediate = new THREE.Vector3(position.x * (1 - returnPercent), position.y * (1 - returnPercent), position.z * (1 - returnPercent));
+		intermediateFrame.bonePositions.set(bone, intermediate);
+	});
+	const finalFrame = {
+		time: finalTime,
+		easing: finalConfig.useEaseOut ? "ease-out" : "linear",
+		boneRotations: /* @__PURE__ */ new Map(),
+		bonePositions: /* @__PURE__ */ new Map()
+	};
+	peakKeyframe.boneRotations.forEach((rotation, bone) => {
+		finalFrame.boneRotations.set(bone, new THREE.Euler(0, 0, 0, rotation.order));
+	});
+	if (peakKeyframe.bonePositions) peakKeyframe.bonePositions.forEach((_, bone) => {
+		finalFrame.bonePositions.set(bone, new THREE.Vector3(0, 0, 0));
+	});
+	return {
+		...animation,
+		duration: finalTime,
+		keyframes: [
+			...animation.keyframes,
+			intermediateFrame,
+			finalFrame
+		]
+	};
+}
+//#endregion
+export { addRecoveryPhase };
+
+//# sourceMappingURL=RecoveryPhaseEnhancer.js.map

package/lib/systems/animation/core/RecoveryPhaseEnhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecoveryPhaseEnhancer.js","names":[],"sources":["../../../../src/systems/animation/core/RecoveryPhaseEnhancer.ts"],"sourcesContent":["/**\n * Recovery Phase Enhancement for Black Trigram Animations\n *\n * Implements realistic recovery animations following Korean martial arts principles:\n * - 균형회복 (Gyunhyeong Hoebog) - Balance restoration\n * - 자세복귀 (Jase Bokgwi) - Stance return\n * - 호흡조절 (Hoheup Jojoel) - Breath control during recovery\n * - 근육이완 (Geunryuk Ihwan) - Muscle relaxation after tension\n *\n * @module systems/animation/RecoveryPhaseEnhancer\n * @category Animation System\n * @korean 복귀애니메이션강화\n */\n\nimport * as THREE from \"three\";\nimport type {\n  AnimationKeyframe,\n  SkeletalAnimation,\n} from \"@/types/skeletal\";\n\n/**\n * Recovery phase configuration options\n *\n * **Korean**: 복귀 설정\n *\n * @public\n * @category Animation\n * @korean 복귀설정\n */\nexport interface RecoveryPhaseConfig {\n  /**\n   * Duration of recovery phase in seconds (default: 0.2s = 200ms)\n   * Recommended range: 0.15 - 0.25 seconds\n   * **Korean**: 복귀 시간\n   */\n  readonly duration?: number;\n\n  /**\n   * Percentage of return in intermediate keyframe (default: 0.8 = 80%)\n   * **Korean**: 중간 복귀 비율\n   */\n  readonly intermediateReturnPercent?: number;\n\n  /**\n   * Initial muscle tension level at peak technique (default: 1.0 = 100%)\n   * **Korean**: 최대 근육 긴장도\n   */\n  readonly peakMuscleTension?: number;\n\n  /**\n   * Muscle tension at intermediate recovery (default: 0.4 = 40%)\n   * **Korean**: 중간 근육 긴장도\n   */\n  readonly intermediateMuscleTension?: number;\n\n  /**\n   * Final muscle tension in relaxed state (default: 0.1 = 10%)\n   * **Korean**: 최종 근육 긴장도\n   */\n  readonly finalMuscleTension?: number;\n\n  /**\n   * Whether to use ease-out interpolation (default: true)\n   * **Korean**: 부드러운 감속 사용\n   */\n  readonly useEaseOut?: boolean;\n}\n\n/**\n * Default recovery phase configuration\n * Based on Korean martial arts recovery principles\n *\n * **Korean**: 기본 복귀 설정\n */\nconst DEFAULT_RECOVERY_CONFIG: Required<RecoveryPhaseConfig> = {\n  duration: 0.22, // 220ms - optimal for realistic recovery\n  intermediateReturnPercent: 0.8, // 80% back to neutral\n  peakMuscleTension: 1.0, // 100% tension at technique peak\n  intermediateMuscleTension: 0.4, // 40% tension during recovery\n  finalMuscleTension: 0.1, // 10% relaxed state\n  useEaseOut: true,\n};\n\n/**\n * Add realistic recovery phase to technique animation\n *\n * **Korean**: 기술 애니메이션에 복귀 단계 추가\n *\n * Enhances technique animations with proper recovery phases following\n * Korean martial arts principles of 복귀 (Bokgwi - recovery/return).\n *\n * The recovery phase consists of two keyframes:\n * 1. **Intermediate recovery** (60% of recovery duration):\n *    - Returns 80% toward neutral position\n *    - Reduces muscle tension to 40%\n *    - Uses ease-out for gradual deceleration\n *\n * 2. **Final recovery** (100% of recovery duration):\n *    - Fully returns to neutral stance\n *    - Relaxes muscle tension to 10%\n *    - Completes breath cycle\n *\n * @param animation - Base technique animation\n * @param config - Recovery phase configuration options\n * @returns Enhanced animation with recovery phase\n *\n * @example\n * ```typescript\n * // Add default 220ms recovery to front kick\n * const kickWithRecovery = addRecoveryPhase(FRONT_KICK_ANIMATION);\n *\n * // Add custom 180ms recovery with faster muscle release\n * const quickRecovery = addRecoveryPhase(JAB_ANIMATION, {\n *   duration: 0.18,\n *   intermediateMuscleTension: 0.3,\n *   finalMuscleTension: 0.05,\n * });\n * ```\n *\n * @korean 복귀단계추가\n */\nexport function addRecoveryPhase(\n  animation: SkeletalAnimation,\n  config: RecoveryPhaseConfig = {}\n): SkeletalAnimation {\n  // Merge with defaults\n  const finalConfig: Required<RecoveryPhaseConfig> = {\n    ...DEFAULT_RECOVERY_CONFIG,\n    ...config,\n  };\n\n  // Validate animation has at least 2 keyframes\n  if (animation.keyframes.length < 2) {\n    // In production, this would use proper logging system\n    // For now, using console.warn is acceptable for development\n    // Suppress console output during tests to avoid cluttering test output\n    // Note: In test environments, proper assertions should validate this condition\n    if (process.env.NODE_ENV !== \"test\") {\n      console.warn(\n        `Animation \"${animation.name}\" has fewer than 2 keyframes. Recovery phase not added.`\n      );\n    }\n    return animation;\n  }\n\n  const lastKeyframe = animation.keyframes[animation.keyframes.length - 1];\n  const peakKeyframe = animation.keyframes[animation.keyframes.length - 2];\n\n  // Calculate recovery timing\n  const recoveryStartTime = lastKeyframe.time;\n  const intermediateTime = recoveryStartTime + finalConfig.duration * 0.6;\n  const finalTime = recoveryStartTime + finalConfig.duration;\n\n  // Create intermediate recovery keyframe (80% back to neutral)\n  const intermediateFrame: AnimationKeyframe = {\n    time: intermediateTime,\n    easing: finalConfig.useEaseOut ? \"ease-out\" : \"linear\",\n    boneRotations: new Map(),\n    bonePositions: new Map(),\n  };\n\n  // Interpolate bone rotations 80% toward neutral\n  peakKeyframe.boneRotations.forEach((rotation, bone) => {\n    const intermediate = new THREE.Euler(\n      rotation.x * (1 - finalConfig.intermediateReturnPercent),\n      rotation.y * (1 - finalConfig.intermediateReturnPercent),\n      rotation.z * (1 - finalConfig.intermediateReturnPercent),\n      rotation.order\n    );\n    intermediateFrame.boneRotations.set(bone, intermediate);\n  });\n\n  // Interpolate bone positions 80% toward rest\n  if (peakKeyframe.bonePositions) {\n    peakKeyframe.bonePositions.forEach((position, bone) => {\n      // Manual interpolation instead of Vector3.lerp() because bonePositions map\n      // may contain objects that aren't true THREE.Vector3 instances with prototype methods.\n      // This approach ensures compatibility with any object having x, y, z properties.\n      const returnPercent = finalConfig.intermediateReturnPercent;\n      const intermediate = new THREE.Vector3(\n        position.x * (1 - returnPercent),\n        position.y * (1 - returnPercent),\n        position.z * (1 - returnPercent)\n      );\n      intermediateFrame.bonePositions.set(bone, intermediate);\n    });\n  }\n\n  // Create final recovery frame (100% neutral)\n  const finalFrame: AnimationKeyframe = {\n    time: finalTime,\n    easing: finalConfig.useEaseOut ? \"ease-out\" : \"linear\",\n    boneRotations: new Map(),\n    bonePositions: new Map(),\n  };\n\n  // All bones return to neutral (0 rotation)\n  peakKeyframe.boneRotations.forEach((rotation, bone) => {\n    finalFrame.boneRotations.set(\n      bone,\n      new THREE.Euler(0, 0, 0, rotation.order)\n    );\n  });\n\n  // All positions return to rest\n  if (peakKeyframe.bonePositions) {\n    peakKeyframe.bonePositions.forEach((_, bone) => {\n      finalFrame.bonePositions.set(bone, new THREE.Vector3(0, 0, 0));\n    });\n  }\n\n  // Build enhanced animation\n  return {\n    ...animation,\n    duration: finalTime,\n    keyframes: [...animation.keyframes, intermediateFrame, finalFrame],\n  };\n}\n\n/**\n * Create technique animation with recovery phase\n *\n * **Korean**: 복귀 단계를 포함한 기술 애니메이션 생성\n *\n * Convenience function that wraps animation creation with automatic recovery phase.\n * Use this when creating new technique animations from scratch.\n *\n * @param baseAnimation - Base animation without recovery\n * @param config - Recovery configuration\n * @returns Complete animation with recovery phase\n *\n * @example\n * ```typescript\n * // Create front kick with recovery\n * const frontKick = createTechniqueWithRecovery(\n *   baseFrontKickAnimation,\n *   { duration: 0.22 }\n * );\n * ```\n *\n * @korean 복귀단계기술생성\n */\nexport function createTechniqueWithRecovery(\n  baseAnimation: SkeletalAnimation,\n  config: RecoveryPhaseConfig = {}\n): SkeletalAnimation {\n  return addRecoveryPhase(baseAnimation, config);\n}\n\n/**\n * Validate recovery phase quality\n *\n * **Korean**: 복귀 단계 품질 검증\n *\n * Checks if an animation has proper recovery phase characteristics:\n * - Has at least 2 recovery keyframes\n * - Recovery duration between 150-250ms\n * - Uses ease-out interpolation\n * - Returns to neutral position\n *\n * @param animation - Animation to validate\n * @returns Validation result with details\n *\n * @korean 복귀품질검증\n */\nexport interface RecoveryValidationResult {\n  /** Whether animation has valid recovery phase */\n  readonly isValid: boolean;\n  /** Validation issues found */\n  readonly issues: string[];\n  /** Recovery duration in milliseconds */\n  readonly recoveryDuration: number;\n  /** Number of recovery keyframes */\n  readonly recoveryKeyframes: number;\n}\n\n/**\n * Validate recovery phase in animation\n *\n * @param animation - Animation to validate\n * @returns Validation result\n *\n * @korean 복귀검증\n */\nexport function validateRecoveryPhase(\n  animation: SkeletalAnimation\n): RecoveryValidationResult {\n  const issues: string[] = [];\n\n  if (animation.keyframes.length < 3) {\n    issues.push(\n      \"Animation has fewer than 3 keyframes (needs at least 3 for recovery)\"\n    );\n    return {\n      isValid: false,\n      issues,\n      recoveryDuration: 0,\n      recoveryKeyframes: 0,\n    };\n  }\n\n  // Recovery phase is from the third-to-last keyframe (peak) to last keyframe (final recovery)\n  // This is because addRecoveryPhase adds TWO keyframes: intermediate and final\n  const lastKeyframe = animation.keyframes[animation.keyframes.length - 1];\n  const thirdLastKeyframe = animation.keyframes[animation.keyframes.length - 3];\n\n  const recoveryDuration = (lastKeyframe.time - thirdLastKeyframe.time) * 1000; // ms\n\n  // Validate duration\n  if (recoveryDuration < 150) {\n    issues.push(\n      `Recovery duration too short: ${recoveryDuration.toFixed(\n        0\n      )}ms (minimum: 150ms)`\n    );\n  }\n  if (recoveryDuration > 250) {\n    issues.push(\n      `Recovery duration too long: ${recoveryDuration.toFixed(\n        0\n      )}ms (maximum: 250ms)`\n    );\n  }\n\n  // Validate easing - both ease-out and ease-in are acceptable for recovery\n  // ease-out is preferred but ease-in can also work for final deceleration\n  const acceptableEasings = [\"ease-out\", \"ease-in\"];\n  if (!acceptableEasings.includes(lastKeyframe.easing ?? \"\")) {\n    issues.push(\n      `Last keyframe should use ease-out or ease-in interpolation, found: ${lastKeyframe.easing}`\n    );\n  }\n\n  // Validate return to neutral\n  let hasNonZeroRotation = false;\n  lastKeyframe.boneRotations.forEach((rotation) => {\n    if (\n      Math.abs(rotation.x) > 0.01 ||\n      Math.abs(rotation.y) > 0.01 ||\n      Math.abs(rotation.z) > 0.01\n    ) {\n      hasNonZeroRotation = true;\n    }\n  });\n\n  if (hasNonZeroRotation) {\n    issues.push(\"Final keyframe should return to neutral position (0, 0, 0)\");\n  }\n\n  return {\n    isValid: issues.length === 0,\n    issues,\n    recoveryDuration,\n    recoveryKeyframes: 2,\n  };\n}\n\n/**\n * Calculate muscle tension at specific time in animation\n *\n * **Korean**: 애니메이션 시간별 근육 긴장도 계산\n *\n * Interpolates muscle tension based on animation progress and recovery phase.\n * Tension peaks during technique execution and gradually releases during recovery.\n *\n * @param animation - Animation with recovery phase\n * @param currentTime - Current time in animation (seconds)\n * @param config - Recovery configuration used\n * @returns Muscle tension value (0.0 to 1.0)\n *\n * @korean 근육긴장도계산\n */\nexport function calculateMuscleTension(\n  animation: SkeletalAnimation,\n  currentTime: number,\n  config: RecoveryPhaseConfig = {}\n): number {\n  const finalConfig = { ...DEFAULT_RECOVERY_CONFIG, ...config };\n\n  if (animation.keyframes.length < 2) {\n    return finalConfig.finalMuscleTension;\n  }\n\n  // Recovery phase starts at the third-to-last keyframe (after peak)\n  const lastKeyframe = animation.keyframes[animation.keyframes.length - 1];\n  const recoveryStartTime =\n    animation.keyframes.length >= 3\n      ? animation.keyframes[animation.keyframes.length - 3].time\n      : animation.keyframes[animation.keyframes.length - 2].time;\n\n  // Before recovery: peak tension\n  if (currentTime < recoveryStartTime) {\n    return finalConfig.peakMuscleTension;\n  }\n\n  // During recovery: interpolate from peak to relaxed\n  const recoveryProgress =\n    (currentTime - recoveryStartTime) / (lastKeyframe.time - recoveryStartTime);\n  const clampedProgress = Math.max(0, Math.min(1, recoveryProgress));\n\n  // Use ease-out curve for natural muscle release\n  const easedProgress = 1 - Math.pow(1 - clampedProgress, 2);\n\n  // Interpolate tension\n  if (easedProgress < 0.6) {\n    // First 60%: peak -> intermediate\n    const t = easedProgress / 0.6;\n    return (\n      finalConfig.peakMuscleTension +\n      (finalConfig.intermediateMuscleTension - finalConfig.peakMuscleTension) *\n        t\n    );\n  } else {\n    // Last 40%: intermediate -> final\n    const t = (easedProgress - 0.6) / 0.4;\n    return (\n      finalConfig.intermediateMuscleTension +\n      (finalConfig.finalMuscleTension - finalConfig.intermediateMuscleTension) *\n        t\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA0EA,IAAM,0BAAyD;CAC7D,UAAU;CACV,2BAA2B;CAC3B,mBAAmB;CACnB,2BAA2B;CAC3B,oBAAoB;CACpB,YAAY;CACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCD,SAAgB,iBACd,WACA,SAA8B,EAAE,EACb;CAEnB,MAAM,cAA6C;EACjD,GAAG;EACH,GAAG;EACJ;AAGD,KAAI,UAAU,UAAU,SAAS,GAAG;AAKlC,MAAA,QAAA,IAAA,aAA6B,OAC3B,SAAQ,KACN,cAAc,UAAU,KAAK,yDAC9B;AAEH,SAAO;;CAGT,MAAM,eAAe,UAAU,UAAU,UAAU,UAAU,SAAS;CACtE,MAAM,eAAe,UAAU,UAAU,UAAU,UAAU,SAAS;CAGtE,MAAM,oBAAoB,aAAa;CACvC,MAAM,mBAAmB,oBAAoB,YAAY,WAAW;CACpE,MAAM,YAAY,oBAAoB,YAAY;CAGlD,MAAM,oBAAuC;EAC3C,MAAM;EACN,QAAQ,YAAY,aAAa,aAAa;EAC9C,+BAAe,IAAI,KAAK;EACxB,+BAAe,IAAI,KAAK;EACzB;AAGD,cAAa,cAAc,SAAS,UAAU,SAAS;EACrD,MAAM,eAAe,IAAI,MAAM,MAC7B,SAAS,KAAK,IAAI,YAAY,4BAC9B,SAAS,KAAK,IAAI,YAAY,4BAC9B,SAAS,KAAK,IAAI,YAAY,4BAC9B,SAAS,MACV;AACD,oBAAkB,cAAc,IAAI,MAAM,aAAa;GACvD;AAGF,KAAI,aAAa,cACf,cAAa,cAAc,SAAS,UAAU,SAAS;EAIrD,MAAM,gBAAgB,YAAY;EAClC,MAAM,eAAe,IAAI,MAAM,QAC7B,SAAS,KAAK,IAAI,gBAClB,SAAS,KAAK,IAAI,gBAClB,SAAS,KAAK,IAAI,eACnB;AACD,oBAAkB,cAAc,IAAI,MAAM,aAAa;GACvD;CAIJ,MAAM,aAAgC;EACpC,MAAM;EACN,QAAQ,YAAY,aAAa,aAAa;EAC9C,+BAAe,IAAI,KAAK;EACxB,+BAAe,IAAI,KAAK;EACzB;AAGD,cAAa,cAAc,SAAS,UAAU,SAAS;AACrD,aAAW,cAAc,IACvB,MACA,IAAI,MAAM,MAAM,GAAG,GAAG,GAAG,SAAS,MAAM,CACzC;GACD;AAGF,KAAI,aAAa,cACf,cAAa,cAAc,SAAS,GAAG,SAAS;AAC9C,aAAW,cAAc,IAAI,MAAM,IAAI,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC;GAC9D;AAIJ,QAAO;EACL,GAAG;EACH,UAAU;EACV,WAAW;GAAC,GAAG,UAAU;GAAW;GAAmB;GAAW;EACnE"}

package/lib/systems/animation/core/TechniqueAnimationMapper.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Technique Animation Mapper
+ *
+ * Maps 70 Korean techniques to appropriate attack animation types.
+ * Implements the technique-to-animation link system for authentic martial arts animations.
+ *
+ * @module systems/animation/TechniqueAnimationMapper
+ * @category Animation System
+ * @korean 기술애니메이션매퍼
+ */
+import { AttackAnimationType } from "../../../types/skeletal";
+/**
+ * Get skeletal animation name for an attack animation type
+ *
+ * @param animationType - Attack animation type enum
+ * @returns Name of skeletal animation from ATTACK_ANIMATIONS map
+ *
+ * @public
+ * @korean 애니메이션타입에서이름가져오기
+ */
+export declare function getAnimationNameForType(animationType: AttackAnimationType): string;
+/**
+ * Check if an animation type has a defined animation
+ *
+ * @param animationType - Attack animation type enum
+ * @returns True if animation exists in ATTACK_ANIMATIONS map
+ *
+ * @public
+ * @korean 애니메이션존재확인
+ */
+export declare function hasAnimationForType(animationType: AttackAnimationType): boolean;
+/**
+ * Determines appropriate animation type from technique characteristics
+ *
+ * Uses technique name, damage type, and keywords to automatically
+ * select the best-matching attack animation type.
+ *
+ * @param techniqueName - English or Korean technique name
+ * @param techniqueId - Technique ID
+ * @param damageType - Type of damage dealt
+ * @returns Best-matching attack animation type
+ *
+ * @public
+ * @korean 기술에서애니메이션타입결정
+ */
+export declare function determineAnimationTypeForTechnique(techniqueName: string, techniqueId: string, damageType?: string): AttackAnimationType;
+/**
+ * Calculates animation speed modifier based on technique power level
+ *
+ * Implements the rule:
+ * - Light techniques (damage <20): 1.2x speed
+ * - Normal techniques (damage 20-35): 1.0x speed
+ * - Heavy techniques (damage >35): 0.8x speed
+ *
+ * @param damage - Base damage of the technique
+ * @returns Speed modifier (0.8 - 1.2)
+ *
+ * @public
+ * @korean 기술위력에서속도배율계산
+ */
+export declare function calculateSpeedModifierForDamage(damage: number): number;
+/**
+ * Get animation duration adjusted by speed modifier
+ *
+ * @param baseAnimationName - Name of base animation
+ * @param speedModifier - Speed multiplier (0.8 - 1.2)
+ * @returns Adjusted duration in milliseconds
+ *
+ * @public
+ * @korean 조정된애니메이션지속시간
+ */
+export declare function getAdjustedAnimationDuration(baseAnimationName: string, speedModifier: number): number;
+import { MappingValidationResult, TechniqueAnimation, TechniqueAnimationKey } from "./types";
+/**
+ * Comprehensive Technique Animation Mapper Class
+ *
+ * **Korean**: 기술 애니메이션 매퍼 클래스
+ *
+ * Provides O(1) lookup for all 1024 technique-stance combinations
+ * with intelligent fallback system and build-time validation.
+ *
+ * @class
+ * @public
+ */
+export declare class TechniqueAnimationMapper {
+    /** Primary animation mapping table */
+    private readonly animationMap;
+    /** Fallback animations by technique type */
+    private readonly fallbackMap;
+    /** Cache for generated combinations (validation) */
+    private allCombinationsCache?;
+    constructor();
+    /**
+     * Get animation for specific technique
+     *
+     * **Korean**: 특정 기술의 애니메이션 가져오기
+     *
+     * Uses 3-tier lookup strategy:
+     * 1. Exact match (stance + type + part + intensity)
+     * 2. Intensity-agnostic (stance + type + part + medium intensity)
+     * 3. Technique type fallback (generic animation for technique type)
+     *
+     * @param key - Technique animation key
+     * @returns Technique animation configuration
+     *
+     * @public
+     * @korean 애니메이션가져오기
+     */
+    getAnimation(key: TechniqueAnimationKey): TechniqueAnimation;
+    /**
+     * Create composite lookup key from technique animation key
+     *
+     * **Korean**: 복합 조회 키 생성
+     *
+     * Format: "stance-type-part-intensity"
+     * Example: "geon-strike-head-heavy"
+     *
+     * @param key - Technique animation key
+     * @returns Composite lookup string
+     *
+     * @private
+     */
+    private createLookupKey;
+    /**
+     * Initialize fallback animations by technique type
+     *
+     * **Korean**: 기술 유형별 대체 애니메이션 초기화
+     *
+     * @private
+     */
+    private initializeFallbacks;
+    /**
+     * Initialize complete mapping table
+     *
+     * **Korean**: 전체 매핑 테이블 초기화
+     *
+     * Maps all 1024 combinations organized by:
+     * - 8 stances
+     * - 4 technique types
+     * - 8 body parts
+     * - 4 intensity levels
+     *
+     * Uses data-driven STANCE_ANIMATION_CONFIG to eliminate code duplication.
+     *
+     * @private
+     */
+    private initializeCompleteMapping;
+    /**
+     * Add single technique mapping to the map with automatic rotation calculation
+     *
+     * **Korean**: 단일 기술 매핑 추가
+     *
+     * @private
+     */
+    private mapTechnique;
+    /**
+     * Get duration based on intensity level
+     *
+     * **Korean**: 강도 레벨에 따른 지속시간 가져오기
+     *
+     * @private
+     */
+    private getDurationForIntensity;
+    /**
+     * Get impact frame based on intensity level
+     *
+     * **Korean**: 강도 레벨에 따른 충격 프레임 가져오기
+     *
+     * @private
+     */
+    private getImpactFrameForIntensity;
+    /**
+     * Get recovery frames based on intensity level
+     *
+     * **Korean**: 강도 레벨에 따른 회복 프레임 가져오기
+     *
+     * @private
+     */
+    private getRecoveryFramesForIntensity;
+    /**
+     * Calculate torso rotation for stance-technique combination
+     *
+     * **Korean**: 자세-기술 조합의 허리 회전 계산
+     *
+     * Returns rotation in radians (-π/2 to π/2)
+     *
+     * @private
+     */
+    private getTorsoRotationForStanceTechnique;
+    /**
+     * Calculate hip engagement for stance-technique combination
+     *
+     * **Korean**: 자세-기술 조합의 골반 참여도 계산
+     *
+     * Returns engagement factor (0-1)
+     *
+     * @private
+     */
+    private getHipEngagementForStanceTechnique;
+    /**
+     * Calculate power modifier from hip engagement
+     *
+     * **Korean**: 골반 참여도로부터 파워 배율 계산
+     *
+     * Based on PR #1132 calculateHipRotationPowerModifier system
+     *
+     * @private
+     */
+    private calculatePowerModifier;
+    /**
+     * Generate Korean technique name
+     *
+     * **Korean**: 한글 기술 이름 생성
+     *
+     * Format: "스탠스 신체부위 강도 기술유형"
+     * Example: "건괘 두부 강 타격"
+     *
+     * @private
+     */
+    private generateKoreanName;
+    /**
+     * Generate English technique name
+     *
+     * Format: "Stance BodyPart Intensity TechniqueType"
+     * Example: "Heaven Head Heavy Strike"
+     *
+     * @private
+     */
+    private generateEnglishName;
+    /**
+     * Get Korean intensity name
+     *
+     * @private
+     */
+    private getIntensityKorean;
+    /**
+     * Adjust animation for different intensity
+     *
+     * **Korean**: 강도에 따른 애니메이션 조정
+     *
+     * @private
+     */
+    private adjustForIntensity;
+    /**
+     * Get duration multiplier for intensity
+     *
+     * @private
+     */
+    private getDurationMultiplierForIntensity;
+    /**
+     * Get fallback animation when no exact match
+     *
+     * **Korean**: 일치하는 항목이 없을 때 대체 애니메이션 가져오기
+     *
+     * @private
+     */
+    private getFallbackAnimation;
+    /**
+     * Generate all possible technique combinations
+     *
+     * **Korean**: 모든 가능한 기술 조합 생성
+     *
+     * @private
+     */
+    private generateAllCombinations;
+    /**
+     * Validate mapping completeness at build time
+     *
+     * **Korean**: 빌드 시간에 매핑 완전성 검증
+     *
+     * Reports coverage percentage and lists missing mappings.
+     * Expected: 8 stances × 4 technique types × 8 body parts × 4 intensities = 1024 combinations
+     *
+     * @returns Validation result with coverage and missing mappings
+     *
+     * @public
+     * @korean 완전성검증
+     */
+    validateCompleteness(): MappingValidationResult;
+    /**
+     * Get total number of mapped combinations
+     *
+     * **Korean**: 매핑된 조합의 총 개수 가져오기
+     *
+     * @returns Number of mapped combinations
+     *
+     * @public
+     */
+    getMappedCount(): number;
+}
+/**
+ * Singleton instance of TechniqueAnimationMapper
+ *
+ * **Korean**: 기술 애니메이션 매퍼 싱글톤 인스턴스
+ *
+ * Use this instance throughout the application for consistent
+ * technique animation mapping.
+ *
+ * @public
+ * @korean 싱글톤인스턴스
+ */
+export declare const techniqueAnimationMapper: TechniqueAnimationMapper;
+//# sourceMappingURL=TechniqueAnimationMapper.d.ts.map

package/lib/systems/animation/core/TechniqueAnimationMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TechniqueAnimationMapper.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/core/TechniqueAnimationMapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAmCvD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,mBAAmB,GACjC,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,mBAAmB,GACjC,OAAO,CAGT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,mBAAmB,CAuHrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,iBAAiB,EAAE,MAAM,EACzB,aAAa,EAAE,MAAM,GACpB,MAAM,CAUR;AAsCD,OAAO,EAGL,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EAGtB,MAAM,SAAS,CAAC;AAgMjB;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;IACnC,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAE/D,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IAEzE,oDAAoD;IACpD,OAAO,CAAC,oBAAoB,CAAC,CAAmC;;IAQhE;;;;;;;;;;;;;;;OAeG;IACI,YAAY,CAAC,GAAG,EAAE,qBAAqB,GAAG,kBAAkB;IAsBnE;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,yBAAyB;IA8DjC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IA+BpB;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IAalC;;;;;;OAMG;IACH,OAAO,CAAC,6BAA6B;IAarC;;;;;;;;OAQG;IACH,OAAO,CAAC,kCAAkC;IA8B1C;;;;;;;;OAQG;IACH,OAAO,CAAC,kCAAkC;IA2C1C;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;;;OAIG;IACH,OAAO,CAAC,iCAAiC;IAezC;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAyC/B;;;;;;;;;;;;OAYG;IACI,oBAAoB,IAAI,uBAAuB;IAsBtD;;;;;;;;OAQG;IACI,cAAc,IAAI,MAAM;CAGhC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,0BAAiC,CAAC"}