blacktrigram 0.7.2

package/lib/systems/movement/InjuryMovementModifier.js

@@ -0,0 +1,281 @@
+import { STANCE_SPEED_MODIFIERS } from "../physics/MovementPhysics.js";
+//#region src/systems/movement/InjuryMovementModifier.ts
+/**
+* Default configuration matching acceptance criteria.
+*/
+var DEFAULT_INJURY_MOVEMENT_CONFIG = {
+	legThresholds: {
+		normal: 70,
+		limping: 30,
+		critical: 10
+	},
+	maxTorsoPenalty: .3,
+	bothLegsInjuredMultiplier: .8,
+	painOverloadThreshold: 80,
+	painOverloadMultiplier: .85,
+	minSpeedMultiplier: .1
+};
+/**
+* Singleton instance for global access.
+* 
+* @public
+*/
+var injuryMovementModifier = new class InjuryMovementModifier {
+	config;
+	/**
+	* Threshold for determining if both legs are significantly injured.
+	* Uses epsilon to avoid floating-point rounding issues at boundary.
+	* 
+	* @private
+	*/
+	static BOTH_LEGS_THRESHOLD = .3000000001;
+	/**
+	* Creates a new InjuryMovementModifier with optional configuration.
+	* 
+	* @param config - Optional configuration overrides (supports partial threshold overrides)
+	*/
+	constructor(config) {
+		const mergedConfig = {
+			legThresholds: {
+				normal: config?.legThresholds?.normal ?? DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.normal,
+				limping: config?.legThresholds?.limping ?? DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.limping,
+				critical: config?.legThresholds?.critical ?? DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.critical
+			},
+			maxTorsoPenalty: config?.maxTorsoPenalty ?? DEFAULT_INJURY_MOVEMENT_CONFIG.maxTorsoPenalty,
+			bothLegsInjuredMultiplier: config?.bothLegsInjuredMultiplier ?? DEFAULT_INJURY_MOVEMENT_CONFIG.bothLegsInjuredMultiplier,
+			painOverloadThreshold: config?.painOverloadThreshold ?? DEFAULT_INJURY_MOVEMENT_CONFIG.painOverloadThreshold,
+			painOverloadMultiplier: config?.painOverloadMultiplier ?? DEFAULT_INJURY_MOVEMENT_CONFIG.painOverloadMultiplier,
+			minSpeedMultiplier: config?.minSpeedMultiplier ?? DEFAULT_INJURY_MOVEMENT_CONFIG.minSpeedMultiplier
+		};
+		if (process.env.NODE_ENV !== "production") {
+			const { normal, limping, critical } = mergedConfig.legThresholds;
+			if (!(Number.isFinite(normal) && Number.isFinite(limping) && Number.isFinite(critical)) || !(normal >= limping && limping >= critical)) console.warn("[InjuryMovementModifier] Invalid legThresholds configuration detected:", mergedConfig.legThresholds);
+		}
+		this.config = mergedConfig;
+	}
+	/**
+	* Calculate modified movement speed based on all injury factors.
+	* 
+	* **Korean**: 이동 속도 계산
+	* 
+	* Applies penalties from:
+	* 1. Leg injuries (primary factor)
+	* 2. Torso injuries (minor factor)
+	* 3. Both legs injured (cumulative penalty)
+	* 4. Stance modifiers
+	* 5. Pain overload
+	* 
+	* @param baseSpeed - Base movement speed (m/s)
+	* @param bodyPartHealth - Current body part health values
+	* @param stance - Current trigram stance
+	* @param painLevel - Current pain level (0-100)
+	* @returns Complete movement calculation result
+	* 
+	* @public
+	* @korean 이동속도계산
+	*/
+	calculateMovementSpeed(baseSpeed, bodyPartHealth, stance, painLevel) {
+		const leftLegPenalty = this.calculateLegPenalty(bodyPartHealth.legLeft);
+		const rightLegPenalty = this.calculateLegPenalty(bodyPartHealth.legRight);
+		let speedMultiplier = 1 - Math.max(leftLegPenalty, rightLegPenalty);
+		const bothLegsInjured = this.areBothLegsInjured(leftLegPenalty, rightLegPenalty);
+		if (bothLegsInjured) speedMultiplier *= this.config.bothLegsInjuredMultiplier;
+		const avgTorsoHealth = (bodyPartHealth.torsoUpper + bodyPartHealth.torsoLower) / 2;
+		const torsoPenalty = (100 - Math.min(100, Math.max(0, avgTorsoHealth))) / 100 * this.config.maxTorsoPenalty;
+		speedMultiplier *= 1 - torsoPenalty;
+		const stanceModifier = this.getStanceSpeedModifier(stance);
+		speedMultiplier *= stanceModifier;
+		const painOverload = painLevel >= this.config.painOverloadThreshold;
+		if (painOverload) speedMultiplier *= this.config.painOverloadMultiplier;
+		speedMultiplier = Math.max(speedMultiplier, this.config.minSpeedMultiplier);
+		const finalSpeed = baseSpeed * speedMultiplier;
+		const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);
+		const isLimping = worstLegHealth < this.config.legThresholds.normal && worstLegHealth >= this.config.legThresholds.limping;
+		const isSevereLimp = worstLegHealth < this.config.legThresholds.limping;
+		const statusText = this.generateStatusText(worstLegHealth, bothLegsInjured, painOverload);
+		return {
+			finalSpeed,
+			speedMultiplier,
+			penalties: {
+				leftLegPenalty,
+				rightLegPenalty,
+				torsoPenalty,
+				bothLegsInjured,
+				stanceModifier,
+				painOverload
+			},
+			isLimping,
+			isSevereLimp,
+			statusText
+		};
+	}
+	/**
+	* Calculate movement penalty from leg injury severity.
+	* 
+	* **Korean**: 다리 부상 페널티 계산
+	* 
+	* Progressive penalty scaling:
+	* - 100-70%: No penalty (0%)
+	* - 70-30%: Linear scaling (0-40%)
+	* - 30-10%: Accelerated scaling (40-80%)
+	* - 10-0%: Critical scaling (80-100%)
+	* 
+	* @param legHealth - Leg health (0-100)
+	* @returns Penalty factor (0.0-1.0), clamped to valid range
+	* 
+	* @private
+	*/
+	calculateLegPenalty(legHealth) {
+		const { normal, limping, critical } = this.config.legThresholds;
+		const clampedHealth = Math.min(Math.max(legHealth, 0), 100);
+		let penalty;
+		if (clampedHealth >= normal) penalty = 0;
+		else if (clampedHealth >= limping) {
+			const healthRange = normal - limping;
+			penalty = (healthRange > 0 ? (normal - clampedHealth) / healthRange : 0) * .4;
+		} else if (clampedHealth >= critical) {
+			const healthRange = limping - critical;
+			penalty = .4 + (healthRange > 0 ? (limping - clampedHealth) / healthRange : 0) * .4;
+		} else penalty = .8 + (critical > 0 ? (critical - clampedHealth) / critical : 1) * .2;
+		return Math.min(Math.max(penalty, 0), 1);
+	}
+	/**
+	* Checks if both legs are significantly injured (>30% penalty each).
+	* Uses epsilon-based comparison for floating-point robustness.
+	* 
+	* @param leftLegPenalty - Penalty for left leg (0-1)
+	* @param rightLegPenalty - Penalty for right leg (0-1)
+	* @returns True if both legs are significantly injured
+	* @private
+	*/
+	areBothLegsInjured(leftLegPenalty, rightLegPenalty) {
+		return leftLegPenalty >= InjuryMovementModifier.BOTH_LEGS_THRESHOLD && rightLegPenalty >= InjuryMovementModifier.BOTH_LEGS_THRESHOLD;
+	}
+	/**
+	* Get stance-based speed modifier.
+	* 
+	* **Korean**: 자세 속도 배수 가져오기
+	* 
+	* @param stance - Current trigram stance
+	* @returns Speed multiplier (0.8-1.25), defaults to 1.0 for unknown stances
+	* 
+	* @public
+	*/
+	getStanceSpeedModifier(stance) {
+		const modifier = STANCE_SPEED_MODIFIERS[stance];
+		if (modifier == null) {
+			if (typeof process !== "undefined" && process.env.NODE_ENV === "development") console.warn(`[InjuryMovementModifier] Unknown stance "${String(stance)}" received in getStanceSpeedModifier; defaulting to 1.0.`);
+			return 1;
+		}
+		return modifier;
+	}
+	/**
+	* Generate bilingual status text based on injury state.
+	* 
+	* **Korean**: 상태 텍스트 생성
+	* 
+	* @param legHealthForStatus - Leg health percentage used for status determination (typically worst leg)
+	* @param bothLegsInjured - Whether both legs are significantly injured
+	* @param painOverload - Whether pain is over threshold
+	* @returns Bilingual status text
+	* 
+	* @private
+	*/
+	generateStatusText(legHealthForStatus, bothLegsInjured, painOverload) {
+		const { normal, limping, critical } = this.config.legThresholds;
+		if (legHealthForStatus < critical) {
+			const painText = painOverload ? " | 고통 과부하" : "";
+			const painTextEn = painOverload ? " | Pain Overload" : "";
+			const baseKorean = bothLegsInjured ? "심각한 부상 | 양 다리" : "심각한 부상";
+			const baseEnglish = bothLegsInjured ? "Critical Injury | Both Legs" : "Critical Injury";
+			return {
+				korean: `${baseKorean}${painText}`,
+				english: `${baseEnglish}${painTextEn}`
+			};
+		} else if (legHealthForStatus < limping) {
+			const painText = painOverload ? " | 고통 과부하" : "";
+			const painTextEn = painOverload ? " | Pain Overload" : "";
+			const baseKorean = bothLegsInjured ? "중증 절름거림 | 양 다리" : "중증 절름거림";
+			const baseEnglish = bothLegsInjured ? "Severe Limping | Both Legs" : "Severe Limping";
+			return {
+				korean: `${baseKorean}${painText}`,
+				english: `${baseEnglish}${painTextEn}`
+			};
+		} else if (legHealthForStatus < normal) {
+			const statusKrParts = ["절름거림"];
+			const statusEnParts = ["Limping"];
+			if (bothLegsInjured) {
+				statusKrParts.push("양 다리");
+				statusEnParts.push("Both Legs");
+			}
+			if (painOverload) {
+				statusKrParts.push("고통 과부하");
+				statusEnParts.push("Pain Overload");
+			}
+			return {
+				korean: statusKrParts.join(" | "),
+				english: statusEnParts.join(" | ")
+			};
+		} else if (painOverload) return {
+			korean: "고통 과부하",
+			english: "Pain Overload"
+		};
+		else return {
+			korean: "정상",
+			english: "Normal"
+		};
+	}
+	/**
+	* Check if player should display limping animation.
+	* 
+	* **Korean**: 절름거림 확인
+	* 
+	* Uses worst leg health to match movement penalty behavior.
+	* 
+	* @param bodyPartHealth - Current body part health
+	* @returns True if limping animation should play
+	* 
+	* @public
+	*/
+	shouldLimp(bodyPartHealth) {
+		return Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight) < this.config.legThresholds.normal;
+	}
+	/**
+	* Check if player has severe limp.
+	* 
+	* **Korean**: 중증 절름거림 확인
+	* 
+	* Uses worst leg health to match movement penalty behavior.
+	* 
+	* @param bodyPartHealth - Current body part health
+	* @returns True if severe limp (leg health < 30%)
+	* 
+	* @public
+	*/
+	hasSevereLimp(bodyPartHealth) {
+		return Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight) < this.config.legThresholds.limping;
+	}
+	/**
+	* Get current injury state description.
+	* 
+	* **Korean**: 부상 상태 설명
+	* 
+	* Uses worst leg health to match movement penalty behavior.
+	* 
+	* @param bodyPartHealth - Current body part health
+	* @returns Bilingual injury description
+	* 
+	* @public
+	*/
+	getInjuryDescription(bodyPartHealth) {
+		const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);
+		const leftLegPenalty = this.calculateLegPenalty(bodyPartHealth.legLeft);
+		const rightLegPenalty = this.calculateLegPenalty(bodyPartHealth.legRight);
+		const bothLegsInjured = this.areBothLegsInjured(leftLegPenalty, rightLegPenalty);
+		return this.generateStatusText(worstLegHealth, bothLegsInjured, false);
+	}
+}();
+//#endregion
+export { injuryMovementModifier };
+
+//# sourceMappingURL=InjuryMovementModifier.js.map

