blacktrigram 0.7.2

package/lib/systems/animation/constants/AnatomicalLimits.js

@@ -0,0 +1,61 @@
+//#region src/systems/animation/constants/AnatomicalLimits.ts
+/**
+* Anatomical Limits Constants
+*
+* Centralized biomechanical safety limits for Korean martial arts animations.
+* These constants document safe physiological ranges for joint movements,
+* validated by Korean martial arts experts and biomechanical research.
+*
+* **Korean Martial Arts Context:**
+* - 한국 무술 생체역학 안전 기준 (Korean Martial Arts Biomechanical Safety Standards)
+* - 관절 안전 범위 (Joint Safety Ranges)
+* - 실전 기술 적용 (Practical Technique Application)
+*
+* **Purpose:**
+* These limits serve as reference documentation and inform animation design
+* to ensure realistic, safe joint mechanics. Actual animations are designed
+* to stay well within these limits through authentic martial arts biomechanics.
+*
+* **Note:** All values are in radians for Three.js compatibility.
+* Convert degrees to radians: degrees * (π / 180)
+*
+* @module systems/animation/constants
+* @category Animation Constants
+* @korean 생체역학안전상수
+*/
+/**
+* Anatomical Limits for Joint Rotations
+*
+* Comprehensive set of safe physiological ranges for all major joints
+* used in Korean martial arts movements.
+*/
+var ANATOMICAL_LIMITS = {
+	SHOULDER: {
+		MAX_OVERHEAD: -2.35,
+		MAX_ROTATION: 1.57,
+		MAX_ELEVATION: -.61
+	},
+	ELBOW: {
+		MAX_BEND: 2.18,
+		MAX_FLEXION: 2.53,
+		MAX_BEND_GUARD: 2.09
+	},
+	WRIST: { MAX_BEND: 1.22 },
+	HIP: {
+		MAX_FLEXION: 1.92,
+		MAX_ROTATION: 1.22
+	},
+	KNEE: {
+		MAX_FLEXION: 1.57,
+		MAX_BEND: 2.27,
+		MAX_BEND_ROOTED: .44
+	},
+	ANKLE: {
+		MAX_DORSIFLEXION: .44,
+		MAX_DORSIFLEX: .35
+	}
+};
+//#endregion
+export { ANATOMICAL_LIMITS };
+
+//# sourceMappingURL=AnatomicalLimits.js.map

