blacktrigram 0.7.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"KnockbackPhysics.js","names":[],"sources":["../../../src/systems/physics/KnockbackPhysics.ts"],"sourcesContent":["/**\n * Knockback Physics System for realistic force-based displacement.\n * \n * **Korean**: 밀침 물리 시스템 (Knockback Physics System)\n * \n * Implements realistic combat knockback mechanics that calculate force-based\n * displacement when players are hit. The system integrates with BalanceSystem\n * for authentic stumbling/falling reactions.\n * \n * ## Knockback Mechanics\n * \n * Knockback force is determined by:\n * - Attack damage and technique type\n * - Impact angle and direction\n * - Current balance state\n * - Stance resistance modifiers (8 trigram stances)\n * \n * ## Balance Integration\n * \n * - High balance (>70%): Reduced knockback by 30%\n * - Medium balance (40-70%): Normal knockback\n * - Low balance (<40%): Increased knockback by 50%, stumbling\n * - Critical balance (<20%): Guaranteed fall, 2s recovery\n * \n * ## Performance\n * \n * Optimized for 60fps with efficient vector calculations and smooth\n * easing curves for realistic knockback feel.\n * \n * @module systems/physics/KnockbackPhysics\n * @category Physics System\n * @korean 밀침물리\n */\n\nimport * as THREE from 'three';\nimport { TrigramStance } from '@/types/common';\n\n/**\n * Balance state information for knockback calculations.\n * \n * **Korean**: 균형 상태 (Balance State)\n * \n * @public\n * @korean 균형상태\n */\nexport interface BalanceState {\n  /** Current balance value (0-100) */\n  readonly current: number;\n  /** Maximum balance value (typically 100) */\n  readonly max: number;\n}\n\n/**\n * Configuration for knockback force calculation.\n * \n * **Korean**: 밀침 설정 (Knockback Configuration)\n * \n * @public\n * @korean 밀침설정\n */\nexport interface KnockbackConfig {\n  /** Force magnitude in Newtons */\n  readonly force: number;\n  /** Normalized attack direction vector (attacker → defender) */\n  readonly direction: THREE.Vector3;\n  /** Duration of knockback effect in seconds */\n  readonly duration: number;\n  /** Current balance state */\n  readonly balanceState: BalanceState;\n  /** Current trigram stance */\n  readonly currentStance: TrigramStance;\n}\n\n/**\n * Result of knockback calculation.\n * \n * **Korean**: 밀침 결과 (Knockback Result)\n * \n * Contains displacement vector, animation timing, and fall determination.\n * \n * @public\n * @korean 밀침결과\n */\nexport interface KnockbackResult {\n  /** Total knockback displacement vector in world space */\n  readonly displacement: THREE.Vector3;\n  /** Duration of knockback animation in seconds */\n  readonly duration: number;\n  /** Vulnerable state duration after knockback ends in seconds */\n  readonly recoveryWindow: number;\n  /** Whether fall animation should trigger */\n  readonly shouldFall: boolean;\n}\n\n/**\n * Knockback Physics Engine.\n * \n * **Korean**: 밀침 물리 엔진\n * \n * Calculates realistic knockback displacement based on attack force,\n * stance resistance, and balance state. Integrates with BalanceSystem\n * for stumbling and falling mechanics.\n * \n * @example\n * ```typescript\n * const physics = new KnockbackPhysics();\n * \n * // Calculate knockback from heavy strike\n * const config: KnockbackConfig = {\n *   force: 800, // 80 damage\n *   direction: new THREE.Vector3(1, 0, 0).normalize(),\n *   duration: 0.8,\n *   balanceState: { current: 35, max: 100 }, // Low balance\n *   currentStance: TrigramStance.LI, // Fire stance (low resistance)\n * };\n * \n * const result = physics.calculateKnockback(config, 80);\n * // Result: 2.5m base * 1.3 (Fire penalty) * 1.5 (low balance) = ~4.9m\n * // shouldFall: false (balance > 20%)\n * // recoveryWindow: 1.05s (0.7s * 1.5 for low balance)\n * ```\n * \n * @public\n * @korean 밀침물리\n */\nexport class KnockbackPhysics {\n  /**\n   * Calculates knockback displacement and effects.\n   * \n   * **Korean**: 밀침 계산 (Calculate Knockback)\n   * \n   * Determines knockback distance, duration, and fall state based on:\n   * 1. Base knockback from damage amount\n   * 2. Stance resistance modifier (8 trigram effects)\n   * 3. Balance state modifier (stumbling/falling)\n   * 4. Recovery window (vulnerable state after)\n   * \n   * @param config - Knockback configuration with force and state\n   * @param attackDamage - Damage dealt by attack (0-100+)\n   * @returns Knockback result with displacement and timing\n   * \n   * @example\n   * ```typescript\n   * // Light strike on stable player\n   * const light = physics.calculateKnockback({\n   *   force: 300,\n   *   direction: attackVector,\n   *   duration: 0.3,\n   *   balanceState: { current: 85, max: 100 },\n   *   currentStance: TrigramStance.GEON,\n   * }, 30);\n   * // Result: ~0.3m knockback (0.5m * 0.9 Geon * 0.7 high balance)\n   * \n   * // Critical strike on low-balance player\n   * const critical = physics.calculateKnockback({\n   *   force: 1200,\n   *   direction: attackVector,\n   *   duration: 1.2,\n   *   balanceState: { current: 15, max: 100 },\n   *   currentStance: TrigramStance.SON,\n   * }, 110);\n   * // Result: ~9.6m knockback, shouldFall: true, 3.0s recovery\n   * ```\n   * \n   * @public\n   * @korean 밀침계산\n   */\n  calculateKnockback(config: KnockbackConfig, attackDamage: number): KnockbackResult {\n    // 1. Base knockback distance from damage\n    let baseDistance = this.getBaseKnockbackDistance(attackDamage);\n    \n    // 2. Apply stance resistance modifier\n    const stanceResistance = this.getStanceResistanceModifier(config.currentStance);\n    baseDistance *= (1 - stanceResistance);\n    \n    // 3. Apply balance modifier (stumbling/falling)\n    const balanceModifier = this.getBalanceModifier(config.balanceState);\n    const finalDistance = baseDistance * balanceModifier;\n    \n    // 4. Calculate displacement vector\n    const displacement = config.direction.clone().multiplyScalar(finalDistance);\n    \n    // 5. Determine duration based on distance\n    const duration = this.calculateKnockbackDuration(finalDistance);\n    \n    // 6. Calculate recovery window (vulnerable state)\n    const recoveryWindow = this.calculateRecoveryWindow(attackDamage, config.balanceState);\n    \n    // 7. Check if balance is critical (should fall)\n    const shouldFall = config.balanceState.current < 20;\n    \n    return {\n      displacement,\n      duration,\n      recoveryWindow,\n      shouldFall,\n    };\n  }\n\n  /**\n   * Gets base knockback distance from damage amount.\n   * \n   * **Korean**: 기본 밀침 거리 (Base Knockback Distance)\n   * \n   * Damage thresholds:\n   * - Light (20-40): 0.5m knockback, 0.3s duration\n   * - Medium (40-70): 1.2m knockback, 0.5s duration\n   * - Heavy (70-100): 2.5m knockback, 0.8s duration\n   * - Critical (100+): 4.0m knockback, 1.2s duration + fall\n   * \n   * @param damage - Attack damage amount\n   * @returns Base knockback distance in meters\n   * \n   * @private\n   * @korean 기본밀침거리\n   */\n  private getBaseKnockbackDistance(damage: number): number {\n    if (damage < 40) return 0.5;  // Light strike\n    if (damage < 70) return 1.2;  // Medium strike\n    if (damage < 100) return 2.5; // Heavy strike\n    return 4.0; // Critical strike\n  }\n\n  /**\n   * Gets stance resistance modifier for knockback.\n   * \n   * **Korean**: 자세 저항 배율 (Stance Resistance Modifier)\n   * \n   * Trigram stance resistance modifiers:\n   * - ☶ 간 (Gan/Mountain): +40% resistance (defensive mastery)\n   * - ☷ 곤 (Gon/Earth): +30% resistance (grounded techniques)\n   * - ☰ 건 (Geon/Heaven): +10% resistance (balanced force)\n   * - ☵ 감 (Gam/Water): 0% (neutral, adaptive)\n   * - ☱ 태 (Tae/Lake): 0% (neutral, fluid)\n   * - ☳ 진 (Jin/Thunder): -10% resistance (explosive power)\n   * - ☴ 손 (Son/Wind): -20% resistance (fluid, mobile)\n   * - ☲ 리 (Li/Fire): -30% resistance (aggressive, exposed)\n   * \n   * @param stance - Current trigram stance\n   * @returns Resistance modifier (-0.3 to +0.4)\n   * \n   * @private\n   * @korean 자세저항배율\n   */\n  private getStanceResistanceModifier(stance: TrigramStance): number {\n    const resistances: Record<TrigramStance, number> = {\n      [TrigramStance.GAN]: 0.40,  // Mountain: +40% resistance\n      [TrigramStance.GON]: 0.30,  // Earth: +30% resistance\n      [TrigramStance.GEON]: 0.10, // Heaven: +10% resistance\n      [TrigramStance.GAM]: 0.00,  // Water: neutral\n      [TrigramStance.TAE]: 0.00,  // Lake: neutral\n      [TrigramStance.JIN]: -0.10, // Thunder: -10% resistance\n      [TrigramStance.SON]: -0.20, // Wind: -20% resistance (fluid)\n      [TrigramStance.LI]: -0.30,  // Fire: -30% resistance (aggressive)\n    };\n    return resistances[stance];\n  }\n\n  /**\n   * Gets balance modifier for knockback distance.\n   * \n   * **Korean**: 균형 배율 (Balance Modifier)\n   * \n   * Balance thresholds:\n   * - High balance (>70%): 0.70x (30% reduction)\n   * - Medium balance (40-70%): 1.00x (normal)\n   * - Low balance (20-40%): 1.50x (50% increase, stumbling)\n   * - Critical balance (<20%): 2.00x (100% increase, falling)\n   * \n   * @param balanceState - Current balance state\n   * @returns Balance multiplier (0.7 to 2.0)\n   * \n   * @private\n   * @korean 균형배율\n   */\n  private getBalanceModifier(balanceState: BalanceState): number {\n    const balancePercent = (balanceState.current / balanceState.max) * 100;\n    \n    if (balancePercent > 70) return 0.70; // High balance: -30% knockback\n    if (balancePercent > 40) return 1.00; // Normal knockback\n    if (balancePercent > 20) return 1.50; // Low balance: +50% knockback\n    return 2.00; // Critical balance: +100% knockback\n  }\n\n  /**\n   * Calculates knockback animation duration.\n   * \n   * **Korean**: 밀침 지속시간 계산 (Calculate Knockback Duration)\n   * \n   * Linear relationship between distance and duration:\n   * - 0.5m = 0.3s (light)\n   * - 1.2m = 0.48s\n   * - 2.5m = 0.86s\n   * - 4.0m = 1.2s (critical)\n   * \n   * @param distance - Knockback distance in meters\n   * @returns Duration in seconds\n   * \n   * @private\n   * @korean 밀침지속시간계산\n   */\n  private calculateKnockbackDuration(distance: number): number {\n    // Linear relationship: 0.5m = 0.3s, 4.0m = 1.2s\n    return 0.3 + (distance / 4.0) * 0.9;\n  }\n\n  /**\n   * Calculates recovery window (vulnerability duration).\n   * \n   * **Korean**: 회복 대기시간 계산 (Calculate Recovery Window)\n   * \n   * Recovery windows by damage:\n   * - Light (<40): 0.2s vulnerability\n   * - Medium (40-70): 0.4s vulnerability\n   * - Heavy (70-100): 0.7s vulnerability\n   * - Critical (100+): 1.5s vulnerability + grounded\n   * \n   * Low balance increases vulnerability by 50%.\n   * \n   * @param damage - Attack damage amount\n   * @param balanceState - Current balance state\n   * @returns Vulnerability duration in seconds\n   * \n   * @private\n   * @korean 회복대기시간계산\n   */\n  private calculateRecoveryWindow(damage: number, balanceState: BalanceState): number {\n    // Base recovery time from damage\n    const baseRecoveryTime = damage < 40 ? 0.2 : damage < 70 ? 0.4 : damage < 100 ? 0.7 : 1.5;\n    \n    // Increase recovery time if balance is low (more vulnerable)\n    const balancePercent = (balanceState.current / balanceState.max) * 100;\n    const balanceModifier = balancePercent < 40 ? 1.5 : 1.0;\n    \n    return baseRecoveryTime * balanceModifier;\n  }\n\n  /**\n   * Applies knockback force to player position over time.\n   * \n   * **Korean**: 밀침 힘 적용 (Apply Knockback Force)\n   * \n   * Uses smooth ease-out cubic curve for realistic knockback feel:\n   * - Fast initial displacement (impact)\n   * - Gradual deceleration (friction/resistance)\n   * - Smooth stop at final position\n   * \n   * @param playerPosition - Current player position\n   * @param result - Knockback result with displacement\n   * @param deltaTime - Time elapsed since knockback started\n   * @param progress - Knockback progress (0 to 1)\n   * @returns New player position\n   * \n   * @example\n   * ```typescript\n   * // In game loop (60fps)\n   * const newPosition = physics.applyKnockbackForce(\n   *   playerPosition,\n   *   knockbackResult,\n   *   deltaTime,\n   *   elapsedTime / knockbackResult.duration\n   * );\n   * \n   * // Progress 0.0: At original position\n   * // Progress 0.5: ~88% of total displacement (ease-out)\n   * // Progress 1.0: At final position\n   * ```\n   * \n   * @public\n   * @korean 밀침힘적용\n   */\n  applyKnockbackForce(\n    playerPosition: THREE.Vector3,\n    result: KnockbackResult,\n    _deltaTime: number,\n    progress: number\n  ): THREE.Vector3 {\n    // Clamp progress to [0, 1]\n    const clampedProgress = Math.max(0, Math.min(1, progress));\n    \n    // Smooth knockback curve (ease-out cubic)\n    // Fast initial impact, gradual deceleration\n    const easedProgress = 1 - Math.pow(1 - clampedProgress, 3);\n    \n    // Calculate position along knockback path\n    const currentDisplacement = result.displacement.clone().multiplyScalar(easedProgress);\n    \n    return playerPosition.clone().add(currentDisplacement);\n  }\n\n  /**\n   * Checks if player is currently in knockback state.\n   * \n   * **Korean**: 밀침 상태 확인 (Check Knockback State)\n   * \n   * @param elapsedTime - Time elapsed since knockback started\n   * @param duration - Total knockback duration\n   * @returns True if still in knockback animation\n   * \n   * @public\n   * @korean 밀침상태확인\n   */\n  isInKnockback(elapsedTime: number, duration: number): boolean {\n    return elapsedTime < duration;\n  }\n\n  /**\n   * Checks if player is in recovery window (vulnerable state).\n   * \n   * **Korean**: 회복 대기 확인 (Check Recovery Window)\n   * \n   * @param elapsedTime - Time elapsed since knockback ended\n   * @param recoveryWindow - Total recovery window duration\n   * @returns True if in vulnerable recovery state\n   * \n   * @public\n   * @korean 회복대기확인\n   */\n  isInRecoveryWindow(elapsedTime: number, recoveryWindow: number): boolean {\n    return elapsedTime < recoveryWindow;\n  }\n\n  /**\n   * Gets bilingual Korean-English name for knockback state.\n   * \n   * **Korean**: 밀침 상태 이름 (Knockback State Name)\n   * \n   * @param shouldFall - Whether knockback causes fall\n   * @returns Korean and English state names\n   * \n   * @public\n   * @korean 밀침상태이름\n   */\n  static getKnockbackStateName(shouldFall: boolean): { korean: string; english: string } {\n    if (shouldFall) {\n      return {\n        korean: \"넘어짐\",\n        english: \"Falling\",\n      };\n    }\n    \n    return {\n      korean: \"밀침\",\n      english: \"Knockback\",\n    };\n  }\n\n  /**\n   * Gets bilingual Korean-English name for recovery state.\n   * \n   * **Korean**: 회복 상태 이름 (Recovery State Name)\n   * \n   * @returns Korean and English state names\n   * \n   * @public\n   * @korean 회복상태이름\n   */\n  getRecoveryStateName(): { korean: string; english: string } {\n    return {\n      korean: \"회복\",\n      english: \"Recovery\",\n    };\n  }\n\n  /**\n   * Gets bilingual Korean-English name for stumbling state.\n   * \n   * **Korean**: 휘청거림 상태 이름 (Stumbling State Name)\n   * \n   * @returns Korean and English state names\n   * \n   * @public\n   * @korean 휘청거림상태이름\n   */\n  getStumblingStateName(): { korean: string; english: string } {\n    return {\n      korean: \"휘청거림\",\n      english: \"Stumbling\",\n    };\n  }\n}\n\nexport default KnockbackPhysics;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6HA,IAAa,mBAAb,MAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C5B,mBAAmB,QAAyB,cAAuC;EAEjF,IAAI,eAAe,KAAK,yBAAyB,aAAa;EAG9D,MAAM,mBAAmB,KAAK,4BAA4B,OAAO,cAAc;AAC/E,kBAAiB,IAAI;EAGrB,MAAM,kBAAkB,KAAK,mBAAmB,OAAO,aAAa;EACpE,MAAM,gBAAgB,eAAe;AAcrC,SAAO;GACL,cAZmB,OAAO,UAAU,OAAO,CAAC,eAAe,cAAc;GAazE,UAVe,KAAK,2BAA2B,cAAc;GAW7D,gBARqB,KAAK,wBAAwB,cAAc,OAAO,aAAa;GASpF,YANiB,OAAO,aAAa,UAAU;GAOhD;;;;;;;;;;;;;;;;;;;CAoBH,yBAAiC,QAAwB;AACvD,MAAI,SAAS,GAAI,QAAO;AACxB,MAAI,SAAS,GAAI,QAAO;AACxB,MAAI,SAAS,IAAK,QAAO;AACzB,SAAO;;;;;;;;;;;;;;;;;;;;;;;CAwBT,4BAAoC,QAA+B;AAWjE,SAVmD;IAChD,cAAc,MAAM;IACpB,cAAc,MAAM;IACpB,cAAc,OAAO;IACrB,cAAc,MAAM;IACpB,cAAc,MAAM;IACpB,cAAc,MAAM;IACpB,cAAc,MAAM;IACpB,cAAc,KAAK;GACrB,CACkB;;;;;;;;;;;;;;;;;;;CAoBrB,mBAA2B,cAAoC;EAC7D,MAAM,iBAAkB,aAAa,UAAU,aAAa,MAAO;AAEnE,MAAI,iBAAiB,GAAI,QAAO;AAChC,MAAI,iBAAiB,GAAI,QAAO;AAChC,MAAI,iBAAiB,GAAI,QAAO;AAChC,SAAO;;;;;;;;;;;;;;;;;;;CAoBT,2BAAmC,UAA0B;AAE3D,SAAO,KAAO,WAAW,IAAO;;;;;;;;;;;;;;;;;;;;;;CAuBlC,wBAAgC,QAAgB,cAAoC;AAQlF,UANyB,SAAS,KAAK,KAAM,SAAS,KAAK,KAAM,SAAS,MAAM,KAAM,QAG9D,aAAa,UAAU,aAAa,MAAO,MAC1B,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCtD,oBACE,gBACA,QACA,YACA,UACe;EAMf,MAAM,gBAAgB,IAAI,KAAK,IAAI,IAJX,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,SAAS,CAAC,EAIF,EAAE;EAG1D,MAAM,sBAAsB,OAAO,aAAa,OAAO,CAAC,eAAe,cAAc;AAErF,SAAO,eAAe,OAAO,CAAC,IAAI,oBAAoB;;;;;;;;;;;;;;CAexD,cAAc,aAAqB,UAA2B;AAC5D,SAAO,cAAc;;;;;;;;;;;;;;CAevB,mBAAmB,aAAqB,gBAAiC;AACvE,SAAO,cAAc;;;;;;;;;;;;;CAcvB,OAAO,sBAAsB,YAA0D;AACrF,MAAI,WACF,QAAO;GACL,QAAQ;GACR,SAAS;GACV;AAGH,SAAO;GACL,QAAQ;GACR,SAAS;GACV;;;;;;;;;;;;CAaH,uBAA4D;AAC1D,SAAO;GACL,QAAQ;GACR,SAAS;GACV;;;;;;;;;;;;CAaH,wBAA6D;AAC3D,SAAO;GACL,QAAQ;GACR,SAAS;GACV"}

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

