blacktrigram 0.7.2

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

@@ -0,0 +1,349 @@
+import { AnimationPriority, STEP_PRIORITY } from "./types.js";
+//#region src/systems/animation/core/AnimationPriority.ts
+/**
+* Animation priority system for Black Trigram
+* 
+* Determines which animations can interrupt others based on priority levels.
+* Higher priority animations can interrupt lower priority ones.
+* 
+* Priority order: recovery > fall > ko > hit > attack > defend > stance_change > movement > idle
+* 
+* Enhanced with:
+* - Deterministic conflict resolution for simultaneous equal-priority animations
+* - Animation queue system for pending animations
+* - Interruptibility windows (frame-based interrupt control)
+* - Korean terminology for all priority levels and conflicts
+* 
+* @module systems/animation/AnimationPriority
+* @category Animation
+* @korean 애니메이션우선순위
+*/
+/**
+* Map animation states to their priority levels
+* 
+* Stance guard animations have same priority as idle (0) since they are
+* also idle states, just stance-specific.
+* Tactical steps have priority 5 (same as attacks) to ensure commitment.
+* 
+* @korean 애니메이션우선순위맵
+*/
+var ANIMATION_PRIORITY_MAP = {
+	idle: AnimationPriority.IDLE,
+	walk: AnimationPriority.WALK,
+	run: AnimationPriority.RUN,
+	stance_change: AnimationPriority.STANCE_CHANGE,
+	stance_side_switch: AnimationPriority.STANCE_CHANGE,
+	defend: AnimationPriority.DEFEND,
+	defend_block_success: AnimationPriority.HIT,
+	defend_parry: AnimationPriority.KO,
+	defend_guard_break: AnimationPriority.FALL,
+	defend_recovery: AnimationPriority.RUN,
+	attack: AnimationPriority.ATTACK,
+	hit: AnimationPriority.HIT,
+	ko: AnimationPriority.KO,
+	stance_guard_geon: AnimationPriority.IDLE,
+	stance_guard_tae: AnimationPriority.IDLE,
+	stance_guard_li: AnimationPriority.IDLE,
+	stance_guard_jin: AnimationPriority.IDLE,
+	stance_guard_son: AnimationPriority.IDLE,
+	stance_guard_gam: AnimationPriority.IDLE,
+	stance_guard_gan: AnimationPriority.IDLE,
+	stance_guard_gon: AnimationPriority.IDLE,
+	step_forward: STEP_PRIORITY,
+	step_back: STEP_PRIORITY,
+	step_left: STEP_PRIORITY,
+	step_right: STEP_PRIORITY,
+	step_forward_left: STEP_PRIORITY,
+	step_forward_right: STEP_PRIORITY,
+	step_back_left: STEP_PRIORITY,
+	step_back_right: STEP_PRIORITY,
+	fall_forward: AnimationPriority.FALL,
+	fall_backward: AnimationPriority.FALL,
+	fall_side_left: AnimationPriority.FALL,
+	fall_side_right: AnimationPriority.FALL,
+	ground_prone: AnimationPriority.IDLE,
+	ground_supine: AnimationPriority.IDLE,
+	ground_side_left: AnimationPriority.IDLE,
+	ground_side_right: AnimationPriority.IDLE,
+	turn_left: STEP_PRIORITY,
+	turn_right: STEP_PRIORITY,
+	footwork_circular_left: STEP_PRIORITY,
+	footwork_circular_right: STEP_PRIORITY,
+	footwork_pivot_left: STEP_PRIORITY,
+	footwork_pivot_right: STEP_PRIORITY,
+	footwork_slide_forward: AnimationPriority.DEFEND,
+	footwork_slide_back: AnimationPriority.DEFEND,
+	footwork_slide_left: AnimationPriority.DEFEND,
+	footwork_slide_right: AnimationPriority.DEFEND,
+	footwork_shuffle: AnimationPriority.STANCE_CHANGE,
+	recovery_prone_standup: AnimationPriority.RECOVERY,
+	recovery_supine_standup: AnimationPriority.RECOVERY,
+	recovery_roll: AnimationPriority.RECOVERY,
+	recovery_defensive: AnimationPriority.RECOVERY,
+	grapple_entry: AnimationPriority.ATTACK,
+	grapple_control: AnimationPriority.ATTACK,
+	grapple_struggle: AnimationPriority.HIT,
+	grapple_escape: AnimationPriority.HIT
+};
+/**
+* Check if an animation can interrupt another based on priority
+* 
+* @param current - Current animation state
+* @param requested - Requested animation state
+* @param currentInterruptible - Whether current animation is interruptible
+* @returns Whether the requested animation can interrupt the current one
+* 
+* @example
+* ```typescript
+* // Hit can interrupt attack
+* canInterrupt("attack", "hit", true); // true
+* 
+* // Attack cannot interrupt hit
+* canInterrupt("hit", "attack", true); // false
+* 
+* // Nothing can interrupt non-interruptible animations
+* canInterrupt("attack", "hit", false); // false (unless same priority)
+* ```
+* 
+* @korean 중단가능여부확인
+*/
+function canInterrupt(current, requested, currentInterruptible) {
+	const currentPriority = ANIMATION_PRIORITY_MAP[current];
+	const requestedPriority = ANIMATION_PRIORITY_MAP[requested];
+	if (currentPriority === requestedPriority) return true;
+	if (!currentInterruptible) return requestedPriority > currentPriority;
+	return requestedPriority >= currentPriority;
+}
+AnimationPriority.IDLE, AnimationPriority.WALK, AnimationPriority.RUN, AnimationPriority.STANCE_CHANGE, AnimationPriority.DEFEND, AnimationPriority.ATTACK, AnimationPriority.HIT, AnimationPriority.KO, AnimationPriority.FALL, AnimationPriority.RECOVERY;
+/**
+* Resolve conflict between two equal-priority animations
+* 
+* **Korean**: 충돌 해결
+* 
+* Uses the specified strategy to deterministically decide which animation
+* should play when both have equal priority.
+* 
+* @param current - Current animation request
+* @param requested - Requested animation request
+* @param strategy - Conflict resolution strategy
+* @returns Which animation should play: 'current' or 'requested'
+* 
+* @example
+* ```typescript
+* const current = {
+*   state: AnimationState.ATTACK,
+*   timestamp: 1000,
+*   priority: AnimationPriority.ATTACK,
+* };
+* const requested = {
+*   state: AnimationState.STEP_FORWARD,
+*   timestamp: 1001,
+*   priority: AnimationPriority.ATTACK,
+* };
+* 
+* // Timestamp strategy: current wins (1000 < 1001)
+* resolveConflict(current, requested, "timestamp"); // "current"
+* 
+* // Requested strategy: always take new animation
+* resolveConflict(current, requested, "requested"); // "requested"
+* ```
+* 
+* @korean 충돌해결
+*/
+function resolveConflict(current, requested, strategy = "timestamp") {
+	if (requested.forced && !current.forced) return "requested";
+	if (current.forced && !requested.forced) return "current";
+	switch (strategy) {
+		case "timestamp": return current.timestamp <= requested.timestamp ? "current" : "requested";
+		case "state_order": return current.state <= requested.state ? "current" : "requested";
+		case "current": return "current";
+		case "requested": return "requested";
+		default: return current.timestamp <= requested.timestamp ? "current" : "requested";
+	}
+}
+/**
+* Animation queue for managing pending animations
+* 
+* **Korean**: 애니메이션 대기열
+* 
+* Stores pending animation requests that should play after the current
+* animation completes. Useful for:
+* - Buffering input during non-interruptible animations
+* - Creating animation chains/combos
+* - Handling rapid input sequences
+* 
+* Queue is priority-ordered: highest priority animations are dequeued first.
+* 
+* @korean 애니메이션대기열
+*/
+var AnimationQueue = class {
+	queue = [];
+	maxSize;
+	conflictStrategy;
+	/**
+	* Create a new animation queue
+	* 
+	* @param maxSize - Maximum queue size (default: 3)
+	* @param conflictStrategy - Strategy for resolving equal-priority conflicts
+	* 
+	* @korean 생성자
+	*/
+	constructor(maxSize = 3, conflictStrategy = "timestamp") {
+		this.maxSize = maxSize;
+		this.conflictStrategy = conflictStrategy;
+	}
+	/**
+	* Add animation request to queue
+	* 
+	* **Korean**: 대기열에 추가
+	* 
+	* Adds an animation request to the queue if space is available.
+	* Queue is kept sorted by priority (highest first).
+	* 
+	* @param request - Animation request to enqueue
+	* @returns Whether request was successfully enqueued
+	* 
+	* @korean 대기열추가
+	*/
+	enqueue(request) {
+		if (this.queue.length >= this.maxSize) {
+			const lowestPriorityItem = this.queue[this.queue.length - 1];
+			if (request.priority > lowestPriorityItem.priority) this.queue.pop();
+			else return false;
+		}
+		let low = 0;
+		let high = this.queue.length;
+		while (low < high) {
+			const mid = low + high >> 1;
+			if (this.queue[mid].priority < request.priority) high = mid;
+			else low = mid + 1;
+		}
+		this.queue.splice(low, 0, request);
+		return true;
+	}
+	/**
+	* Remove and return highest priority request from queue
+	* 
+	* **Korean**: 대기열에서 제거
+	* 
+	* Dequeues the highest priority animation request.
+	* If multiple requests have equal priority, uses conflict resolution strategy.
+	* 
+	* @returns Next animation request or null if queue is empty
+	* 
+	* @korean 대기열제거
+	*/
+	dequeue() {
+		if (this.queue.length === 0) return null;
+		const highestPriority = this.queue[0].priority;
+		const highestPriorityRequests = this.queue.filter((r) => r.priority === highestPriority);
+		let selectedRequest;
+		if (highestPriorityRequests.length === 1) selectedRequest = highestPriorityRequests[0];
+		else selectedRequest = highestPriorityRequests.reduce((current, next) => {
+			return resolveConflict(current, next, this.conflictStrategy) === "current" ? current : next;
+		});
+		const index = this.queue.indexOf(selectedRequest);
+		this.queue.splice(index, 1);
+		return selectedRequest;
+	}
+	/**
+	* Peek at next request without removing it
+	* 
+	* **Korean**: 다음 요청 확인
+	* 
+	* @returns Next animation request or null if queue is empty
+	* 
+	* @korean 다음요청확인
+	*/
+	peek() {
+		return this.queue.length > 0 ? this.queue[0] : null;
+	}
+	/**
+	* Clear all pending requests
+	* 
+	* **Korean**: 대기열 초기화
+	* 
+	* @korean 대기열초기화
+	*/
+	clear() {
+		this.queue = [];
+	}
+	/**
+	* Get number of pending requests
+	* 
+	* **Korean**: 대기열 크기
+	* 
+	* @returns Number of pending requests
+	* 
+	* @korean 대기열크기
+	*/
+	size() {
+		return this.queue.length;
+	}
+	/**
+	* Check if queue is empty
+	* 
+	* **Korean**: 대기열 비어있음
+	* 
+	* @returns True if queue has no pending requests
+	* 
+	* @korean 대기열비어있음
+	*/
+	isEmpty() {
+		return this.queue.length === 0;
+	}
+	/**
+	* Check if queue is full
+	* 
+	* **Korean**: 대기열 가득참
+	* 
+	* @returns True if queue is at maximum capacity
+	* 
+	* @korean 대기열가득찬
+	*/
+	isFull() {
+		return this.queue.length >= this.maxSize;
+	}
+	/**
+	* Get all pending requests (read-only)
+	* 
+	* **Korean**: 모든 대기 요청
+	* 
+	* @returns Array of pending requests
+	* 
+	* @korean 모든대기요청
+	*/
+	getAll() {
+		return [...this.queue];
+	}
+	/**
+	* Get maximum queue size
+	* 
+	* **Korean**: 최대 대기열 크기
+	* 
+	* @returns Maximum queue capacity
+	* 
+	* @korean 최대대기열크기
+	*/
+	getMaxSize() {
+		return this.maxSize;
+	}
+	/**
+	* Set conflict resolution strategy
+	* 
+	* **Korean**: 충돌 해결 전략 설정
+	* 
+	* Updates the strategy used to resolve equal-priority conflicts.
+	* 
+	* @param strategy - New conflict resolution strategy
+	* 
+	* @korean 충돌해결전략설정
+	*/
+	setConflictStrategy(strategy) {
+		this.conflictStrategy = strategy;
+	}
+};
+//#endregion
+export { ANIMATION_PRIORITY_MAP, AnimationQueue, canInterrupt };
+
+//# sourceMappingURL=AnimationPriority.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationPriority.js","names":[],"sources":["../../../../src/systems/animation/core/AnimationPriority.ts"],"sourcesContent":["/**\n * Animation priority system for Black Trigram\n * \n * Determines which animations can interrupt others based on priority levels.\n * Higher priority animations can interrupt lower priority ones.\n * \n * Priority order: recovery > fall > ko > hit > attack > defend > stance_change > movement > idle\n * \n * Enhanced with:\n * - Deterministic conflict resolution for simultaneous equal-priority animations\n * - Animation queue system for pending animations\n * - Interruptibility windows (frame-based interrupt control)\n * - Korean terminology for all priority levels and conflicts\n * \n * @module systems/animation/AnimationPriority\n * @category Animation\n * @korean 애니메이션우선순위\n */\n\nimport { AnimationPriority, AnimationState, STEP_PRIORITY } from \"./types\";\n\n/**\n * Map animation states to their priority levels\n * \n * Stance guard animations have same priority as idle (0) since they are\n * also idle states, just stance-specific.\n * Tactical steps have priority 5 (same as attacks) to ensure commitment.\n * \n * @korean 애니메이션우선순위맵\n */\nexport const ANIMATION_PRIORITY_MAP: Record<AnimationState, AnimationPriority> = {\n  idle: AnimationPriority.IDLE,\n  walk: AnimationPriority.WALK,\n  run: AnimationPriority.RUN,\n  stance_change: AnimationPriority.STANCE_CHANGE,\n  stance_side_switch: AnimationPriority.STANCE_CHANGE, // Same priority as stance_change\n  defend: AnimationPriority.DEFEND,\n  // Defensive animations (방어 애니메이션)\n  defend_block_success: AnimationPriority.HIT, // Priority 6 - same as hit\n  defend_parry: AnimationPriority.KO, // Priority 7 - higher than block\n  defend_guard_break: AnimationPriority.FALL, // Priority 8 - highest (same as fall)\n  defend_recovery: AnimationPriority.RUN, // Priority 2 - interruptible recovery\n  attack: AnimationPriority.ATTACK,\n  hit: AnimationPriority.HIT,\n  ko: AnimationPriority.KO,\n  // Stance-specific guard animations (팔괘 방어 자세)\n  stance_guard_geon: AnimationPriority.IDLE,\n  stance_guard_tae: AnimationPriority.IDLE,\n  stance_guard_li: AnimationPriority.IDLE,\n  stance_guard_jin: AnimationPriority.IDLE,\n  stance_guard_son: AnimationPriority.IDLE,\n  stance_guard_gam: AnimationPriority.IDLE,\n  stance_guard_gan: AnimationPriority.IDLE,\n  stance_guard_gon: AnimationPriority.IDLE,\n  // Tactical step animations (전술적 발걸음) - non-interruptible\n  step_forward: STEP_PRIORITY,\n  step_back: STEP_PRIORITY,\n  step_left: STEP_PRIORITY,\n  step_right: STEP_PRIORITY,\n  step_forward_left: STEP_PRIORITY,\n  step_forward_right: STEP_PRIORITY,\n  step_back_left: STEP_PRIORITY,\n  step_back_right: STEP_PRIORITY,\n  // Fall animations (낙법) - highest priority\n  fall_forward: AnimationPriority.FALL,\n  fall_backward: AnimationPriority.FALL,\n  fall_side_left: AnimationPriority.FALL,\n  fall_side_right: AnimationPriority.FALL,\n  // Ground states (지면 자세) - idle priority\n  ground_prone: AnimationPriority.IDLE,\n  ground_supine: AnimationPriority.IDLE,\n  ground_side_left: AnimationPriority.IDLE,\n  ground_side_right: AnimationPriority.IDLE,\n  // 180-degree turn animations (180도 회전) - same as steps (committed action)\n  turn_left: STEP_PRIORITY,\n  turn_right: STEP_PRIORITY,\n  // Footwork patterns (보법) - Korean martial arts specialized footwork\n  footwork_circular_left: STEP_PRIORITY,\n  footwork_circular_right: STEP_PRIORITY,\n  footwork_pivot_left: STEP_PRIORITY,\n  footwork_pivot_right: STEP_PRIORITY,\n  footwork_slide_forward: AnimationPriority.DEFEND,\n  footwork_slide_back: AnimationPriority.DEFEND,\n  footwork_slide_left: AnimationPriority.DEFEND,\n  footwork_slide_right: AnimationPriority.DEFEND,\n  footwork_shuffle: AnimationPriority.STANCE_CHANGE,\n  // Recovery animations (기상 애니메이션) - highest priority (can interrupt anything)\n  recovery_prone_standup: AnimationPriority.RECOVERY,\n  recovery_supine_standup: AnimationPriority.RECOVERY,\n  recovery_roll: AnimationPriority.RECOVERY,\n  recovery_defensive: AnimationPriority.RECOVERY,\n  // Grappling animations (잡기 애니메이션) - high priority like attacks/hits\n  grapple_entry: AnimationPriority.ATTACK, // Priority 5 - same as attack\n  grapple_control: AnimationPriority.ATTACK, // Priority 5 - maintain control\n  grapple_struggle: AnimationPriority.HIT, // Priority 6 - struggling escape\n  grapple_escape: AnimationPriority.HIT, // Priority 6 - successful escape\n};\n\n/**\n * Check if an animation can interrupt another based on priority\n * \n * @param current - Current animation state\n * @param requested - Requested animation state\n * @param currentInterruptible - Whether current animation is interruptible\n * @returns Whether the requested animation can interrupt the current one\n * \n * @example\n * ```typescript\n * // Hit can interrupt attack\n * canInterrupt(\"attack\", \"hit\", true); // true\n * \n * // Attack cannot interrupt hit\n * canInterrupt(\"hit\", \"attack\", true); // false\n * \n * // Nothing can interrupt non-interruptible animations\n * canInterrupt(\"attack\", \"hit\", false); // false (unless same priority)\n * ```\n * \n * @korean 중단가능여부확인\n */\nexport function canInterrupt(\n  current: AnimationState,\n  requested: AnimationState,\n  currentInterruptible: boolean\n): boolean {\n  const currentPriority = ANIMATION_PRIORITY_MAP[current];\n  const requestedPriority = ANIMATION_PRIORITY_MAP[requested];\n\n  // Same priority animations can always transition\n  if (currentPriority === requestedPriority) {\n    return true;\n  }\n\n  // Non-interruptible animations can only be interrupted by higher priority\n  if (!currentInterruptible) {\n    return requestedPriority > currentPriority;\n  }\n\n  // Interruptible animations can be interrupted by same or higher priority\n  return requestedPriority >= currentPriority;\n}\n\n/**\n * Get the priority level for an animation state\n * \n * @param state - Animation state\n * @returns Priority level\n * \n * @korean 우선순위가져오기\n */\nexport function getPriority(state: AnimationState): AnimationPriority {\n  return ANIMATION_PRIORITY_MAP[state];\n}\n\n/**\n * Compare two animation priorities\n * \n * @param state1 - First animation state\n * @param state2 - Second animation state\n * @returns Positive if state1 has higher priority, negative if state2 has higher priority, 0 if equal\n * \n * @korean 우선순위비교\n */\nexport function comparePriority(\n  state1: AnimationState,\n  state2: AnimationState\n): number {\n  return ANIMATION_PRIORITY_MAP[state1] - ANIMATION_PRIORITY_MAP[state2];\n}\n\n// ===== Korean Priority Level Terminology (우선순위 등급 용어) =====\n\n/**\n * Korean names for each priority level\n * \n * Maps priority levels to their Korean martial arts terminology:\n * - IDLE (0): 대기 (Daegi) - Waiting/Ready state\n * - WALK (1): 보행 (Bohaeng) - Walking movement\n * - RUN (2): 질주 (Jilju) - Running movement\n * - STANCE_CHANGE (3): 자세전환 (Jase Jeonhwan) - Stance transition\n * - DEFEND (4): 방어 (Bangeo) - Defense action\n * - ATTACK (5): 공격 (Gonggyeok) - Attack action\n * - HIT (6): 피격 (Pigyeok) - Being hit\n * - KO (7): 기절 (Gijeol) - Knockout\n * - FALL (8): 낙법 (Nakbeop) - Falling technique\n * - RECOVERY (9): 기상 (Gisang) - Recovery/Getting up\n * \n * @korean 우선순위한글용어\n */\nexport const PRIORITY_LEVEL_KOREAN_NAMES: Record<AnimationPriority, {\n  korean: string;\n  romanized: string;\n  english: string;\n}> = {\n  [AnimationPriority.IDLE]: {\n    korean: \"대기\",\n    romanized: \"Daegi\",\n    english: \"Ready State\",\n  },\n  [AnimationPriority.WALK]: {\n    korean: \"보행\",\n    romanized: \"Bohaeng\",\n    english: \"Walking\",\n  },\n  [AnimationPriority.RUN]: {\n    korean: \"질주\",\n    romanized: \"Jilju\",\n    english: \"Running\",\n  },\n  [AnimationPriority.STANCE_CHANGE]: {\n    korean: \"자세전환\",\n    romanized: \"Jase Jeonhwan\",\n    english: \"Stance Change\",\n  },\n  [AnimationPriority.DEFEND]: {\n    korean: \"방어\",\n    romanized: \"Bangeo\",\n    english: \"Defense\",\n  },\n  [AnimationPriority.ATTACK]: {\n    korean: \"공격\",\n    romanized: \"Gonggyeok\",\n    english: \"Attack\",\n  },\n  [AnimationPriority.HIT]: {\n    korean: \"피격\",\n    romanized: \"Pigyeok\",\n    english: \"Hit\",\n  },\n  [AnimationPriority.KO]: {\n    korean: \"기절\",\n    romanized: \"Gijeol\",\n    english: \"Knockout\",\n  },\n  [AnimationPriority.FALL]: {\n    korean: \"낙법\",\n    romanized: \"Nakbeop\",\n    english: \"Falling\",\n  },\n  [AnimationPriority.RECOVERY]: {\n    korean: \"기상\",\n    romanized: \"Gisang\",\n    english: \"Recovery\",\n  },\n};\n\n/**\n * Get Korean name for a priority level\n * \n * @param priority - Animation priority level\n * @returns Korean terminology object\n * \n * @korean 우선순위한글이름가져오기\n */\nexport function getPriorityKoreanName(priority: AnimationPriority): {\n  korean: string;\n  romanized: string;\n  english: string;\n} {\n  return PRIORITY_LEVEL_KOREAN_NAMES[priority];\n}\n\n// ===== Conflict Resolution (충돌 해결) =====\n\n/**\n * Conflict resolution strategy for equal-priority animations\n * \n * **Korean**: 충돌 해결 전략\n * \n * Determines how to handle when two animations of equal priority\n * are requested simultaneously:\n * \n * - `timestamp`: First animation requested wins (FIFO - 선입선출)\n * - `state_order`: Use AnimationState enum order as tiebreaker\n * - `current`: Keep current animation running\n * - `requested`: Always switch to requested animation\n * \n * @korean 충돌해결전략\n */\nexport type ConflictResolutionStrategy =\n  | \"timestamp\" // 시간순서 (First requested wins)\n  | \"state_order\" // 상태순서 (Enum order tiebreaker)\n  | \"current\" // 현재유지 (Keep current)\n  | \"requested\"; // 요청수락 (Accept requested)\n\n/**\n * Animation request with timestamp for conflict resolution\n * \n * **Korean**: 애니메이션 요청\n * \n * Tracks animation requests with timestamps to enable deterministic\n * conflict resolution when multiple equal-priority animations compete.\n * \n * @korean 애니메이션요청\n */\nexport interface AnimationRequest {\n  /** Requested animation state */\n  readonly state: AnimationState;\n  /** Request timestamp in milliseconds (from performance.now()) */\n  readonly timestamp: number;\n  /** Request priority */\n  readonly priority: AnimationPriority;\n  /** \n   * Whether this is a forced request (wins conflict resolution against non-forced requests)\n   * \n   * Note: This only affects conflict resolution between equal-priority animations in the queue.\n   * It does not bypass priority checks or interrupt rules for the initial transition.\n   * \n   * @korean 강제요청\n   */\n  readonly forced?: boolean;\n}\n\n/**\n * Resolve conflict between two equal-priority animations\n * \n * **Korean**: 충돌 해결\n * \n * Uses the specified strategy to deterministically decide which animation\n * should play when both have equal priority.\n * \n * @param current - Current animation request\n * @param requested - Requested animation request\n * @param strategy - Conflict resolution strategy\n * @returns Which animation should play: 'current' or 'requested'\n * \n * @example\n * ```typescript\n * const current = {\n *   state: AnimationState.ATTACK,\n *   timestamp: 1000,\n *   priority: AnimationPriority.ATTACK,\n * };\n * const requested = {\n *   state: AnimationState.STEP_FORWARD,\n *   timestamp: 1001,\n *   priority: AnimationPriority.ATTACK,\n * };\n * \n * // Timestamp strategy: current wins (1000 < 1001)\n * resolveConflict(current, requested, \"timestamp\"); // \"current\"\n * \n * // Requested strategy: always take new animation\n * resolveConflict(current, requested, \"requested\"); // \"requested\"\n * ```\n * \n * @korean 충돌해결\n */\nexport function resolveConflict(\n  current: AnimationRequest,\n  requested: AnimationRequest,\n  strategy: ConflictResolutionStrategy = \"timestamp\"\n): \"current\" | \"requested\" {\n  // If only one is forced, forced wins\n  if (requested.forced && !current.forced) {\n    return \"requested\";\n  }\n  if (current.forced && !requested.forced) {\n    return \"current\";\n  }\n  \n  // If both are forced OR both are normal, use conflict resolution strategy\n\n  // Apply conflict resolution strategy\n  switch (strategy) {\n    case \"timestamp\":\n      // Earlier timestamp wins (FIFO)\n      return current.timestamp <= requested.timestamp ? \"current\" : \"requested\";\n    \n    case \"state_order\":\n      // Use enum value comparison as tiebreaker\n      return current.state <= requested.state ? \"current\" : \"requested\";\n    \n    case \"current\":\n      // Always keep current animation\n      return \"current\";\n    \n    case \"requested\":\n      // Always accept requested animation\n      return \"requested\";\n    \n    default:\n      // Default to timestamp strategy\n      return current.timestamp <= requested.timestamp ? \"current\" : \"requested\";\n  }\n}\n\n// ===== Animation Queue System (애니메이션 대기열) =====\n\n/**\n * Animation queue for managing pending animations\n * \n * **Korean**: 애니메이션 대기열\n * \n * Stores pending animation requests that should play after the current\n * animation completes. Useful for:\n * - Buffering input during non-interruptible animations\n * - Creating animation chains/combos\n * - Handling rapid input sequences\n * \n * Queue is priority-ordered: highest priority animations are dequeued first.\n * \n * @korean 애니메이션대기열\n */\nexport class AnimationQueue {\n  private queue: AnimationRequest[] = [];\n  private maxSize: number;\n  private conflictStrategy: ConflictResolutionStrategy;\n\n  /**\n   * Create a new animation queue\n   * \n   * @param maxSize - Maximum queue size (default: 3)\n   * @param conflictStrategy - Strategy for resolving equal-priority conflicts\n   * \n   * @korean 생성자\n   */\n  constructor(\n    maxSize: number = 3,\n    conflictStrategy: ConflictResolutionStrategy = \"timestamp\"\n  ) {\n    this.maxSize = maxSize;\n    this.conflictStrategy = conflictStrategy;\n  }\n\n  /**\n   * Add animation request to queue\n   * \n   * **Korean**: 대기열에 추가\n   * \n   * Adds an animation request to the queue if space is available.\n   * Queue is kept sorted by priority (highest first).\n   * \n   * @param request - Animation request to enqueue\n   * @returns Whether request was successfully enqueued\n   * \n   * @korean 대기열추가\n   */\n  enqueue(request: AnimationRequest): boolean {\n    // Check if queue is full\n    if (this.queue.length >= this.maxSize) {\n      // Queue is sorted by priority (highest first), so last element is lowest priority\n      const lowestPriorityItem = this.queue[this.queue.length - 1];\n      \n      if (request.priority > lowestPriorityItem.priority) {\n        // Remove lowest priority item to make space\n        this.queue.pop();\n      } else {\n        return false; // Queue full, request discarded\n      }\n    }\n\n    // Insert request into queue while maintaining sort by priority (highest first).\n    // Use binary search (O(log n)) to find insertion position, then splice (O(n)) to insert.\n    // Overall: O(n) per insertion, avoiding an O(n log n) full sort of the entire queue.\n    let low = 0;\n    let high = this.queue.length;\n\n    // Binary search to find insertion index\n    while (low < high) {\n      const mid = (low + high) >> 1;\n      const midPriority = this.queue[mid].priority;\n\n      if (midPriority < request.priority) {\n        // New request has higher priority; search left half\n        high = mid;\n      } else {\n        // New request has equal or lower priority; search right half\n        low = mid + 1;\n      }\n    }\n\n    // Insert at computed index to keep queue sorted (highest priority first)\n    this.queue.splice(low, 0, request);\n    \n    return true;\n  }\n\n  /**\n   * Remove and return highest priority request from queue\n   * \n   * **Korean**: 대기열에서 제거\n   * \n   * Dequeues the highest priority animation request.\n   * If multiple requests have equal priority, uses conflict resolution strategy.\n   * \n   * @returns Next animation request or null if queue is empty\n   * \n   * @korean 대기열제거\n   */\n  dequeue(): AnimationRequest | null {\n    if (this.queue.length === 0) {\n      return null;\n    }\n\n    // Get all requests with highest priority\n    const highestPriority = this.queue[0].priority;\n    const highestPriorityRequests = this.queue.filter(\n      r => r.priority === highestPriority\n    );\n\n    let selectedRequest: AnimationRequest;\n\n    if (highestPriorityRequests.length === 1) {\n      selectedRequest = highestPriorityRequests[0];\n    } else {\n      // Multiple equal-priority requests - use conflict resolution\n      selectedRequest = highestPriorityRequests.reduce((current, next) => {\n        const winner = resolveConflict(current, next, this.conflictStrategy);\n        return winner === \"current\" ? current : next;\n      });\n    }\n\n    // Remove selected request from queue\n    const index = this.queue.indexOf(selectedRequest);\n    this.queue.splice(index, 1);\n\n    return selectedRequest;\n  }\n\n  /**\n   * Peek at next request without removing it\n   * \n   * **Korean**: 다음 요청 확인\n   * \n   * @returns Next animation request or null if queue is empty\n   * \n   * @korean 다음요청확인\n   */\n  peek(): AnimationRequest | null {\n    return this.queue.length > 0 ? this.queue[0] : null;\n  }\n\n  /**\n   * Clear all pending requests\n   * \n   * **Korean**: 대기열 초기화\n   * \n   * @korean 대기열초기화\n   */\n  clear(): void {\n    this.queue = [];\n  }\n\n  /**\n   * Get number of pending requests\n   * \n   * **Korean**: 대기열 크기\n   * \n   * @returns Number of pending requests\n   * \n   * @korean 대기열크기\n   */\n  size(): number {\n    return this.queue.length;\n  }\n\n  /**\n   * Check if queue is empty\n   * \n   * **Korean**: 대기열 비어있음\n   * \n   * @returns True if queue has no pending requests\n   * \n   * @korean 대기열비어있음\n   */\n  isEmpty(): boolean {\n    return this.queue.length === 0;\n  }\n\n  /**\n   * Check if queue is full\n   * \n   * **Korean**: 대기열 가득참\n   * \n   * @returns True if queue is at maximum capacity\n   * \n   * @korean 대기열가득찬\n   */\n  isFull(): boolean {\n    return this.queue.length >= this.maxSize;\n  }\n\n  /**\n   * Get all pending requests (read-only)\n   * \n   * **Korean**: 모든 대기 요청\n   * \n   * @returns Array of pending requests\n   * \n   * @korean 모든대기요청\n   */\n  getAll(): readonly AnimationRequest[] {\n    return [...this.queue];\n  }\n\n  /**\n   * Get maximum queue size\n   * \n   * **Korean**: 최대 대기열 크기\n   * \n   * @returns Maximum queue capacity\n   * \n   * @korean 최대대기열크기\n   */\n  getMaxSize(): number {\n    return this.maxSize;\n  }\n\n  /**\n   * Set conflict resolution strategy\n   * \n   * **Korean**: 충돌 해결 전략 설정\n   * \n   * Updates the strategy used to resolve equal-priority conflicts.\n   * \n   * @param strategy - New conflict resolution strategy\n   * \n   * @korean 충돌해결전략설정\n   */\n  setConflictStrategy(strategy: ConflictResolutionStrategy): void {\n    this.conflictStrategy = strategy;\n  }\n}\n\n// ===== Interruptibility Windows (중단 가능 구간) =====\n\n/**\n * Interruptibility window definition\n * \n * **Korean**: 중단 가능 구간\n * \n * Defines specific frame ranges where an animation can be interrupted,\n * allowing for more nuanced control than simple boolean interruptibility.\n * \n * Example: Attack animation might be interruptible only in startup frames (0-3)\n * and recovery frames (10-12), but not during active frames (4-9).\n * \n * @korean 중단가능구간\n */\nexport interface InterruptibilityWindow {\n  /** Starting frame (inclusive) */\n  readonly startFrame: number;\n  /** Ending frame (inclusive) */\n  readonly endFrame: number;\n  /** Minimum priority required to interrupt during this window */\n  readonly minPriorityToInterrupt: AnimationPriority;\n}\n\n/**\n * Check if an animation can be interrupted at a specific frame\n * \n * **Korean**: 프레임별 중단 가능 여부\n * \n * Determines if an animation can be interrupted based on:\n * - Current frame index\n * - Interruptibility windows\n * - Requested animation priority\n * \n * @param currentFrame - Current frame index in animation\n * @param requestedPriority - Priority of animation trying to interrupt\n * @param windows - Array of interruptibility windows\n * @returns Whether animation can be interrupted at this frame\n * \n * @example\n * ```typescript\n * const attackWindows: InterruptibilityWindow[] = [\n *   { startFrame: 0, endFrame: 3, minPriorityToInterrupt: AnimationPriority.ATTACK },\n *   { startFrame: 10, endFrame: 12, minPriorityToInterrupt: AnimationPriority.DEFEND },\n * ];\n * \n * // Frame 2: interruptible by attacks or higher\n * canInterruptAtFrame(2, AnimationPriority.HIT, attackWindows); // true\n * canInterruptAtFrame(2, AnimationPriority.DEFEND, attackWindows); // false\n * \n * // Frame 5: not interruptible (no window)\n * canInterruptAtFrame(5, AnimationPriority.KO, attackWindows); // false\n * ```\n * \n * @korean 프레임별중단가능여부\n */\nexport function canInterruptAtFrame(\n  currentFrame: number,\n  requestedPriority: AnimationPriority,\n  windows: readonly InterruptibilityWindow[]\n): boolean {\n  // Find window that contains current frame\n  const activeWindow = windows.find(\n    w => currentFrame >= w.startFrame && currentFrame <= w.endFrame\n  );\n\n  // If no window contains this frame, cannot interrupt\n  if (!activeWindow) {\n    return false;\n  }\n\n  // Check if requested priority meets window's minimum\n  return requestedPriority >= activeWindow.minPriorityToInterrupt;\n}\n\n/**\n * Get interruptibility window for current frame\n * \n * **Korean**: 현재 프레임 중단 가능 구간\n * \n * Returns the active interruptibility window for the given frame,\n * or null if frame is not in any window.\n * \n * @param currentFrame - Current frame index\n * @param windows - Array of interruptibility windows\n * @returns Active window or null\n * \n * @korean 현재프레임중단가능구간\n */\nexport function getInterruptibilityWindow(\n  currentFrame: number,\n  windows: readonly InterruptibilityWindow[]\n): InterruptibilityWindow | null {\n  return windows.find(\n    w => currentFrame >= w.startFrame && currentFrame <= w.endFrame\n  ) ?? null;\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,220 @@
+/**
+ * Animation Registry
+ *
+ * Central registry for all martial arts animations.
+ * Combines all animation modules and provides unified access.
+ *
+ * 무술 애니메이션 레지스트리 - 모든 애니메이션 통합 관리
+ *
+ * **RECOVERY PHASE INTEGRATION (복귀 단계 통합)**
+ *
+ * Enhanced animations with realistic recovery phases are now the default for:
+ * - JAB_ANIMATION → JAB_ANIMATION_ENHANCED (200ms recovery)
+ * - CROSS_ANIMATION → CROSS_ANIMATION_ENHANCED (220ms recovery)
+ * - FRONT_KICK_ANIMATION → FRONT_KICK_ANIMATION_ENHANCED (170ms recovery)
+ * - ROUNDHOUSE_KICK_ANIMATION → ROUNDHOUSE_KICK_ANIMATION_ENHANCED (180ms recovery)
+ * - ELBOW_STRIKE_ANIMATION → ELBOW_STRIKE_ANIMATION_ENHANCED (160ms recovery)
+ * - ELBOW_UPPERCUT_ANIMATION → ELBOW_UPPERCUT_ANIMATION_ENHANCED (170ms recovery)
+ * - KNEE_STRIKE_ANIMATION → KNEE_STRIKE_ANIMATION_ENHANCED (190ms recovery)
+ *
+ * Enhanced animations follow Korean martial arts principles (복귀/Bokgwi):
+ * - 균형회복 (Gyunhyeong Hoebog) - Balance restoration
+ * - 자세복귀 (Jase Bokgwi) - Stance return
+ * - 호흡조절 (Hoheup Jojoel) - Breath control during recovery
+ * - 근육이완 (Geunryuk Ihwan) - Muscle relaxation after tension
+ *
+ * All code using ANIMATION_REGISTRY or getAnimationForTechnique() will
+ * automatically use enhanced versions with no code changes required.
+ *
+ * @module systems/animation/AnimationRegistry
+ * @korean 애니메이션레지스트리
+ */
+import type { SkeletalAnimation } from "../../../types/skeletal";
+import { AnimationType } from "../builders/MartialArtsAnimationBuilder";
+import { COMBO_ANIMATIONS } from "../catalogs/ComboAnimations";
+import { DARKOPS_ANIMATIONS } from "../catalogs/DarkOpsAnimations";
+import { ELBOW_KNEE_ANIMATIONS, ELBOW_STRIKE_ANIMATION, ELBOW_UPPERCUT_ANIMATION, KNEE_STRIKE_ANIMATION } from "../catalogs/ElbowKneeAnimations";
+import { ARM_BAR_ANIMATION, BLOCK_ANIMATION, COUNTER_ATTACK_ANIMATION, COUNTER_STRIKE_ANIMATION, GRAPPLE_ANIMATION, GRAPPLING_ANIMATIONS, SLAM_ANIMATION, THROW_ANIMATION, WRIST_LOCK_ANIMATION } from "../catalogs/GrapplingAnimations";
+import { AXE_KICK_ANIMATION, BACK_KICK_ANIMATION, FRONT_KICK_ANIMATION, JUMPING_KICK_ANIMATION, KICK_ANIMATIONS, LOW_KICK_ANIMATION, ROUNDHOUSE_KICK_ANIMATION, SIDE_KICK_ANIMATION, SWEEP_ANIMATION, TORNADO_KICK_ANIMATION } from "../catalogs/KickAnimations";
+import { MOVEMENT_ANIMATIONS } from "../catalogs/MovementAnimations";
+import { CROSS_ANIMATION, HOOK_ANIMATION, JAB_ANIMATION, PALM_STRIKE_ANIMATION, PUNCH_ANIMATIONS } from "../catalogs/PunchAnimations";
+import { STANCE_ANIMATIONS } from "../catalogs/StanceAnimations";
+import { hasAnimationMapping, type AnimationConfig } from "./TechniqueAnimationMapping";
+/**
+ * Master registry of all animations by AnimationType
+ * 애니메이션 타입별 마스터 레지스트리
+ */
+export declare const ANIMATION_REGISTRY: ReadonlyMap<AnimationType, SkeletalAnimation>;
+/**
+ * All animations combined into a single map by name
+ * 이름별 전체 애니메이션 맵
+ */
+export declare const ALL_ANIMATIONS: ReadonlyMap<string, SkeletalAnimation>;
+/**
+ * Animation ID Registry - Direct mapping from technique animationId to SkeletalAnimation
+ *
+ * This provides 1-1 mapping between technique IDs and animations, using the new
+ * animationId field instead of the legacy AnimationType enum.
+ *
+ * 기술 ID에서 애니메이션으로의 직접 매핑 (1-1 관계)
+ *
+ * @see TechniqueAnimationMapping.ts for legacy technique → AnimationType mappings
+ * @korean 애니메이션ID레지스트리
+ */
+export declare const ANIMATION_ID_REGISTRY: ReadonlyMap<string, SkeletalAnimation>;
+/**
+ * Category-based default animations for fallback
+ *
+ * When an animationId is not found, fallback to category default.
+ *
+ * 카테고리별 기본 애니메이션 (fallback용)
+ */
+export declare const CATEGORY_DEFAULT_ANIMATIONS: ReadonlyMap<string, SkeletalAnimation>;
+/**
+ * Get animation by AnimationType
+ *
+ * @param type - Animation type enum value
+ * @returns Skeletal animation or undefined
+ *
+ * @korean 애니메이션타입으로조회
+ */
+export declare function getAnimationByType(type: AnimationType): SkeletalAnimation | undefined;
+/**
+ * Get animation by AnimationType with fallback
+ *
+ * @param type - Animation type enum value
+ * @param fallback - Fallback animation type
+ * @returns Skeletal animation (never undefined)
+ *
+ * @korean 애니메이션타입으로조회_기본값
+ */
+export declare function getAnimationByTypeOrDefault(type: AnimationType, fallback?: AnimationType): SkeletalAnimation;
+/**
+ * Get animation for a technique by technique ID (using AnimationType mapping)
+ *
+ * Uses the TechniqueAnimationMapping to find the correct animation
+ * for any technique in the game.
+ *
+ * @param techniqueId - Technique identifier (e.g., "geon_frontal_kick")
+ * @returns Skeletal animation or undefined
+ *
+ * @korean 기술ID로애니메이션조회
+ */
+export declare function getAnimationForTechniqueId(techniqueId: string): SkeletalAnimation | undefined;
+/**
+ * Get animation for a technique with fallback
+ *
+ * @param techniqueId - Technique identifier
+ * @param fallbackType - Fallback animation type
+ * @returns Animation with speed modifier
+ *
+ * @korean 기술ID로애니메이션조회_기본값
+ */
+export declare function getAnimationForTechniqueIdWithConfig(techniqueId: string, fallbackType?: AnimationType): {
+    animation: SkeletalAnimation;
+    speed: number;
+};
+/**
+ * Get animation by animationId (new architecture)
+ *
+ * Direct 1-1 lookup using the new animationId field from technique.
+ * This is the preferred method for the new animation architecture.
+ *
+ * @param animationId - Technique's animationId (e.g., "geon_heaven_strike")
+ * @returns SkeletalAnimation or undefined if not found
+ *
+ * @korean 애니메이션ID로조회
+ */
+export declare function getAnimationById(animationId: string): SkeletalAnimation | undefined;
+/**
+ * Get animation by ID with category-based fallback
+ *
+ * Implements a 3-tier fallback system:
+ * 1. Try direct ID lookup in ANIMATION_ID_REGISTRY
+ * 2. If not found, use category default from CATEGORY_DEFAULT_ANIMATIONS
+ * 3. If no category, use IDLE_STANCE as ultimate fallback
+ *
+ * This function never returns undefined, making it safe for use in game logic.
+ *
+ * @param animationId - Technique's animationId
+ * @param animationCategory - Technique's animationCategory for fallback
+ * @returns SkeletalAnimation (never undefined)
+ *
+ * @korean 애니메이션ID로조회_카테고리대체
+ */
+export declare function getAnimationByIdWithFallback(animationId: string | undefined, animationCategory?: string): SkeletalAnimation;
+/**
+ * Check if animation ID exists in registry
+ *
+ * @param animationId - Animation ID to check
+ * @returns true if animation exists in ANIMATION_ID_REGISTRY
+ *
+ * @korean 애니메이션ID존재확인
+ */
+export declare function hasAnimationId(animationId: string): boolean;
+/**
+ * Get category default animation
+ *
+ * Returns the default animation for a given category, useful for fallback logic.
+ *
+ * @param category - Animation category (e.g., "punch", "kick")
+ * @returns SkeletalAnimation or undefined if category not found
+ *
+ * @korean 카테고리기본애니메이션조회
+ */
+export declare function getCategoryDefaultAnimation(category: string): SkeletalAnimation | undefined;
+/**
+ * Get animation by name (legacy support)
+ *
+ * @param name - Animation name (e.g., "front_kick")
+ * @returns Skeletal animation or undefined
+ *
+ * @korean 이름으로애니메이션조회
+ */
+export declare function getAnimationByName(name: string): SkeletalAnimation | undefined;
+/**
+ * Get animation by name - unified lookup across all animation registries
+ *
+ * Searches ALL_ANIMATIONS which includes:
+ * - BASIC_ANIMATIONS (idle, walk, run, fall)
+ * - KICK_ANIMATIONS, PUNCH_ANIMATIONS, etc.
+ * - STANCE_ANIMATIONS, MOVEMENT_ANIMATIONS
+ * - ALL_ATTACK_ANIMATIONS (stance-specific attacks)
+ *
+ * @param name - Animation name (e.g., "idle", "front_kick", "walk")
+ * @returns Skeletal animation or undefined
+ *
+ * @korean 애니메이션가져오기
+ */
+export declare function getAnimation(name: string): SkeletalAnimation | undefined;
+/**
+ * Get animation name for a technique
+ *
+ * PRIORITY ORDER:
+ * 1. Direct lookup in ALL_ANIMATIONS by technique ID (stance-specific)
+ * 2. Regex pattern matching for generic techniques
+ * 3. Fallback to "jab"
+ *
+ * This ensures stance-specific animations like "geon_heaven_strike"
+ * are used when available, while still supporting generic technique names.
+ *
+ * @param techniqueNameOrId - Technique name, ID, or Korean name
+ * @returns Animation name from ALL_ANIMATIONS
+ *
+ * @example
+ * ```typescript
+ * getAnimationForTechnique("geon_heaven_strike") // "geon_heaven_strike" (exact match)
+ * getAnimationForTechnique("tae_wrist_lock") // "tae_wrist_lock" (exact match)
+ * getAnimationForTechnique("roundhouse_kick") // "roundhouse_kick" (regex match)
+ * getAnimationForTechnique("앞차기") // "front_kick" (regex match)
+ * ```
+ *
+ * @korean 기술에맞는애니메이션가져오기
+ */
+export declare function getAnimationForTechnique(techniqueNameOrId: string): string;
+export { ARM_BAR_ANIMATION, AXE_KICK_ANIMATION, BACK_KICK_ANIMATION, BLOCK_ANIMATION, COUNTER_ATTACK_ANIMATION, COUNTER_STRIKE_ANIMATION, CROSS_ANIMATION, ELBOW_STRIKE_ANIMATION, ELBOW_UPPERCUT_ANIMATION, FRONT_KICK_ANIMATION, GRAPPLE_ANIMATION, HOOK_ANIMATION, JAB_ANIMATION, JUMPING_KICK_ANIMATION, KNEE_STRIKE_ANIMATION, LOW_KICK_ANIMATION, PALM_STRIKE_ANIMATION, ROUNDHOUSE_KICK_ANIMATION, SIDE_KICK_ANIMATION, SLAM_ANIMATION, SWEEP_ANIMATION, THROW_ANIMATION, TORNADO_KICK_ANIMATION, WRIST_LOCK_ANIMATION, };
+export { COMBO_ANIMATIONS, DARKOPS_ANIMATIONS, ELBOW_KNEE_ANIMATIONS, GRAPPLING_ANIMATIONS, KICK_ANIMATIONS, MOVEMENT_ANIMATIONS, PUNCH_ANIMATIONS, STANCE_ANIMATIONS, };
+export { AnimationType } from "../builders/MartialArtsAnimationBuilder";
+export { hasAnimationMapping };
+export type { AnimationConfig };
+//# sourceMappingURL=AnimationRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationRegistry.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/core/AnimationRegistry.ts"],"names":[],"mappings":"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"}