blacktrigram 0.7.44 → 0.7.47

package/lib/systems/physics/MovementPhysics.js

@@ -86,7 +86,6 @@ var STANCE_SPEED_MODIFIERS = {
 * physics.updateMovement(state, input, deltaTime);
 * ```
 *
-* @public
 * @category Physics System
 * @korean 이동물리엔진
 */
@@ -184,7 +183,6 @@ var MovementPhysics = class {
 	* const largePhysics = new MovementPhysics(14.0);
 	* ```
 	*
-	* @public
 	*/
 	constructor(arenaWidthMeters = 10) {
 		if (arenaWidthMeters <= 0 || !Number.isFinite(arenaWidthMeters)) throw new Error(`Arena width must be a positive finite number, got: ${arenaWidthMeters}`);
@@ -402,7 +400,6 @@ var MovementPhysics = class {
 	*
 	* @param speed - Maximum speed in m/s
 	*
-	* @public
 	*/
 	setMaxSpeed(speed) {
 		this._overrideMaxSpeed = speed;
@@ -418,7 +415,6 @@ var MovementPhysics = class {
 	*
 	* @param acceleration - Acceleration in m/s²
 	*
-	* @public
 	*/
 	setAcceleration(acceleration) {
 		this._overrideAcceleration = acceleration;
@@ -431,7 +427,6 @@ var MovementPhysics = class {
 	* Resets movement to use default calculations without external
 	* override values.
 	*
-	* @public
 	*/
 	clearOverrides() {
 		this._overrideMaxSpeed = null;
@@ -449,7 +444,6 @@ var MovementPhysics = class {
 	* @param widthMeters - Arena width in meters (must be positive)
 	* @throws {Error} If widthMeters is not a positive number
 	*
-	* @public
 	*/
 	setArenaWidth(widthMeters) {
 		if (widthMeters <= 0 || !Number.isFinite(widthMeters)) throw new Error(`Arena width must be a positive finite number, got: ${widthMeters}`);
@@ -463,7 +457,6 @@ var MovementPhysics = class {
 	*
 	* @returns Arena width in meters
 	*
-	* @public
 	*/
 	getArenaWidth() {
 		return this._arenaWidthMeters;
@@ -477,7 +470,6 @@ var MovementPhysics = class {
 	*
 	* @returns Arena-based speed multiplier (0.7 to 1.3)
 	*
-	* @public
 	*/
 	getArenaSpeedScale() {
 		return this._cachedArenaSpeedScale;

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

@@ -1 +1 @@
-{"version":3,"file":"MovementPhysics.js","names":[],"sources":["../../../src/systems/physics/MovementPhysics.ts"],"sourcesContent":["/**\n * Physics-based movement system for realistic combat movement.\n *\n * **Korean**: 이동 물리 시스템 (Movement Physics System)\n *\n * This module implements realistic physics-based player movement with proper\n * acceleration/deceleration, foot-wide step precision, and stance-based speed\n * modifiers for authentic Korean martial arts combat feel.\n *\n * ## Features\n *\n * - **Realistic Acceleration**: 0 to 2m/s in 0.5 seconds (4.0 m/s²)\n * - **Realistic Deceleration**: 2m/s to 0 in 0.3 seconds (6.67 m/s²)\n * - **Foot-wide Steps**: Discrete 30cm movement increments for tactical positioning\n * - **Stance Modifiers**: 8 trigram stances with different speed characteristics\n * - **Injury Integration**: Movement speed reduced by leg damage (10-50%)\n *\n * @module systems/physics/MovementPhysics\n * @category Physics System\n * @korean 이동물리\n */\n\nimport { TrigramStance } from \"@/types/common\";\nimport { BASE_MOVEMENT_ACCELERATION } from \"@/types/physicsConstants\";\nimport type { MovementArenaBounds } from \"@/types/PhysicsTypes\";\nimport * as THREE from \"three\";\n\n/**\n * Movement input from keyboard/gamepad controls.\n *\n * **Korean**: 이동 입력 (Movement Input)\n *\n * @public\n * @category Physics System\n * @korean 이동입력\n */\nexport interface MovementInput {\n  /** Forward/backward input (-1 to 1, where 1 is forward) */\n  readonly forward: number;\n  /** Lateral left/right input (-1 to 1, where 1 is right) */\n  readonly lateral: number;\n  /** Whether sprint/run key is held */\n  readonly isRunning: boolean;\n  /** Whether any movement input is active */\n  readonly isMoving: boolean;\n  /** Whether to use tactical step mode (30cm grid) */\n  readonly useTacticalSteps: boolean;\n}\n\n/**\n * Complete movement state for physics calculations.\n *\n * **Korean**: 이동 상태 (Movement State)\n *\n * Contains position, velocity, and current movement parameters.\n * All vectors are mutable for performance (updated in-place during physics loop).\n *\n * @public\n * @category Physics System\n * @korean 이동상태\n */\nexport interface MovementState {\n  /**\n   * Current position in 3D space (meters).\n   *\n   * NOTE: This is a readonly reference to a mutable THREE.Vector3.\n   * The physics engine intentionally mutates the vector in-place\n   * (e.g. via position.add(...)) for performance. The readonly\n   * modifier prevents reassignment of the Vector3 instance, not\n   * mutation of its components.\n   */\n  readonly position: THREE.Vector3;\n  /**\n   * Current velocity vector (m/s).\n   *\n   * NOTE: This is a readonly reference to a mutable THREE.Vector3.\n   * The physics engine updates this vector in-place each frame.\n   * Callers must not reassign the velocity reference, but may pass\n   * it to APIs that read or modify its components.\n   */\n  readonly velocity: THREE.Vector3;\n  /** Current acceleration magnitude (m/s²) */\n  acceleration: number;\n  /** Maximum speed for current state (m/s) */\n  maxSpeed: number;\n  /** Current Eight Trigram stance */\n  readonly currentStance: TrigramStance;\n  /** Leg injury percentage (0-1, where 1 is fully injured) */\n  legInjuryFactor: number;\n}\n\n/**\n * Stance-based speed modifiers for Eight Trigram system.\n *\n * **Korean**: 팔괘 속도 배수 (Eight Trigram Speed Multipliers)\n *\n * Each trigram stance has unique movement characteristics based on\n * traditional Korean martial arts philosophy:\n *\n * - ☰ 건 (Geon/Heaven): 100% - Balanced, standard speed\n * - ☱ 태 (Tae/Lake): 110% - Fluid movement, flowing techniques\n * - ☲ 리 (Li/Fire): 120% - Aggressive, fast attacks\n * - ☳ 진 (Jin/Thunder): 115% - Explosive power\n * - ☴ 손 (Son/Wind): 125% - Continuous motion, fastest stance\n * - ☵ 감 (Gam/Water): 105% - Adaptive, slightly faster than neutral\n * - ☶ 간 (Gan/Mountain): 80% - Solid defense, slower movement\n * - ☷ 곤 (Gon/Earth): 85% - Grounded, stable but slower\n *\n * @korean 자세속도배수\n */\nexport const STANCE_SPEED_MODIFIERS: Record<TrigramStance, number> = {\n  [TrigramStance.GEON]: 1.0, // Heaven: balanced\n  [TrigramStance.TAE]: 1.1, // Lake: fluid\n  [TrigramStance.LI]: 1.2, // Fire: aggressive\n  [TrigramStance.JIN]: 1.15, // Thunder: explosive\n  [TrigramStance.SON]: 1.25, // Wind: fastest\n  [TrigramStance.GAM]: 1.05, // Water: adaptive\n  [TrigramStance.GAN]: 0.8, // Mountain: defensive\n  [TrigramStance.GON]: 0.85, // Earth: grounded\n};\n\n/**\n * Physics-based movement engine for combat.\n *\n * **Korean**: 이동 물리 엔진 (Movement Physics Engine)\n *\n * Implements realistic acceleration, deceleration, and stance-based movement\n * for authentic Korean martial arts combat. Supports both continuous movement\n * and tactical foot-wide steps for precise positioning.\n *\n * @example\n * ```typescript\n * const physics = new MovementPhysics();\n *\n * const state: MovementState = {\n *   position: new THREE.Vector3(0, 0, 0),\n *   velocity: new THREE.Vector3(0, 0, 0),\n *   acceleration: 0,\n *   maxSpeed: 2.0,\n *   currentStance: TrigramStance.GEON,\n *   legInjuryFactor: 0,\n * };\n *\n * const input: MovementInput = {\n *   forward: 1.0,\n *   lateral: 0,\n *   isRunning: false,\n *   isMoving: true,\n *   useTacticalSteps: false,\n * };\n *\n * // In game loop at 60fps\n * physics.updateMovement(state, input, deltaTime);\n * ```\n *\n * @public\n * @category Physics System\n * @korean 이동물리엔진\n */\nexport class MovementPhysics {\n  /**\n   * Base acceleration rate (m/s²)\n   * Achieves 0 to 6m/s in 0.2 seconds (instant-response combat movement)\n   * Increased from 12.0 to 30.0 for arcade-style responsiveness\n   *\n   * Imported from physicsConstants.ts to maintain consistency across systems.\n   *\n   * **Korean**: 기본 가속도 (Base Acceleration)\n   */\n  private readonly BASE_ACCELERATION = BASE_MOVEMENT_ACCELERATION;\n\n  /**\n   * Base deceleration rate (m/s²)\n   * Achieves 6m/s to 0 in 0.3 seconds (responsive combat stopping)\n   *\n   * **Korean**: 기본 감속도 (Base Deceleration)\n   */\n  private readonly BASE_DECELERATION = 20.0;\n\n  /**\n   * Foot-wide step size (meters)\n   * Standard Korean martial arts step is approximately 30cm\n   *\n   * **Korean**: 보법 거리 (Step Distance)\n   */\n  private readonly STEP_SIZE = 0.3;\n\n  /**\n   * Base walking speed (m/s)\n   * Optimized for responsive combat movement - crosses 14m arena in ~2.3s\n   *\n   * **Korean**: 기본 걷기 속도 (Base Walking Speed)\n   */\n  private readonly BASE_WALK_SPEED = 6.0;\n\n  /**\n   * Base running speed (m/s)\n   * Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s\n   *\n   * **Korean**: 기본 달리기 속도 (Base Running Speed)\n   */\n  private readonly BASE_RUN_SPEED = 10.0;\n\n  /**\n   * Reference arena size for speed calibration (meters).\n   * All speeds are calibrated for a 10m arena.\n   *\n   * **Korean**: 기준 경기장 크기 (Reference Arena Size)\n   */\n  private readonly REFERENCE_ARENA_SIZE = 10.0;\n\n  /**\n   * Current arena width in meters for arena-aware speed scaling.\n   *\n   * **Korean**: 현재 경기장 너비 (Current Arena Width)\n   */\n  private _arenaWidthMeters: number = 10.0;\n\n  // LATERAL_SPEED removed - now using state.maxSpeed for all directions\n  // This ensures speed override applies to lateral movement too\n\n  /**\n   * Override for max speed from external speed modifier systems.\n   *\n   * **Korean**: 최대속도 재정의 (Max Speed Override)\n   */\n  private _overrideMaxSpeed: number | null = null;\n\n  /**\n   * Override for acceleration from external speed modifier systems.\n   *\n   * **Korean**: 가속도 재정의 (Acceleration Override)\n   */\n  private _overrideAcceleration: number | null = null;\n\n  /**\n   * Cached arena speed scale to avoid repeated calculations.\n   *\n   * **Korean**: 캐시된 경기장 속도 배수 (Cached Arena Speed Scale)\n   */\n  private _cachedArenaSpeedScale: number = 1.0;\n\n  // Temporary vectors to avoid allocations in update loop\n  private readonly tempTargetVelocity = new THREE.Vector3();\n  private readonly tempMovement = new THREE.Vector3();\n  private readonly tempDirection = new THREE.Vector3();\n  private readonly tempTargetDirection = new THREE.Vector3();\n\n  /**\n   * Create a new MovementPhysics instance.\n   *\n   * **Korean**: 이동 물리 생성 (Create Movement Physics)\n   *\n   * @param arenaWidthMeters - Width of the arena in meters (default: 10m, min: 1m)\n   * @throws {Error} If arenaWidthMeters is not a positive number\n   *\n   * @example\n   * ```typescript\n   * // Default 10m arena (1.0x speed scale)\n   * const physics = new MovementPhysics();\n   *\n   * // Small 6m arena (0.7x speed scale)\n   * const smallPhysics = new MovementPhysics(6.0);\n   *\n   * // Large 14m arena (1.3x speed scale)\n   * const largePhysics = new MovementPhysics(14.0);\n   * ```\n   *\n   * @public\n   */\n  constructor(arenaWidthMeters: number = 10.0) {\n    if (arenaWidthMeters <= 0 || !Number.isFinite(arenaWidthMeters)) {\n      throw new Error(\n        `Arena width must be a positive finite number, got: ${arenaWidthMeters}`,\n      );\n    }\n    this._arenaWidthMeters = arenaWidthMeters;\n    this._cachedArenaSpeedScale = this.calculateArenaSpeedScale();\n  }\n\n  /**\n   * Calculate arena-aware speed scaling factor.\n   *\n   * **Korean**: 경기장 크기 기반 속도 배수 (Arena-Based Speed Multiplier)\n   *\n   * Scales movement speed proportionally to arena size to maintain consistent\n   * gameplay feel across different screen resolutions. Smaller arenas get\n   * slightly slower speeds, larger arenas get slightly faster speeds.\n   *\n   * Formula: scaleFactor = arenaWidth / referenceArenaSize\n   * Clamped to [0.7, 1.3] range for balanced gameplay\n   *\n   * Examples:\n   * - 6m arena: 0.7x speed (70% of base)\n   * - 10m arena: 1.0x speed (baseline)\n   * - 14m arena: 1.3x speed (130% of base)\n   *\n   * @returns Speed multiplier (0.7 to 1.3)\n   *\n   * @korean 경기장속도배수\n   */\n  private calculateArenaSpeedScale(): number {\n    const rawScale = this._arenaWidthMeters / this.REFERENCE_ARENA_SIZE;\n    // Clamp to reasonable range to maintain gameplay balance\n    return Math.max(0.7, Math.min(1.3, rawScale));\n  }\n\n  /**\n   * Update player movement based on input and physics.\n   *\n   * **Korean**: 이동 업데이트 (Update Movement)\n   *\n   * Called every frame (60fps) to update player position based on\n   * current velocity, acceleration, and input. Applies stance modifiers\n   * and injury penalties automatically.\n   *\n   * @param state - Current movement state (modified in-place)\n   * @param input - Current movement input from controls\n   * @param deltaTime - Time since last update (seconds)\n   * @param bounds - Optional arena bounds for clamping position (meters)\n   *\n   * @korean 이동업데이트\n   */\n  public updateMovement(\n    state: MovementState,\n    input: MovementInput,\n    deltaTime: number,\n    bounds?: MovementArenaBounds,\n  ): void {\n    // Use cached arena-aware speed scaling\n    const arenaSpeedScale = this._cachedArenaSpeedScale;\n\n    // Calculate stance speed modifier\n    const stanceModifier = this.getStanceSpeedModifier(state.currentStance);\n\n    // Calculate injury penalty (0-50% speed reduction)\n    const injuryPenalty = 1.0 - state.legInjuryFactor * 0.5;\n\n    // Calculate base target speed (walking or running)\n    const baseSpeed = input.isRunning\n      ? this.BASE_RUN_SPEED\n      : this.BASE_WALK_SPEED;\n\n    // Apply all modifiers including arena scaling to get final max speed (or use override)\n    state.maxSpeed =\n      this._overrideMaxSpeed ??\n      baseSpeed * arenaSpeedScale * stanceModifier * injuryPenalty;\n\n    // Use override acceleration if set, otherwise use base\n    const currentAcceleration =\n      this._overrideAcceleration ?? this.BASE_ACCELERATION;\n\n    // Calculate target velocity based on input direction\n    // forward > 0 = moving in positive Z direction (toward bottom of screen)\n    // forward < 0 = moving in negative Z direction (toward top of screen)\n    // ✅ REMOVED backward multiplier: All directions use full speed for responsive gameplay\n    // The backward penalty should be applied contextually by the combat system\n    // based on player facing direction vs movement direction\n    // ✅ FIX: Both lateral and forward now use state.maxSpeed (which includes all modifiers)\n    // This ensures consistent speed in all movement directions and includes arena scaling\n    this.tempTargetVelocity.set(\n      input.lateral * state.maxSpeed,\n      0,\n      input.forward * state.maxSpeed,\n    );\n\n    // Apply acceleration or deceleration\n    if (input.isMoving) {\n      // Accelerate toward target velocity with realistic direction changes\n      const currentSpeed = state.velocity.length();\n      const targetSpeed = this.tempTargetVelocity.length();\n\n      if (currentSpeed < targetSpeed) {\n        // Check if direction change is needed\n        if (currentSpeed > 0.001 && targetSpeed > 0.001) {\n          // Current movement direction\n          this.tempDirection.copy(state.velocity).normalize();\n          // Desired movement direction (reuse temp vector to avoid allocation)\n          this.tempTargetDirection.copy(this.tempTargetVelocity).normalize();\n          const directionDot = this.tempDirection.dot(this.tempTargetDirection);\n\n          if (directionDot < 0) {\n            // Moving in opposite direction: decelerate first before reversing\n            const velocityDelta = this.BASE_DECELERATION * deltaTime;\n            const newSpeed = Math.max(currentSpeed - velocityDelta, 0);\n\n            if (newSpeed > 0.001) {\n              state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            } else {\n              // Fully stopped; can now start accelerating in new direction\n              state.velocity.set(0, 0, 0);\n            }\n            state.acceleration = -this.BASE_DECELERATION;\n          } else if (directionDot < 0.7) {\n            // Perpendicular direction change (e.g., forward to strafe): moderate deceleration\n            const blendedAccel = currentAcceleration * 0.6; // Reduced acceleration for sharp turns\n            const velocityDelta = blendedAccel * deltaTime;\n            const newSpeed = Math.min(\n              currentSpeed + velocityDelta,\n              targetSpeed,\n            );\n            this.tempDirection.copy(this.tempTargetVelocity).normalize();\n            state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            state.acceleration = blendedAccel;\n          } else {\n            // Same or similar direction: full acceleration\n            this.tempDirection.copy(this.tempTargetVelocity).normalize();\n            const velocityDelta = currentAcceleration * deltaTime;\n            const newSpeed = Math.min(\n              currentSpeed + velocityDelta,\n              targetSpeed,\n            );\n            state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            state.acceleration = currentAcceleration;\n          }\n        } else {\n          // Very low speed: safe to accelerate directly toward target\n          this.tempDirection.copy(this.tempTargetVelocity).normalize();\n          const velocityDelta = currentAcceleration * deltaTime;\n          const newSpeed = Math.min(currentSpeed + velocityDelta, targetSpeed);\n          state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n          state.acceleration = currentAcceleration;\n        }\n      } else {\n        // Already at or above target speed: snap to target velocity\n        state.velocity.copy(this.tempTargetVelocity);\n        state.acceleration = 0;\n      }\n    } else {\n      // Decelerate to stop\n      const currentSpeed = state.velocity.length();\n      if (currentSpeed > 0.01) {\n        this.tempDirection.copy(state.velocity).normalize();\n        const velocityDelta = this.BASE_DECELERATION * deltaTime;\n        const newSpeed = Math.max(currentSpeed - velocityDelta, 0);\n        state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n      } else {\n        state.velocity.set(0, 0, 0);\n      }\n      state.acceleration = -this.BASE_DECELERATION;\n    }\n\n    // Calculate movement delta for this frame\n    this.tempMovement.copy(state.velocity).multiplyScalar(deltaTime);\n\n    // Apply tactical step quantization if enabled\n    if (input.useTacticalSteps) {\n      // Quantize to 30cm grid steps\n      this.tempMovement.x =\n        Math.round(this.tempMovement.x / this.STEP_SIZE) * this.STEP_SIZE;\n      this.tempMovement.z =\n        Math.round(this.tempMovement.z / this.STEP_SIZE) * this.STEP_SIZE;\n    }\n\n    // Update position\n    state.position.add(this.tempMovement);\n\n    // Apply arena bounds clamping if bounds provided\n    if (bounds) {\n      // Check if position exceeded boundaries\n      const exceededMinX = state.position.x < bounds.minX;\n      const exceededMaxX = state.position.x > bounds.maxX;\n      const exceededMinZ = state.position.z < bounds.minZ;\n      const exceededMaxZ = state.position.z > bounds.maxZ;\n\n      // Clamp position to arena boundaries\n      state.position.x = Math.max(bounds.minX, Math.min(bounds.maxX, state.position.x));\n      state.position.z = Math.max(bounds.minZ, Math.min(bounds.maxZ, state.position.z));\n\n      // Zero velocity component if exceeded boundary (smooth stopping)\n      if (exceededMinX || exceededMaxX) {\n        state.velocity.x = 0;\n      }\n      if (exceededMinZ || exceededMaxZ) {\n        state.velocity.z = 0;\n      }\n    }\n  }\n\n  /**\n   * Get speed modifier for a specific trigram stance.\n   *\n   * **Korean**: 자세 속도 배수 가져오기 (Get Stance Speed Modifier)\n   *\n   * @param stance - Eight Trigram stance\n   * @returns Speed multiplier (0.8 to 1.25)\n   *\n   * @korean 자세속도배수\n   */\n  public getStanceSpeedModifier(stance: TrigramStance): number {\n    return STANCE_SPEED_MODIFIERS[stance];\n  }\n\n  /**\n   * Calculate movement penalty from leg injury.\n   *\n   * **Korean**: 부상 이동 페널티 (Injury Movement Penalty)\n   *\n   * Leg damage reduces movement speed by 10-50% based on injury severity.\n   *\n   * @param legHealthPercentage - Remaining leg health (0-1)\n   * @returns Injury factor (0 = no injury, 1 = maximum injury)\n   *\n   * @korean 부상페널티\n   */\n  public calculateInjuryPenalty(legHealthPercentage: number): number {\n    // Injury penalty scales from 0% (healthy) to 50% (critical)\n    // Clamp between 0 and 1\n    const healthFactor = Math.max(0, Math.min(1, legHealthPercentage));\n    return 1.0 - healthFactor;\n  }\n\n  /**\n   * Get maximum speed for current state configuration.\n   *\n   * **Korean**: 최대 속도 계산 (Calculate Maximum Speed)\n   *\n   * @param isRunning - Whether running (vs walking)\n   * @param stance - Current trigram stance\n   * @param legInjuryFactor - Leg injury severity (0-1)\n   * @returns Maximum speed in m/s (includes arena scaling)\n   *\n   * @korean 최대속도\n   */\n  public getMaxSpeed(\n    isRunning: boolean,\n    stance: TrigramStance,\n    legInjuryFactor: number,\n  ): number {\n    const arenaSpeedScale = this._cachedArenaSpeedScale;\n    const baseSpeed = isRunning ? this.BASE_RUN_SPEED : this.BASE_WALK_SPEED;\n    const stanceModifier = this.getStanceSpeedModifier(stance);\n    const injuryPenalty = 1.0 - legInjuryFactor * 0.5;\n    return baseSpeed * arenaSpeedScale * stanceModifier * injuryPenalty;\n  }\n\n  /**\n   * Calculate time required to reach target speed from current velocity.\n   *\n   * **Korean**: 가속 시간 (Acceleration Time)\n   *\n   * @param currentSpeed - Current speed magnitude (m/s)\n   * @param targetSpeed - Desired speed magnitude (m/s)\n   * @returns Time in seconds to reach target speed\n   *\n   * @korean 가속시간\n   */\n  public getAccelerationTime(\n    currentSpeed: number,\n    targetSpeed: number,\n  ): number {\n    const speedDiff = Math.abs(targetSpeed - currentSpeed);\n    return speedDiff / this.BASE_ACCELERATION;\n  }\n\n  /**\n   * Calculate stopping distance from current velocity.\n   *\n   * **Korean**: 제동 거리 (Braking Distance)\n   *\n   * @param currentSpeed - Current speed magnitude (m/s)\n   * @returns Distance in meters required to stop\n   *\n   * @korean 제동거리\n   */\n  public getStoppingDistance(currentSpeed: number): number {\n    // Using kinematic equation: d = v² / (2a)\n    return (currentSpeed * currentSpeed) / (2 * this.BASE_DECELERATION);\n  }\n\n  /**\n   * Get tactical step size.\n   *\n   * **Korean**: 보법 거리 (Step Distance)\n   *\n   * @returns Step size in meters (0.3m = 30cm)\n   *\n   * @korean 보법거리\n   */\n  public getStepSize(): number {\n    return this.STEP_SIZE;\n  }\n\n  /**\n   * Override maximum speed for external speed modifier systems.\n   *\n   * **Korean**: 최대 속도 설정 (Set Maximum Speed)\n   *\n   * Allows external systems (like SpeedModifierSystem) to override\n   * the calculated maximum speed. This is applied in the next\n   * updateMovement call.\n   *\n   * @param speed - Maximum speed in m/s\n   *\n   * @public\n   */\n  public setMaxSpeed(speed: number): void {\n    this._overrideMaxSpeed = speed;\n  }\n\n  /**\n   * Override acceleration for external speed modifier systems.\n   *\n   * **Korean**: 가속도 설정 (Set Acceleration)\n   *\n   * Allows external systems (like SpeedModifierSystem) to override\n   * the base acceleration rate. This is applied in the next\n   * updateMovement call.\n   *\n   * @param acceleration - Acceleration in m/s²\n   *\n   * @public\n   */\n  public setAcceleration(acceleration: number): void {\n    this._overrideAcceleration = acceleration;\n  }\n\n  /**\n   * Clear speed and acceleration overrides.\n   *\n   * **Korean**: 속도 재정의 해제 (Clear Speed Overrides)\n   *\n   * Resets movement to use default calculations without external\n   * override values.\n   *\n   * @public\n   */\n  public clearOverrides(): void {\n    this._overrideMaxSpeed = null;\n    this._overrideAcceleration = null;\n  }\n\n  /**\n   * Set arena width for arena-aware speed scaling.\n   *\n   * **Korean**: 경기장 너비 설정 (Set Arena Width)\n   *\n   * Updates the arena width used for speed scaling calculations.\n   * Call this when the arena size changes (e.g., screen resize).\n   * Recalculates and caches the arena speed scale.\n   *\n   * @param widthMeters - Arena width in meters (must be positive)\n   * @throws {Error} If widthMeters is not a positive number\n   *\n   * @public\n   */\n  public setArenaWidth(widthMeters: number): void {\n    if (widthMeters <= 0 || !Number.isFinite(widthMeters)) {\n      throw new Error(\n        `Arena width must be a positive finite number, got: ${widthMeters}`,\n      );\n    }\n    this._arenaWidthMeters = widthMeters;\n    this._cachedArenaSpeedScale = this.calculateArenaSpeedScale();\n  }\n\n  /**\n   * Get current arena width.\n   *\n   * **Korean**: 경기장 너비 가져오기 (Get Arena Width)\n   *\n   * @returns Arena width in meters\n   *\n   * @public\n   */\n  public getArenaWidth(): number {\n    return this._arenaWidthMeters;\n  }\n\n  /**\n   * Get current arena speed scale factor.\n   *\n   * **Korean**: 경기장 속도 배수 가져오기 (Get Arena Speed Scale)\n   *\n   * Returns the cached arena speed scale value.\n   *\n   * @returns Arena-based speed multiplier (0.7 to 1.3)\n   *\n   * @public\n   */\n  public getArenaSpeedScale(): number {\n    return this._cachedArenaSpeedScale;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"MovementPhysics.js","names":[],"sources":["../../../src/systems/physics/MovementPhysics.ts"],"sourcesContent":["/**\n * Physics-based movement system for realistic combat movement.\n *\n * **Korean**: 이동 물리 시스템 (Movement Physics System)\n *\n * This module implements realistic physics-based player movement with proper\n * acceleration/deceleration, foot-wide step precision, and stance-based speed\n * modifiers for authentic Korean martial arts combat feel.\n *\n * ## Features\n *\n * - **Realistic Acceleration**: 0 to 2m/s in 0.5 seconds (4.0 m/s²)\n * - **Realistic Deceleration**: 2m/s to 0 in 0.3 seconds (6.67 m/s²)\n * - **Foot-wide Steps**: Discrete 30cm movement increments for tactical positioning\n * - **Stance Modifiers**: 8 trigram stances with different speed characteristics\n * - **Injury Integration**: Movement speed reduced by leg damage (10-50%)\n *\n * @module systems/physics/MovementPhysics\n * @category Physics System\n * @korean 이동물리\n */\n\nimport { TrigramStance } from \"@/types/common\";\nimport { BASE_MOVEMENT_ACCELERATION } from \"@/types/physicsConstants\";\nimport type { MovementArenaBounds } from \"@/types/PhysicsTypes\";\nimport * as THREE from \"three\";\n\n/**\n * Movement input from keyboard/gamepad controls.\n *\n * **Korean**: 이동 입력 (Movement Input)\n *\n * @category Physics System\n * @korean 이동입력\n */\nexport interface MovementInput {\n  /** Forward/backward input (-1 to 1, where 1 is forward) */\n  readonly forward: number;\n  /** Lateral left/right input (-1 to 1, where 1 is right) */\n  readonly lateral: number;\n  /** Whether sprint/run key is held */\n  readonly isRunning: boolean;\n  /** Whether any movement input is active */\n  readonly isMoving: boolean;\n  /** Whether to use tactical step mode (30cm grid) */\n  readonly useTacticalSteps: boolean;\n}\n\n/**\n * Complete movement state for physics calculations.\n *\n * **Korean**: 이동 상태 (Movement State)\n *\n * Contains position, velocity, and current movement parameters.\n * All vectors are mutable for performance (updated in-place during physics loop).\n *\n * @category Physics System\n * @korean 이동상태\n */\nexport interface MovementState {\n  /**\n   * Current position in 3D space (meters).\n   *\n   * NOTE: This is a readonly reference to a mutable THREE.Vector3.\n   * The physics engine intentionally mutates the vector in-place\n   * (e.g. via position.add(...)) for performance. The readonly\n   * modifier prevents reassignment of the Vector3 instance, not\n   * mutation of its components.\n   */\n  readonly position: THREE.Vector3;\n  /**\n   * Current velocity vector (m/s).\n   *\n   * NOTE: This is a readonly reference to a mutable THREE.Vector3.\n   * The physics engine updates this vector in-place each frame.\n   * Callers must not reassign the velocity reference, but may pass\n   * it to APIs that read or modify its components.\n   */\n  readonly velocity: THREE.Vector3;\n  /** Current acceleration magnitude (m/s²) */\n  acceleration: number;\n  /** Maximum speed for current state (m/s) */\n  maxSpeed: number;\n  /** Current Eight Trigram stance */\n  readonly currentStance: TrigramStance;\n  /** Leg injury percentage (0-1, where 1 is fully injured) */\n  legInjuryFactor: number;\n}\n\n/**\n * Stance-based speed modifiers for Eight Trigram system.\n *\n * **Korean**: 팔괘 속도 배수 (Eight Trigram Speed Multipliers)\n *\n * Each trigram stance has unique movement characteristics based on\n * traditional Korean martial arts philosophy:\n *\n * - ☰ 건 (Geon/Heaven): 100% - Balanced, standard speed\n * - ☱ 태 (Tae/Lake): 110% - Fluid movement, flowing techniques\n * - ☲ 리 (Li/Fire): 120% - Aggressive, fast attacks\n * - ☳ 진 (Jin/Thunder): 115% - Explosive power\n * - ☴ 손 (Son/Wind): 125% - Continuous motion, fastest stance\n * - ☵ 감 (Gam/Water): 105% - Adaptive, slightly faster than neutral\n * - ☶ 간 (Gan/Mountain): 80% - Solid defense, slower movement\n * - ☷ 곤 (Gon/Earth): 85% - Grounded, stable but slower\n *\n * @korean 자세속도배수\n */\nexport const STANCE_SPEED_MODIFIERS: Record<TrigramStance, number> = {\n  [TrigramStance.GEON]: 1.0, // Heaven: balanced\n  [TrigramStance.TAE]: 1.1, // Lake: fluid\n  [TrigramStance.LI]: 1.2, // Fire: aggressive\n  [TrigramStance.JIN]: 1.15, // Thunder: explosive\n  [TrigramStance.SON]: 1.25, // Wind: fastest\n  [TrigramStance.GAM]: 1.05, // Water: adaptive\n  [TrigramStance.GAN]: 0.8, // Mountain: defensive\n  [TrigramStance.GON]: 0.85, // Earth: grounded\n};\n\n/**\n * Physics-based movement engine for combat.\n *\n * **Korean**: 이동 물리 엔진 (Movement Physics Engine)\n *\n * Implements realistic acceleration, deceleration, and stance-based movement\n * for authentic Korean martial arts combat. Supports both continuous movement\n * and tactical foot-wide steps for precise positioning.\n *\n * @example\n * ```typescript\n * const physics = new MovementPhysics();\n *\n * const state: MovementState = {\n *   position: new THREE.Vector3(0, 0, 0),\n *   velocity: new THREE.Vector3(0, 0, 0),\n *   acceleration: 0,\n *   maxSpeed: 2.0,\n *   currentStance: TrigramStance.GEON,\n *   legInjuryFactor: 0,\n * };\n *\n * const input: MovementInput = {\n *   forward: 1.0,\n *   lateral: 0,\n *   isRunning: false,\n *   isMoving: true,\n *   useTacticalSteps: false,\n * };\n *\n * // In game loop at 60fps\n * physics.updateMovement(state, input, deltaTime);\n * ```\n *\n * @category Physics System\n * @korean 이동물리엔진\n */\nexport class MovementPhysics {\n  /**\n   * Base acceleration rate (m/s²)\n   * Achieves 0 to 6m/s in 0.2 seconds (instant-response combat movement)\n   * Increased from 12.0 to 30.0 for arcade-style responsiveness\n   *\n   * Imported from physicsConstants.ts to maintain consistency across systems.\n   *\n   * **Korean**: 기본 가속도 (Base Acceleration)\n   */\n  private readonly BASE_ACCELERATION = BASE_MOVEMENT_ACCELERATION;\n\n  /**\n   * Base deceleration rate (m/s²)\n   * Achieves 6m/s to 0 in 0.3 seconds (responsive combat stopping)\n   *\n   * **Korean**: 기본 감속도 (Base Deceleration)\n   */\n  private readonly BASE_DECELERATION = 20.0;\n\n  /**\n   * Foot-wide step size (meters)\n   * Standard Korean martial arts step is approximately 30cm\n   *\n   * **Korean**: 보법 거리 (Step Distance)\n   */\n  private readonly STEP_SIZE = 0.3;\n\n  /**\n   * Base walking speed (m/s)\n   * Optimized for responsive combat movement - crosses 14m arena in ~2.3s\n   *\n   * **Korean**: 기본 걷기 속도 (Base Walking Speed)\n   */\n  private readonly BASE_WALK_SPEED = 6.0;\n\n  /**\n   * Base running speed (m/s)\n   * Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s\n   *\n   * **Korean**: 기본 달리기 속도 (Base Running Speed)\n   */\n  private readonly BASE_RUN_SPEED = 10.0;\n\n  /**\n   * Reference arena size for speed calibration (meters).\n   * All speeds are calibrated for a 10m arena.\n   *\n   * **Korean**: 기준 경기장 크기 (Reference Arena Size)\n   */\n  private readonly REFERENCE_ARENA_SIZE = 10.0;\n\n  /**\n   * Current arena width in meters for arena-aware speed scaling.\n   *\n   * **Korean**: 현재 경기장 너비 (Current Arena Width)\n   */\n  private _arenaWidthMeters: number = 10.0;\n\n  // LATERAL_SPEED removed - now using state.maxSpeed for all directions\n  // This ensures speed override applies to lateral movement too\n\n  /**\n   * Override for max speed from external speed modifier systems.\n   *\n   * **Korean**: 최대속도 재정의 (Max Speed Override)\n   */\n  private _overrideMaxSpeed: number | null = null;\n\n  /**\n   * Override for acceleration from external speed modifier systems.\n   *\n   * **Korean**: 가속도 재정의 (Acceleration Override)\n   */\n  private _overrideAcceleration: number | null = null;\n\n  /**\n   * Cached arena speed scale to avoid repeated calculations.\n   *\n   * **Korean**: 캐시된 경기장 속도 배수 (Cached Arena Speed Scale)\n   */\n  private _cachedArenaSpeedScale: number = 1.0;\n\n  // Temporary vectors to avoid allocations in update loop\n  private readonly tempTargetVelocity = new THREE.Vector3();\n  private readonly tempMovement = new THREE.Vector3();\n  private readonly tempDirection = new THREE.Vector3();\n  private readonly tempTargetDirection = new THREE.Vector3();\n\n  /**\n   * Create a new MovementPhysics instance.\n   *\n   * **Korean**: 이동 물리 생성 (Create Movement Physics)\n   *\n   * @param arenaWidthMeters - Width of the arena in meters (default: 10m, min: 1m)\n   * @throws {Error} If arenaWidthMeters is not a positive number\n   *\n   * @example\n   * ```typescript\n   * // Default 10m arena (1.0x speed scale)\n   * const physics = new MovementPhysics();\n   *\n   * // Small 6m arena (0.7x speed scale)\n   * const smallPhysics = new MovementPhysics(6.0);\n   *\n   * // Large 14m arena (1.3x speed scale)\n   * const largePhysics = new MovementPhysics(14.0);\n   * ```\n   *\n   */\n  constructor(arenaWidthMeters: number = 10.0) {\n    if (arenaWidthMeters <= 0 || !Number.isFinite(arenaWidthMeters)) {\n      throw new Error(\n        `Arena width must be a positive finite number, got: ${arenaWidthMeters}`,\n      );\n    }\n    this._arenaWidthMeters = arenaWidthMeters;\n    this._cachedArenaSpeedScale = this.calculateArenaSpeedScale();\n  }\n\n  /**\n   * Calculate arena-aware speed scaling factor.\n   *\n   * **Korean**: 경기장 크기 기반 속도 배수 (Arena-Based Speed Multiplier)\n   *\n   * Scales movement speed proportionally to arena size to maintain consistent\n   * gameplay feel across different screen resolutions. Smaller arenas get\n   * slightly slower speeds, larger arenas get slightly faster speeds.\n   *\n   * Formula: scaleFactor = arenaWidth / referenceArenaSize\n   * Clamped to [0.7, 1.3] range for balanced gameplay\n   *\n   * Examples:\n   * - 6m arena: 0.7x speed (70% of base)\n   * - 10m arena: 1.0x speed (baseline)\n   * - 14m arena: 1.3x speed (130% of base)\n   *\n   * @returns Speed multiplier (0.7 to 1.3)\n   *\n   * @korean 경기장속도배수\n   */\n  private calculateArenaSpeedScale(): number {\n    const rawScale = this._arenaWidthMeters / this.REFERENCE_ARENA_SIZE;\n    // Clamp to reasonable range to maintain gameplay balance\n    return Math.max(0.7, Math.min(1.3, rawScale));\n  }\n\n  /**\n   * Update player movement based on input and physics.\n   *\n   * **Korean**: 이동 업데이트 (Update Movement)\n   *\n   * Called every frame (60fps) to update player position based on\n   * current velocity, acceleration, and input. Applies stance modifiers\n   * and injury penalties automatically.\n   *\n   * @param state - Current movement state (modified in-place)\n   * @param input - Current movement input from controls\n   * @param deltaTime - Time since last update (seconds)\n   * @param bounds - Optional arena bounds for clamping position (meters)\n   *\n   * @korean 이동업데이트\n   */\n  public updateMovement(\n    state: MovementState,\n    input: MovementInput,\n    deltaTime: number,\n    bounds?: MovementArenaBounds,\n  ): void {\n    // Use cached arena-aware speed scaling\n    const arenaSpeedScale = this._cachedArenaSpeedScale;\n\n    // Calculate stance speed modifier\n    const stanceModifier = this.getStanceSpeedModifier(state.currentStance);\n\n    // Calculate injury penalty (0-50% speed reduction)\n    const injuryPenalty = 1.0 - state.legInjuryFactor * 0.5;\n\n    // Calculate base target speed (walking or running)\n    const baseSpeed = input.isRunning\n      ? this.BASE_RUN_SPEED\n      : this.BASE_WALK_SPEED;\n\n    // Apply all modifiers including arena scaling to get final max speed (or use override)\n    state.maxSpeed =\n      this._overrideMaxSpeed ??\n      baseSpeed * arenaSpeedScale * stanceModifier * injuryPenalty;\n\n    // Use override acceleration if set, otherwise use base\n    const currentAcceleration =\n      this._overrideAcceleration ?? this.BASE_ACCELERATION;\n\n    // Calculate target velocity based on input direction\n    // forward > 0 = moving in positive Z direction (toward bottom of screen)\n    // forward < 0 = moving in negative Z direction (toward top of screen)\n    // ✅ REMOVED backward multiplier: All directions use full speed for responsive gameplay\n    // The backward penalty should be applied contextually by the combat system\n    // based on player facing direction vs movement direction\n    // ✅ FIX: Both lateral and forward now use state.maxSpeed (which includes all modifiers)\n    // This ensures consistent speed in all movement directions and includes arena scaling\n    this.tempTargetVelocity.set(\n      input.lateral * state.maxSpeed,\n      0,\n      input.forward * state.maxSpeed,\n    );\n\n    // Apply acceleration or deceleration\n    if (input.isMoving) {\n      // Accelerate toward target velocity with realistic direction changes\n      const currentSpeed = state.velocity.length();\n      const targetSpeed = this.tempTargetVelocity.length();\n\n      if (currentSpeed < targetSpeed) {\n        // Check if direction change is needed\n        if (currentSpeed > 0.001 && targetSpeed > 0.001) {\n          // Current movement direction\n          this.tempDirection.copy(state.velocity).normalize();\n          // Desired movement direction (reuse temp vector to avoid allocation)\n          this.tempTargetDirection.copy(this.tempTargetVelocity).normalize();\n          const directionDot = this.tempDirection.dot(this.tempTargetDirection);\n\n          if (directionDot < 0) {\n            // Moving in opposite direction: decelerate first before reversing\n            const velocityDelta = this.BASE_DECELERATION * deltaTime;\n            const newSpeed = Math.max(currentSpeed - velocityDelta, 0);\n\n            if (newSpeed > 0.001) {\n              state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            } else {\n              // Fully stopped; can now start accelerating in new direction\n              state.velocity.set(0, 0, 0);\n            }\n            state.acceleration = -this.BASE_DECELERATION;\n          } else if (directionDot < 0.7) {\n            // Perpendicular direction change (e.g., forward to strafe): moderate deceleration\n            const blendedAccel = currentAcceleration * 0.6; // Reduced acceleration for sharp turns\n            const velocityDelta = blendedAccel * deltaTime;\n            const newSpeed = Math.min(\n              currentSpeed + velocityDelta,\n              targetSpeed,\n            );\n            this.tempDirection.copy(this.tempTargetVelocity).normalize();\n            state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            state.acceleration = blendedAccel;\n          } else {\n            // Same or similar direction: full acceleration\n            this.tempDirection.copy(this.tempTargetVelocity).normalize();\n            const velocityDelta = currentAcceleration * deltaTime;\n            const newSpeed = Math.min(\n              currentSpeed + velocityDelta,\n              targetSpeed,\n            );\n            state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n            state.acceleration = currentAcceleration;\n          }\n        } else {\n          // Very low speed: safe to accelerate directly toward target\n          this.tempDirection.copy(this.tempTargetVelocity).normalize();\n          const velocityDelta = currentAcceleration * deltaTime;\n          const newSpeed = Math.min(currentSpeed + velocityDelta, targetSpeed);\n          state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n          state.acceleration = currentAcceleration;\n        }\n      } else {\n        // Already at or above target speed: snap to target velocity\n        state.velocity.copy(this.tempTargetVelocity);\n        state.acceleration = 0;\n      }\n    } else {\n      // Decelerate to stop\n      const currentSpeed = state.velocity.length();\n      if (currentSpeed > 0.01) {\n        this.tempDirection.copy(state.velocity).normalize();\n        const velocityDelta = this.BASE_DECELERATION * deltaTime;\n        const newSpeed = Math.max(currentSpeed - velocityDelta, 0);\n        state.velocity.copy(this.tempDirection.multiplyScalar(newSpeed));\n      } else {\n        state.velocity.set(0, 0, 0);\n      }\n      state.acceleration = -this.BASE_DECELERATION;\n    }\n\n    // Calculate movement delta for this frame\n    this.tempMovement.copy(state.velocity).multiplyScalar(deltaTime);\n\n    // Apply tactical step quantization if enabled\n    if (input.useTacticalSteps) {\n      // Quantize to 30cm grid steps\n      this.tempMovement.x =\n        Math.round(this.tempMovement.x / this.STEP_SIZE) * this.STEP_SIZE;\n      this.tempMovement.z =\n        Math.round(this.tempMovement.z / this.STEP_SIZE) * this.STEP_SIZE;\n    }\n\n    // Update position\n    state.position.add(this.tempMovement);\n\n    // Apply arena bounds clamping if bounds provided\n    if (bounds) {\n      // Check if position exceeded boundaries\n      const exceededMinX = state.position.x < bounds.minX;\n      const exceededMaxX = state.position.x > bounds.maxX;\n      const exceededMinZ = state.position.z < bounds.minZ;\n      const exceededMaxZ = state.position.z > bounds.maxZ;\n\n      // Clamp position to arena boundaries\n      state.position.x = Math.max(bounds.minX, Math.min(bounds.maxX, state.position.x));\n      state.position.z = Math.max(bounds.minZ, Math.min(bounds.maxZ, state.position.z));\n\n      // Zero velocity component if exceeded boundary (smooth stopping)\n      if (exceededMinX || exceededMaxX) {\n        state.velocity.x = 0;\n      }\n      if (exceededMinZ || exceededMaxZ) {\n        state.velocity.z = 0;\n      }\n    }\n  }\n\n  /**\n   * Get speed modifier for a specific trigram stance.\n   *\n   * **Korean**: 자세 속도 배수 가져오기 (Get Stance Speed Modifier)\n   *\n   * @param stance - Eight Trigram stance\n   * @returns Speed multiplier (0.8 to 1.25)\n   *\n   * @korean 자세속도배수\n   */\n  public getStanceSpeedModifier(stance: TrigramStance): number {\n    return STANCE_SPEED_MODIFIERS[stance];\n  }\n\n  /**\n   * Calculate movement penalty from leg injury.\n   *\n   * **Korean**: 부상 이동 페널티 (Injury Movement Penalty)\n   *\n   * Leg damage reduces movement speed by 10-50% based on injury severity.\n   *\n   * @param legHealthPercentage - Remaining leg health (0-1)\n   * @returns Injury factor (0 = no injury, 1 = maximum injury)\n   *\n   * @korean 부상페널티\n   */\n  public calculateInjuryPenalty(legHealthPercentage: number): number {\n    // Injury penalty scales from 0% (healthy) to 50% (critical)\n    // Clamp between 0 and 1\n    const healthFactor = Math.max(0, Math.min(1, legHealthPercentage));\n    return 1.0 - healthFactor;\n  }\n\n  /**\n   * Get maximum speed for current state configuration.\n   *\n   * **Korean**: 최대 속도 계산 (Calculate Maximum Speed)\n   *\n   * @param isRunning - Whether running (vs walking)\n   * @param stance - Current trigram stance\n   * @param legInjuryFactor - Leg injury severity (0-1)\n   * @returns Maximum speed in m/s (includes arena scaling)\n   *\n   * @korean 최대속도\n   */\n  public getMaxSpeed(\n    isRunning: boolean,\n    stance: TrigramStance,\n    legInjuryFactor: number,\n  ): number {\n    const arenaSpeedScale = this._cachedArenaSpeedScale;\n    const baseSpeed = isRunning ? this.BASE_RUN_SPEED : this.BASE_WALK_SPEED;\n    const stanceModifier = this.getStanceSpeedModifier(stance);\n    const injuryPenalty = 1.0 - legInjuryFactor * 0.5;\n    return baseSpeed * arenaSpeedScale * stanceModifier * injuryPenalty;\n  }\n\n  /**\n   * Calculate time required to reach target speed from current velocity.\n   *\n   * **Korean**: 가속 시간 (Acceleration Time)\n   *\n   * @param currentSpeed - Current speed magnitude (m/s)\n   * @param targetSpeed - Desired speed magnitude (m/s)\n   * @returns Time in seconds to reach target speed\n   *\n   * @korean 가속시간\n   */\n  public getAccelerationTime(\n    currentSpeed: number,\n    targetSpeed: number,\n  ): number {\n    const speedDiff = Math.abs(targetSpeed - currentSpeed);\n    return speedDiff / this.BASE_ACCELERATION;\n  }\n\n  /**\n   * Calculate stopping distance from current velocity.\n   *\n   * **Korean**: 제동 거리 (Braking Distance)\n   *\n   * @param currentSpeed - Current speed magnitude (m/s)\n   * @returns Distance in meters required to stop\n   *\n   * @korean 제동거리\n   */\n  public getStoppingDistance(currentSpeed: number): number {\n    // Using kinematic equation: d = v² / (2a)\n    return (currentSpeed * currentSpeed) / (2 * this.BASE_DECELERATION);\n  }\n\n  /**\n   * Get tactical step size.\n   *\n   * **Korean**: 보법 거리 (Step Distance)\n   *\n   * @returns Step size in meters (0.3m = 30cm)\n   *\n   * @korean 보법거리\n   */\n  public getStepSize(): number {\n    return this.STEP_SIZE;\n  }\n\n  /**\n   * Override maximum speed for external speed modifier systems.\n   *\n   * **Korean**: 최대 속도 설정 (Set Maximum Speed)\n   *\n   * Allows external systems (like SpeedModifierSystem) to override\n   * the calculated maximum speed. This is applied in the next\n   * updateMovement call.\n   *\n   * @param speed - Maximum speed in m/s\n   *\n   */\n  public setMaxSpeed(speed: number): void {\n    this._overrideMaxSpeed = speed;\n  }\n\n  /**\n   * Override acceleration for external speed modifier systems.\n   *\n   * **Korean**: 가속도 설정 (Set Acceleration)\n   *\n   * Allows external systems (like SpeedModifierSystem) to override\n   * the base acceleration rate. This is applied in the next\n   * updateMovement call.\n   *\n   * @param acceleration - Acceleration in m/s²\n   *\n   */\n  public setAcceleration(acceleration: number): void {\n    this._overrideAcceleration = acceleration;\n  }\n\n  /**\n   * Clear speed and acceleration overrides.\n   *\n   * **Korean**: 속도 재정의 해제 (Clear Speed Overrides)\n   *\n   * Resets movement to use default calculations without external\n   * override values.\n   *\n   */\n  public clearOverrides(): void {\n    this._overrideMaxSpeed = null;\n    this._overrideAcceleration = null;\n  }\n\n  /**\n   * Set arena width for arena-aware speed scaling.\n   *\n   * **Korean**: 경기장 너비 설정 (Set Arena Width)\n   *\n   * Updates the arena width used for speed scaling calculations.\n   * Call this when the arena size changes (e.g., screen resize).\n   * Recalculates and caches the arena speed scale.\n   *\n   * @param widthMeters - Arena width in meters (must be positive)\n   * @throws {Error} If widthMeters is not a positive number\n   *\n   */\n  public setArenaWidth(widthMeters: number): void {\n    if (widthMeters <= 0 || !Number.isFinite(widthMeters)) {\n      throw new Error(\n        `Arena width must be a positive finite number, got: ${widthMeters}`,\n      );\n    }\n    this._arenaWidthMeters = widthMeters;\n    this._cachedArenaSpeedScale = this.calculateArenaSpeedScale();\n  }\n\n  /**\n   * Get current arena width.\n   *\n   * **Korean**: 경기장 너비 가져오기 (Get Arena Width)\n   *\n   * @returns Arena width in meters\n   *\n   */\n  public getArenaWidth(): number {\n    return this._arenaWidthMeters;\n  }\n\n  /**\n   * Get current arena speed scale factor.\n   *\n   * **Korean**: 경기장 속도 배수 가져오기 (Get Arena Speed Scale)\n   *\n   * Returns the cached arena speed scale value.\n   *\n   * @returns Arena-based speed multiplier (0.7 to 1.3)\n   *\n   */\n  public getArenaSpeedScale(): number {\n    return this._cachedArenaSpeedScale;\n  }\n}\n"],"mappings":"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"}

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

@@ -31,7 +31,6 @@ import { AnimationType } from "../animation";
  *
  * **Korean**: 물리적 도달 계산 결과
  *
- * @public
  * @korean 물리적도달결과
  */
 export interface PhysicalReachResult {
@@ -101,7 +100,6 @@ export interface PhysicalReachResult {
  * Calculates reality-based reach using archetype physical attributes
  * and animation timing.
  *
- * @public
  * @korean 물리적도달계산기
  */
 export declare class PhysicalReachCalculator {
@@ -165,7 +163,6 @@ export declare class PhysicalReachCalculator {
      * // Uses animation multiplier (1.0) only
      * ```
      *
-     * @public
      * @korean 도달계산
      */
     calculateReach(physicalAttributes: PhysicalAttributes, animationType: AnimationType, animationTime: number, stance: TrigramStance, reachConfig?: PhysicalReachConfig): PhysicalReachResult;
@@ -205,7 +202,6 @@ export declare class PhysicalReachCalculator {
      * // Uses animation multiplier only (1.0)
      * ```
      *
-     * @public
      * @korean 최대도달계산
      */
     calculateMaxReach(physicalAttributes: PhysicalAttributes, animationType: AnimationType, stance: TrigramStance, reachConfig?: PhysicalReachConfig): number;
@@ -232,7 +228,6 @@ export declare class PhysicalReachCalculator {
      * @param animationType - Animation type
      * @returns Technique type
      *
-     * @public
      * @korean 기술유형결정
      */
     getTechniqueTypeFromAnimation(animationType: AnimationType): TechniqueType;
@@ -254,7 +249,6 @@ export declare class PhysicalReachCalculator {
  * );
  * ```
  *
- * @public
  * @korean 싱글톤인스턴스
  */
 export declare const physicalReachCalculator: PhysicalReachCalculator;

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

@@ -1 +1 @@
-{"version":3,"file":"PhysicalReachCalculator.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/PhysicalReachCalculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAEL,aAAa,EACb,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,aAAa,EAId,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAuB;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACH,cAAc,CACZ,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,mBAAmB,GAChC,mBAAmB;IAiHtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,iBAAiB,CACf,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,mBAAmB,GAChC,MAAM;IAmCT;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;;;;;;;;;;OAYG;IACI,6BAA6B,CAClC,aAAa,EAAE,aAAa,GAC3B,aAAa;CAiFjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,yBAAgC,CAAC"}
+{"version":3,"file":"PhysicalReachCalculator.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/PhysicalReachCalculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAEL,aAAa,EACb,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,aAAa,EAId,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAE1C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACH,cAAc,CACZ,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,mBAAmB,GAChC,mBAAmB;IAiHtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,iBAAiB,CACf,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,aAAa,EACrB,WAAW,CAAC,EAAE,mBAAmB,GAChC,MAAM;IAmCT;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;;;;;;;;;OAWG;IACI,6BAA6B,CAClC,aAAa,EAAE,aAAa,GAC3B,aAAa;CAiFjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,yBAAgC,CAAC"}

package/lib/systems/physics/PhysicalReachCalculator.js

@@ -10,7 +10,6 @@ import { getAnimationHitTiming, getCurrentReachMultiplier, isWithinHitWindow } f
 * Calculates reality-based reach using archetype physical attributes
 * and animation timing.
 *
-* @public
 * @korean 물리적도달계산기
 */
 var PhysicalReachCalculator = class {
@@ -74,7 +73,6 @@ var PhysicalReachCalculator = class {
 	* // Uses animation multiplier (1.0) only
 	* ```
 	*
-	* @public
 	* @korean 도달계산
 	*/
 	calculateReach(physicalAttributes, animationType, animationTime, stance, reachConfig) {
@@ -145,7 +143,6 @@ var PhysicalReachCalculator = class {
 	* // Uses animation multiplier only (1.0)
 	* ```
 	*
-	* @public
 	* @korean 최대도달계산
 	*/
 	calculateMaxReach(physicalAttributes, animationType, stance, reachConfig) {
@@ -186,7 +183,6 @@ var PhysicalReachCalculator = class {
 	* @param animationType - Animation type
 	* @returns Technique type
 	*
-	* @public
 	* @korean 기술유형결정
 	*/
 	getTechniqueTypeFromAnimation(animationType) {
@@ -215,7 +211,6 @@ var PhysicalReachCalculator = class {
 * );
 * ```
 *
-* @public
 * @korean 싱글톤인스턴스
 */
 var physicalReachCalculator = new PhysicalReachCalculator();

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

@@ -1 +1 @@
-{"version":3,"file":"PhysicalReachCalculator.js","names":[],"sources":["../../../src/systems/physics/PhysicalReachCalculator.ts"],"sourcesContent":["/**\n * Physical Reach Calculator\n *\n * **Korean**: 물리적 도달 거리 계산기\n *\n * Calculates actual combat reach based on physical attributes and animation timing.\n * Integrates archetype-specific limb lengths with animation hit windows for\n * reality-based hit detection.\n *\n * ## Philosophy\n *\n * Black Trigram emphasizes realistic combat. Hit detection must account for:\n * - Physical differences between archetypes (arm/leg length)\n * - Animation phase (chamber vs extension vs retraction)\n * - Technique type (punch vs kick vs elbow)\n * - Stance modifiers from Eight Trigrams\n *\n * A small Hacker (73cm arms) cannot reach as far as a large Jojik (84cm arms),\n * and this difference must be reflected in combat.\n *\n * @module systems/physics/PhysicalReachCalculator\n * @category Combat Physics\n * @korean 물리적도달계산기\n */\n\nimport { PhysicalAttributes } from \"@/types\";\nimport { TrigramStance } from \"../../types/common\";\nimport { \n  STANCE_REACH_MODIFIERS, \n  TechniqueType,\n  PhysicalReachConfig,\n} from \"../../types/physics\";\nimport {\n  AnimationType,\n  getAnimationHitTiming,\n  getCurrentReachMultiplier,\n  isWithinHitWindow,\n} from \"../animation\";\n\n/**\n * Physical reach calculation result.\n *\n * **Korean**: 물리적 도달 계산 결과\n *\n * @public\n * @korean 물리적도달결과\n */\nexport interface PhysicalReachResult {\n  /**\n   * Base limb length in meters.\n   * Archetype-specific arm or leg length from physical attributes.\n   * @korean 기본팔다리길이\n   */\n  readonly baseLimbLength: number;\n\n  /**\n   * Body pivot contribution in meters (kicks only).\n   * Accounts for hip rotation and torso lean during kicks (~0.25m).\n   * @korean 몸통회전기여도\n   */\n  readonly bodyPivotContribution: number;\n\n  /**\n   * Technique type used.\n   * @korean 기술유형\n   */\n  readonly techniqueType: TechniqueType;\n\n  /**\n   * Current animation time in seconds.\n   * @korean 현재애니메이션시간\n   */\n  readonly animationTime: number;\n\n  /**\n   * Animation reach multiplier at current time (0.0 - 1.5).\n   * @korean 애니메이션도달배수\n   */\n  readonly animationReachMultiplier: number;\n\n  /**\n   * Base extension from technique reachConfig (0.0 - 1.5).\n   * Designer-specified reach multiplier from technique definition.\n   * @korean 기본확장배수\n   */\n  readonly baseExtension?: number;\n\n  /**\n   * Final extension multiplier used in reach calculation.\n   * When reachConfig is provided, applies curve factor to hybrid peak:\n   * `(animationReachMultiplier / peakMultiplier) * max(baseExtension, peakMultiplier)`\n   * Otherwise uses time-varying animationReachMultiplier directly.\n   * @korean 최종확장배수\n   */\n  readonly finalExtensionMultiplier: number;\n\n  /**\n   * Stance reach modifier (0.9 - 1.2).\n   * @korean 자세도달수정자\n   */\n  readonly stanceModifier: number;\n\n  /**\n   * Final effective reach in meters.\n   * (baseLimbLength + bodyPivotContribution) × finalExtensionMultiplier × stanceModifier\n   * @korean 최종유효도달\n   */\n  readonly effectiveReach: number;\n\n  /**\n   * Whether currently within hit window.\n   * @korean 타격창내여부\n   */\n  readonly canHit: boolean;\n}\n\n/**\n * Physical Reach Calculator.\n *\n * **Korean**: 물리적 도달 계산기\n *\n * Calculates reality-based reach using archetype physical attributes\n * and animation timing.\n *\n * @public\n * @korean 물리적도달계산기\n */\nexport class PhysicalReachCalculator {\n  /**\n   * Calculate effective reach for a technique at a specific animation time.\n   *\n   * **Korean**: 특정 애니메이션 시간의 유효 도달 거리 계산\n   *\n   * This is the core method that integrates:\n   * 1. Physical attributes (archetype-specific limb length)\n   * 2. Animation timing (hit window and extension phase)\n   * 3. Technique baseExtension (designer-specified reach)\n   * 4. Stance modifiers (Eight Trigrams reach bonuses)\n   * 5. Body pivot contribution (hip rotation and torso lean for kicks)\n   *\n   * **Hybrid Reach System**: Uses the maximum of:\n   * - `reachConfig.baseExtension` (designer-specified reach)\n   * - `maxReachMultiplier` (animation-driven reach)\n   *\n   * This ensures techniques get at least their designed reach while allowing\n   * animations to extend beyond the base if needed.\n   *\n   * **Body Pivot Mechanics for Kicks**:\n   * Kicks benefit from whole-body rotation that punches don't utilize:\n   * - Hip rotation adds ~0.15m (pelvis width + pivot)\n   * - Torso lean adds ~0.1m (forward lean during kick)\n   * - Total body pivot: ~0.25m additional reach\n   *\n   * This accounts for the biomechanics of kicks where the fighter rotates\n   * their entire body to extend reach, unlike punches which rely primarily\n   * on arm extension.\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param animationType - Animation being executed\n   * @param animationTime - Current time in animation (seconds)\n   * @param stance - Current trigram stance\n   * @param reachConfig - Optional technique reach configuration with baseExtension\n   * @returns Physical reach calculation result\n   *\n   * @example\n   * ```typescript\n   * const calculator = new PhysicalReachCalculator();\n   *\n   * // With reachConfig (uses max of baseExtension and animation multiplier)\n   * const frontKick = calculator.calculateReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   0.27, // Peak time\n   *   TrigramStance.GEON,\n   *   { bodyPart: \"leg\", techniqueType: \"kick\", baseExtension: 1.05 }\n   * );\n   * // Uses max(1.05, 1.0) = 1.05 for proper designed reach\n   *\n   * // Without reachConfig (uses only animation multiplier - backward compatible)\n   * const legacyKick = calculator.calculateReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   0.27,\n   *   TrigramStance.GEON\n   * );\n   * // Uses animation multiplier (1.0) only\n   * ```\n   *\n   * @public\n   * @korean 도달계산\n   */\n  calculateReach(\n    physicalAttributes: PhysicalAttributes,\n    animationType: AnimationType,\n    animationTime: number,\n    stance: TrigramStance,\n    reachConfig?: PhysicalReachConfig,\n  ): PhysicalReachResult {\n    // Determine technique type from animation\n    const techniqueType = this.getTechniqueTypeFromAnimation(animationType);\n\n    // Get base limb length for technique type\n    const baseLimbLength = this.getLimbLength(\n      physicalAttributes,\n      techniqueType,\n    );\n\n    // Get animation hit timing\n    const canHit = isWithinHitWindow(animationType, animationTime);\n    const animationReachMultiplier = getCurrentReachMultiplier(\n      animationType,\n      animationTime,\n    );\n\n    // **Hybrid Reach System with Curve Factor**:\n    // Apply baseExtension at the peak reach level, then scale by the time-varying\n    // curve factor so reach still ramps up and down with the animation.\n    // This prevents phantom hits at the start/end of the hit window.\n    const baseExtension = reachConfig?.baseExtension;\n\n    // Retrieve peak (max) reach multiplier for this animation's hit window\n    const hitTiming = getAnimationHitTiming(animationType);\n    const rawPeakMultiplier = hitTiming?.hitWindow.maxReachMultiplier;\n\n    // Determine whether we have valid timing data. When timing is missing or\n    // the configured peak multiplier is non-positive, fall back to a neutral\n    // curve so reach/damage checks remain possible for those techniques.\n    const hasValidTiming =\n      rawPeakMultiplier !== undefined && rawPeakMultiplier > 0;\n\n    const fallbackBase = baseExtension ?? 1;\n\n    const peakMultiplier = hasValidTiming ? rawPeakMultiplier : fallbackBase;\n\n    const effectiveAnimationReachMultiplier = hasValidTiming\n      ? animationReachMultiplier\n      : fallbackBase;\n\n    // Normalized curve factor in [0, 1] that represents where we are on\n    // the reach curve. When peakMultiplier is 0, we treat reach as 0.\n    const curveFactor =\n      peakMultiplier > 0 ? effectiveAnimationReachMultiplier / peakMultiplier : 0;\n\n    // Apply the hybrid \"max\" at the peak level, then reapply the curve\n    const peakExtension =\n      baseExtension !== undefined\n        ? Math.max(baseExtension, peakMultiplier)\n        : peakMultiplier;\n\n    const finalExtensionMultiplier = curveFactor * peakExtension;\n\n    // Get stance modifier\n    const stanceModifier = STANCE_REACH_MODIFIERS[stance];\n\n    // Calculate final effective reach\n    // Convert cm to meters for consistency with physics system\n    const baseLimbLengthMeters = baseLimbLength / 100;\n\n    // Add body pivot/offset contribution based on technique type\n    // This accounts for the fact that limbs extend from the body surface,\n    // not the body center, plus rotational contributions\n    let bodyPivotContribution: number;\n\n    if (techniqueType === \"kick\" || techniqueType === \"knee\") {\n      // Kicks benefit from hip rotation and torso lean which add 0.25m\n      // This accounts for:\n      // - Hip width/rotation (0.15m)\n      // - Torso lean during kick (0.1m)\n      // Total body pivot contribution: 0.25m for kicks\n      bodyPivotContribution = 0.25;\n    } else if (\n      techniqueType === \"punch\" ||\n      techniqueType === \"pressure_point\"\n    ) {\n      // Punches extend from the shoulder, which is offset from body center\n      // Shoulder offset = shoulderWidth / 2 (converted to meters)\n      // Plus torso rotation contribution for cross/hooks (~0.1m)\n      // Average shoulder width ~45cm → offset ~0.225m, plus rotation ~0.1m\n      // Total: ~0.30m for arm techniques\n      const shoulderOffset = physicalAttributes.shoulderWidth / 2 / 100; // Convert cm to m\n      const torsoRotation = 0.1; // 10cm from torso rotation during punches\n      bodyPivotContribution = shoulderOffset + torsoRotation;\n    } else if (techniqueType === \"elbow\") {\n      // Elbows are close range but still extend from shoulder\n      // Less torso rotation contribution\n      const shoulderOffset = physicalAttributes.shoulderWidth / 2 / 100;\n      bodyPivotContribution = shoulderOffset;\n    } else {\n      bodyPivotContribution = 0;\n    }\n\n    const effectiveReach =\n      (baseLimbLengthMeters + bodyPivotContribution) *\n      finalExtensionMultiplier *\n      stanceModifier;\n\n    return {\n      baseLimbLength: baseLimbLengthMeters,\n      bodyPivotContribution,\n      techniqueType,\n      animationTime,\n      animationReachMultiplier,\n      baseExtension,\n      finalExtensionMultiplier,\n      stanceModifier,\n      effectiveReach,\n      canHit,\n    };\n  }\n\n  /**\n   * Calculate maximum possible reach for a technique.\n   *\n   * **Korean**: 기술의 최대 가능 도달 거리\n   *\n   * Calculates reach at peak animation time (maximum extension).\n   * Uses hybrid reach system with reachConfig if provided.\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param animationType - Animation type\n   * @param stance - Current trigram stance\n   * @param reachConfig - Optional technique reach configuration with baseExtension\n   * @returns Maximum effective reach in meters\n   *\n   * @example\n   * ```typescript\n   * const calculator = new PhysicalReachCalculator();\n   *\n   * // With reachConfig for accurate designed reach\n   * const maxReachWithConfig = calculator.calculateMaxReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   TrigramStance.GEON,\n   *   { bodyPart: \"leg\", techniqueType: \"kick\", baseExtension: 1.05 }\n   * );\n   * // Uses max(1.05, 1.0) = 1.05\n   *\n   * // Without reachConfig (backward compatible)\n   * const maxReachLegacy = calculator.calculateMaxReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   TrigramStance.GEON\n   * );\n   * // Uses animation multiplier only (1.0)\n   * ```\n   *\n   * @public\n   * @korean 최대도달계산\n   */\n  calculateMaxReach(\n    physicalAttributes: PhysicalAttributes,\n    animationType: AnimationType,\n    stance: TrigramStance,\n    reachConfig?: PhysicalReachConfig,\n  ): number {\n    const hitTiming = getAnimationHitTiming(animationType);\n    \n    // Handle missing AnimationHitTiming entries\n    // When timing data is unavailable, use baseExtension if provided,\n    // otherwise use a neutral 1.0 multiplier to keep reach calculations functional.\n    // This ensures techniques like GEON_ROUNDHOUSE, WATER_COUNTER, IRON_BLOCK\n    // (which have technique definitions but missing animation timing entries)\n    // can still perform reach/damage checks.\n    if (!hitTiming) {\n      // Use fallback approach: calculate reach with neutral timing\n      const fallbackTime = 0.5; // Midpoint of typical animation\n      const result = this.calculateReach(\n        physicalAttributes,\n        animationType,\n        fallbackTime,\n        stance,\n        reachConfig,\n      );\n      return result.effectiveReach;\n    }\n    \n    const peakTime = hitTiming.hitWindow.peakTime;\n\n    const result = this.calculateReach(\n      physicalAttributes,\n      animationType,\n      peakTime,\n      stance,\n      reachConfig,\n    );\n\n    return result.effectiveReach;\n  }\n\n  /**\n   * Get limb length for a technique type.\n   *\n   * **Korean**: 기술 유형에 대한 팔다리 길이 가져오기\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param techniqueType - Type of technique\n   * @returns Limb length in centimeters\n   *\n   * @private\n   * @korean 팔다리길이가져오기\n   */\n  private getLimbLength(\n    physicalAttributes: PhysicalAttributes,\n    techniqueType: TechniqueType,\n  ): number {\n    switch (techniqueType) {\n      case \"punch\":\n      case \"elbow\":\n      case \"pressure_point\":\n        // Use arm length for hand-based techniques\n        return physicalAttributes.armLength;\n\n      case \"kick\":\n      case \"knee\":\n        // Use leg length for leg-based techniques\n        return physicalAttributes.legLength;\n\n      default:\n        // Fallback to arm length\n        return physicalAttributes.armLength;\n    }\n  }\n\n  /**\n   * Determine technique type from animation type.\n   *\n   * Public method exposed to avoid duplication across codebase.\n   *\n   * **Korean**: 애니메이션 타입에서 기술 유형 결정\n   *\n   * @param animationType - Animation type\n   * @returns Technique type\n   *\n   * @public\n   * @korean 기술유형결정\n   */\n  public getTechniqueTypeFromAnimation(\n    animationType: AnimationType,\n  ): TechniqueType {\n    // Punch techniques\n    if (\n      animationType === AnimationType.JAB ||\n      animationType === AnimationType.CROSS ||\n      animationType === AnimationType.HOOK ||\n      animationType === AnimationType.UPPERCUT ||\n      animationType === AnimationType.OVERHAND ||\n      animationType === AnimationType.BACKFIST ||\n      animationType === AnimationType.HAMMER_FIST ||\n      animationType === AnimationType.PALM_STRIKE ||\n      animationType === AnimationType.SPEAR_HAND_STRIKE ||\n      animationType === AnimationType.HEAVEN_STRIKE ||\n      animationType === AnimationType.FLOWING_CROSS ||\n      animationType === AnimationType.SOLAR_PLEXUS_STRIKE ||\n      animationType === AnimationType.FLOWING_PUSH ||\n      animationType === AnimationType.LIVER_DISRUPTION ||\n      animationType === AnimationType.EAR_STRIKE\n    ) {\n      return \"punch\";\n    }\n\n    // Kick techniques\n    if (\n      animationType === AnimationType.FRONT_KICK ||\n      animationType === AnimationType.ROUNDHOUSE_KICK ||\n      animationType === AnimationType.SIDE_KICK ||\n      animationType === AnimationType.BACK_KICK ||\n      animationType === AnimationType.AXE_KICK ||\n      animationType === AnimationType.CRESCENT_KICK ||\n      animationType === AnimationType.LOW_KICK ||\n      animationType === AnimationType.PUSH_KICK ||\n      animationType === AnimationType.JUMPING_KICK ||\n      animationType === AnimationType.SPINNING_HEEL_KICK ||\n      animationType === AnimationType.TORNADO_KICK\n    ) {\n      return \"kick\";\n    }\n\n    // Elbow techniques\n    if (\n      animationType === AnimationType.ELBOW_STRIKE ||\n      animationType === AnimationType.ELBOW_UPPERCUT ||\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    ) {\n      return \"elbow\";\n    }\n\n    // Knee techniques\n    if (\n      animationType === AnimationType.KNEE_STRIKE ||\n      animationType === AnimationType.FLYING_KNEE ||\n      animationType === AnimationType.KIDNEY_KNEE ||\n      animationType === AnimationType.FEMORAL_KNEE\n    ) {\n      return \"knee\";\n    }\n\n    // Pressure point techniques\n    if (\n      animationType === AnimationType.NERVE_STRIKE ||\n      animationType === AnimationType.PRESSURE_POINT_STRIKE ||\n      animationType === AnimationType.NERVE_PARALYSIS ||\n      animationType === AnimationType.THROAT_STRIKE ||\n      animationType === AnimationType.EYE_GOUGE\n    ) {\n      return \"pressure_point\";\n    }\n\n    // Default to \"punch\" for any techniques not explicitly mapped above, including\n    // complex grappling or hybrid animations. For *reach calculation* purposes we\n    // approximate these using primary arm/forearm extension, since initial contact\n    // is typically established with the upper limbs before the torso closes distance.\n    // If a dedicated grappling TechniqueType and reach model are introduced later,\n    // update this fallback to return that specific type instead of \"punch\".\n    return \"punch\";\n  }\n}\n\n/**\n * Singleton instance for convenient access.\n *\n * **Korean**: 싱글톤 인스턴스\n *\n * @example\n * ```typescript\n * import { physicalReachCalculator } from '@/systems/physics/PhysicalReachCalculator';\n *\n * const reach = physicalReachCalculator.calculateReach(\n *   playerPhysical,\n *   AnimationType.ROUNDHOUSE_KICK,\n *   0.32, // Peak time\n *   TrigramStance.GEON\n * );\n * ```\n *\n * @public\n * @korean 싱글톤인스턴스\n */\nexport const physicalReachCalculator = new PhysicalReachCalculator();\n"],"mappings":"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"}
+{"version":3,"file":"PhysicalReachCalculator.js","names":[],"sources":["../../../src/systems/physics/PhysicalReachCalculator.ts"],"sourcesContent":["/**\n * Physical Reach Calculator\n *\n * **Korean**: 물리적 도달 거리 계산기\n *\n * Calculates actual combat reach based on physical attributes and animation timing.\n * Integrates archetype-specific limb lengths with animation hit windows for\n * reality-based hit detection.\n *\n * ## Philosophy\n *\n * Black Trigram emphasizes realistic combat. Hit detection must account for:\n * - Physical differences between archetypes (arm/leg length)\n * - Animation phase (chamber vs extension vs retraction)\n * - Technique type (punch vs kick vs elbow)\n * - Stance modifiers from Eight Trigrams\n *\n * A small Hacker (73cm arms) cannot reach as far as a large Jojik (84cm arms),\n * and this difference must be reflected in combat.\n *\n * @module systems/physics/PhysicalReachCalculator\n * @category Combat Physics\n * @korean 물리적도달계산기\n */\n\nimport { PhysicalAttributes } from \"@/types\";\nimport { TrigramStance } from \"../../types/common\";\nimport { \n  STANCE_REACH_MODIFIERS, \n  TechniqueType,\n  PhysicalReachConfig,\n} from \"../../types/physics\";\nimport {\n  AnimationType,\n  getAnimationHitTiming,\n  getCurrentReachMultiplier,\n  isWithinHitWindow,\n} from \"../animation\";\n\n/**\n * Physical reach calculation result.\n *\n * **Korean**: 물리적 도달 계산 결과\n *\n * @korean 물리적도달결과\n */\nexport interface PhysicalReachResult {\n  /**\n   * Base limb length in meters.\n   * Archetype-specific arm or leg length from physical attributes.\n   * @korean 기본팔다리길이\n   */\n  readonly baseLimbLength: number;\n\n  /**\n   * Body pivot contribution in meters (kicks only).\n   * Accounts for hip rotation and torso lean during kicks (~0.25m).\n   * @korean 몸통회전기여도\n   */\n  readonly bodyPivotContribution: number;\n\n  /**\n   * Technique type used.\n   * @korean 기술유형\n   */\n  readonly techniqueType: TechniqueType;\n\n  /**\n   * Current animation time in seconds.\n   * @korean 현재애니메이션시간\n   */\n  readonly animationTime: number;\n\n  /**\n   * Animation reach multiplier at current time (0.0 - 1.5).\n   * @korean 애니메이션도달배수\n   */\n  readonly animationReachMultiplier: number;\n\n  /**\n   * Base extension from technique reachConfig (0.0 - 1.5).\n   * Designer-specified reach multiplier from technique definition.\n   * @korean 기본확장배수\n   */\n  readonly baseExtension?: number;\n\n  /**\n   * Final extension multiplier used in reach calculation.\n   * When reachConfig is provided, applies curve factor to hybrid peak:\n   * `(animationReachMultiplier / peakMultiplier) * max(baseExtension, peakMultiplier)`\n   * Otherwise uses time-varying animationReachMultiplier directly.\n   * @korean 최종확장배수\n   */\n  readonly finalExtensionMultiplier: number;\n\n  /**\n   * Stance reach modifier (0.9 - 1.2).\n   * @korean 자세도달수정자\n   */\n  readonly stanceModifier: number;\n\n  /**\n   * Final effective reach in meters.\n   * (baseLimbLength + bodyPivotContribution) × finalExtensionMultiplier × stanceModifier\n   * @korean 최종유효도달\n   */\n  readonly effectiveReach: number;\n\n  /**\n   * Whether currently within hit window.\n   * @korean 타격창내여부\n   */\n  readonly canHit: boolean;\n}\n\n/**\n * Physical Reach Calculator.\n *\n * **Korean**: 물리적 도달 계산기\n *\n * Calculates reality-based reach using archetype physical attributes\n * and animation timing.\n *\n * @korean 물리적도달계산기\n */\nexport class PhysicalReachCalculator {\n  /**\n   * Calculate effective reach for a technique at a specific animation time.\n   *\n   * **Korean**: 특정 애니메이션 시간의 유효 도달 거리 계산\n   *\n   * This is the core method that integrates:\n   * 1. Physical attributes (archetype-specific limb length)\n   * 2. Animation timing (hit window and extension phase)\n   * 3. Technique baseExtension (designer-specified reach)\n   * 4. Stance modifiers (Eight Trigrams reach bonuses)\n   * 5. Body pivot contribution (hip rotation and torso lean for kicks)\n   *\n   * **Hybrid Reach System**: Uses the maximum of:\n   * - `reachConfig.baseExtension` (designer-specified reach)\n   * - `maxReachMultiplier` (animation-driven reach)\n   *\n   * This ensures techniques get at least their designed reach while allowing\n   * animations to extend beyond the base if needed.\n   *\n   * **Body Pivot Mechanics for Kicks**:\n   * Kicks benefit from whole-body rotation that punches don't utilize:\n   * - Hip rotation adds ~0.15m (pelvis width + pivot)\n   * - Torso lean adds ~0.1m (forward lean during kick)\n   * - Total body pivot: ~0.25m additional reach\n   *\n   * This accounts for the biomechanics of kicks where the fighter rotates\n   * their entire body to extend reach, unlike punches which rely primarily\n   * on arm extension.\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param animationType - Animation being executed\n   * @param animationTime - Current time in animation (seconds)\n   * @param stance - Current trigram stance\n   * @param reachConfig - Optional technique reach configuration with baseExtension\n   * @returns Physical reach calculation result\n   *\n   * @example\n   * ```typescript\n   * const calculator = new PhysicalReachCalculator();\n   *\n   * // With reachConfig (uses max of baseExtension and animation multiplier)\n   * const frontKick = calculator.calculateReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   0.27, // Peak time\n   *   TrigramStance.GEON,\n   *   { bodyPart: \"leg\", techniqueType: \"kick\", baseExtension: 1.05 }\n   * );\n   * // Uses max(1.05, 1.0) = 1.05 for proper designed reach\n   *\n   * // Without reachConfig (uses only animation multiplier - backward compatible)\n   * const legacyKick = calculator.calculateReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   0.27,\n   *   TrigramStance.GEON\n   * );\n   * // Uses animation multiplier (1.0) only\n   * ```\n   *\n   * @korean 도달계산\n   */\n  calculateReach(\n    physicalAttributes: PhysicalAttributes,\n    animationType: AnimationType,\n    animationTime: number,\n    stance: TrigramStance,\n    reachConfig?: PhysicalReachConfig,\n  ): PhysicalReachResult {\n    // Determine technique type from animation\n    const techniqueType = this.getTechniqueTypeFromAnimation(animationType);\n\n    // Get base limb length for technique type\n    const baseLimbLength = this.getLimbLength(\n      physicalAttributes,\n      techniqueType,\n    );\n\n    // Get animation hit timing\n    const canHit = isWithinHitWindow(animationType, animationTime);\n    const animationReachMultiplier = getCurrentReachMultiplier(\n      animationType,\n      animationTime,\n    );\n\n    // **Hybrid Reach System with Curve Factor**:\n    // Apply baseExtension at the peak reach level, then scale by the time-varying\n    // curve factor so reach still ramps up and down with the animation.\n    // This prevents phantom hits at the start/end of the hit window.\n    const baseExtension = reachConfig?.baseExtension;\n\n    // Retrieve peak (max) reach multiplier for this animation's hit window\n    const hitTiming = getAnimationHitTiming(animationType);\n    const rawPeakMultiplier = hitTiming?.hitWindow.maxReachMultiplier;\n\n    // Determine whether we have valid timing data. When timing is missing or\n    // the configured peak multiplier is non-positive, fall back to a neutral\n    // curve so reach/damage checks remain possible for those techniques.\n    const hasValidTiming =\n      rawPeakMultiplier !== undefined && rawPeakMultiplier > 0;\n\n    const fallbackBase = baseExtension ?? 1;\n\n    const peakMultiplier = hasValidTiming ? rawPeakMultiplier : fallbackBase;\n\n    const effectiveAnimationReachMultiplier = hasValidTiming\n      ? animationReachMultiplier\n      : fallbackBase;\n\n    // Normalized curve factor in [0, 1] that represents where we are on\n    // the reach curve. When peakMultiplier is 0, we treat reach as 0.\n    const curveFactor =\n      peakMultiplier > 0 ? effectiveAnimationReachMultiplier / peakMultiplier : 0;\n\n    // Apply the hybrid \"max\" at the peak level, then reapply the curve\n    const peakExtension =\n      baseExtension !== undefined\n        ? Math.max(baseExtension, peakMultiplier)\n        : peakMultiplier;\n\n    const finalExtensionMultiplier = curveFactor * peakExtension;\n\n    // Get stance modifier\n    const stanceModifier = STANCE_REACH_MODIFIERS[stance];\n\n    // Calculate final effective reach\n    // Convert cm to meters for consistency with physics system\n    const baseLimbLengthMeters = baseLimbLength / 100;\n\n    // Add body pivot/offset contribution based on technique type\n    // This accounts for the fact that limbs extend from the body surface,\n    // not the body center, plus rotational contributions\n    let bodyPivotContribution: number;\n\n    if (techniqueType === \"kick\" || techniqueType === \"knee\") {\n      // Kicks benefit from hip rotation and torso lean which add 0.25m\n      // This accounts for:\n      // - Hip width/rotation (0.15m)\n      // - Torso lean during kick (0.1m)\n      // Total body pivot contribution: 0.25m for kicks\n      bodyPivotContribution = 0.25;\n    } else if (\n      techniqueType === \"punch\" ||\n      techniqueType === \"pressure_point\"\n    ) {\n      // Punches extend from the shoulder, which is offset from body center\n      // Shoulder offset = shoulderWidth / 2 (converted to meters)\n      // Plus torso rotation contribution for cross/hooks (~0.1m)\n      // Average shoulder width ~45cm → offset ~0.225m, plus rotation ~0.1m\n      // Total: ~0.30m for arm techniques\n      const shoulderOffset = physicalAttributes.shoulderWidth / 2 / 100; // Convert cm to m\n      const torsoRotation = 0.1; // 10cm from torso rotation during punches\n      bodyPivotContribution = shoulderOffset + torsoRotation;\n    } else if (techniqueType === \"elbow\") {\n      // Elbows are close range but still extend from shoulder\n      // Less torso rotation contribution\n      const shoulderOffset = physicalAttributes.shoulderWidth / 2 / 100;\n      bodyPivotContribution = shoulderOffset;\n    } else {\n      bodyPivotContribution = 0;\n    }\n\n    const effectiveReach =\n      (baseLimbLengthMeters + bodyPivotContribution) *\n      finalExtensionMultiplier *\n      stanceModifier;\n\n    return {\n      baseLimbLength: baseLimbLengthMeters,\n      bodyPivotContribution,\n      techniqueType,\n      animationTime,\n      animationReachMultiplier,\n      baseExtension,\n      finalExtensionMultiplier,\n      stanceModifier,\n      effectiveReach,\n      canHit,\n    };\n  }\n\n  /**\n   * Calculate maximum possible reach for a technique.\n   *\n   * **Korean**: 기술의 최대 가능 도달 거리\n   *\n   * Calculates reach at peak animation time (maximum extension).\n   * Uses hybrid reach system with reachConfig if provided.\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param animationType - Animation type\n   * @param stance - Current trigram stance\n   * @param reachConfig - Optional technique reach configuration with baseExtension\n   * @returns Maximum effective reach in meters\n   *\n   * @example\n   * ```typescript\n   * const calculator = new PhysicalReachCalculator();\n   *\n   * // With reachConfig for accurate designed reach\n   * const maxReachWithConfig = calculator.calculateMaxReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   TrigramStance.GEON,\n   *   { bodyPart: \"leg\", techniqueType: \"kick\", baseExtension: 1.05 }\n   * );\n   * // Uses max(1.05, 1.0) = 1.05\n   *\n   * // Without reachConfig (backward compatible)\n   * const maxReachLegacy = calculator.calculateMaxReach(\n   *   MUSA_PHYSICAL,\n   *   AnimationType.FRONT_KICK,\n   *   TrigramStance.GEON\n   * );\n   * // Uses animation multiplier only (1.0)\n   * ```\n   *\n   * @korean 최대도달계산\n   */\n  calculateMaxReach(\n    physicalAttributes: PhysicalAttributes,\n    animationType: AnimationType,\n    stance: TrigramStance,\n    reachConfig?: PhysicalReachConfig,\n  ): number {\n    const hitTiming = getAnimationHitTiming(animationType);\n    \n    // Handle missing AnimationHitTiming entries\n    // When timing data is unavailable, use baseExtension if provided,\n    // otherwise use a neutral 1.0 multiplier to keep reach calculations functional.\n    // This ensures techniques like GEON_ROUNDHOUSE, WATER_COUNTER, IRON_BLOCK\n    // (which have technique definitions but missing animation timing entries)\n    // can still perform reach/damage checks.\n    if (!hitTiming) {\n      // Use fallback approach: calculate reach with neutral timing\n      const fallbackTime = 0.5; // Midpoint of typical animation\n      const result = this.calculateReach(\n        physicalAttributes,\n        animationType,\n        fallbackTime,\n        stance,\n        reachConfig,\n      );\n      return result.effectiveReach;\n    }\n    \n    const peakTime = hitTiming.hitWindow.peakTime;\n\n    const result = this.calculateReach(\n      physicalAttributes,\n      animationType,\n      peakTime,\n      stance,\n      reachConfig,\n    );\n\n    return result.effectiveReach;\n  }\n\n  /**\n   * Get limb length for a technique type.\n   *\n   * **Korean**: 기술 유형에 대한 팔다리 길이 가져오기\n   *\n   * @param physicalAttributes - Fighter's physical attributes\n   * @param techniqueType - Type of technique\n   * @returns Limb length in centimeters\n   *\n   * @private\n   * @korean 팔다리길이가져오기\n   */\n  private getLimbLength(\n    physicalAttributes: PhysicalAttributes,\n    techniqueType: TechniqueType,\n  ): number {\n    switch (techniqueType) {\n      case \"punch\":\n      case \"elbow\":\n      case \"pressure_point\":\n        // Use arm length for hand-based techniques\n        return physicalAttributes.armLength;\n\n      case \"kick\":\n      case \"knee\":\n        // Use leg length for leg-based techniques\n        return physicalAttributes.legLength;\n\n      default:\n        // Fallback to arm length\n        return physicalAttributes.armLength;\n    }\n  }\n\n  /**\n   * Determine technique type from animation type.\n   *\n   * Public method exposed to avoid duplication across codebase.\n   *\n   * **Korean**: 애니메이션 타입에서 기술 유형 결정\n   *\n   * @param animationType - Animation type\n   * @returns Technique type\n   *\n   * @korean 기술유형결정\n   */\n  public getTechniqueTypeFromAnimation(\n    animationType: AnimationType,\n  ): TechniqueType {\n    // Punch techniques\n    if (\n      animationType === AnimationType.JAB ||\n      animationType === AnimationType.CROSS ||\n      animationType === AnimationType.HOOK ||\n      animationType === AnimationType.UPPERCUT ||\n      animationType === AnimationType.OVERHAND ||\n      animationType === AnimationType.BACKFIST ||\n      animationType === AnimationType.HAMMER_FIST ||\n      animationType === AnimationType.PALM_STRIKE ||\n      animationType === AnimationType.SPEAR_HAND_STRIKE ||\n      animationType === AnimationType.HEAVEN_STRIKE ||\n      animationType === AnimationType.FLOWING_CROSS ||\n      animationType === AnimationType.SOLAR_PLEXUS_STRIKE ||\n      animationType === AnimationType.FLOWING_PUSH ||\n      animationType === AnimationType.LIVER_DISRUPTION ||\n      animationType === AnimationType.EAR_STRIKE\n    ) {\n      return \"punch\";\n    }\n\n    // Kick techniques\n    if (\n      animationType === AnimationType.FRONT_KICK ||\n      animationType === AnimationType.ROUNDHOUSE_KICK ||\n      animationType === AnimationType.SIDE_KICK ||\n      animationType === AnimationType.BACK_KICK ||\n      animationType === AnimationType.AXE_KICK ||\n      animationType === AnimationType.CRESCENT_KICK ||\n      animationType === AnimationType.LOW_KICK ||\n      animationType === AnimationType.PUSH_KICK ||\n      animationType === AnimationType.JUMPING_KICK ||\n      animationType === AnimationType.SPINNING_HEEL_KICK ||\n      animationType === AnimationType.TORNADO_KICK\n    ) {\n      return \"kick\";\n    }\n\n    // Elbow techniques\n    if (\n      animationType === AnimationType.ELBOW_STRIKE ||\n      animationType === AnimationType.ELBOW_UPPERCUT ||\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    ) {\n      return \"elbow\";\n    }\n\n    // Knee techniques\n    if (\n      animationType === AnimationType.KNEE_STRIKE ||\n      animationType === AnimationType.FLYING_KNEE ||\n      animationType === AnimationType.KIDNEY_KNEE ||\n      animationType === AnimationType.FEMORAL_KNEE\n    ) {\n      return \"knee\";\n    }\n\n    // Pressure point techniques\n    if (\n      animationType === AnimationType.NERVE_STRIKE ||\n      animationType === AnimationType.PRESSURE_POINT_STRIKE ||\n      animationType === AnimationType.NERVE_PARALYSIS ||\n      animationType === AnimationType.THROAT_STRIKE ||\n      animationType === AnimationType.EYE_GOUGE\n    ) {\n      return \"pressure_point\";\n    }\n\n    // Default to \"punch\" for any techniques not explicitly mapped above, including\n    // complex grappling or hybrid animations. For *reach calculation* purposes we\n    // approximate these using primary arm/forearm extension, since initial contact\n    // is typically established with the upper limbs before the torso closes distance.\n    // If a dedicated grappling TechniqueType and reach model are introduced later,\n    // update this fallback to return that specific type instead of \"punch\".\n    return \"punch\";\n  }\n}\n\n/**\n * Singleton instance for convenient access.\n *\n * **Korean**: 싱글톤 인스턴스\n *\n * @example\n * ```typescript\n * import { physicalReachCalculator } from '@/systems/physics/PhysicalReachCalculator';\n *\n * const reach = physicalReachCalculator.calculateReach(\n *   playerPhysical,\n *   AnimationType.ROUNDHOUSE_KICK,\n *   0.32, // Peak time\n *   TrigramStance.GEON\n * );\n * ```\n *\n * @korean 싱글톤인스턴스\n */\nexport const physicalReachCalculator = new PhysicalReachCalculator();\n"],"mappings":"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"}

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

@@ -42,7 +42,6 @@ import type { PlayerState } from "../player";
  * Contains all calculated speed modifiers and final values for application
  * to the physics-based movement system.
  *
- * @public
  * @category Physics System
  * @korean 속도변경상태
  */
@@ -69,7 +68,6 @@ export interface SpeedModifierState {
  *
  * **Korean**: 이동 유형 (Movement Type)
  *
- * @public
  * @category Physics System
  */
 export declare enum MovementType {
@@ -108,7 +106,6 @@ export declare enum MovementType {
  * movementPhysics.setAcceleration(modifiers.finalAcceleration);
  * ```
  *
- * @public
  * @category Physics System
  */
 export declare class SpeedModifierSystem {
@@ -176,7 +173,6 @@ export declare class SpeedModifierSystem {
      * @param isCrouching - Whether player is in crouching stance
      * @returns Complete speed modifier state with all factors
      *
-     * @public
      */
     calculateSpeedModifiers(playerState: PlayerState, movementType?: MovementType, isCrouching?: boolean): SpeedModifierState;
     /**
@@ -292,7 +288,6 @@ export declare class SpeedModifierSystem {
      * @param movementPhysics - Movement physics system to update
      * @param modifiers - Calculated speed modifier state
      *
-     * @public
      */
     applySpeedModifiers(movementPhysics: {
         setMaxSpeed: (speed: number) => void;

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

@@ -1 +1 @@
-{"version":3,"file":"SpeedModifierSystem.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/SpeedModifierSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,oBAAY,YAAY;IACtB,mCAAmC;IACnC,OAAO,YAAY;IACnB,8CAA8C;IAC9C,OAAO,YAAY;IACnB,mCAAmC;IACnC,QAAQ,aAAa;IACrB,8CAA8C;IAC9C,OAAO,YAAY;IACnB,wCAAwC;IACxC,SAAS,cAAc;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAE1C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAO;IAErC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAO;IAEvC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAQ;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA8B;IAEhE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAUrC;IAKF;;;;;;;;;;;;;;OAcG;IACI,uBAAuB,CAC5B,WAAW,EAAE,WAAW,EACxB,YAAY,GAAE,YAAmC,EACjD,WAAW,GAAE,OAAe,GAC3B,kBAAkB;IAoErB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,YAAY;IAkCpB;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAI9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,sBAAsB;IA6B9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,uBAAuB;IAqB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;;;;;;;;OAYG;IACI,mBAAmB,CACxB,eAAe,EAAE;QACf,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACrC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1C,EACD,SAAS,EAAE,kBAAkB,GAC5B,IAAI;CAIR"}
+{"version":3,"file":"SpeedModifierSystem.d.ts","sourceRoot":"","sources":["../../../src/systems/physics/SpeedModifierSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,oBAAY,YAAY;IACtB,mCAAmC;IACnC,OAAO,YAAY;IACnB,8CAA8C;IAC9C,OAAO,YAAY;IACnB,mCAAmC;IACnC,QAAQ,aAAa;IACrB,8CAA8C;IAC9C,OAAO,YAAY;IACnB,wCAAwC;IACxC,SAAS,cAAc;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAE1C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAO;IAErC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAO;IAEvC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAQ;IAElD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA8B;IAEhE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAUrC;IAKF;;;;;;;;;;;;;OAaG;IACI,uBAAuB,CAC5B,WAAW,EAAE,WAAW,EACxB,YAAY,GAAE,YAAmC,EACjD,WAAW,GAAE,OAAe,GAC3B,kBAAkB;IAoErB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,YAAY;IAkCpB;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAI9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,sBAAsB;IA6B9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,uBAAuB;IAqB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;;;;;;;OAWG;IACI,mBAAmB,CACxB,eAAe,EAAE;QACf,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACrC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1C,EACD,SAAS,EAAE,kBAAkB,GAC5B,IAAI;CAIR"}

package/lib/systems/physics/SpeedModifierSystem.js

@@ -8,7 +8,6 @@ import { injuryMovementModifier } from "../movement/InjuryMovementModifier.js";
 *
 * **Korean**: 이동 유형 (Movement Type)
 *
-* @public
 * @category Physics System
 */
 var MovementType = /* @__PURE__ */ function(MovementType) {
@@ -48,7 +47,6 @@ var MovementType = /* @__PURE__ */ function(MovementType) {
 * movementPhysics.setAcceleration(modifiers.finalAcceleration);
 * ```
 *
-* @public
 * @category Physics System
 */
 var SpeedModifierSystem = class {
@@ -126,7 +124,6 @@ var SpeedModifierSystem = class {
 	* @param isCrouching - Whether player is in crouching stance
 	* @returns Complete speed modifier state with all factors
 	*
-	* @public
 	*/
 	calculateSpeedModifiers(playerState, movementType = MovementType.WALKING, isCrouching = false) {
 		const baseSpeed = this.getBaseSpeed(movementType, isCrouching, playerState.physicalAttributes);
@@ -289,7 +286,6 @@ var SpeedModifierSystem = class {
 	* @param movementPhysics - Movement physics system to update
 	* @param modifiers - Calculated speed modifier state
 	*
-	* @public
 	*/
 	applySpeedModifiers(movementPhysics, modifiers) {
 		movementPhysics.setMaxSpeed(modifiers.finalSpeed);

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

@@ -1 +1 @@
-{"version":3,"file":"SpeedModifierSystem.js","names":[],"sources":["../../../src/systems/physics/SpeedModifierSystem.ts"],"sourcesContent":["/**\n * Speed Modifier System\n *\n * **Korean**: 속도 변경 시스템 (Speed Modifier System)\n *\n * Implements comprehensive movement speed modifier system that dynamically adjusts\n * player movement speed based on multiple factors: combat stance, leg injuries,\n * stamina depletion, and combat state. Integrates with physics-based movement\n * system for authentic Korean martial arts combat feel.\n *\n * ## System Features\n *\n * - Base movement speeds for walking, running, backward, lateral, and crouching\n * - Eight Trigram stance-based speed modifiers (80% to 125%)\n * - Injury-based speed reduction from leg damage (0% to 100% penalty)\n * - Stamina-based acceleration penalty (0% to 75% penalty)\n * - Combat state speed adjustments (0% to 100% penalty)\n * - Multiplicative and additive modifier stacking\n *\n * ## Speed Calculation Formula\n *\n * ```\n * Final Speed = Base Speed\n *               × Stance Modifier\n *               × (1 - Injury Penalty from Legs, Torso & Pain)\n *               × (1 - Combat State Penalty)\n *\n * Final Acceleration = Base Acceleration\n *                      × (1 - Stamina Penalty)\n * ```\n *\n * @module systems/physics/SpeedModifierSystem\n * @category Physics System\n * @korean 속도변경시스템\n */\n\nimport type {\n  BodyPartHealth,\n  BodyPartMaxHealth,\n} from \"@/systems/bodypart/types\";\nimport type { PlayerState } from \"@/systems/player\";\nimport { CombatState, TrigramStance } from \"@/types/common\";\nimport { BASE_MOVEMENT_ACCELERATION } from \"@/types/physicsConstants\";\nimport { STANCE_SPEED_MODIFIERS } from \"./MovementPhysics\";\nimport { injuryMovementModifier } from \"@/systems/movement/InjuryMovementModifier\";\n\n/**\n * Complete speed modifier state for physics calculations.\n *\n * **Korean**: 속도 변경 상태 (Speed Modifier State)\n *\n * Contains all calculated speed modifiers and final values for application\n * to the physics-based movement system.\n *\n * @public\n * @category Physics System\n * @korean 속도변경상태\n */\nexport interface SpeedModifierState {\n  /** Base movement speed before modifiers (m/s) */\n  readonly baseSpeed: number;\n  /** Stance-based speed multiplier (0.80 to 1.25) */\n  readonly stanceModifier: number;\n  /** Injury-based speed reduction (0.0 to 0.75, percentage reduction) - Korean: 부상감소 */\n  readonly injuryPenalty: number;\n  /** Combat state speed reduction (0.0 to 1.0, percentage reduction) */\n  readonly combatStatePenalty: number;\n  /** Stamina-based acceleration reduction (0.0 to 0.75, percentage reduction) - Korean: 스태미나효과 */\n  readonly staminaPenalty: number;\n  /** Final calculated movement speed (m/s) */\n  readonly finalSpeed: number;\n  /** Final calculated acceleration (m/s²) */\n  readonly finalAcceleration: number;\n  /** Whether running is allowed (false when stamina < 10%) */\n  readonly canRun: boolean;\n}\n\n/**\n * Movement type enumeration.\n *\n * **Korean**: 이동 유형 (Movement Type)\n *\n * @public\n * @category Physics System\n */\nexport enum MovementType {\n  /** Walking forward - Korean: 걷기 */\n  WALKING = \"walking\",\n  /** Running/sprinting forward - Korean: 달리기 */\n  RUNNING = \"running\",\n  /** Moving backward - Korean: 후퇴 */\n  BACKWARD = \"backward\",\n  /** Side-stepping left/right - Korean: 측면이동 */\n  LATERAL = \"lateral\",\n  /** Crouching movement - Korean: 웅크리기 */\n  CROUCHING = \"crouching\",\n}\n\n/**\n * Speed Modifier System class.\n *\n * **Korean**: 속도 변경 시스템 클래스\n *\n * Calculates comprehensive speed modifiers from multiple factors including\n * stance, injuries, stamina, and combat state. Integrates with existing\n * body part and movement systems.\n *\n * @example\n * ```typescript\n * const system = new SpeedModifierSystem();\n *\n * const modifiers = system.calculateSpeedModifiers(\n *   playerState,\n *   MovementType.RUNNING,\n *   true // isCrouching\n * );\n *\n * // Apply to movement physics\n * movementPhysics.setMaxSpeed(modifiers.finalSpeed);\n * movementPhysics.setAcceleration(modifiers.finalAcceleration);\n * ```\n *\n * @public\n * @category Physics System\n */\nexport class SpeedModifierSystem {\n  /**\n   * Base walking speed (m/s)\n   * Standard walking pace for combat movement - crosses 14m arena in ~2.3s\n   *\n   * **Korean**: 기본 걷기 속도 (Base Walking Speed)\n   */\n  private readonly BASE_WALKING_SPEED = 6.0;\n\n  /**\n   * Base running speed (m/s)\n   * Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s\n   *\n   * **Korean**: 기본 달리기 속도 (Base Running Speed)\n   */\n  private readonly BASE_RUNNING_SPEED = 10.0;\n\n  /**\n   * Lateral movement speed (m/s)\n   * Fast side-stepping for combat positioning\n   *\n   * **Korean**: 측면 이동 속도 (Lateral Movement Speed)\n   */\n  private readonly LATERAL_SPEED = 5.0;\n\n  /**\n   * Crouching movement speed (m/s)\n   * Defensive low movement for cautious approach\n   *\n   * **Korean**: 웅크림 이동 속도 (Crouching Movement Speed)\n   */\n  private readonly CROUCHING_SPEED = 3.0;\n\n  /**\n   * Backward speed multiplier (75% of forward speed)\n   *\n   * **Korean**: 후퇴 속도 배수 (Backward Speed Multiplier)\n   */\n  private readonly BACKWARD_SPEED_MULTIPLIER = 0.75;\n\n  /**\n   * Base acceleration rate (m/s²)\n   * Instant-response acceleration for combat movement\n   * (e.g., reaches 6 m/s walking speed in 0.2s; 10 m/s sprint speed in 0.33s)\n   * Increased from 12.0 to 30.0 for responsive, arcade-style combat feel\n   *\n   * Imported from physicsConstants.ts to maintain consistency across systems.\n   *\n   * **Korean**: 기본 가속도 (Base Acceleration)\n   */\n  private readonly BASE_ACCELERATION = BASE_MOVEMENT_ACCELERATION;\n\n  /**\n   * Combat state speed penalty multipliers\n   *\n   * **Korean**: 전투 상태 속도 패널티 (Combat State Speed Penalties)\n   */\n  private readonly COMBAT_STATE_PENALTIES: Record<CombatState, number> = {\n    [CombatState.IDLE]: 0.0, // No penalty when idle\n    [CombatState.ATTACKING]: 0.3, // -30% during attack commitment\n    [CombatState.DEFENDING]: 0.2, // -20% while guarding\n    [CombatState.STUNNED]: 1.0, // Cannot move when stunned\n    [CombatState.RECOVERING]: 0.4, // -40% during recovery frames\n    [CombatState.COUNTERING]: 0.25, // -25% during counter execution\n    [CombatState.TRANSITIONING]: 0.15, // -15% during stance transitions\n    [CombatState.GRAPPLING]: 0.8, // -80% while controlling opponent\n    [CombatState.GRAPPLED]: 1.0, // Cannot move while being controlled\n  };\n\n  // Constructor removed - no longer need MovementPenaltySystem instance\n  // Using injuryMovementModifier singleton instead\n\n  /**\n   * Calculate comprehensive speed modifiers for player movement.\n   *\n   * **Korean**: 속도 변경 계산 (Calculate Speed Modifiers)\n   *\n   * Analyzes player state and returns complete speed modifier information\n   * including all individual factors and final calculated values.\n   *\n   * @param playerState - Current player state with stance, health, stamina\n   * @param movementType - Type of movement being performed\n   * @param isCrouching - Whether player is in crouching stance\n   * @returns Complete speed modifier state with all factors\n   *\n   * @public\n   */\n  public calculateSpeedModifiers(\n    playerState: PlayerState,\n    movementType: MovementType = MovementType.WALKING,\n    isCrouching: boolean = false,\n  ): SpeedModifierState {\n    // Get base speed based on movement type and archetype-specific speeds\n    const baseSpeed = this.getBaseSpeed(\n      movementType,\n      isCrouching,\n      playerState.physicalAttributes,\n    );\n\n    // Calculate injury penalty from leg damage using NEW InjuryMovementModifier system\n    // This replaces the old MovementPenaltySystem with comprehensive injury calculations\n    const injuryPenalty = this.calculateInjuryPenalty(\n      playerState.bodyPartHealth,\n      playerState.bodyPartMaxHealth,\n      playerState.pain,\n    );\n\n    // Calculate stance modifier separately.\n    // NOTE: InjuryMovementModifier is called with neutral GEON stance inside\n    // calculateInjuryPenalty() so that injury effects are isolated from stance.\n    // The actual current stance effect must be applied here via stanceModifier.\n    const stanceModifier = this.getStanceSpeedModifier(\n      playerState.currentStance,\n    );\n\n    // Calculate combat state penalty\n    const combatStatePenalty = this.getCombatStatePenalty(\n      playerState.combatState,\n    );\n\n    // Calculate stamina penalty (affects acceleration only)\n    const staminaPenalty = this.calculateStaminaPenalty(\n      playerState.stamina,\n      playerState.maxStamina,\n    );\n\n    // Check if running is allowed\n    const canRun = this.canPlayerRun(\n      playerState.stamina,\n      playerState.maxStamina,\n    );\n\n    // Calculate final speed with all modifiers applied multiplicatively\n    // Formula: Base × Stance × (1 - Injury) × (1 - CombatState)\n    // Note: Injury penalty now excludes stance (calculated with GEON), so we apply stance here\n    const finalSpeed =\n      baseSpeed *\n      stanceModifier *\n      (1.0 - injuryPenalty) *\n      (1.0 - combatStatePenalty);\n\n    // Calculate final acceleration using archetype-specific base and stamina penalty\n    // Formula: ArchetypeAcceleration × (1 - StaminaPenalty)\n    const archetypeAcceleration =\n      playerState.physicalAttributes?.acceleration ?? this.BASE_ACCELERATION;\n    const finalAcceleration = archetypeAcceleration * (1.0 - staminaPenalty);\n\n    return {\n      baseSpeed,\n      stanceModifier,\n      injuryPenalty,\n      combatStatePenalty,\n      staminaPenalty,\n      finalSpeed,\n      finalAcceleration,\n      canRun,\n    };\n  }\n\n  /**\n   * Get base speed for movement type.\n   *\n   * **Korean**: 기본 속도 계산 (Get Base Speed)\n   *\n   * Uses archetype-specific walk/run speeds when available,\n   * falls back to default values for backwards compatibility.\n   *\n   * @param movementType - Type of movement\n   * @param isCrouching - Whether player is crouching\n   * @param physicalAttributes - Player's physical attributes (optional)\n   * @returns Base speed in m/s\n   *\n   * @private\n   */\n  private getBaseSpeed(\n    movementType: MovementType,\n    isCrouching: boolean,\n    physicalAttributes?: import(\"@/types\").PhysicalAttributes,\n  ): number {\n    if (isCrouching) {\n      return this.CROUCHING_SPEED;\n    }\n\n    // Use archetype-specific speeds if available\n    const archetypeWalkSpeed =\n      physicalAttributes?.walkSpeed ?? this.BASE_WALKING_SPEED;\n    const archetypeRunSpeed =\n      physicalAttributes?.runSpeed ?? this.BASE_RUNNING_SPEED;\n\n    switch (movementType) {\n      case MovementType.WALKING:\n        return archetypeWalkSpeed;\n      case MovementType.RUNNING:\n        return archetypeRunSpeed;\n      case MovementType.BACKWARD:\n        return archetypeWalkSpeed * this.BACKWARD_SPEED_MULTIPLIER;\n      case MovementType.LATERAL:\n        // Lateral speed scales proportionally to archetype walk speed\n        return (\n          archetypeWalkSpeed * (this.LATERAL_SPEED / this.BASE_WALKING_SPEED)\n        );\n      case MovementType.CROUCHING:\n        return this.CROUCHING_SPEED;\n      default:\n        return archetypeWalkSpeed;\n    }\n  }\n\n  /**\n   * Get stance-based speed modifier.\n   *\n   * **Korean**: 자세 속도 배수 계산 (Get Stance Speed Modifier)\n   *\n   * @param stance - Current Eight Trigram stance\n   * @returns Speed multiplier (0.80 to 1.25)\n   *\n   * @private\n   */\n  private getStanceSpeedModifier(stance: TrigramStance): number {\n    return STANCE_SPEED_MODIFIERS[stance] ?? 1.0;\n  }\n\n  /**\n   * Calculate injury-based speed penalty from leg damage.\n   *\n   * **Korean**: 부상 속도 패널티 계산 (Calculate Injury Penalty)\n   *\n   * Uses NEW InjuryMovementModifier to determine speed reduction based on\n   * leg damage severity, torso damage, and pain levels.\n   * NOTE: Stance modifier is calculated separately to maintain compatibility\n   * with existing SpeedModifierState interface.\n   * \n   * Penalties are progressive and realistic:\n   * - Leg injuries: 0-100% penalty based on health\n   * - Torso injuries: 0-30% minor penalty\n   * - Both legs injured: Additional 20% cumulative penalty\n   * - Pain overload: -15% when pain ≥ 80\n   *\n   * @param bodyPartHealth - Current body part health\n   * @param bodyPartMaxHealth - Maximum body part health\n   * @param painLevel - Current pain level (0-100)\n   * @returns Speed penalty as percentage (0.0 to 0.9 max)\n   *\n   * @private\n   */\n  private calculateInjuryPenalty(\n    bodyPartHealth: BodyPartHealth | undefined,\n    bodyPartMaxHealth: BodyPartMaxHealth | undefined,\n    painLevel: number,\n  ): number {\n    if (!bodyPartHealth || !bodyPartMaxHealth) {\n      return 0.0; // No penalty if body part health not tracked\n    }\n\n    // Use NEW InjuryMovementModifier system for comprehensive injury calculation\n    // Use NEUTRAL stance (GEON = 1.0x) to get pure injury penalty without stance influence\n    // Stance is applied separately in calculateSpeedModifiers for compatibility\n    const result = injuryMovementModifier.calculateMovementSpeed(\n      1.0, // Base speed of 1.0 to get pure multiplier\n      bodyPartHealth,\n      TrigramStance.GEON, // Neutral stance to isolate injury penalty\n      painLevel,\n    );\n\n    // Convert speedMultiplier to penalty percentage\n    // speedMultiplier of 1.0 = no penalty (0.0)\n    // speedMultiplier of 0.5 = 50% penalty (0.5)\n    // speedMultiplier of 0.1 = 90% penalty (0.9)\n    const penalty = 1.0 - result.speedMultiplier;\n\n    // Return penalty (already clamped by InjuryMovementModifier to min 0.1 speed)\n    return Math.min(penalty, 0.9);\n  }\n\n  /**\n   * Calculate combat state speed penalty.\n   *\n   * **Korean**: 전투 상태 속도 패널티 계산 (Get Combat State Penalty)\n   *\n   * Different combat states restrict movement:\n   * - IDLE: 0% penalty (full movement)\n   * - ATTACKING: -30% penalty (committed to technique)\n   * - DEFENDING: -20% penalty (guard up, limited mobility)\n   * - STUNNED: -100% penalty (cannot move)\n   * - RECOVERING: -40% penalty (vulnerable, slow movement)\n   * - COUNTERING: -25% penalty (counter execution)\n   * - TRANSITIONING: -15% penalty (stance change)\n   *\n   * @param combatState - Current combat state\n   * @returns Speed penalty as percentage (0.0 to 1.0)\n   *\n   * @private\n   */\n  private getCombatStatePenalty(combatState: CombatState): number {\n    return this.COMBAT_STATE_PENALTIES[combatState] ?? 0.0;\n  }\n\n  /**\n   * Calculate stamina-based acceleration penalty.\n   *\n   * **Korean**: 스태미나 가속 패널티 계산 (Calculate Stamina Penalty)\n   *\n   * Stamina affects acceleration rate, making it harder to change direction\n   * or speed up when fatigued:\n   * - High stamina (70-100%): 0% penalty (normal acceleration)\n   * - Medium stamina (40-70%): -20% penalty\n   * - Low stamina (10-40%): -50% penalty\n   * - Depleted stamina (<10%): -75% penalty, cannot run\n   *\n   * @param currentStamina - Current stamina points\n   * @param maxStamina - Maximum stamina capacity\n   * @returns Acceleration penalty as percentage (0.0 to 0.75)\n   *\n   * @private\n   */\n  private calculateStaminaPenalty(\n    currentStamina: number,\n    maxStamina: number,\n  ): number {\n    if (maxStamina <= 0) {\n      return 0.0; // No penalty if stamina not tracked\n    }\n\n    const staminaPercent = (currentStamina / maxStamina) * 100;\n\n    if (staminaPercent >= 70) {\n      return 0.0; // High stamina: no penalty\n    } else if (staminaPercent >= 40) {\n      return 0.2; // Medium stamina: -20% acceleration\n    } else if (staminaPercent >= 10) {\n      return 0.5; // Low stamina: -50% acceleration\n    } else {\n      return 0.75; // Depleted stamina: -75% acceleration\n    }\n  }\n\n  /**\n   * Check if player can run based on stamina level.\n   *\n   * **Korean**: 달리기 가능 확인 (Can Player Run)\n   *\n   * @param currentStamina - Current stamina points\n   * @param maxStamina - Maximum stamina capacity\n   * @returns True if player has enough stamina to run\n   *\n   * @private\n   */\n  private canPlayerRun(currentStamina: number, maxStamina: number): boolean {\n    if (maxStamina <= 0) {\n      return true; // Allow running if stamina not tracked\n    }\n\n    const staminaPercent = (currentStamina / maxStamina) * 100;\n    return staminaPercent >= 10; // Cannot run when stamina < 10%\n  }\n\n  /**\n   * Apply speed modifiers to movement physics system.\n   *\n   * **Korean**: 속도 변경 적용 (Apply Speed Modifiers)\n   *\n   * Convenience method to directly apply calculated modifiers to a\n   * movement physics instance.\n   *\n   * @param movementPhysics - Movement physics system to update\n   * @param modifiers - Calculated speed modifier state\n   *\n   * @public\n   */\n  public applySpeedModifiers(\n    movementPhysics: {\n      setMaxSpeed: (speed: number) => void;\n      setAcceleration: (accel: number) => void;\n    },\n    modifiers: SpeedModifierState,\n  ): void {\n    movementPhysics.setMaxSpeed(modifiers.finalSpeed);\n    movementPhysics.setAcceleration(modifiers.finalAcceleration);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAqFA,IAAY,eAAL,yBAAA,cAAA;;CAEL,aAAA,aAAU;;CAEV,aAAA,aAAU;;CAEV,aAAA,cAAW;;CAEX,aAAA,aAAU;;CAEV,aAAA,eAAY;;KACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BD,IAAa,sBAAb,MAAiC;;;;;;;CAO/B,qBAAsC;;;;;;;CAQtC,qBAAsC;;;;;;;CAQtC,gBAAiC;;;;;;;CAQjC,kBAAmC;;;;;;CAOnC,4BAA6C;;;;;;;;;;;CAY7C,oBAAA;;;;;;CAOA,yBAAuE;GACpE,YAAY,OAAO;GACnB,YAAY,YAAY;GACxB,YAAY,YAAY;GACxB,YAAY,UAAU;GACtB,YAAY,aAAa;GACzB,YAAY,aAAa;GACzB,YAAY,gBAAgB;GAC5B,YAAY,YAAY;GACxB,YAAY,WAAW;EACzB;;;;;;;;;;;;;;;;CAoBD,wBACE,aACA,eAA6B,aAAa,SAC1C,cAAuB,OACH;EAEpB,MAAM,YAAY,KAAK,aACrB,cACA,aACA,YAAY,mBACb;EAID,MAAM,gBAAgB,KAAK,uBACzB,YAAY,gBACZ,YAAY,mBACZ,YAAY,KACb;EAMD,MAAM,iBAAiB,KAAK,uBAC1B,YAAY,cACb;EAGD,MAAM,qBAAqB,KAAK,sBAC9B,YAAY,YACb;EAGD,MAAM,iBAAiB,KAAK,wBAC1B,YAAY,SACZ,YAAY,WACb;EAGD,MAAM,SAAS,KAAK,aAClB,YAAY,SACZ,YAAY,WACb;EAiBD,OAAO;GACL;GACA;GACA;GACA;GACA;GACA,YAjBA,YACA,kBACC,IAAM,kBACN,IAAM;GAeP,oBAVA,YAAY,oBAAoB,gBAAgB,KAAK,sBACJ,IAAM;GAUvD;GACD;;;;;;;;;;;;;;;;;CAkBH,aACE,cACA,aACA,oBACQ;EACR,IAAI,aACF,OAAO,KAAK;EAId,MAAM,qBACJ,oBAAoB,aAAa,KAAK;EACxC,MAAM,oBACJ,oBAAoB,YAAY,KAAK;EAEvC,QAAQ,cAAR;GACE,KAAK,aAAa,SAChB,OAAO;GACT,KAAK,aAAa,SAChB,OAAO;GACT,KAAK,aAAa,UAChB,OAAO,qBAAqB,KAAK;GACnC,KAAK,aAAa,SAEhB,OACE,sBAAsB,KAAK,gBAAgB,KAAK;GAEpD,KAAK,aAAa,WAChB,OAAO,KAAK;GACd,SACE,OAAO;;;;;;;;;;;;;CAcb,uBAA+B,QAA+B;EAC5D,OAAO,uBAAuB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;CA0B3C,uBACE,gBACA,mBACA,WACQ;EACR,IAAI,CAAC,kBAAkB,CAAC,mBACtB,OAAO;EAiBT,MAAM,UAAU,IAXD,uBAAuB,uBACpC,GACA,gBACA,cAAc,MACd,UAOoB,CAAO;EAG7B,OAAO,KAAK,IAAI,SAAS,GAAI;;;;;;;;;;;;;;;;;;;;;CAsB/B,sBAA8B,aAAkC;EAC9D,OAAO,KAAK,uBAAuB,gBAAgB;;;;;;;;;;;;;;;;;;;;CAqBrD,wBACE,gBACA,YACQ;EACR,IAAI,cAAc,GAChB,OAAO;EAGT,MAAM,iBAAkB,iBAAiB,aAAc;EAEvD,IAAI,kBAAkB,IACpB,OAAO;OACF,IAAI,kBAAkB,IAC3B,OAAO;OACF,IAAI,kBAAkB,IAC3B,OAAO;OAEP,OAAO;;;;;;;;;;;;;CAeX,aAAqB,gBAAwB,YAA6B;EACxE,IAAI,cAAc,GAChB,OAAO;EAIT,OADwB,iBAAiB,aAAc,OAC9B;;;;;;;;;;;;;;;CAgB3B,oBACE,iBAIA,WACM;EACN,gBAAgB,YAAY,UAAU,WAAW;EACjD,gBAAgB,gBAAgB,UAAU,kBAAkB"}
+{"version":3,"file":"SpeedModifierSystem.js","names":[],"sources":["../../../src/systems/physics/SpeedModifierSystem.ts"],"sourcesContent":["/**\n * Speed Modifier System\n *\n * **Korean**: 속도 변경 시스템 (Speed Modifier System)\n *\n * Implements comprehensive movement speed modifier system that dynamically adjusts\n * player movement speed based on multiple factors: combat stance, leg injuries,\n * stamina depletion, and combat state. Integrates with physics-based movement\n * system for authentic Korean martial arts combat feel.\n *\n * ## System Features\n *\n * - Base movement speeds for walking, running, backward, lateral, and crouching\n * - Eight Trigram stance-based speed modifiers (80% to 125%)\n * - Injury-based speed reduction from leg damage (0% to 100% penalty)\n * - Stamina-based acceleration penalty (0% to 75% penalty)\n * - Combat state speed adjustments (0% to 100% penalty)\n * - Multiplicative and additive modifier stacking\n *\n * ## Speed Calculation Formula\n *\n * ```\n * Final Speed = Base Speed\n *               × Stance Modifier\n *               × (1 - Injury Penalty from Legs, Torso & Pain)\n *               × (1 - Combat State Penalty)\n *\n * Final Acceleration = Base Acceleration\n *                      × (1 - Stamina Penalty)\n * ```\n *\n * @module systems/physics/SpeedModifierSystem\n * @category Physics System\n * @korean 속도변경시스템\n */\n\nimport type {\n  BodyPartHealth,\n  BodyPartMaxHealth,\n} from \"@/systems/bodypart/types\";\nimport type { PlayerState } from \"@/systems/player\";\nimport { CombatState, TrigramStance } from \"@/types/common\";\nimport { BASE_MOVEMENT_ACCELERATION } from \"@/types/physicsConstants\";\nimport { STANCE_SPEED_MODIFIERS } from \"./MovementPhysics\";\nimport { injuryMovementModifier } from \"@/systems/movement/InjuryMovementModifier\";\n\n/**\n * Complete speed modifier state for physics calculations.\n *\n * **Korean**: 속도 변경 상태 (Speed Modifier State)\n *\n * Contains all calculated speed modifiers and final values for application\n * to the physics-based movement system.\n *\n * @category Physics System\n * @korean 속도변경상태\n */\nexport interface SpeedModifierState {\n  /** Base movement speed before modifiers (m/s) */\n  readonly baseSpeed: number;\n  /** Stance-based speed multiplier (0.80 to 1.25) */\n  readonly stanceModifier: number;\n  /** Injury-based speed reduction (0.0 to 0.75, percentage reduction) - Korean: 부상감소 */\n  readonly injuryPenalty: number;\n  /** Combat state speed reduction (0.0 to 1.0, percentage reduction) */\n  readonly combatStatePenalty: number;\n  /** Stamina-based acceleration reduction (0.0 to 0.75, percentage reduction) - Korean: 스태미나효과 */\n  readonly staminaPenalty: number;\n  /** Final calculated movement speed (m/s) */\n  readonly finalSpeed: number;\n  /** Final calculated acceleration (m/s²) */\n  readonly finalAcceleration: number;\n  /** Whether running is allowed (false when stamina < 10%) */\n  readonly canRun: boolean;\n}\n\n/**\n * Movement type enumeration.\n *\n * **Korean**: 이동 유형 (Movement Type)\n *\n * @category Physics System\n */\nexport enum MovementType {\n  /** Walking forward - Korean: 걷기 */\n  WALKING = \"walking\",\n  /** Running/sprinting forward - Korean: 달리기 */\n  RUNNING = \"running\",\n  /** Moving backward - Korean: 후퇴 */\n  BACKWARD = \"backward\",\n  /** Side-stepping left/right - Korean: 측면이동 */\n  LATERAL = \"lateral\",\n  /** Crouching movement - Korean: 웅크리기 */\n  CROUCHING = \"crouching\",\n}\n\n/**\n * Speed Modifier System class.\n *\n * **Korean**: 속도 변경 시스템 클래스\n *\n * Calculates comprehensive speed modifiers from multiple factors including\n * stance, injuries, stamina, and combat state. Integrates with existing\n * body part and movement systems.\n *\n * @example\n * ```typescript\n * const system = new SpeedModifierSystem();\n *\n * const modifiers = system.calculateSpeedModifiers(\n *   playerState,\n *   MovementType.RUNNING,\n *   true // isCrouching\n * );\n *\n * // Apply to movement physics\n * movementPhysics.setMaxSpeed(modifiers.finalSpeed);\n * movementPhysics.setAcceleration(modifiers.finalAcceleration);\n * ```\n *\n * @category Physics System\n */\nexport class SpeedModifierSystem {\n  /**\n   * Base walking speed (m/s)\n   * Standard walking pace for combat movement - crosses 14m arena in ~2.3s\n   *\n   * **Korean**: 기본 걷기 속도 (Base Walking Speed)\n   */\n  private readonly BASE_WALKING_SPEED = 6.0;\n\n  /**\n   * Base running speed (m/s)\n   * Sprint speed for rapid repositioning - crosses 14m arena in ~1.4s\n   *\n   * **Korean**: 기본 달리기 속도 (Base Running Speed)\n   */\n  private readonly BASE_RUNNING_SPEED = 10.0;\n\n  /**\n   * Lateral movement speed (m/s)\n   * Fast side-stepping for combat positioning\n   *\n   * **Korean**: 측면 이동 속도 (Lateral Movement Speed)\n   */\n  private readonly LATERAL_SPEED = 5.0;\n\n  /**\n   * Crouching movement speed (m/s)\n   * Defensive low movement for cautious approach\n   *\n   * **Korean**: 웅크림 이동 속도 (Crouching Movement Speed)\n   */\n  private readonly CROUCHING_SPEED = 3.0;\n\n  /**\n   * Backward speed multiplier (75% of forward speed)\n   *\n   * **Korean**: 후퇴 속도 배수 (Backward Speed Multiplier)\n   */\n  private readonly BACKWARD_SPEED_MULTIPLIER = 0.75;\n\n  /**\n   * Base acceleration rate (m/s²)\n   * Instant-response acceleration for combat movement\n   * (e.g., reaches 6 m/s walking speed in 0.2s; 10 m/s sprint speed in 0.33s)\n   * Increased from 12.0 to 30.0 for responsive, arcade-style combat feel\n   *\n   * Imported from physicsConstants.ts to maintain consistency across systems.\n   *\n   * **Korean**: 기본 가속도 (Base Acceleration)\n   */\n  private readonly BASE_ACCELERATION = BASE_MOVEMENT_ACCELERATION;\n\n  /**\n   * Combat state speed penalty multipliers\n   *\n   * **Korean**: 전투 상태 속도 패널티 (Combat State Speed Penalties)\n   */\n  private readonly COMBAT_STATE_PENALTIES: Record<CombatState, number> = {\n    [CombatState.IDLE]: 0.0, // No penalty when idle\n    [CombatState.ATTACKING]: 0.3, // -30% during attack commitment\n    [CombatState.DEFENDING]: 0.2, // -20% while guarding\n    [CombatState.STUNNED]: 1.0, // Cannot move when stunned\n    [CombatState.RECOVERING]: 0.4, // -40% during recovery frames\n    [CombatState.COUNTERING]: 0.25, // -25% during counter execution\n    [CombatState.TRANSITIONING]: 0.15, // -15% during stance transitions\n    [CombatState.GRAPPLING]: 0.8, // -80% while controlling opponent\n    [CombatState.GRAPPLED]: 1.0, // Cannot move while being controlled\n  };\n\n  // Constructor removed - no longer need MovementPenaltySystem instance\n  // Using injuryMovementModifier singleton instead\n\n  /**\n   * Calculate comprehensive speed modifiers for player movement.\n   *\n   * **Korean**: 속도 변경 계산 (Calculate Speed Modifiers)\n   *\n   * Analyzes player state and returns complete speed modifier information\n   * including all individual factors and final calculated values.\n   *\n   * @param playerState - Current player state with stance, health, stamina\n   * @param movementType - Type of movement being performed\n   * @param isCrouching - Whether player is in crouching stance\n   * @returns Complete speed modifier state with all factors\n   *\n   */\n  public calculateSpeedModifiers(\n    playerState: PlayerState,\n    movementType: MovementType = MovementType.WALKING,\n    isCrouching: boolean = false,\n  ): SpeedModifierState {\n    // Get base speed based on movement type and archetype-specific speeds\n    const baseSpeed = this.getBaseSpeed(\n      movementType,\n      isCrouching,\n      playerState.physicalAttributes,\n    );\n\n    // Calculate injury penalty from leg damage using NEW InjuryMovementModifier system\n    // This replaces the old MovementPenaltySystem with comprehensive injury calculations\n    const injuryPenalty = this.calculateInjuryPenalty(\n      playerState.bodyPartHealth,\n      playerState.bodyPartMaxHealth,\n      playerState.pain,\n    );\n\n    // Calculate stance modifier separately.\n    // NOTE: InjuryMovementModifier is called with neutral GEON stance inside\n    // calculateInjuryPenalty() so that injury effects are isolated from stance.\n    // The actual current stance effect must be applied here via stanceModifier.\n    const stanceModifier = this.getStanceSpeedModifier(\n      playerState.currentStance,\n    );\n\n    // Calculate combat state penalty\n    const combatStatePenalty = this.getCombatStatePenalty(\n      playerState.combatState,\n    );\n\n    // Calculate stamina penalty (affects acceleration only)\n    const staminaPenalty = this.calculateStaminaPenalty(\n      playerState.stamina,\n      playerState.maxStamina,\n    );\n\n    // Check if running is allowed\n    const canRun = this.canPlayerRun(\n      playerState.stamina,\n      playerState.maxStamina,\n    );\n\n    // Calculate final speed with all modifiers applied multiplicatively\n    // Formula: Base × Stance × (1 - Injury) × (1 - CombatState)\n    // Note: Injury penalty now excludes stance (calculated with GEON), so we apply stance here\n    const finalSpeed =\n      baseSpeed *\n      stanceModifier *\n      (1.0 - injuryPenalty) *\n      (1.0 - combatStatePenalty);\n\n    // Calculate final acceleration using archetype-specific base and stamina penalty\n    // Formula: ArchetypeAcceleration × (1 - StaminaPenalty)\n    const archetypeAcceleration =\n      playerState.physicalAttributes?.acceleration ?? this.BASE_ACCELERATION;\n    const finalAcceleration = archetypeAcceleration * (1.0 - staminaPenalty);\n\n    return {\n      baseSpeed,\n      stanceModifier,\n      injuryPenalty,\n      combatStatePenalty,\n      staminaPenalty,\n      finalSpeed,\n      finalAcceleration,\n      canRun,\n    };\n  }\n\n  /**\n   * Get base speed for movement type.\n   *\n   * **Korean**: 기본 속도 계산 (Get Base Speed)\n   *\n   * Uses archetype-specific walk/run speeds when available,\n   * falls back to default values for backwards compatibility.\n   *\n   * @param movementType - Type of movement\n   * @param isCrouching - Whether player is crouching\n   * @param physicalAttributes - Player's physical attributes (optional)\n   * @returns Base speed in m/s\n   *\n   * @private\n   */\n  private getBaseSpeed(\n    movementType: MovementType,\n    isCrouching: boolean,\n    physicalAttributes?: import(\"@/types\").PhysicalAttributes,\n  ): number {\n    if (isCrouching) {\n      return this.CROUCHING_SPEED;\n    }\n\n    // Use archetype-specific speeds if available\n    const archetypeWalkSpeed =\n      physicalAttributes?.walkSpeed ?? this.BASE_WALKING_SPEED;\n    const archetypeRunSpeed =\n      physicalAttributes?.runSpeed ?? this.BASE_RUNNING_SPEED;\n\n    switch (movementType) {\n      case MovementType.WALKING:\n        return archetypeWalkSpeed;\n      case MovementType.RUNNING:\n        return archetypeRunSpeed;\n      case MovementType.BACKWARD:\n        return archetypeWalkSpeed * this.BACKWARD_SPEED_MULTIPLIER;\n      case MovementType.LATERAL:\n        // Lateral speed scales proportionally to archetype walk speed\n        return (\n          archetypeWalkSpeed * (this.LATERAL_SPEED / this.BASE_WALKING_SPEED)\n        );\n      case MovementType.CROUCHING:\n        return this.CROUCHING_SPEED;\n      default:\n        return archetypeWalkSpeed;\n    }\n  }\n\n  /**\n   * Get stance-based speed modifier.\n   *\n   * **Korean**: 자세 속도 배수 계산 (Get Stance Speed Modifier)\n   *\n   * @param stance - Current Eight Trigram stance\n   * @returns Speed multiplier (0.80 to 1.25)\n   *\n   * @private\n   */\n  private getStanceSpeedModifier(stance: TrigramStance): number {\n    return STANCE_SPEED_MODIFIERS[stance] ?? 1.0;\n  }\n\n  /**\n   * Calculate injury-based speed penalty from leg damage.\n   *\n   * **Korean**: 부상 속도 패널티 계산 (Calculate Injury Penalty)\n   *\n   * Uses NEW InjuryMovementModifier to determine speed reduction based on\n   * leg damage severity, torso damage, and pain levels.\n   * NOTE: Stance modifier is calculated separately to maintain compatibility\n   * with existing SpeedModifierState interface.\n   * \n   * Penalties are progressive and realistic:\n   * - Leg injuries: 0-100% penalty based on health\n   * - Torso injuries: 0-30% minor penalty\n   * - Both legs injured: Additional 20% cumulative penalty\n   * - Pain overload: -15% when pain ≥ 80\n   *\n   * @param bodyPartHealth - Current body part health\n   * @param bodyPartMaxHealth - Maximum body part health\n   * @param painLevel - Current pain level (0-100)\n   * @returns Speed penalty as percentage (0.0 to 0.9 max)\n   *\n   * @private\n   */\n  private calculateInjuryPenalty(\n    bodyPartHealth: BodyPartHealth | undefined,\n    bodyPartMaxHealth: BodyPartMaxHealth | undefined,\n    painLevel: number,\n  ): number {\n    if (!bodyPartHealth || !bodyPartMaxHealth) {\n      return 0.0; // No penalty if body part health not tracked\n    }\n\n    // Use NEW InjuryMovementModifier system for comprehensive injury calculation\n    // Use NEUTRAL stance (GEON = 1.0x) to get pure injury penalty without stance influence\n    // Stance is applied separately in calculateSpeedModifiers for compatibility\n    const result = injuryMovementModifier.calculateMovementSpeed(\n      1.0, // Base speed of 1.0 to get pure multiplier\n      bodyPartHealth,\n      TrigramStance.GEON, // Neutral stance to isolate injury penalty\n      painLevel,\n    );\n\n    // Convert speedMultiplier to penalty percentage\n    // speedMultiplier of 1.0 = no penalty (0.0)\n    // speedMultiplier of 0.5 = 50% penalty (0.5)\n    // speedMultiplier of 0.1 = 90% penalty (0.9)\n    const penalty = 1.0 - result.speedMultiplier;\n\n    // Return penalty (already clamped by InjuryMovementModifier to min 0.1 speed)\n    return Math.min(penalty, 0.9);\n  }\n\n  /**\n   * Calculate combat state speed penalty.\n   *\n   * **Korean**: 전투 상태 속도 패널티 계산 (Get Combat State Penalty)\n   *\n   * Different combat states restrict movement:\n   * - IDLE: 0% penalty (full movement)\n   * - ATTACKING: -30% penalty (committed to technique)\n   * - DEFENDING: -20% penalty (guard up, limited mobility)\n   * - STUNNED: -100% penalty (cannot move)\n   * - RECOVERING: -40% penalty (vulnerable, slow movement)\n   * - COUNTERING: -25% penalty (counter execution)\n   * - TRANSITIONING: -15% penalty (stance change)\n   *\n   * @param combatState - Current combat state\n   * @returns Speed penalty as percentage (0.0 to 1.0)\n   *\n   * @private\n   */\n  private getCombatStatePenalty(combatState: CombatState): number {\n    return this.COMBAT_STATE_PENALTIES[combatState] ?? 0.0;\n  }\n\n  /**\n   * Calculate stamina-based acceleration penalty.\n   *\n   * **Korean**: 스태미나 가속 패널티 계산 (Calculate Stamina Penalty)\n   *\n   * Stamina affects acceleration rate, making it harder to change direction\n   * or speed up when fatigued:\n   * - High stamina (70-100%): 0% penalty (normal acceleration)\n   * - Medium stamina (40-70%): -20% penalty\n   * - Low stamina (10-40%): -50% penalty\n   * - Depleted stamina (<10%): -75% penalty, cannot run\n   *\n   * @param currentStamina - Current stamina points\n   * @param maxStamina - Maximum stamina capacity\n   * @returns Acceleration penalty as percentage (0.0 to 0.75)\n   *\n   * @private\n   */\n  private calculateStaminaPenalty(\n    currentStamina: number,\n    maxStamina: number,\n  ): number {\n    if (maxStamina <= 0) {\n      return 0.0; // No penalty if stamina not tracked\n    }\n\n    const staminaPercent = (currentStamina / maxStamina) * 100;\n\n    if (staminaPercent >= 70) {\n      return 0.0; // High stamina: no penalty\n    } else if (staminaPercent >= 40) {\n      return 0.2; // Medium stamina: -20% acceleration\n    } else if (staminaPercent >= 10) {\n      return 0.5; // Low stamina: -50% acceleration\n    } else {\n      return 0.75; // Depleted stamina: -75% acceleration\n    }\n  }\n\n  /**\n   * Check if player can run based on stamina level.\n   *\n   * **Korean**: 달리기 가능 확인 (Can Player Run)\n   *\n   * @param currentStamina - Current stamina points\n   * @param maxStamina - Maximum stamina capacity\n   * @returns True if player has enough stamina to run\n   *\n   * @private\n   */\n  private canPlayerRun(currentStamina: number, maxStamina: number): boolean {\n    if (maxStamina <= 0) {\n      return true; // Allow running if stamina not tracked\n    }\n\n    const staminaPercent = (currentStamina / maxStamina) * 100;\n    return staminaPercent >= 10; // Cannot run when stamina < 10%\n  }\n\n  /**\n   * Apply speed modifiers to movement physics system.\n   *\n   * **Korean**: 속도 변경 적용 (Apply Speed Modifiers)\n   *\n   * Convenience method to directly apply calculated modifiers to a\n   * movement physics instance.\n   *\n   * @param movementPhysics - Movement physics system to update\n   * @param modifiers - Calculated speed modifier state\n   *\n   */\n  public applySpeedModifiers(\n    movementPhysics: {\n      setMaxSpeed: (speed: number) => void;\n      setAcceleration: (accel: number) => void;\n    },\n    modifiers: SpeedModifierState,\n  ): void {\n    movementPhysics.setMaxSpeed(modifiers.finalSpeed);\n    movementPhysics.setAcceleration(modifiers.finalAcceleration);\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAmFA,IAAY,eAAL,yBAAA,cAAA;;CAEL,aAAA,aAAU;;CAEV,aAAA,aAAU;;CAEV,aAAA,cAAW;;CAEX,aAAA,aAAU;;CAEV,aAAA,eAAY;;KACb;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BD,IAAa,sBAAb,MAAiC;;;;;;;CAO/B,qBAAsC;;;;;;;CAQtC,qBAAsC;;;;;;;CAQtC,gBAAiC;;;;;;;CAQjC,kBAAmC;;;;;;CAOnC,4BAA6C;;;;;;;;;;;CAY7C,oBAAA;;;;;;CAOA,yBAAuE;GACpE,YAAY,OAAO;GACnB,YAAY,YAAY;GACxB,YAAY,YAAY;GACxB,YAAY,UAAU;GACtB,YAAY,aAAa;GACzB,YAAY,aAAa;GACzB,YAAY,gBAAgB;GAC5B,YAAY,YAAY;GACxB,YAAY,WAAW;EACzB;;;;;;;;;;;;;;;CAmBD,wBACE,aACA,eAA6B,aAAa,SAC1C,cAAuB,OACH;EAEpB,MAAM,YAAY,KAAK,aACrB,cACA,aACA,YAAY,mBACb;EAID,MAAM,gBAAgB,KAAK,uBACzB,YAAY,gBACZ,YAAY,mBACZ,YAAY,KACb;EAMD,MAAM,iBAAiB,KAAK,uBAC1B,YAAY,cACb;EAGD,MAAM,qBAAqB,KAAK,sBAC9B,YAAY,YACb;EAGD,MAAM,iBAAiB,KAAK,wBAC1B,YAAY,SACZ,YAAY,WACb;EAGD,MAAM,SAAS,KAAK,aAClB,YAAY,SACZ,YAAY,WACb;EAiBD,OAAO;GACL;GACA;GACA;GACA;GACA;GACA,YAjBA,YACA,kBACC,IAAM,kBACN,IAAM;GAeP,oBAVA,YAAY,oBAAoB,gBAAgB,KAAK,sBACJ,IAAM;GAUvD;GACD;;;;;;;;;;;;;;;;;CAkBH,aACE,cACA,aACA,oBACQ;EACR,IAAI,aACF,OAAO,KAAK;EAId,MAAM,qBACJ,oBAAoB,aAAa,KAAK;EACxC,MAAM,oBACJ,oBAAoB,YAAY,KAAK;EAEvC,QAAQ,cAAR;GACE,KAAK,aAAa,SAChB,OAAO;GACT,KAAK,aAAa,SAChB,OAAO;GACT,KAAK,aAAa,UAChB,OAAO,qBAAqB,KAAK;GACnC,KAAK,aAAa,SAEhB,OACE,sBAAsB,KAAK,gBAAgB,KAAK;GAEpD,KAAK,aAAa,WAChB,OAAO,KAAK;GACd,SACE,OAAO;;;;;;;;;;;;;CAcb,uBAA+B,QAA+B;EAC5D,OAAO,uBAAuB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;CA0B3C,uBACE,gBACA,mBACA,WACQ;EACR,IAAI,CAAC,kBAAkB,CAAC,mBACtB,OAAO;EAiBT,MAAM,UAAU,IAXD,uBAAuB,uBACpC,GACA,gBACA,cAAc,MACd,UAOoB,CAAO;EAG7B,OAAO,KAAK,IAAI,SAAS,GAAI;;;;;;;;;;;;;;;;;;;;;CAsB/B,sBAA8B,aAAkC;EAC9D,OAAO,KAAK,uBAAuB,gBAAgB;;;;;;;;;;;;;;;;;;;;CAqBrD,wBACE,gBACA,YACQ;EACR,IAAI,cAAc,GAChB,OAAO;EAGT,MAAM,iBAAkB,iBAAiB,aAAc;EAEvD,IAAI,kBAAkB,IACpB,OAAO;OACF,IAAI,kBAAkB,IAC3B,OAAO;OACF,IAAI,kBAAkB,IAC3B,OAAO;OAEP,OAAO;;;;;;;;;;;;;CAeX,aAAqB,gBAAwB,YAA6B;EACxE,IAAI,cAAc,GAChB,OAAO;EAIT,OADwB,iBAAiB,aAAc,OAC9B;;;;;;;;;;;;;;CAe3B,oBACE,iBAIA,WACM;EACN,gBAAgB,YAAY,UAAU,WAAW;EACjD,gBAAgB,gBAAgB,UAAU,kBAAkB"}

package/lib/systems/player.d.ts

@@ -83,7 +83,6 @@ import { CombatState, KoreanText, PlayerArchetype, Position, TrigramStance } fro
  * };
  * ```
  *
- * @public
  * @category Player & Archetypes
  * @korean 플레이어상태
  */
@@ -242,7 +241,6 @@ export interface PlayerState {
  * };
  * ```
  *
- * @public
  * @category Player & Archetypes
  * @korean 플레이어생성
  */
@@ -271,7 +269,6 @@ export interface PlayerCreationData {
  *
  * Tracks performance metrics for a single combat match.
  *
- * @public
  * @category Player & Archetypes
  * @korean 경기통계
  */
@@ -315,7 +312,6 @@ export interface PlayerMatchStats {
  * };
  * ```
  *
- * @public
  * @category Player & Archetypes
  */
 export type PlayerUpdateData = Partial<PlayerState>;
@@ -327,7 +323,6 @@ export type PlayerUpdateData = Partial<PlayerState>;
  * Simplified player state for systems that don't require full combat data.
  * Useful for UI displays and simple calculations.
  *
- * @public
  * @category Player & Archetypes
  * @korean 최소상태
  */