blacktrigram 0.7.2

package/lib/systems/physics/AttackMovementPhysics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttackMovementPhysics.js","names":[],"sources":["../../../src/systems/physics/AttackMovementPhysics.ts"],"sourcesContent":["/**\n * Attack Movement Physics System for realistic forward momentum during attacks.\n *\n * **Korean**: 공격 이동 물리 시스템 (Attack Movement Physics System)\n *\n * Implements realistic forward movement physics when fighters execute attacks.\n * Kicks naturally extend the body forward, punches lunge with body weight,\n * and spinning techniques carry rotational momentum.\n *\n * ## Attack Movement Mechanics\n *\n * Forward movement distance is determined by:\n * - Animation type (kicks > punches > elbows/knees)\n * - Stance modifiers (8 trigram stances affect aggression)\n * - Animation phase timing (extension → peak → recovery)\n *\n * ## Movement Integration\n *\n * - Extension phase (frames 3-6): Forward lunge with ease-out\n * - Peak phase (frame 6): Maximum extension reached\n * - Recovery phase (frames 7-10): Return to original stance\n * - Arena bounds: Automatically clamp movement to valid zone\n *\n * ## Performance\n *\n * Optimized for 60fps with efficient vector calculations and\n * smooth easing curves for realistic attack momentum feel.\n *\n * @module systems/physics/AttackMovementPhysics\n * @category Physics System\n * @korean 공격이동물리\n */\n\nimport * as THREE from \"three\";\nimport { TrigramStance } from \"@/types/common\";\nimport { AnimationType } from \"@/systems/animation\";\n\n/**\n * Configuration for attack movement calculation.\n *\n * **Korean**: 공격 이동 설정 (Attack Movement Configuration)\n *\n * @public\n * @korean 공격이동설정\n */\nexport interface AttackMovementConfig {\n  /** Animation type being executed */\n  readonly animationType: AnimationType;\n  /** Current trigram stance */\n  readonly currentStance: TrigramStance;\n  /** Normalized attack direction vector (attacker → target) */\n  readonly direction: THREE.Vector3;\n  /** Total attack animation duration in seconds */\n  readonly animationDuration: number;\n}\n\n/**\n * Result of attack movement calculation.\n *\n * **Korean**: 공격 이동 결과 (Attack Movement Result)\n *\n * Contains displacement vector and timing for attack lunge.\n *\n * @public\n * @korean 공격이동결과\n */\nexport interface AttackMovementResult {\n  /** Total forward displacement vector in world space */\n  readonly displacement: THREE.Vector3;\n  /** Duration of forward lunge phase in seconds */\n  readonly lungeDuration: number;\n  /** Duration of recovery return phase in seconds */\n  readonly recoveryDuration: number;\n  /** Total movement cycle duration in seconds */\n  readonly totalDuration: number;\n}\n\n/**\n * Attack Movement Physics Engine.\n *\n * **Korean**: 공격 이동 물리 엔진\n *\n * Calculates realistic forward movement during attack animations\n * based on technique type, stance modifiers, and animation timing.\n * Provides smooth lunge and recovery phases for authentic martial arts feel.\n *\n * @example\n * ```typescript\n * const physics = new AttackMovementPhysics();\n *\n * // Calculate movement for roundhouse kick\n * const config: AttackMovementConfig = {\n *   animationType: AnimationType.ROUNDHOUSE_KICK,\n *   currentStance: TrigramStance.LI, // Fire stance (aggressive)\n *   direction: new THREE.Vector3(1, 0, 0).normalize(),\n *   animationDuration: 0.48, // 480ms kick animation\n * };\n *\n * const result = physics.calculateAttackMovement(config);\n * // Result: 1.0m base * 1.3 (Fire bonus) = ~1.3m forward lunge\n * // lungeDuration: 0.24s (50% of animation)\n * // recoveryDuration: 0.24s (50% of animation)\n * ```\n *\n * @public\n * @korean 공격이동물리\n */\nexport class AttackMovementPhysics {\n  /**\n   * Calculates attack movement displacement and timing.\n   *\n   * **Korean**: 공격 이동 계산 (Calculate Attack Movement)\n   *\n   * Determines forward lunge distance and recovery timing based on:\n   * 1. Base movement from animation type\n   * 2. Stance movement modifier (8 trigram effects)\n   * 3. Animation phase durations (lunge vs recovery)\n   *\n   * @param config - Attack movement configuration\n   * @returns Attack movement result with displacement and timing\n   *\n   * @example\n   * ```typescript\n   * // Front kick with Heaven stance\n   * const kick = physics.calculateAttackMovement({\n   *   animationType: AnimationType.FRONT_KICK,\n   *   currentStance: TrigramStance.GEON,\n   *   direction: attackVector,\n   *   animationDuration: 0.4,\n   * });\n   * // Result: ~0.88m forward (0.8m * 1.1 Geon modifier)\n   *\n   * // Jab with Mountain stance\n   * const jab = physics.calculateAttackMovement({\n   *   animationType: AnimationType.JAB,\n   *   currentStance: TrigramStance.GAN,\n   *   direction: attackVector,\n   *   animationDuration: 0.25,\n   * });\n   * // Result: ~0.24m forward (0.3m * 0.8 Gan modifier)\n   * ```\n   *\n   * @public\n   * @korean 공격이동계산\n   */\n  calculateAttackMovement(\n    config: AttackMovementConfig\n  ): AttackMovementResult {\n    // 1. Get base movement distance for animation type\n    const baseDistance = this.getBaseMovementDistance(config.animationType);\n\n    // 2. Apply stance movement modifier\n    const stanceModifier = this.getStanceMovementModifier(config.currentStance);\n    const finalDistance = baseDistance * stanceModifier;\n\n    // 3. Calculate displacement vector\n    const displacement = config.direction.clone().multiplyScalar(finalDistance);\n\n    // 4. Calculate phase durations (lunge + recovery)\n    const lungeDuration = config.animationDuration * 0.5; // First 50% = forward\n    const recoveryDuration = config.animationDuration * 0.5; // Last 50% = return\n\n    return {\n      displacement,\n      lungeDuration,\n      recoveryDuration,\n      totalDuration: config.animationDuration,\n    };\n  }\n\n  /**\n   * Gets base forward movement distance for animation type.\n   *\n   * **Korean**: 기본 이동 거리 (Base Movement Distance)\n   *\n   * Movement distances by technique category:\n   * - Kicks: 0.8-1.2m (leg extension, longest reach)\n   * - Punches: 0.3-0.5m (arm extension, body lunge)\n   * - Elbows/Knees: 0.2-0.3m (close range techniques)\n   * - Spinning: 0.5-0.8m (rotation carries momentum)\n   *\n   * @param animationType - Type of attack animation\n   * @returns Base movement distance in meters\n   *\n   * @private\n   * @korean 기본이동거리\n   */\n  private getBaseMovementDistance(animationType: AnimationType): number {\n    // Kicks - highest forward movement (leg extension)\n    if (\n      animationType === AnimationType.ROUNDHOUSE_KICK ||\n      animationType === AnimationType.SIDE_KICK ||\n      animationType === AnimationType.BACK_KICK\n    ) {\n      return 1.0; // 1.0m forward lunge\n    }\n\n    if (\n      animationType === AnimationType.FRONT_KICK ||\n      animationType === AnimationType.PUSH_KICK\n    ) {\n      return 0.8; // 0.8m forward lunge\n    }\n\n    if (\n      animationType === AnimationType.AXE_KICK ||\n      animationType === AnimationType.CRESCENT_KICK ||\n      animationType === AnimationType.LOW_KICK\n    ) {\n      return 0.9; // 0.9m forward lunge\n    }\n\n    // Spinning kicks - momentum carries body forward\n    if (\n      animationType === AnimationType.SPINNING_HOOK ||\n      animationType === AnimationType.SPINNING_HEEL_KICK ||\n      animationType === AnimationType.TORNADO_KICK\n    ) {\n      return 0.8; // 0.8m with rotation\n    }\n\n    // Jumping/flying kicks - aerial momentum\n    if (\n      animationType === AnimationType.FLYING_KICK ||\n      animationType === AnimationType.JUMPING_KICK\n    ) {\n      return 1.2; // 1.2m maximum extension\n    }\n\n    // Punches - moderate forward movement (arm + body lunge)\n    if (\n      animationType === AnimationType.CROSS ||\n      animationType === AnimationType.OVERHAND ||\n      animationType === AnimationType.HOOK\n    ) {\n      return 0.5; // 0.5m forward lunge\n    }\n\n    if (\n      animationType === AnimationType.JAB ||\n      animationType === AnimationType.BACKFIST\n    ) {\n      return 0.3; // 0.3m forward lunge\n    }\n\n    if (\n      animationType === AnimationType.UPPERCUT ||\n      animationType === AnimationType.HAMMER_FIST ||\n      animationType === AnimationType.PALM_STRIKE\n    ) {\n      return 0.4; // 0.4m forward lunge\n    }\n\n    // Elbow/Knee - minimal movement (close range)\n    if (\n      animationType === AnimationType.ELBOW_STRIKE ||\n      animationType === AnimationType.KNEE_STRIKE ||\n      animationType === AnimationType.KNEE_KICK ||\n      animationType === AnimationType.ELBOW_UPPERCUT ||\n      animationType === AnimationType.FLYING_KNEE ||\n      animationType === AnimationType.CLINCH_KNEE ||\n      animationType === AnimationType.SPINNING_ELBOW ||\n      animationType === AnimationType.TEMPLE_ELBOW ||\n      animationType === AnimationType.SPINNING_BACK_ELBOW ||\n      animationType === AnimationType.SPINAL_ELBOW ||\n      animationType === AnimationType.BRACHIAL_ELBOW ||\n      animationType === AnimationType.KIDNEY_KNEE ||\n      animationType === AnimationType.FEMORAL_KNEE\n    ) {\n      return 0.2; // 0.2m forward lunge\n    }\n\n    // Specialized jab variants - similar to jab (quick extension)\n    if (\n      animationType === AnimationType.SPEAR_HAND_STRIKE ||\n      animationType === AnimationType.NERVE_STRIKE ||\n      animationType === AnimationType.PRESSURE_POINT_STRIKE ||\n      animationType === AnimationType.LIGHTNING_STRIKE ||\n      animationType === AnimationType.RAPID_BARRAGE ||\n      animationType === AnimationType.RHYTHMIC_STRIKES ||\n      animationType === AnimationType.NERVE_PARALYSIS ||\n      animationType === AnimationType.THROAT_STRIKE ||\n      animationType === AnimationType.EYE_GOUGE\n    ) {\n      return 0.3; // 0.3m forward lunge (jab-like)\n    }\n\n    // Specialized cross variants - similar to cross (body weight transfer)\n    if (\n      animationType === AnimationType.HEAVEN_STRIKE ||\n      animationType === AnimationType.FLOWING_CROSS\n    ) {\n      return 0.5; // 0.5m forward lunge (cross-like)\n    }\n\n    // Specialized palm strikes - similar to palm strike\n    if (\n      animationType === AnimationType.SOLAR_PLEXUS_STRIKE ||\n      animationType === AnimationType.FLOWING_PUSH ||\n      animationType === AnimationType.LIVER_DISRUPTION ||\n      animationType === AnimationType.EAR_STRIKE\n    ) {\n      return 0.4; // 0.4m forward lunge (palm-like)\n    }\n\n    // Grappling - minimal forward movement (rotation/off-balancing in place)\n    if (\n      animationType === AnimationType.THROW ||\n      animationType === AnimationType.JOINT_LOCK ||\n      animationType === AnimationType.TAKEDOWN ||\n      animationType === AnimationType.SWEEP ||\n      animationType === AnimationType.CLINCH ||\n      animationType === AnimationType.GRAPPLE ||\n      animationType === AnimationType.SLAM ||\n      animationType === AnimationType.WRIST_LOCK ||\n      animationType === AnimationType.ARM_BAR ||\n      animationType === AnimationType.SHOULDER_LOCK ||\n      animationType === AnimationType.HIP_THROW ||\n      animationType === AnimationType.LEG_REAP ||\n      animationType === AnimationType.SMALL_CIRCLE_LOCK ||\n      animationType === AnimationType.FINGER_LOCK ||\n      animationType === AnimationType.ELBOW_LOCK ||\n      animationType === AnimationType.SHOULDER_MANIPULATION ||\n      animationType === AnimationType.MOUNTAIN_LOCK ||\n      animationType === AnimationType.EARTH_EMBRACE ||\n      animationType === AnimationType.CAROTID_CHOKE\n    ) {\n      return 0.05; // 0.05m forward movement for grappling entries\n    }\n\n    // Default - conservative minimal movement for any unmapped types\n    // Additional AnimationType values can be grouped with the closest category above\n    // to fine-tune their forward displacement without changing overall behavior\n    return 0.2;\n  }\n\n  /**\n   * Gets stance movement modifier for attack lunge.\n   *\n   * **Korean**: 자세 이동 배율 (Stance Movement Modifier)\n   *\n   * Trigram stance movement modifiers based on combat philosophy:\n   * - ☰ 건 (Geon/Heaven): +30% movement (aggressive, drives forward with pure yang)\n   * - ☳ 진 (Jin/Thunder): +20% movement (explosive power, shocking force)\n   * - ☴ 손 (Son/Wind): +15% movement (continuous flow, mobile)\n   * - ☲ 리 (Li/Fire): +10% movement (precision strikes, controlled aggression)\n   * - ☱ 태 (Tae/Lake): 0% (neutral, fluid and adaptive)\n   * - ☵ 감 (Gam/Water): 0% (neutral, flowing and flexible)\n   * - ☷ 곤 (Gon/Earth): -10% movement (grounded, stable techniques)\n   * - ☶ 간 (Gan/Mountain): -20% movement (defensive mastery, minimal advance)\n   *\n   * @param stance - Current trigram stance\n   * @returns Movement multiplier (0.8 to 1.3)\n   *\n   * @private\n   * @korean 자세이동배율\n   */\n  private getStanceMovementModifier(stance: TrigramStance): number {\n    const modifiers: Record<TrigramStance, number> = {\n      [TrigramStance.GEON]: 1.3, // Heaven: +30% aggressive forward pressure (pure yang drives forward)\n      [TrigramStance.JIN]: 1.2, // Thunder: +20% explosive movement\n      [TrigramStance.SON]: 1.15, // Wind: +15% flowing movement\n      [TrigramStance.LI]: 1.1, // Fire: +10% precision strikes with controlled forward movement\n      [TrigramStance.TAE]: 1.0, // Lake: neutral movement\n      [TrigramStance.GAM]: 1.0, // Water: neutral movement\n      [TrigramStance.GON]: 0.9, // Earth: -10% grounded movement\n      [TrigramStance.GAN]: 0.8, // Mountain: -20% defensive movement\n    };\n    return modifiers[stance];\n  }\n\n  /**\n   * Applies attack movement force to attacker position over time.\n   *\n   * **Korean**: 공격 이동 적용 (Apply Attack Movement)\n   *\n   * Uses smooth ease-out cubic curve for realistic lunge feel:\n   * - Fast initial forward movement (attack commitment)\n   * - Gradual deceleration at peak extension\n   * - Smooth return during recovery phase\n   *\n   * @param basePosition - Original stance position (does not change during attack)\n   * @param result - Attack movement result with displacement\n   * @param elapsedTime - Time elapsed since attack started\n   * @param isRecoveryPhase - Whether in recovery (return) phase\n   * @returns New position with attack displacement applied\n   *\n   * @example\n   * ```typescript\n   * // In animation update loop (60fps)\n   * const basePos = new THREE.Vector3(0, 0, 0); // Original stance position\n   * \n   * if (elapsedTime < result.lungeDuration) {\n   *   // Lunge forward phase\n   *   const newPosition = physics.applyAttackMovement(\n   *     basePos,\n   *     result,\n   *     elapsedTime,\n   *     false\n   *   );\n   * } else if (elapsedTime < result.totalDuration) {\n   *   // Recovery return phase\n   *   const newPosition = physics.applyAttackMovement(\n   *     basePos,\n   *     result,\n   *     elapsedTime,\n   *     true\n   *   );\n   * }\n   * ```\n   *\n   * @public\n   * @korean 공격이동적용\n   */\n  applyAttackMovement(\n    basePosition: THREE.Vector3,\n    result: AttackMovementResult,\n    elapsedTime: number,\n    isRecoveryPhase: boolean\n  ): THREE.Vector3 {\n    let progress: number;\n\n    if (!isRecoveryPhase) {\n      // Lunge forward phase\n      progress = Math.min(1.0, elapsedTime / result.lungeDuration);\n\n      // Smooth forward lunge curve (ease-out cubic)\n      // Fast initial commitment, gradual deceleration at peak\n      const easedProgress = 1 - Math.pow(1 - progress, 3);\n\n      // Calculate position along forward path\n      const currentDisplacement = result.displacement\n        .clone()\n        .multiplyScalar(easedProgress);\n\n      return basePosition.clone().add(currentDisplacement);\n    } else {\n      // Recovery return phase\n      const recoveryTime = elapsedTime - result.lungeDuration;\n      progress = Math.min(1.0, recoveryTime / result.recoveryDuration);\n\n      // Smooth return curve (ease-in cubic)\n      // Gradual start, faster finish back to stance\n      const easedProgress = Math.pow(progress, 3);\n\n      // Calculate return position (from peak back to origin)\n      const returnDisplacement = result.displacement\n        .clone()\n        .multiplyScalar(1.0 - easedProgress);\n\n      return basePosition.clone().add(returnDisplacement);\n    }\n  }\n\n  /**\n   * Checks if attacker is currently in lunge phase.\n   *\n   * **Korean**: 돌진 상태 확인 (Check Lunge State)\n   *\n   * @param elapsedTime - Time elapsed since attack started\n   * @param lungeDuration - Total lunge phase duration\n   * @returns True if in forward lunge phase\n   *\n   * @public\n   * @korean 돌진상태확인\n   */\n  isInLungePhase(elapsedTime: number, lungeDuration: number): boolean {\n    return elapsedTime < lungeDuration;\n  }\n\n  /**\n   * Checks if attacker is in recovery return phase.\n   *\n   * **Korean**: 회복 상태 확인 (Check Recovery State)\n   *\n   * @param elapsedTime - Time elapsed since attack started\n   * @param result - Attack movement result with timing\n   * @returns True if in recovery return phase\n   *\n   * @public\n   * @korean 회복상태확인\n   */\n  isInRecoveryPhase(\n    elapsedTime: number,\n    result: AttackMovementResult\n  ): boolean {\n    return (\n      elapsedTime >= result.lungeDuration &&\n      elapsedTime < result.totalDuration\n    );\n  }\n\n  /**\n   * Gets bilingual Korean-English name for lunge phase.\n   *\n   * **Korean**: 돌진 단계 이름 (Lunge Phase Name)\n   *\n   * @returns Korean and English phase names\n   *\n   * @public\n   * @korean 돌진단계이름\n   */\n  getLungePhaseName(): { korean: string; english: string } {\n    return {\n      korean: \"돌진\",\n      english: \"Lunge\",\n    };\n  }\n\n  /**\n   * Gets bilingual Korean-English name for recovery phase.\n   *\n   * **Korean**: 복귀 단계 이름 (Recovery Phase Name)\n   *\n   * @returns Korean and English phase names\n   *\n   * @public\n   * @korean 복귀단계이름\n   */\n  getRecoveryPhaseName(): { korean: string; english: string } {\n    return {\n      korean: \"복귀\",\n      english: \"Recovery\",\n    };\n  }\n}\n\nexport default AttackMovementPhysics;\n"],"mappings":"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"}