package/lib/systems/movement/InjuryMovementModifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InjuryMovementModifier.js","names":[],"sources":["../../../src/systems/movement/InjuryMovementModifier.ts"],"sourcesContent":["/**\n * Injury-Based Movement Modifier System\n * \n * **Korean**: 손상 기반 이동 시스템 (Injury-Based Movement System)\n * \n * Dynamically calculates movement speed modifiers based on leg injuries, torso\n * damage, stance configuration, and pain levels. Part of the 12 combat realism\n * systems for authentic Korean martial arts gameplay.\n * \n * ## Movement Speed Calculation\n * \n * Base speed is modified by multiple factors:\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 * - **Stance Modifiers**: -20% (defensive) to +25% (offensive)\n * - **Pain Overload**: -15% when pain ≥ 80\n * \n * ## Injury Severity Thresholds\n * \n * | Leg Health | State | Speed Penalty |\n * |-----------|-------|---------------|\n * | 70-100% | Normal | 0% |\n * | 30-69% | Limping | 0-40% |\n * | 10-29% | Severe Limp | 40-80% |\n * | 0-9% | Critical | 80-100% |\n * \n * @module systems/movement/InjuryMovementModifier\n * @category Movement System\n * @korean 손상기반이동\n */\n\nimport type { TrigramStance } from \"@/types/common\";\nimport type { BodyPartHealth } from \"../bodypart/types\";\nimport { STANCE_SPEED_MODIFIERS } from \"../physics/MovementPhysics\";\n\n/**\n * Configuration for injury-based movement calculations.\n * \n * **Korean**: 손상 이동 설정\n * \n * @public\n * @category Movement System\n */\nexport interface InjuryMovementConfig {\n  /** Leg health thresholds for injury states */\n  readonly legThresholds: {\n    readonly normal: number;       // 70% - no penalty\n    readonly limping: number;      // 30% - start of severe penalty\n    readonly critical: number;     // 10% - near-maximum penalty\n  };\n  /** Maximum torso injury penalty (0.3 = 30%) */\n  readonly maxTorsoPenalty: number;\n  /** Both legs injured cumulative penalty multiplier (0.8 = -20%) */\n  readonly bothLegsInjuredMultiplier: number;\n  /** Pain overload threshold (80) */\n  readonly painOverloadThreshold: number;\n  /** Pain overload penalty multiplier (0.85 = -15%) */\n  readonly painOverloadMultiplier: number;\n  /** Minimum speed multiplier (0.1 = 10% of base speed) */\n  readonly minSpeedMultiplier: number;\n}\n\n/**\n * Deep partial type for InjuryMovementConfig to support partial overrides.\n * Allows callers to override individual threshold values without providing all.\n * \n * @public\n * @category Movement System\n */\nexport type PartialInjuryMovementConfig = {\n  readonly legThresholds?: Partial<InjuryMovementConfig[\"legThresholds\"]>;\n  readonly maxTorsoPenalty?: number;\n  readonly bothLegsInjuredMultiplier?: number;\n  readonly painOverloadThreshold?: number;\n  readonly painOverloadMultiplier?: number;\n  readonly minSpeedMultiplier?: number;\n};\n\n/**\n * Default configuration matching acceptance criteria.\n */\nexport const DEFAULT_INJURY_MOVEMENT_CONFIG: InjuryMovementConfig = {\n  legThresholds: {\n    normal: 70,\n    limping: 30,\n    critical: 10,\n  },\n  maxTorsoPenalty: 0.3,\n  bothLegsInjuredMultiplier: 0.8,\n  painOverloadThreshold: 80,\n  painOverloadMultiplier: 0.85,\n  minSpeedMultiplier: 0.1,\n} as const;\n\n/**\n * Result of injury-based movement calculation.\n * \n * **Korean**: 손상 이동 결과\n * \n * @public\n * @category Movement System\n */\nexport interface InjuryMovementResult {\n  /** Final speed in units/second */\n  readonly finalSpeed: number;\n  /** Combined speed multiplier (0.1-1.0+) */\n  readonly speedMultiplier: number;\n  /** Breakdown of penalty sources */\n  readonly penalties: {\n    readonly leftLegPenalty: number;\n    readonly rightLegPenalty: number;\n    readonly torsoPenalty: number;\n    readonly bothLegsInjured: boolean;\n    readonly stanceModifier: number;\n    readonly painOverload: boolean;\n  };\n  /** Whether player is limping */\n  readonly isLimping: boolean;\n  /** Whether player has severe limp */\n  readonly isSevereLimp: boolean;\n  /** Bilingual status text */\n  readonly statusText: {\n    readonly korean: string;\n    readonly english: string;\n  };\n}\n\n/**\n * Injury-Based Movement Modifier System.\n * \n * **Korean**: 손상 기반 이동 수정자 시스템\n * \n * Calculates dynamic movement speed based on injuries, stance, and pain.\n * Integrates with MovementPhysics to apply realistic combat trauma effects.\n * \n * @example\n * ```typescript\n * const modifier = new InjuryMovementModifier();\n * \n * const result = modifier.calculateMovementSpeed(\n *   5.0,                    // base speed\n *   bodyPartHealth,         // current health\n *   TrigramStance.GEON,     // current stance\n *   65                      // pain level\n * );\n * \n * console.log(`Speed: ${result.finalSpeed} m/s`);\n * console.log(`Status: ${result.statusText.korean} | ${result.statusText.english}`);\n * ```\n * \n * @public\n * @category Movement System\n * @korean 손상기반이동수정자\n */\nexport class InjuryMovementModifier {\n  private readonly config: InjuryMovementConfig;\n\n  /**\n   * Threshold for determining if both legs are significantly injured.\n   * Uses epsilon to avoid floating-point rounding issues at boundary.\n   * \n   * @private\n   */\n  private static readonly BOTH_LEGS_THRESHOLD = 0.3 + 1e-10;\n\n  /**\n   * Creates a new InjuryMovementModifier with optional configuration.\n   * \n   * @param config - Optional configuration overrides (supports partial threshold overrides)\n   */\n  constructor(config?: PartialInjuryMovementConfig) {\n    // Deep merge leg thresholds to prevent partial overrides from breaking the config.\n    // Use ?? to avoid undefined values overwriting defaults when exactOptionalPropertyTypes is disabled.\n    const mergedLegThresholds = {\n      normal:\n        config?.legThresholds?.normal ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.normal,\n      limping:\n        config?.legThresholds?.limping ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.limping,\n      critical:\n        config?.legThresholds?.critical ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.legThresholds.critical,\n    };\n\n    const mergedConfig: InjuryMovementConfig = {\n      legThresholds: mergedLegThresholds,\n      maxTorsoPenalty:\n        config?.maxTorsoPenalty ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.maxTorsoPenalty,\n      bothLegsInjuredMultiplier:\n        config?.bothLegsInjuredMultiplier ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.bothLegsInjuredMultiplier,\n      painOverloadThreshold:\n        config?.painOverloadThreshold ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.painOverloadThreshold,\n      painOverloadMultiplier:\n        config?.painOverloadMultiplier ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.painOverloadMultiplier,\n      minSpeedMultiplier:\n        config?.minSpeedMultiplier ??\n        DEFAULT_INJURY_MOVEMENT_CONFIG.minSpeedMultiplier,\n    };\n\n    // Development-mode sanity check: ensure thresholds are finite and ordered\n    if (process.env.NODE_ENV !== \"production\") {\n      const { normal, limping, critical } = mergedConfig.legThresholds;\n      const allFinite =\n        Number.isFinite(normal) &&\n        Number.isFinite(limping) &&\n        Number.isFinite(critical);\n      const ordered = normal >= limping && limping >= critical;\n\n      if (!allFinite || !ordered) {\n        // Non-throwing warning to avoid breaking existing behavior\n        console.warn(\n          \"[InjuryMovementModifier] Invalid legThresholds configuration detected:\",\n          mergedConfig.legThresholds\n        );\n      }\n    }\n\n    this.config = mergedConfig;\n  }\n\n  /**\n   * Calculate modified movement speed based on all injury factors.\n   * \n   * **Korean**: 이동 속도 계산\n   * \n   * Applies penalties from:\n   * 1. Leg injuries (primary factor)\n   * 2. Torso injuries (minor factor)\n   * 3. Both legs injured (cumulative penalty)\n   * 4. Stance modifiers\n   * 5. Pain overload\n   * \n   * @param baseSpeed - Base movement speed (m/s)\n   * @param bodyPartHealth - Current body part health values\n   * @param stance - Current trigram stance\n   * @param painLevel - Current pain level (0-100)\n   * @returns Complete movement calculation result\n   * \n   * @public\n   * @korean 이동속도계산\n   */\n  public calculateMovementSpeed(\n    baseSpeed: number,\n    bodyPartHealth: BodyPartHealth,\n    stance: TrigramStance,\n    painLevel: number\n  ): InjuryMovementResult {\n    // Calculate individual leg penalties\n    const leftLegPenalty = this.calculateLegPenalty(bodyPartHealth.legLeft);\n    const rightLegPenalty = this.calculateLegPenalty(bodyPartHealth.legRight);\n\n    // Use worst leg penalty as base\n    const baseLegPenalty = Math.max(leftLegPenalty, rightLegPenalty);\n    let speedMultiplier = 1.0 - baseLegPenalty;\n\n    // Check if both legs are significantly injured using centralized method\n    const bothLegsInjured = this.areBothLegsInjured(leftLegPenalty, rightLegPenalty);\n    if (bothLegsInjured) {\n      // Additional 20% penalty when both legs injured\n      speedMultiplier *= this.config.bothLegsInjuredMultiplier;\n    }\n\n    // Calculate torso penalty (minor effect, 0-30% max)\n    const avgTorsoHealth = (bodyPartHealth.torsoUpper + bodyPartHealth.torsoLower) / 2;\n    // Clamp torso health to prevent negative penalties or exceeding max penalty\n    const clampedAvgTorsoHealth = Math.min(100, Math.max(0, avgTorsoHealth));\n    const torsoPenalty = ((100 - clampedAvgTorsoHealth) / 100) * this.config.maxTorsoPenalty;\n    speedMultiplier *= (1 - torsoPenalty);\n\n    // Apply stance modifier\n    const stanceModifier = this.getStanceSpeedModifier(stance);\n    speedMultiplier *= stanceModifier;\n\n    // Apply pain overload penalty if applicable (>= threshold, not just >)\n    const painOverload = painLevel >= this.config.painOverloadThreshold;\n    if (painOverload) {\n      speedMultiplier *= this.config.painOverloadMultiplier; // -15%\n    }\n\n    // Clamp to minimum speed (10% of base)\n    speedMultiplier = Math.max(speedMultiplier, this.config.minSpeedMultiplier);\n\n    // Calculate final speed\n    const finalSpeed = baseSpeed * speedMultiplier;\n\n    // Determine injury state for status text based on worst leg health\n    // This ensures status matches the actual movement penalty (which uses worst leg)\n    // Note: isLimping = true when leg health is in range [30-70) (limping range with 0-40% penalty)\n    //       isSevereLimp = true when leg health is < 30 (severe/critical with 40-100% penalty)\n    const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);\n    const isLimping =\n      worstLegHealth < this.config.legThresholds.normal &&\n      worstLegHealth >= this.config.legThresholds.limping;\n    const isSevereLimp = worstLegHealth < this.config.legThresholds.limping;\n\n    // Generate status text\n    const statusText = this.generateStatusText(worstLegHealth, bothLegsInjured, painOverload);\n\n    return {\n      finalSpeed,\n      speedMultiplier,\n      penalties: {\n        leftLegPenalty,\n        rightLegPenalty,\n        torsoPenalty,\n        bothLegsInjured,\n        stanceModifier,\n        painOverload,\n      },\n      isLimping,\n      isSevereLimp,\n      statusText,\n    };\n  }\n\n  /**\n   * Calculate movement penalty from leg injury severity.\n   * \n   * **Korean**: 다리 부상 페널티 계산\n   * \n   * Progressive penalty scaling:\n   * - 100-70%: No penalty (0%)\n   * - 70-30%: Linear scaling (0-40%)\n   * - 30-10%: Accelerated scaling (40-80%)\n   * - 10-0%: Critical scaling (80-100%)\n   * \n   * @param legHealth - Leg health (0-100)\n   * @returns Penalty factor (0.0-1.0), clamped to valid range\n   * \n   * @private\n   */\n  private calculateLegPenalty(legHealth: number): number {\n    const { normal, limping, critical } = this.config.legThresholds;\n\n    // Clamp input health to valid range to prevent runaway penalties\n    const clampedHealth = Math.min(Math.max(legHealth, 0), 100);\n\n    let penalty: number;\n\n    if (clampedHealth >= normal) {\n      // 70-100%: No penalty\n      penalty = 0;\n    } else if (clampedHealth >= limping) {\n      // 30-70%: 0-40% penalty (linear)\n      const healthRange = normal - limping;\n      // Guard against division by zero if thresholds are misconfigured\n      const healthFactor = healthRange > 0 \n        ? (normal - clampedHealth) / healthRange \n        : 0;\n      penalty = healthFactor * 0.4;\n    } else if (clampedHealth >= critical) {\n      // 10-30%: 40-80% penalty (accelerated)\n      const healthRange = limping - critical;\n      // Guard against division by zero if thresholds are misconfigured\n      const healthFactor = healthRange > 0 \n        ? (limping - clampedHealth) / healthRange \n        : 0;\n      penalty = 0.4 + (healthFactor * 0.4);\n    } else {\n      // 0-10%: 80-100% penalty (critical)\n      // Guard against division by zero if critical is 0\n      const healthFactor = critical > 0 \n        ? (critical - clampedHealth) / critical \n        : 1;\n      penalty = 0.8 + (healthFactor * 0.2);\n    }\n\n    // Ensure returned penalty is always within [0, 1]\n    return Math.min(Math.max(penalty, 0), 1);\n  }\n\n  /**\n   * Checks if both legs are significantly injured (>30% penalty each).\n   * Uses epsilon-based comparison for floating-point robustness.\n   * \n   * @param leftLegPenalty - Penalty for left leg (0-1)\n   * @param rightLegPenalty - Penalty for right leg (0-1)\n   * @returns True if both legs are significantly injured\n   * @private\n   */\n  private areBothLegsInjured(leftLegPenalty: number, rightLegPenalty: number): boolean {\n    return leftLegPenalty >= InjuryMovementModifier.BOTH_LEGS_THRESHOLD && \n           rightLegPenalty >= InjuryMovementModifier.BOTH_LEGS_THRESHOLD;\n  }\n\n  /**\n   * Get stance-based speed modifier.\n   * \n   * **Korean**: 자세 속도 배수 가져오기\n   * \n   * @param stance - Current trigram stance\n   * @returns Speed multiplier (0.8-1.25), defaults to 1.0 for unknown stances\n   * \n   * @public\n   */\n  public getStanceSpeedModifier(stance: TrigramStance): number {\n    const modifier = STANCE_SPEED_MODIFIERS[stance];\n\n    // Defensive fallback for unknown stances (e.g., test/invalid values)\n    if (modifier == null) {\n      // Runtime-safe environment check (works in both Node and browser/Vite environments)\n      if (\n        typeof process !== \"undefined\" &&\n        process.env?.NODE_ENV === \"development\"\n      ) {\n        console.warn(\n          `[InjuryMovementModifier] Unknown stance \"${String(\n            stance\n          )}\" received in getStanceSpeedModifier; defaulting to 1.0.`\n        );\n      }\n      return 1.0;\n    }\n\n    return modifier;\n  }\n\n  /**\n   * Generate bilingual status text based on injury state.\n   * \n   * **Korean**: 상태 텍스트 생성\n   * \n   * @param legHealthForStatus - Leg health percentage used for status determination (typically worst leg)\n   * @param bothLegsInjured - Whether both legs are significantly injured\n   * @param painOverload - Whether pain is over threshold\n   * @returns Bilingual status text\n   * \n   * @private\n   */\n  private generateStatusText(\n    legHealthForStatus: number,\n    bothLegsInjured: boolean,\n    painOverload: boolean\n  ): { korean: string; english: string } {\n    const { normal, limping, critical } = this.config.legThresholds;\n\n    if (legHealthForStatus < critical) {\n      const painText = painOverload ? \" | 고통 과부하\" : \"\";\n      const painTextEn = painOverload ? \" | Pain Overload\" : \"\";\n      const baseKorean = bothLegsInjured ? \"심각한 부상 | 양 다리\" : \"심각한 부상\";\n      const baseEnglish = bothLegsInjured ? \"Critical Injury | Both Legs\" : \"Critical Injury\";\n      return {\n        korean: `${baseKorean}${painText}`,\n        english: `${baseEnglish}${painTextEn}`,\n      };\n    } else if (legHealthForStatus < limping) {\n      const painText = painOverload ? \" | 고통 과부하\" : \"\";\n      const painTextEn = painOverload ? \" | Pain Overload\" : \"\";\n      const baseKorean = bothLegsInjured ? \"중증 절름거림 | 양 다리\" : \"중증 절름거림\";\n      const baseEnglish = bothLegsInjured ? \"Severe Limping | Both Legs\" : \"Severe Limping\";\n      return {\n        korean: `${baseKorean}${painText}`,\n        english: `${baseEnglish}${painTextEn}`,\n      };\n    } else if (legHealthForStatus < normal) {\n      const statusKrParts = [\"절름거림\"];\n      const statusEnParts = [\"Limping\"];\n\n      if (bothLegsInjured) {\n        statusKrParts.push(\"양 다리\");\n        statusEnParts.push(\"Both Legs\");\n      }\n\n      if (painOverload) {\n        statusKrParts.push(\"고통 과부하\");\n        statusEnParts.push(\"Pain Overload\");\n      }\n\n      return {\n        korean: statusKrParts.join(\" | \"),\n        english: statusEnParts.join(\" | \"),\n      };\n    } else if (painOverload) {\n      return {\n        korean: \"고통 과부하\",\n        english: \"Pain Overload\",\n      };\n    } else {\n      return {\n        korean: \"정상\",\n        english: \"Normal\",\n      };\n    }\n  }\n\n  /**\n   * Check if player should display limping animation.\n   * \n   * **Korean**: 절름거림 확인\n   * \n   * Uses worst leg health to match movement penalty behavior.\n   * \n   * @param bodyPartHealth - Current body part health\n   * @returns True if limping animation should play\n   * \n   * @public\n   */\n  public shouldLimp(bodyPartHealth: BodyPartHealth): boolean {\n    const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);\n    return worstLegHealth < this.config.legThresholds.normal;\n  }\n\n  /**\n   * Check if player has severe limp.\n   * \n   * **Korean**: 중증 절름거림 확인\n   * \n   * Uses worst leg health to match movement penalty behavior.\n   * \n   * @param bodyPartHealth - Current body part health\n   * @returns True if severe limp (leg health < 30%)\n   * \n   * @public\n   */\n  public hasSevereLimp(bodyPartHealth: BodyPartHealth): boolean {\n    const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);\n    return worstLegHealth < this.config.legThresholds.limping;\n  }\n\n  /**\n   * Get current injury state description.\n   * \n   * **Korean**: 부상 상태 설명\n   * \n   * Uses worst leg health to match movement penalty behavior.\n   * \n   * @param bodyPartHealth - Current body part health\n   * @returns Bilingual injury description\n   * \n   * @public\n   */\n  public getInjuryDescription(bodyPartHealth: BodyPartHealth): {\n    korean: string;\n    english: string;\n  } {\n    const worstLegHealth = Math.min(bodyPartHealth.legLeft, bodyPartHealth.legRight);\n    const leftLegPenalty = this.calculateLegPenalty(bodyPartHealth.legLeft);\n    const rightLegPenalty = this.calculateLegPenalty(bodyPartHealth.legRight);\n    const bothLegsInjured = this.areBothLegsInjured(leftLegPenalty, rightLegPenalty);\n\n    return this.generateStatusText(worstLegHealth, bothLegsInjured, false);\n  }\n}\n\n/**\n * Singleton instance for global access.\n * \n * @public\n */\nexport const injuryMovementModifier = new InjuryMovementModifier();\n"],"mappings":"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"}