@@ -0,0 +1,428 @@
+/**
+ * Physics-based movement system for realistic combat movement.
+ *
+ * **Korean**: 이동 물리 시스템 (Movement Physics System)
+ *
+ * This module implements realistic physics-based player movement with proper
+ * acceleration/deceleration, foot-wide step precision, and stance-based speed
+ * modifiers for authentic Korean martial arts combat feel.
+ *
+ * ## Features
+ *
+ * - **Realistic Acceleration**: 0 to 2m/s in 0.5 seconds (4.0 m/s²)
+ * - **Realistic Deceleration**: 2m/s to 0 in 0.3 seconds (6.67 m/s²)
+ * - **Foot-wide Steps**: Discrete 30cm movement increments for tactical positioning
+ * - **Stance Modifiers**: 8 trigram stances with different speed characteristics
+ * - **Injury Integration**: Movement speed reduced by leg damage (10-50%)
+ *
+ * @module systems/physics/MovementPhysics
+ * @category Physics System
+ * @korean 이동물리
+ */
+import { TrigramStance } from "../../types/common";
+import type { MovementArenaBounds } from "../../types/PhysicsTypes";
+import * as THREE from "three";
+/**
+ * Movement input from keyboard/gamepad controls.
+ *
+ * **Korean**: 이동 입력 (Movement Input)
+ *
+ * @public
+ * @category Physics System
+ * @korean 이동입력
+ */
+export interface MovementInput {
+    /** Forward/backward input (-1 to 1, where 1 is forward) */
+    readonly forward: number;
+    /** Lateral left/right input (-1 to 1, where 1 is right) */
+    readonly lateral: number;
+    /** Whether sprint/run key is held */
+    readonly isRunning: boolean;
+    /** Whether any movement input is active */
+    readonly isMoving: boolean;
+    /** Whether to use tactical step mode (30cm grid) */
+    readonly useTacticalSteps: boolean;
+}
+/**
+ * Complete movement state for physics calculations.
+ *
+ * **Korean**: 이동 상태 (Movement State)
+ *
+ * Contains position, velocity, and current movement parameters.
+ * All vectors are mutable for performance (updated in-place during physics loop).
+ *
+ * @public
+ * @category Physics System
+ * @korean 이동상태
+ */
+export interface MovementState {
+    /**
+     * Current position in 3D space (meters).
+     *
+     * NOTE: This is a readonly reference to a mutable THREE.Vector3.
+     * The physics engine intentionally mutates the vector in-place
+     * (e.g. via position.add(...)) for performance. The readonly
+     * modifier prevents reassignment of the Vector3 instance, not
+     * mutation of its components.
+     */
+    readonly position: THREE.Vector3;
+    /**
+     * Current velocity vector (m/s).
+     *
+     * NOTE: This is a readonly reference to a mutable THREE.Vector3.
+     * The physics engine updates this vector in-place each frame.
+     * Callers must not reassign the velocity reference, but may pass
+     * it to APIs that read or modify its components.
+     */
+    readonly velocity: THREE.Vector3;
+    /** Current acceleration magnitude (m/s²) */
+    acceleration: number;
+    /** Maximum speed for current state (m/s) */
+    maxSpeed: number;
+    /** Current Eight Trigram stance */
+    readonly currentStance: TrigramStance;
+    /** Leg injury percentage (0-1, where 1 is fully injured) */
+    legInjuryFactor: number;
+}
+/**
+ * Stance-based speed modifiers for Eight Trigram system.
+ *
+ * **Korean**: 팔괘 속도 배수 (Eight Trigram Speed Multipliers)
+ *
+ * Each trigram stance has unique movement characteristics based on
+ * traditional Korean martial arts philosophy:
+ *
+ * - ☰ 건 (Geon/Heaven): 100% - Balanced, standard speed
+ * - ☱ 태 (Tae/Lake): 110% - Fluid movement, flowing techniques
+ * - ☲ 리 (Li/Fire): 120% - Aggressive, fast attacks
+ * - ☳ 진 (Jin/Thunder): 115% - Explosive power
+ * - ☴ 손 (Son/Wind): 125% - Continuous motion, fastest stance
+ * - ☵ 감 (Gam/Water): 105% - Adaptive, slightly faster than neutral
+ * - ☶ 간 (Gan/Mountain): 80% - Solid defense, slower movement
+ * - ☷ 곤 (Gon/Earth): 85% - Grounded, stable but slower
+ *
+ * @korean 자세속도배수
+ */
+export declare const STANCE_SPEED_MODIFIERS: Record<TrigramStance, number>;
+/**
+ * Physics-based movement engine for combat.
+ *
+ * **Korean**: 이동 물리 엔진 (Movement Physics Engine)
+ *
+ * Implements realistic acceleration, deceleration, and stance-based movement
+ * for authentic Korean martial arts combat. Supports both continuous movement
+ * and tactical foot-wide steps for precise positioning.
+ *
+ * @example
+ * ```typescript
+ * const physics = new MovementPhysics();
+ *
+ * const state: MovementState = {
+ *   position: new THREE.Vector3(0, 0, 0),
+ *   velocity: new THREE.Vector3(0, 0, 0),
+ *   acceleration: 0,
+ *   maxSpeed: 2.0,
+ *   currentStance: TrigramStance.GEON,
+ *   legInjuryFactor: 0,
+ * };
+ *
+ * const input: MovementInput = {
+ *   forward: 1.0,
+ *   lateral: 0,
+ *   isRunning: false,
+ *   isMoving: true,
+ *   useTacticalSteps: false,
+ * };
+ *
+ * // In game loop at 60fps
+ * physics.updateMovement(state, input, deltaTime);
+ * ```
+ *
+ * @public
+ * @category Physics System
+ * @korean 이동물리엔진
+ */
+export declare class MovementPhysics {
+    /**
+     * Base acceleration rate (m/s²)
+     * Achieves 0 to 6m/s in 0.2 seconds (instant-response combat movement)
+     * Increased from 12.0 to 30.0 for arcade-style responsiveness
+     *
+     * Imported from physicsConstants.ts to maintain consistency across systems.
+     *
+     * **Korean**: 기본 가속도 (Base Acceleration)
+     */
+    private readonly BASE_ACCELERATION;
+    /**
+     * Base deceleration rate (m/s²)
+     * Achieves 6m/s to 0 in 0.3 seconds (responsive combat stopping)
+     *
+     * **Korean**: 기본 감속도 (Base Deceleration)
+     */
+    private readonly BASE_DECELERATION;
+    /**
+     * Foot-wide step size (meters)
+     * Standard Korean martial arts step is approximately 30cm
+     *
+     * **Korean**: 보법 거리 (Step Distance)
+     */
+    private readonly STEP_SIZE;
+    /**
+     * Base walking speed (m/s)
+     * Optimized for responsive combat movement - crosses 14m arena in ~2.3s
+     *
+     * **Korean**: 기본 걷기 속도 (Base Walking Speed)
+     */
+    private readonly BASE_WALK_SPEED;
+    /**
+     * Base running speed (m/s)
+     * Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s
+     *
+     * **Korean**: 기본 달리기 속도 (Base Running Speed)
+     */
+    private readonly BASE_RUN_SPEED;
+    /**
+     * Reference arena size for speed calibration (meters).
+     * All speeds are calibrated for a 10m arena.
+     *
+     * **Korean**: 기준 경기장 크기 (Reference Arena Size)
+     */
+    private readonly REFERENCE_ARENA_SIZE;
+    /**
+     * Current arena width in meters for arena-aware speed scaling.
+     *
+     * **Korean**: 현재 경기장 너비 (Current Arena Width)
+     */
+    private _arenaWidthMeters;
+    /**
+     * Override for max speed from external speed modifier systems.
+     *
+     * **Korean**: 최대속도 재정의 (Max Speed Override)
+     */
+    private _overrideMaxSpeed;
+    /**
+     * Override for acceleration from external speed modifier systems.
+     *
+     * **Korean**: 가속도 재정의 (Acceleration Override)
+     */
+    private _overrideAcceleration;
+    /**
+     * Cached arena speed scale to avoid repeated calculations.
+     *
+     * **Korean**: 캐시된 경기장 속도 배수 (Cached Arena Speed Scale)
+     */
+    private _cachedArenaSpeedScale;
+    private readonly tempTargetVelocity;
+    private readonly tempMovement;
+    private readonly tempDirection;
+    private readonly tempTargetDirection;
+    /**
+     * Create a new MovementPhysics instance.
+     *
+     * **Korean**: 이동 물리 생성 (Create Movement Physics)
+     *
+     * @param arenaWidthMeters - Width of the arena in meters (default: 10m, min: 1m)
+     * @throws {Error} If arenaWidthMeters is not a positive number
+     *
+     * @example
+     * ```typescript
+     * // Default 10m arena (1.0x speed scale)
+     * const physics = new MovementPhysics();
+     *
+     * // Small 6m arena (0.7x speed scale)
+     * const smallPhysics = new MovementPhysics(6.0);
+     *
+     * // Large 14m arena (1.3x speed scale)
+     * const largePhysics = new MovementPhysics(14.0);
+     * ```
+     *
+     * @public
+     */
+    constructor(arenaWidthMeters?: number);
+    /**
+     * Calculate arena-aware speed scaling factor.
+     *
+     * **Korean**: 경기장 크기 기반 속도 배수 (Arena-Based Speed Multiplier)
+     *
+     * Scales movement speed proportionally to arena size to maintain consistent
+     * gameplay feel across different screen resolutions. Smaller arenas get
+     * slightly slower speeds, larger arenas get slightly faster speeds.
+     *
+     * Formula: scaleFactor = arenaWidth / referenceArenaSize
+     * Clamped to [0.7, 1.3] range for balanced gameplay
+     *
+     * Examples:
+     * - 6m arena: 0.7x speed (70% of base)
+     * - 10m arena: 1.0x speed (baseline)
+     * - 14m arena: 1.3x speed (130% of base)
+     *
+     * @returns Speed multiplier (0.7 to 1.3)
+     *
+     * @korean 경기장속도배수
+     */
+    private calculateArenaSpeedScale;
+    /**
+     * Update player movement based on input and physics.
+     *
+     * **Korean**: 이동 업데이트 (Update Movement)
+     *
+     * Called every frame (60fps) to update player position based on
+     * current velocity, acceleration, and input. Applies stance modifiers
+     * and injury penalties automatically.
+     *
+     * @param state - Current movement state (modified in-place)
+     * @param input - Current movement input from controls
+     * @param deltaTime - Time since last update (seconds)
+     * @param bounds - Optional arena bounds for clamping position (meters)
+     *
+     * @korean 이동업데이트
+     */
+    updateMovement(state: MovementState, input: MovementInput, deltaTime: number, bounds?: MovementArenaBounds): void;
+    /**
+     * Get speed modifier for a specific trigram stance.
+     *
+     * **Korean**: 자세 속도 배수 가져오기 (Get Stance Speed Modifier)
+     *
+     * @param stance - Eight Trigram stance
+     * @returns Speed multiplier (0.8 to 1.25)
+     *
+     * @korean 자세속도배수
+     */
+    getStanceSpeedModifier(stance: TrigramStance): number;
+    /**
+     * Calculate movement penalty from leg injury.
+     *
+     * **Korean**: 부상 이동 페널티 (Injury Movement Penalty)
+     *
+     * Leg damage reduces movement speed by 10-50% based on injury severity.
+     *
+     * @param legHealthPercentage - Remaining leg health (0-1)
+     * @returns Injury factor (0 = no injury, 1 = maximum injury)
+     *
+     * @korean 부상페널티
+     */
+    calculateInjuryPenalty(legHealthPercentage: number): number;
+    /**
+     * Get maximum speed for current state configuration.
+     *
+     * **Korean**: 최대 속도 계산 (Calculate Maximum Speed)
+     *
+     * @param isRunning - Whether running (vs walking)
+     * @param stance - Current trigram stance
+     * @param legInjuryFactor - Leg injury severity (0-1)
+     * @returns Maximum speed in m/s (includes arena scaling)
+     *
+     * @korean 최대속도
+     */
+    getMaxSpeed(isRunning: boolean, stance: TrigramStance, legInjuryFactor: number): number;
+    /**
+     * Calculate time required to reach target speed from current velocity.
+     *
+     * **Korean**: 가속 시간 (Acceleration Time)
+     *
+     * @param currentSpeed - Current speed magnitude (m/s)
+     * @param targetSpeed - Desired speed magnitude (m/s)
+     * @returns Time in seconds to reach target speed
+     *
+     * @korean 가속시간
+     */
+    getAccelerationTime(currentSpeed: number, targetSpeed: number): number;
+    /**
+     * Calculate stopping distance from current velocity.
+     *
+     * **Korean**: 제동 거리 (Braking Distance)
+     *
+     * @param currentSpeed - Current speed magnitude (m/s)
+     * @returns Distance in meters required to stop
+     *
+     * @korean 제동거리
+     */
+    getStoppingDistance(currentSpeed: number): number;
+    /**
+     * Get tactical step size.
+     *
+     * **Korean**: 보법 거리 (Step Distance)
+     *
+     * @returns Step size in meters (0.3m = 30cm)
+     *
+     * @korean 보법거리
+     */
+    getStepSize(): number;
+    /**
+     * Override maximum speed for external speed modifier systems.
+     *
+     * **Korean**: 최대 속도 설정 (Set Maximum Speed)
+     *
+     * Allows external systems (like SpeedModifierSystem) to override
+     * the calculated maximum speed. This is applied in the next
+     * updateMovement call.
+     *
+     * @param speed - Maximum speed in m/s
+     *
+     * @public
+     */
+    setMaxSpeed(speed: number): void;
+    /**
+     * Override acceleration for external speed modifier systems.
+     *
+     * **Korean**: 가속도 설정 (Set Acceleration)
+     *
+     * Allows external systems (like SpeedModifierSystem) to override
+     * the base acceleration rate. This is applied in the next
+     * updateMovement call.
+     *
+     * @param acceleration - Acceleration in m/s²
+     *
+     * @public
+     */
+    setAcceleration(acceleration: number): void;
+    /**
+     * Clear speed and acceleration overrides.
+     *
+     * **Korean**: 속도 재정의 해제 (Clear Speed Overrides)
+     *
+     * Resets movement to use default calculations without external
+     * override values.
+     *
+     * @public
+     */
+    clearOverrides(): void;
+    /**
+     * Set arena width for arena-aware speed scaling.
+     *
+     * **Korean**: 경기장 너비 설정 (Set Arena Width)
+     *
+     * Updates the arena width used for speed scaling calculations.
+     * Call this when the arena size changes (e.g., screen resize).
+     * Recalculates and caches the arena speed scale.
+     *
+     * @param widthMeters - Arena width in meters (must be positive)
+     * @throws {Error} If widthMeters is not a positive number
+     *
+     * @public
+     */
+    setArenaWidth(widthMeters: number): void;
+    /**
+     * Get current arena width.
+     *
+     * **Korean**: 경기장 너비 가져오기 (Get Arena Width)
+     *
+     * @returns Arena width in meters
+     *
+     * @public
+     */
+    getArenaWidth(): number;
+    /**
+     * Get current arena speed scale factor.
+     *
+     * **Korean**: 경기장 속도 배수 가져오기 (Get Arena Speed Scale)
+     *
+     * Returns the cached arena speed scale value.
+     *
+     * @returns Arena-based speed multiplier (0.7 to 1.3)
+     *
+     * @public
+     */
+    getArenaSpeedScale(): number;
+}
+//# sourceMappingURL=MovementPhysics.d.ts.map

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

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