package/lib/systems/animation/constants/AnatomicalLimits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnatomicalLimits.js","names":[],"sources":["../../../../src/systems/animation/constants/AnatomicalLimits.ts"],"sourcesContent":["/**\n * Anatomical Limits Constants\n *\n * Centralized biomechanical safety limits for Korean martial arts animations.\n * These constants document safe physiological ranges for joint movements,\n * validated by Korean martial arts experts and biomechanical research.\n *\n * **Korean Martial Arts Context:**\n * - 한국 무술 생체역학 안전 기준 (Korean Martial Arts Biomechanical Safety Standards)\n * - 관절 안전 범위 (Joint Safety Ranges)\n * - 실전 기술 적용 (Practical Technique Application)\n *\n * **Purpose:**\n * These limits serve as reference documentation and inform animation design\n * to ensure realistic, safe joint mechanics. Actual animations are designed\n * to stay well within these limits through authentic martial arts biomechanics.\n *\n * **Note:** All values are in radians for Three.js compatibility.\n * Convert degrees to radians: degrees * (π / 180)\n *\n * @module systems/animation/constants\n * @category Animation Constants\n * @korean 생체역학안전상수\n */\n\n/**\n * Anatomical Limits for Joint Rotations\n *\n * Comprehensive set of safe physiological ranges for all major joints\n * used in Korean martial arts movements.\n */\nexport const ANATOMICAL_LIMITS = {\n  // ═══════════════════════════════════════════════════════════════════════════\n  // UPPER BODY LIMITS (상체 관절 제한)\n  // ═══════════════════════════════════════════════════════════════════════════\n\n  /**\n   * Shoulder Joint Limits (어깨 관절)\n   */\n  SHOULDER: {\n    /**\n     * Maximum safe shoulder overhead rotation: -135° (-2.35 radians)\n     *\n     * Shoulder flexion limit is approximately 150-180°, making -135° a safe\n     * threshold for dramatic overhead positioning (used in Geon/Heaven stance)\n     * without risking constraint violations.\n     *\n     * **Used in:** Geon (건) overhead strikes, powerful techniques\n     */\n    MAX_OVERHEAD: -2.35, // -135° in radians\n\n    /**\n     * Maximum safe shoulder rotation: ±90° (±1.57 radians)\n     *\n     * Safe shoulder rotation range for circular movements without risking\n     * impingement or constraint violations (used in Tae/Lake, Son/Wind stances).\n     *\n     * **Used in:** Tae (태) circular motions, Son (손) continuous attacks\n     */\n    MAX_ROTATION: 1.57, // ±90° in radians\n\n    /**\n     * Maximum safe shoulder elevation: -35° (-0.61 radians)\n     *\n     * Conservative shoulder elevation for defensive positions\n     * (used in Gan/Mountain guard stance).\n     *\n     * **Used in:** Gan (간) defensive guard positioning\n     */\n    MAX_ELEVATION: -0.61, // -35° in radians\n  },\n\n  /**\n   * Elbow Joint Limits (팔꿈치 관절)\n   */\n  ELBOW: {\n    /**\n     * Maximum safe elbow bend: ±125° (±2.18 radians)\n     *\n     * Typical elbow flexion limit is 145-160°, making 125° a conservative\n     * threshold for powerful chambering positions (used in Geon/Heaven strikes).\n     *\n     * **Used in:** Geon (건) powerful overhead chambering\n     */\n    MAX_BEND: 2.18, // ±125° in radians\n\n    /**\n     * Maximum safe elbow flexion: 145° (2.53 radians)\n     *\n     * Full elbow flexion for natural guard positions and joint manipulation\n     * techniques (used in Tae/Lake, Son/Wind stances).\n     *\n     * **Used in:** Tae (태) joint locks, Son (손) guard positions\n     */\n    MAX_FLEXION: 2.53, // 145° in radians\n\n    /**\n     * Maximum safe elbow bend for guard: 120° (2.09 radians)\n     *\n     * Conservative elbow flexion for defensive guard positions\n     * (used in Gan/Mountain defensive stance).\n     *\n     * **Used in:** Gan (간) defensive guard\n     */\n    MAX_BEND_GUARD: 2.09, // 120° in radians\n  },\n\n  /**\n   * Wrist Joint Limits (손목 관절)\n   */\n  WRIST: {\n    /**\n     * Maximum safe wrist flexion/extension: ±70° (±1.22 radians)\n     *\n     * Typical wrist range is 70-90° flexion/extension. We use 70° as a safe\n     * threshold for joint lock techniques (used in Tae/Lake Hapkido techniques).\n     *\n     * **Used in:** Tae (태) wrist locks and joint manipulation\n     */\n    MAX_BEND: 1.22, // ±70° in radians\n  },\n\n  // ═══════════════════════════════════════════════════════════════════════════\n  // LOWER BODY LIMITS (하체 관절 제한)\n  // ═══════════════════════════════════════════════════════════════════════════\n\n  /**\n   * Hip Joint Limits (엉덩이 관절)\n   */\n  HIP: {\n    /**\n     * Maximum safe hip flexion: 110° (1.92 radians)\n     *\n     * Hip flexion for ground techniques and takedowns\n     * (used in Gon/Earth ground control stance).\n     *\n     * **Used in:** Gon (곤) ground techniques, throws\n     */\n    MAX_FLEXION: 1.92, // 110° in radians\n\n    /**\n     * Maximum safe hip rotation: ±70° (±1.22 radians)\n     *\n     * Safe hip rotation range for continuous flowing movements\n     * (used in Son/Wind circular attacks).\n     *\n     * **Used in:** Son (손) circular movements, flow techniques\n     */\n    MAX_ROTATION: 1.22, // ±70° in radians\n  },\n\n  /**\n   * Knee Joint Limits (무릎 관절)\n   */\n  KNEE: {\n    /**\n     * Maximum safe knee flexion: 90° (1.57 radians)\n     *\n     * Deep horse stance knee bend for explosive power generation\n     * (used in Jin/Thunder explosive stance).\n     *\n     * **Used in:** Jin (진) explosive power generation\n     */\n    MAX_FLEXION: 1.57, // 90° in radians\n\n    /**\n     * Maximum safe knee bend: 130° (2.27 radians)\n     *\n     * Deep knee bend for ground control and takedown positioning\n     * (used in Gon/Earth ground techniques).\n     *\n     * **Used in:** Gon (곤) ground control, low positioning\n     */\n    MAX_BEND: 2.27, // 130° in radians\n\n    /**\n     * Maximum safe knee bend for rooted stance: 25° (0.44 radians)\n     *\n     * Conservative knee bend for defensive rooted positions\n     * (used in Gan/Mountain defensive stance).\n     *\n     * **Used in:** Gan (간) rooted defensive positioning\n     */\n    MAX_BEND_ROOTED: 0.44, // 25° in radians\n  },\n\n  /**\n   * Ankle Joint Limits (발목 관절)\n   */\n  ANKLE: {\n    /**\n     * Maximum safe ankle dorsiflexion: 25° (0.44 radians)\n     *\n     * Heel raising for explosive launch and power generation\n     * (used in Jin/Thunder explosive techniques).\n     *\n     * **Used in:** Jin (진) explosive heel raises\n     */\n    MAX_DORSIFLEXION: 0.44, // 25° in radians\n\n    /**\n     * Maximum safe ankle dorsiflex: 20° (0.35 radians)\n     *\n     * Conservative ankle flexion for ground control positioning\n     * (used in Gon/Earth ground techniques).\n     *\n     * **Used in:** Gon (곤) stable ground positioning\n     */\n    MAX_DORSIFLEX: 0.35, // 20° in radians\n  },\n} as const;\n\n/**\n * Type-safe access to anatomical limits\n */\nexport type AnatomicalLimits = typeof ANATOMICAL_LIMITS;\n\n/**\n * Helper function to get anatomical limit by body part and movement type\n *\n * Type-safe function that ensures valid body part and limit type combinations\n * are used at compile time, catching typos before runtime.\n *\n * @param bodyPart - Body part category (SHOULDER, ELBOW, WRIST, HIP, KNEE, ANKLE)\n * @param limitType - Specific limit type (MAX_BEND, MAX_FLEXION, etc.)\n * @returns The anatomical limit value in radians\n *\n * @example\n * ```typescript\n * const maxElbowBend = getAnatomicalLimit('ELBOW', 'MAX_BEND'); // 2.18 radians\n * ```\n */\nexport function getAnatomicalLimit<\n  B extends keyof AnatomicalLimits,\n  L extends keyof AnatomicalLimits[B] & string\n>(\n  bodyPart: B,\n  limitType: L\n): AnatomicalLimits[B][L] {\n  const part = ANATOMICAL_LIMITS[bodyPart];\n  const value = part[limitType];\n\n  if (typeof value !== \"number\") {\n    throw new Error(\n      `Invalid anatomical limit: ${String(bodyPart)}.${String(limitType)}`\n    );\n  }\n\n  return value;\n}\n\n/**\n * Convert degrees to radians for animation calculations\n *\n * @param degrees - Angle in degrees\n * @returns Angle in radians\n *\n * @example\n * ```typescript\n * const radians = degreesToRadians(90); // 1.5708 (π/2)\n * ```\n */\nexport function degreesToRadians(degrees: number): number {\n  return degrees * (Math.PI / 180);\n}\n\n/**\n * Convert radians to degrees for human-readable output\n *\n * @param radians - Angle in radians\n * @returns Angle in degrees\n *\n * @example\n * ```typescript\n * const degrees = radiansToDegrees(1.5708); // 90\n * ```\n */\nexport function radiansToDegrees(radians: number): number {\n  return radians * (180 / Math.PI);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAa,oBAAoB;CAQ/B,UAAU;EAUR,cAAc;EAUd,cAAc;EAUd,eAAe;EAChB;CAKD,OAAO;EASL,UAAU;EAUV,aAAa;EAUb,gBAAgB;EACjB;CAKD,OAAO,EASL,UAAU,MACX;CASD,KAAK;EASH,aAAa;EAUb,cAAc;EACf;CAKD,MAAM;EASJ,aAAa;EAUb,UAAU;EAUV,iBAAiB;EAClB;CAKD,OAAO;EASL,kBAAkB;EAUlB,eAAe;EAChB;CACF"}

package/lib/systems/animation/constants/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Animation Constants Module
+ *
+ * Centralized constants for Korean martial arts animation system.
+ * Provides single source of truth for anatomical limits, timing values,
+ * and other animation-related constants.
+ *
+ * @module systems/animation/constants
+ * @category Animation Constants
+ * @korean 애니메이션상수모듈
+ */
+export { ANATOMICAL_LIMITS, type AnatomicalLimits, getAnatomicalLimit, degreesToRadians, radiansToDegrees, } from "./AnatomicalLimits";
+//# sourceMappingURL=index.d.ts.map

package/lib/systems/animation/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,184 @@
+/**
+ * Animation Hit Timing System
+ *
+ * **Korean**: 애니메이션 타격 타이밍
+ *
+ * Defines when visual contact occurs in animations for reality-based hit detection.
+ * Hits should only register when the animation visually shows limb contact with target.
+ *
+ * ## Philosophy
+ *
+ * Black Trigram emphasizes visual authenticity in combat. Hit detection must align
+ * with what the player sees on screen. This system defines the exact frames/timing
+ * when each technique's strike phase visually connects.
+ *
+ * ## Phases
+ *
+ * Korean martial arts techniques have distinct phases:
+ * - **준비 (Chamber)**: Wind-up, no contact possible
+ * - **실행 (Extension)**: Strike extending, contact window opens
+ * - **정점 (Peak)**: Maximum extension, highest contact probability
+ * - **회수 (Retraction)**: Pulling back, contact window closes
+ * - **복귀 (Recovery)**: Return to stance, no contact
+ *
+ * @module systems/animation/AnimationHitTiming
+ * @category Animation System
+ * @korean 애니메이션타격타이밍
+ */
+import { AnimationType } from "../builders/MartialArtsAnimationBuilder";
+/**
+ * Hit window timing for a technique animation.
+ *
+ * **Korean**: 타격 창 타이밍
+ *
+ * Defines when during an animation the technique can actually make contact.
+ * Based on visual reach during the extension phase.
+ *
+ * @example
+ * ```typescript
+ * const jabTiming: AnimationHitWindow = {
+ *   startTime: 0.10,      // Hit window opens at 100ms (after chamber)
+ *   peakTime: 0.15,       // Peak extension at 150ms
+ *   endTime: 0.20,        // Hit window closes at 200ms (before retraction)
+ *   maxReachMultiplier: 1.0, // 100% of limb length at peak
+ * };
+ * ```
+ *
+ * @public
+ * @korean 타격창타이밍
+ */
+export interface AnimationHitWindow {
+    /**
+     * Time when hit window opens (seconds).
+     * Start of extension phase where limb begins moving toward target.
+     * @korean 시작시간
+     */
+    readonly startTime: number;
+    /**
+     * Time of maximum extension (seconds).
+     * Peak of strike where reach is maximum and damage is highest.
+     * @korean 정점시간
+     */
+    readonly peakTime: number;
+    /**
+     * Time when hit window closes (seconds).
+     * End of extension phase where limb begins retracting.
+     * @korean 종료시간
+     */
+    readonly endTime: number;
+    /**
+     * Reach multiplier at peak extension (0.0 - 1.5).
+     * - 1.0 = full limb extension (standard strikes)
+     * - 0.7 = partial extension (close-range techniques)
+     * - 1.2+ = overextended (special techniques, jumping kicks)
+     * @korean 최대도달배수
+     */
+    readonly maxReachMultiplier: number;
+    /**
+     * Optional reach curve during hit window.
+     * If not provided, assumes linear interpolation from 0 to maxReachMultiplier.
+     * @korean 도달곡선
+     */
+    readonly reachCurve?: (normalizedTime: number) => number;
+}
+/**
+ * Complete hit timing configuration for a technique.
+ *
+ * **Korean**: 기술 타격 타이밍 설정
+ *
+ * @public
+ * @korean 기술타격타이밍
+ */
+export interface TechniqueHitTiming {
+    /**
+     * Animation type this timing applies to.
+     * @korean 애니메이션타입
+     */
+    readonly animationType: AnimationType;
+    /**
+     * Hit window configuration.
+     * @korean 타격창
+     */
+    readonly hitWindow: AnimationHitWindow;
+    /**
+     * Whether this technique requires precise timing (true) or has a wider window (false).
+     * Affects forgiveness in hit detection.
+     * @korean 정밀타이밍필요
+     */
+    readonly requiresPreciseTiming: boolean;
+}
+/**
+ * Hit timing database for animation types.
+ *
+ * **Korean**: 애니메이션 타격 타이밍 데이터베이스
+ *
+ * Based on TECHNIQUE_TIMING constants from MartialArtsAnimationBuilder.
+ * Only includes timing for techniques with actual hit windows.
+ * Movement and non-combat animations can query this and will get undefined.
+ *
+ * @public
+ * @korean 애니메이션타격타이밍데이터베이스
+ */
+export declare const ANIMATION_HIT_TIMING: Partial<Record<AnimationType, TechniqueHitTiming>>;
+/**
+ * Get hit timing configuration for an animation type.
+ *
+ * **Korean**: 애니메이션 타격 타이밍 가져오기
+ *
+ * @param animationType - Animation type to get timing for
+ * @returns Hit timing configuration, or undefined if not a combat animation
+ *
+ * @example
+ * ```typescript
+ * const jabTiming = getAnimationHitTiming(AnimationType.JAB);
+ * if (jabTiming) {
+ *   console.log(`Jab hit window: ${jabTiming.hitWindow.startTime}s - ${jabTiming.hitWindow.endTime}s`);
+ * }
+ * ```
+ *
+ * @public
+ * @korean 애니메이션타격타이밍가져오기
+ */
+export declare function getAnimationHitTiming(animationType: AnimationType): TechniqueHitTiming | undefined;
+/**
+ * Check if a technique can hit at the given animation time.
+ *
+ * **Korean**: 타격 가능 시간 확인
+ *
+ * @param animationType - Animation type
+ * @param currentTime - Current time in animation (seconds)
+ * @returns True if within hit window
+ *
+ * @example
+ * ```typescript
+ * const canHit = isWithinHitWindow(AnimationType.JAB, 0.15);
+ * // Returns true (0.15s is within jab's 0.10-0.25s window)
+ * ```
+ *
+ * @public
+ * @korean 타격가능시간확인
+ */
+export declare function isWithinHitWindow(animationType: AnimationType, currentTime: number): boolean;
+/**
+ * Calculate current reach multiplier at a specific time in the animation.
+ *
+ * **Korean**: 현재 도달 배수 계산
+ *
+ * @param animationType - Animation type
+ * @param currentTime - Current time in animation (seconds)
+ * @returns Reach multiplier (0.0 - max), or 0 if outside hit window
+ *
+ * @example
+ * ```typescript
+ * const reach = getCurrentReachMultiplier(AnimationType.JAB, 0.15);
+ * // Returns 0.95 (jab at peak time)
+ *
+ * const noReach = getCurrentReachMultiplier(AnimationType.JAB, 0.05);
+ * // Returns 0 (before hit window starts)
+ * ```
+ *
+ * @public
+ * @korean 현재도달배수계산
+ */
+export declare function getCurrentReachMultiplier(animationType: AnimationType, currentTime: number): number;
+//# sourceMappingURL=AnimationHitTiming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationHitTiming.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/core/AnimationHitTiming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CACxC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAutB1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,aAAa,GAC3B,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAQT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,MAAM,GAClB,MAAM,CAkCR"}