package/lib/systems/movement/helpers/AccelerationUpdater.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AccelerationUpdater - Component that updates movement acceleration at 60fps
+ *
+ * Uses useFrame to track continuous movement time and calculate acceleration-based speed.
+ * Throttles state updates to only call onSpeedUpdate when speed changes meaningfully.
+ * This component only updates movement state and renders no visual elements.
+ *
+ * @module systems/movement/helpers/AccelerationUpdater
+ * @category Movement
+ * @korean 가속업데이터
+ */
+import React from "react";
+/**
+ * Props for AccelerationUpdater component
+ */
+export interface AccelerationUpdaterProps {
+    /** Whether player is currently moving */
+    readonly isMoving: boolean;
+    /** Current velocity vector */
+    readonly velocity: {
+        x: number;
+        y: number;
+    } | undefined;
+    /** Ref to track accumulated movement time */
+    readonly movementTimeRef: React.MutableRefObject<number>;
+    /** Ref to track last movement direction */
+    readonly lastDirectionRef: React.MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    /** Callback to update calculated speed - only called on meaningful changes */
+    readonly onSpeedUpdate: (speed: number) => void;
+    /** Walking speed in m/s (from archetype or default) */
+    readonly walkSpeed?: number;
+    /** Running speed in m/s (from archetype or default) */
+    readonly runSpeed?: number;
+}
+/**
+ * AccelerationUpdater Component
+ *
+ * Updates movement acceleration at 60fps using Three.js useFrame hook.
+ * Tracks continuous movement time and calculates speed based on direction consistency.
+ * Only calls onSpeedUpdate when speed changes by more than epsilon AND sufficient time
+ * has passed (100ms throttle), preventing excessive React re-renders at frame rate.
+ *
+ * @example
+ * ```tsx
+ * <AccelerationUpdater
+ *   isMoving={isMoving}
+ *   velocity={velocity}
+ *   movementTimeRef={movementTimeRef}
+ *   lastDirectionRef={lastDirectionRef}
+ *   onSpeedUpdate={setAccelerationBasedSpeed}
+ *   walkSpeed={physicalAttributes.walkSpeed}
+ *   runSpeed={physicalAttributes.runSpeed}
+ * />
+ * ```
+ */
+export declare const AccelerationUpdater: React.FC<AccelerationUpdaterProps>;
+export default AccelerationUpdater;
+//# sourceMappingURL=AccelerationUpdater.d.ts.map