package/lib/systems/physics/CollisionDetection.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Collision Detection System for Black Trigram combat physics.
+ *
+ * **Korean**: 충돌 감지 시스템
+ *
+ * Implements precise collision detection for the 70 vital points combat system using:
+ * - Broad-phase AABB (Axis-Aligned Bounding Box) checks for performance
+ * - Narrow-phase raycasting for precise vital point detection
+ * - Attack reach validation based on technique and stance
+ * - Bounding boxes for 5 anatomical regions
+ *
+ * ## Architecture
+ *
+ * The system uses a two-phase collision detection approach:
+ *
+ * 1. **Broad-phase**: Fast AABB checks to eliminate impossible collisions
+ * 2. **Narrow-phase**: Precise raycasting to identify specific vital points
+ *
+ * This ensures 60fps performance even with complex collision queries.
+ *
+ * ## Performance
+ *
+ * - Broad-phase: O(1) per check (simple distance comparison)
+ * - Narrow-phase: O(n) where n = vital points in region (typically 8-20)
+ * - Target: <100 collision checks per frame for 60fps
+ *
+ * @example
+ * ```typescript
+ * const collision = new CollisionDetection();
+ *
+ * const result = collision.checkAttackHit(
+ *   { x: 0, y: 0, z: 5 },        // Attacker position
+ *   { x: 0, y: 0, z: 6.5 },      // Defender position
+ *   { id: "kick", type: "kick" }, // Technique
+ *   TrigramStance.LI,             // Attacker stance
+ *   "torso"                       // Target region
+ * );
+ *
+ * if (result.hit) {
+ *   console.log(`Hit ${result.vitalPoint?.names.english}!`);
+ *   console.log(`Accuracy: ${(result.accuracy * 100).toFixed(1)}%`);
+ * }
+ * ```
+ *
+ * @module systems/physics/CollisionDetection
+ * @category Combat Systems
+ * @korean 충돌감지시스템
+ */
+import { TrigramStance } from "../../types/common";
+import type { AnatomicalRegionPhysics, BoundingBox, CollisionResult, Position3D } from "../../types/physics";
+import type { VitalPoint } from "../vitalpoint/types";
+/**
+ * Collision Detection Engine for combat physics.
+ *
+ * **Korean**: 충돌 감지 엔진
+ *
+ * Provides efficient collision detection for combat using bounding boxes and raycasting.
+ * Optimized for 60fps performance with multiple simultaneous collision checks.
+ *
+ * @public
+ * @category Combat Systems
+ * @korean 충돌감지엔진
+ */
+export declare class CollisionDetection {
+    private readonly boundingBoxes;
+    private readonly raycaster;
+    private vitalPointsByRegion;
+    private readonly geometryCache;
+    private readonly coordinateMapper;
+    /**
+     * Creates a new CollisionDetection instance.
+     *
+     * Initializes bounding boxes for all anatomical regions and organizes
+     * vital points by region for efficient lookup.
+     */
+    constructor();
+    /**
+     * Cleans up Three.js resources.
+     *
+     * **Korean**: 자원 정리
+     *
+     * Disposes of cached geometries and releases memory to prevent leaks.
+     * Should be called when the CollisionDetection instance is no longer needed.
+     *
+     * @public
+     * @korean 자원정리
+     */
+    dispose(): void;
+    /**
+     * Checks if an attack hits the defender.
+     *
+     * **Korean**: 공격 타격 확인
+     *
+     * Performs two-phase collision detection:
+     * 1. Calculate effective attack reach based on technique and stance
+     * 2. Broad-phase: Check if defender is within reach
+     * 3. Broad-phase: Check if target region's AABB is within reach
+     * 4. Narrow-phase: Raycast to find precise vital point hit
+     *
+     * @param attackerPosition - 3D position of the attacker
+     * @param defenderPosition - 3D position of the defender
+     * @param technique - Technique being used with type information
+     * @param attackerStance - Attacker's current trigram stance
+     * @param targetRegion - Anatomical region being targeted
+     * @returns Collision result with hit status, vital point, distance, and accuracy
+     *
+     * @example
+     * ```typescript
+     * const result = collision.checkAttackHit(
+     *   { x: 0, y: 0, z: 5 },
+     *   { x: 0, y: 0, z: 6 },
+     *   { type: "punch" },
+     *   TrigramStance.GEON,
+     *   "head"
+     * );
+     * ```
+     *
+     * @public
+     * @korean 공격타격확인
+     */
+    checkAttackHit(attackerPosition: Position3D, defenderPosition: Position3D, technique: {
+        type?: string;
+        [key: string]: any;
+    }, attackerStance: TrigramStance, targetRegion: AnatomicalRegionPhysics): CollisionResult;
+    /**
+     * Calculates effective attack reach for a technique.
+     *
+     * **Korean**: 공격 범위 계산
+     *
+     * Applies stance modifiers to base technique reach.
+     *
+     * @param techniqueType - Type of technique
+     * @param stance - Current trigram stance
+     * @returns Attack reach with all modifiers applied
+     *
+     * @private
+     * @korean 공격범위계산
+     */
+    private calculateAttackReach;
+    /**
+     * Performs raycasting against a bounding box.
+     *
+     * **Korean**: 경계 상자 광선 투사
+     *
+     * Uses cached geometries from object pool to avoid repeated allocations
+     * during combat. Creates a Three.js mesh for the bounding box and performs
+     * raycasting to detect intersection points.
+     *
+     * Uses object pooling for Vector3 allocations to reduce GC pressure.
+     *
+     * @param query - Raycast query parameters
+     * @param box - Bounding box to test
+     * @param defenderPosition - Position of the defender
+     * @returns Intersection point or null if no hit
+     *
+     * @private
+     * @korean 경계상자광선투사
+     */
+    private raycastBoundingBox;
+    /**
+     * Creates Three.js geometry for a bounding box.
+     *
+     * Helper method for geometry cache initialization.
+     *
+     * @param box - Bounding box specification
+     * @returns Three.js geometry
+     *
+     * @private
+     * @korean 경계상자지오메트리생성
+     */
+    private createGeometryForBox;
+    /**
+     * Identifies the specific vital point hit within a region.
+     *
+     * **Korean**: 급소 식별
+     *
+     * Finds the closest vital point to the hit location within the targeted region.
+     *
+     * @param region - Anatomical region hit
+     * @param hitPoint - 3D point where attack intersected
+     * @param defenderPosition - Position of the defender
+     * @returns Closest vital point or null if none found
+     *
+     * @private
+     * @korean 급소식별
+     */
+    private identifyVitalPoint;
+    /**
+     * Calculates hit accuracy based on distance to vital point center.
+     *
+     * **Korean**: 타격 정확도 계산
+     *
+     * Accuracy decreases linearly with distance from vital point center.
+     * Perfect accuracy (1.0) at center, decreasing to 0 at 5cm radius.
+     *
+     * @param hitPoint - Point where attack landed
+     * @param vitalPoint - Target vital point
+     * @param defenderPosition - Position of the defender
+     * @returns Accuracy value from 0 to 1
+     *
+     * @private
+     * @korean 타격정확도계산
+     */
+    private calculateHitAccuracy;
+    /**
+     * Calculates Euclidean distance between two 3D points.
+     *
+     * @param pos1 - First position
+     * @param pos2 - Second position
+     * @returns Distance in meters
+     *
+     * @private
+     * @korean 3D거리계산
+     */
+    private calculateDistance3D;
+    /**
+     * Subtracts one 3D vector from another.
+     *
+     * @param v1 - First vector
+     * @param v2 - Second vector
+     * @returns Resulting vector
+     *
+     * @private
+     * @korean 벡터빼기
+     */
+    private subtractVectors3D;
+    /**
+     * Normalizes a 3D vector to unit length.
+     *
+     * @param vec - Vector to normalize
+     * @returns Normalized vector
+     *
+     * @private
+     * @korean 벡터정규화
+     */
+    private normalizeVector3D;
+    /**
+     * Parses technique type from string.
+     *
+     * @param techniqueTypeStr - Technique type as string
+     * @returns Parsed technique type
+     *
+     * @private
+     * @korean 기술유형파싱
+     */
+    private parseTechniqueType;
+    /**
+     * Initializes bounding boxes for all anatomical regions.
+     *
+     * Creates collision volumes for the 5 anatomical regions using the
+     * ANATOMICAL_DIMENSIONS constants from the physics types module.
+     *
+     * @private
+     * @korean 경계상자초기화
+     */
+    private initializeBoundingBoxes;
+    /**
+     * Initializes geometry cache for object pooling.
+     *
+     * Pre-creates all geometries needed for raycasting to avoid repeated
+     * allocations during combat. Critical for maintaining 60fps with up to
+     * 100 collision checks per frame.
+     *
+     * @private
+     * @korean 지오메트리캐시초기화
+     */
+    private initializeGeometryCache;
+    /**
+     * Organizes vital points by anatomical region for efficient lookup.
+     *
+     * NOTE: This categorization currently uses y-coordinate thresholds that assume
+     * positions are in meters. However, VITAL_POINTS_DATA uses pixel coordinates
+     * (e.g., y: 50), which will cause incorrect categorization. Most vital points
+     * will end up in the "legs" region since pixel y-coordinates are typically less
+     * than 0.8.
+     *
+     * TODO: After implementing 2D→3D coordinate mapping, update this method to use
+     * the converted 3D positions, or use the anatomical region data that may already
+     * exist in the vital points data structure.
+     *
+     * Categorizes the 70 vital points into their respective regions:
+     * - Head: 10 vital points
+     * - Neck: 8 vital points
+     * - Torso: 20 vital points
+     * - Arms: 16 vital points
+     * - Legs: 16 vital points
+     *
+     * @private
+     * @korean 급소영역별정리
+     */
+    private organizeVitalPointsByRegion;
+    /**
+     * Gets the bounding box for an anatomical region.
+     *
+     * @param region - Anatomical region
+     * @returns Bounding box or undefined if not found
+     *
+     * @public
+     * @korean 경계상자조회
+     */
+    getBoundingBox(region: AnatomicalRegionPhysics): BoundingBox | undefined;
+    /**
+     * Gets all bounding boxes.
+     *
+     * @returns Map of all bounding boxes by region
+     *
+     * @public
+     * @korean 모든경계상자조회
+     */
+    getAllBoundingBoxes(): ReadonlyMap<AnatomicalRegionPhysics, BoundingBox>;
+    /**
+     * Gets vital points for a specific region.
+     *
+     * @param region - Anatomical region
+     * @returns Array of vital points in that region
+     *
+     * @public
+     * @korean 영역별급소조회
+     */
+    getVitalPointsInRegion(region: AnatomicalRegionPhysics): readonly VitalPoint[];
+}
+export default CollisionDetection;
+//# sourceMappingURL=CollisionDetection.d.ts.map

package/lib/systems/physics/CollisionDetection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CollisionDetection.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/CollisionDetection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,eAAe,EACf,UAAU,EAGX,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtD;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAClB;IACZ,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,OAAO,CAAC,mBAAmB,CACf;IAGZ,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgD;IAG9E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD;;;;;OAKG;;IAQH;;;;;;;;;;OAUG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,cAAc,CACZ,gBAAgB,EAAE,UAAU,EAC5B,gBAAgB,EAAE,UAAU,EAE5B,SAAS,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,EAChD,cAAc,EAAE,aAAa,EAC7B,YAAY,EAAE,uBAAuB,GACpC,eAAe;IA4FlB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;IA0B5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,kBAAkB;IAwD1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IA8D/B;;;;;;;;;OASG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,2BAA2B;IAmDnC;;;;;;;;OAQG;IACH,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,WAAW,GAAG,SAAS;IAIxE;;;;;;;OAOG;IACH,mBAAmB,IAAI,WAAW,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAIxE;;;;;;;;OAQG;IACH,sBAAsB,CACpB,MAAM,EAAE,uBAAuB,GAC9B,SAAS,UAAU,EAAE;CAGzB;AAED,eAAe,kBAAkB,CAAC"}