package/lib/systems/movement/helpers/AccelerationUpdater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccelerationUpdater.d.ts","sourceRoot":"","sources":["../../../../src/systems/movement/helpers/AccelerationUpdater.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAiB,MAAM,OAAO,CAAC;AAQtC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACxD,6CAA6C;IAC7C,QAAQ,CAAC,eAAe,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzD,2CAA2C;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5E,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,uDAAuD;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CAiElE,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/lib/systems/movement/helpers/AccelerationUpdater.js

@@ -0,0 +1,75 @@
+import { ACCELERATION_CONSTANTS, calculateAcceleratedSpeed, isDirectionConsistent, isSpeedChangeMeaningful } from "./accelerationUtils.js";
+import { useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+//#region src/systems/movement/helpers/AccelerationUpdater.tsx
+/**
+* AccelerationUpdater - Component that updates movement acceleration at 60fps
+*
+* Uses useFrame to track continuous movement time and calculate acceleration-based speed.
+* Throttles state updates to only call onSpeedUpdate when speed changes meaningfully.
+* This component only updates movement state and renders no visual elements.
+*
+* @module systems/movement/helpers/AccelerationUpdater
+* @category Movement
+* @korean 가속업데이터
+*/
+/**
+* AccelerationUpdater Component
+*
+* Updates movement acceleration at 60fps using Three.js useFrame hook.
+* Tracks continuous movement time and calculates speed based on direction consistency.
+* Only calls onSpeedUpdate when speed changes by more than epsilon AND sufficient time
+* has passed (100ms throttle), preventing excessive React re-renders at frame rate.
+*
+* @example
+* ```tsx
+* <AccelerationUpdater
+*   isMoving={isMoving}
+*   velocity={velocity}
+*   movementTimeRef={movementTimeRef}
+*   lastDirectionRef={lastDirectionRef}
+*   onSpeedUpdate={setAccelerationBasedSpeed}
+*   walkSpeed={physicalAttributes.walkSpeed}
+*   runSpeed={physicalAttributes.runSpeed}
+* />
+* ```
+*/
+var AccelerationUpdater = ({ isMoving, velocity, movementTimeRef, lastDirectionRef, onSpeedUpdate, walkSpeed = ACCELERATION_CONSTANTS.DEFAULT_WALK_SPEED, runSpeed = ACCELERATION_CONSTANTS.DEFAULT_RUN_SPEED }) => {
+	const lastReportedSpeedRef = useRef(walkSpeed);
+	const lastUpdateTimeRef = useRef(0);
+	const UPDATE_THROTTLE_MS = 100;
+	useFrame((_state, delta) => {
+		if (!isMoving || !velocity || velocity.x === 0 && velocity.y === 0) {
+			movementTimeRef.current = 0;
+			lastDirectionRef.current = {
+				x: 0,
+				y: 0
+			};
+			if (isSpeedChangeMeaningful(lastReportedSpeedRef.current, walkSpeed)) {
+				lastReportedSpeedRef.current = walkSpeed;
+				onSpeedUpdate(walkSpeed);
+				lastUpdateTimeRef.current = performance.now();
+			}
+			return;
+		}
+		const currentDir = {
+			x: velocity.x,
+			y: velocity.y
+		};
+		if (!isDirectionConsistent(currentDir, lastDirectionRef.current)) movementTimeRef.current = 0;
+		else movementTimeRef.current += delta;
+		lastDirectionRef.current = currentDir;
+		const newSpeed = calculateAcceleratedSpeed(movementTimeRef.current, walkSpeed, runSpeed);
+		const now = performance.now();
+		if (now - lastUpdateTimeRef.current >= UPDATE_THROTTLE_MS && isSpeedChangeMeaningful(lastReportedSpeedRef.current, newSpeed)) {
+			lastReportedSpeedRef.current = newSpeed;
+			onSpeedUpdate(newSpeed);
+			lastUpdateTimeRef.current = now;
+		}
+	});
+	return null;
+};
+//#endregion
+export { AccelerationUpdater as default };
+
+//# sourceMappingURL=AccelerationUpdater.js.map

package/lib/systems/movement/helpers/AccelerationUpdater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccelerationUpdater.js","names":[],"sources":["../../../../src/systems/movement/helpers/AccelerationUpdater.tsx"],"sourcesContent":["/**\n * AccelerationUpdater - Component that updates movement acceleration at 60fps\n *\n * Uses useFrame to track continuous movement time and calculate acceleration-based speed.\n * Throttles state updates to only call onSpeedUpdate when speed changes meaningfully.\n * This component only updates movement state and renders no visual elements.\n *\n * @module systems/movement/helpers/AccelerationUpdater\n * @category Movement\n * @korean 가속업데이터\n */\n\nimport { useFrame } from \"@react-three/fiber\";\nimport React, { useRef } from \"react\";\nimport {\n  ACCELERATION_CONSTANTS,\n  calculateAcceleratedSpeed,\n  isDirectionConsistent,\n  isSpeedChangeMeaningful,\n} from \"./accelerationUtils\";\n\n/**\n * Props for AccelerationUpdater component\n */\nexport interface AccelerationUpdaterProps {\n  /** Whether player is currently moving */\n  readonly isMoving: boolean;\n  /** Current velocity vector */\n  readonly velocity: { x: number; y: number } | undefined;\n  /** Ref to track accumulated movement time */\n  readonly movementTimeRef: React.MutableRefObject<number>;\n  /** Ref to track last movement direction */\n  readonly lastDirectionRef: React.MutableRefObject<{ x: number; y: number }>;\n  /** Callback to update calculated speed - only called on meaningful changes */\n  readonly onSpeedUpdate: (speed: number) => void;\n  /** Walking speed in m/s (from archetype or default) */\n  readonly walkSpeed?: number;\n  /** Running speed in m/s (from archetype or default) */\n  readonly runSpeed?: number;\n}\n\n/**\n * AccelerationUpdater Component\n *\n * Updates movement acceleration at 60fps using Three.js useFrame hook.\n * Tracks continuous movement time and calculates speed based on direction consistency.\n * Only calls onSpeedUpdate when speed changes by more than epsilon AND sufficient time\n * has passed (100ms throttle), preventing excessive React re-renders at frame rate.\n *\n * @example\n * ```tsx\n * <AccelerationUpdater\n *   isMoving={isMoving}\n *   velocity={velocity}\n *   movementTimeRef={movementTimeRef}\n *   lastDirectionRef={lastDirectionRef}\n *   onSpeedUpdate={setAccelerationBasedSpeed}\n *   walkSpeed={physicalAttributes.walkSpeed}\n *   runSpeed={physicalAttributes.runSpeed}\n * />\n * ```\n */\nexport const AccelerationUpdater: React.FC<AccelerationUpdaterProps> = ({\n  isMoving,\n  velocity,\n  movementTimeRef,\n  lastDirectionRef,\n  onSpeedUpdate,\n  walkSpeed = ACCELERATION_CONSTANTS.DEFAULT_WALK_SPEED,\n  runSpeed = ACCELERATION_CONSTANTS.DEFAULT_RUN_SPEED,\n}) => {\n  // Track last reported speed and time to throttle updates\n  // Initialize with walk speed (archetype-specific or default)\n  const lastReportedSpeedRef = useRef<number>(walkSpeed);\n  const lastUpdateTimeRef = useRef<number>(0);\n  // Throttle interval: update at most every ~100ms (10Hz) instead of 60fps\n  const UPDATE_THROTTLE_MS = 100;\n\n  useFrame((_state, delta) => {\n    // If not moving, reset timers and direction\n    if (!isMoving || !velocity || (velocity.x === 0 && velocity.y === 0)) {\n      movementTimeRef.current = 0;\n      lastDirectionRef.current = { x: 0, y: 0 };\n      \n      // Only update if changed meaningfully\n      if (isSpeedChangeMeaningful(lastReportedSpeedRef.current, walkSpeed)) {\n        lastReportedSpeedRef.current = walkSpeed;\n        onSpeedUpdate(walkSpeed);\n        lastUpdateTimeRef.current = performance.now();\n      }\n      return;\n    }\n\n    // Check direction consistency (within 45 degrees)\n    const currentDir = { x: velocity.x, y: velocity.y };\n    const isSameDirection = isDirectionConsistent(currentDir, lastDirectionRef.current);\n\n    // Reset accumulated movement time if direction changed too much\n    if (!isSameDirection) {\n      movementTimeRef.current = 0;\n    } else {\n      // Accumulate movement time while moving in a consistent direction\n      movementTimeRef.current += delta;\n    }\n\n    // Update last direction for the next frame\n    lastDirectionRef.current = currentDir;\n\n    // Calculate new speed with archetype-specific walk/run speeds\n    const newSpeed = calculateAcceleratedSpeed(movementTimeRef.current, walkSpeed, runSpeed);\n\n    // Throttle updates by both time and epsilon\n    // Only call onSpeedUpdate if enough time has passed AND speed changed meaningfully\n    const now = performance.now();\n    const timeSinceLastUpdate = now - lastUpdateTimeRef.current;\n    \n    if (\n      timeSinceLastUpdate >= UPDATE_THROTTLE_MS &&\n      isSpeedChangeMeaningful(lastReportedSpeedRef.current, newSpeed)\n    ) {\n      lastReportedSpeedRef.current = newSpeed;\n      onSpeedUpdate(newSpeed);\n      lastUpdateTimeRef.current = now;\n    }\n  });\n\n  return null; // Component only updates movement state, renders no visual elements\n};\n\nexport default AccelerationUpdater;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,IAAa,uBAA2D,EACtE,UACA,UACA,iBACA,kBACA,eACA,YAAY,uBAAuB,oBACnC,WAAW,uBAAuB,wBAC9B;CAGJ,MAAM,uBAAuB,OAAe,UAAU;CACtD,MAAM,oBAAoB,OAAe,EAAE;CAE3C,MAAM,qBAAqB;AAE3B,WAAU,QAAQ,UAAU;AAE1B,MAAI,CAAC,YAAY,CAAC,YAAa,SAAS,MAAM,KAAK,SAAS,MAAM,GAAI;AACpE,mBAAgB,UAAU;AAC1B,oBAAiB,UAAU;IAAE,GAAG;IAAG,GAAG;IAAG;AAGzC,OAAI,wBAAwB,qBAAqB,SAAS,UAAU,EAAE;AACpE,yBAAqB,UAAU;AAC/B,kBAAc,UAAU;AACxB,sBAAkB,UAAU,YAAY,KAAK;;AAE/C;;EAIF,MAAM,aAAa;GAAE,GAAG,SAAS;GAAG,GAAG,SAAS;GAAG;AAInD,MAAI,CAHoB,sBAAsB,YAAY,iBAAiB,QAAQ,CAIjF,iBAAgB,UAAU;MAG1B,iBAAgB,WAAW;AAI7B,mBAAiB,UAAU;EAG3B,MAAM,WAAW,0BAA0B,gBAAgB,SAAS,WAAW,SAAS;EAIxF,MAAM,MAAM,YAAY,KAAK;AAG7B,MAF4B,MAAM,kBAAkB,WAG3B,sBACvB,wBAAwB,qBAAqB,SAAS,SAAS,EAC/D;AACA,wBAAqB,UAAU;AAC/B,iBAAc,SAAS;AACvB,qBAAkB,UAAU;;GAE9B;AAEF,QAAO"}

package/lib/systems/movement/helpers/accelerationUtils.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Acceleration Utilities for Movement System
+ *
+ * Pure functions for calculating acceleration-based running speeds.
+ * Extracted for testability and reusability across training and combat screens.
+ *
+ * @module systems/movement/helpers/accelerationUtils
+ * @category Movement
+ * @korean 가속 유틸리티
+ */
+/**
+ * Step distance thresholds for foot laterality alternation
+ * 발 측면성 교대를 위한 걸음 거리 임계값
+ */
+export declare const STEP_DISTANCE_THRESHOLDS: {
+    /**
+     * Average step length when walking (meters)
+     * 걷기 시 평균 걸음 길이
+     */
+    readonly WALK: 0.7;
+    /**
+     * Average step length when running (meters)
+     * 달리기 시 평균 걸음 길이
+     */
+    readonly RUN: 1;
+};
+/**
+ * Constants for acceleration-based running (defaults for non-archetype usage)
+ */
+export declare const ACCELERATION_CONSTANTS: {
+    /** Default walking speed in m/s (when no archetype speed provided) */
+    readonly DEFAULT_WALK_SPEED: 6;
+    /** Default running speed in m/s (when no archetype speed provided) */
+    readonly DEFAULT_RUN_SPEED: 10;
+    /** Time to reach running speed in seconds */
+    readonly TIME_TO_RUN: 1.5;
+    /** Threshold for considering direction "same" (cos(45°) = √2/2) */
+    readonly DIRECTION_THRESHOLD: number;
+    /** Running threshold as percentage of max speed (0-1) */
+    readonly RUN_THRESHOLD_PERCENT: 0.9;
+    /** Epsilon for speed change detection (m/s) */
+    readonly SPEED_CHANGE_EPSILON: 0.05;
+};
+/**
+ * Calculate running threshold speed
+ * @param runSpeed - Maximum running speed (from archetype or default)
+ * @returns Speed at which movement is considered running (m/s)
+ */
+export declare function calculateRunThreshold(runSpeed?: number): number;
+/**
+ * Check if two directions are consistent (within threshold angle)
+ * @param currentDir Current direction vector
+ * @param lastDir Previous direction vector
+ * @returns True if directions are within 45° of each other
+ */
+export declare function isDirectionConsistent(currentDir: {
+    x: number;
+    y: number;
+}, lastDir: {
+    x: number;
+    y: number;
+}): boolean;
+/**
+ * Calculate acceleration-based speed
+ * @param movementTime Accumulated movement time in same direction (seconds)
+ * @param walkSpeed - Walking speed in m/s (from archetype or default)
+ * @param runSpeed - Running speed in m/s (from archetype or default)
+ * @returns Interpolated speed between walk and run (m/s)
+ */
+export declare function calculateAcceleratedSpeed(movementTime: number, walkSpeed?: number, runSpeed?: number): number;
+/**
+ * Check if speed change is meaningful (exceeds epsilon)
+ * @param oldSpeed Previous speed (m/s)
+ * @param newSpeed New speed (m/s)
+ * @returns True if change exceeds threshold
+ */
+export declare function isSpeedChangeMeaningful(oldSpeed: number, newSpeed: number): boolean;
+/**
+ * Determine if player is running based on current speed
+ * @param speed Current speed (m/s)
+ * @param runSpeed - Maximum running speed (from archetype or default)
+ * @returns True if speed exceeds running threshold
+ */
+export declare function isRunningSpeed(speed: number, runSpeed?: number): boolean;
+//# sourceMappingURL=accelerationUtils.d.ts.map

package/lib/systems/movement/helpers/accelerationUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accelerationUtils.d.ts","sourceRoot":"","sources":["../../../../src/systems/movement/helpers/accelerationUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB;IACnC;;;OAGG;;IAGH;;;OAGG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,sBAAsB;IACjC,sEAAsE;;IAEtE,sEAAsE;;IAEtE,6CAA6C;;IAE7C,mEAAmE;;IAEnE,yDAAyD;;IAEzD,+CAA+C;;CAEvC,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,GAAE,MAAiD,GAC1D,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACpC,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAqBT;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAkD,EAC7D,QAAQ,GAAE,MAAiD,GAC1D,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAiD,GAC1D,OAAO,CAET"}

package/lib/systems/movement/helpers/accelerationUtils.js

@@ -0,0 +1,86 @@
+//#region src/systems/movement/helpers/accelerationUtils.ts
+/**
+* Acceleration Utilities for Movement System
+*
+* Pure functions for calculating acceleration-based running speeds.
+* Extracted for testability and reusability across training and combat screens.
+*
+* @module systems/movement/helpers/accelerationUtils
+* @category Movement
+* @korean 가속 유틸리티
+*/
+/**
+* Step distance thresholds for foot laterality alternation
+* 발 측면성 교대를 위한 걸음 거리 임계값
+*/
+var STEP_DISTANCE_THRESHOLDS = {
+	WALK: .7,
+	RUN: 1
+};
+/**
+* Constants for acceleration-based running (defaults for non-archetype usage)
+*/
+var ACCELERATION_CONSTANTS = {
+	DEFAULT_WALK_SPEED: 6,
+	DEFAULT_RUN_SPEED: 10,
+	TIME_TO_RUN: 1.5,
+	DIRECTION_THRESHOLD: Math.cos(Math.PI / 4),
+	RUN_THRESHOLD_PERCENT: .9,
+	SPEED_CHANGE_EPSILON: .05
+};
+/**
+* Calculate running threshold speed
+* @param runSpeed - Maximum running speed (from archetype or default)
+* @returns Speed at which movement is considered running (m/s)
+*/
+function calculateRunThreshold(runSpeed = ACCELERATION_CONSTANTS.DEFAULT_RUN_SPEED) {
+	return runSpeed * ACCELERATION_CONSTANTS.RUN_THRESHOLD_PERCENT;
+}
+/**
+* Check if two directions are consistent (within threshold angle)
+* @param currentDir Current direction vector
+* @param lastDir Previous direction vector
+* @returns True if directions are within 45° of each other
+*/
+function isDirectionConsistent(currentDir, lastDir) {
+	if (lastDir.x === 0 && lastDir.y === 0) return true;
+	const dot = currentDir.x * lastDir.x + currentDir.y * lastDir.y;
+	const magCurrent = Math.sqrt(currentDir.x ** 2 + currentDir.y ** 2);
+	const magLast = Math.sqrt(lastDir.x ** 2 + lastDir.y ** 2);
+	if (magCurrent === 0 || magLast === 0) return false;
+	const cosAngleRaw = dot / (magCurrent * magLast);
+	return Math.max(-1, Math.min(1, cosAngleRaw)) >= ACCELERATION_CONSTANTS.DIRECTION_THRESHOLD;
+}
+/**
+* Calculate acceleration-based speed
+* @param movementTime Accumulated movement time in same direction (seconds)
+* @param walkSpeed - Walking speed in m/s (from archetype or default)
+* @param runSpeed - Running speed in m/s (from archetype or default)
+* @returns Interpolated speed between walk and run (m/s)
+*/
+function calculateAcceleratedSpeed(movementTime, walkSpeed = ACCELERATION_CONSTANTS.DEFAULT_WALK_SPEED, runSpeed = ACCELERATION_CONSTANTS.DEFAULT_RUN_SPEED) {
+	const progress = Math.min(movementTime / ACCELERATION_CONSTANTS.TIME_TO_RUN, 1);
+	return walkSpeed + (runSpeed - walkSpeed) * progress;
+}
+/**
+* Check if speed change is meaningful (exceeds epsilon)
+* @param oldSpeed Previous speed (m/s)
+* @param newSpeed New speed (m/s)
+* @returns True if change exceeds threshold
+*/
+function isSpeedChangeMeaningful(oldSpeed, newSpeed) {
+	return Math.abs(newSpeed - oldSpeed) >= ACCELERATION_CONSTANTS.SPEED_CHANGE_EPSILON;
+}
+/**
+* Determine if player is running based on current speed
+* @param speed Current speed (m/s)
+* @param runSpeed - Maximum running speed (from archetype or default)
+* @returns True if speed exceeds running threshold
+*/
+function isRunningSpeed(speed, runSpeed = ACCELERATION_CONSTANTS.DEFAULT_RUN_SPEED) {
+	return speed >= calculateRunThreshold(runSpeed);
+}
+//#endregion
+export { ACCELERATION_CONSTANTS, STEP_DISTANCE_THRESHOLDS, calculateAcceleratedSpeed, isDirectionConsistent, isRunningSpeed, isSpeedChangeMeaningful };
+
+//# sourceMappingURL=accelerationUtils.js.map