blacktrigram 0.7.2

package/lib/utils/physicalAttributeValidation.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Physical Attributes Validation Utility
+ *
+ * **Korean**: 신체 속성 검증 유틸리티
+ *
+ * Validates physical attributes against anatomical formulas to ensure
+ * realistic body proportions for Korean adult males.
+ *
+ * ## Anatomical References
+ *
+ * Based on Korean anthropometric studies and human proportion canon:
+ * - Arm length: ~44% of height (shoulder to fingertip)
+ * - Leg length: ~48-53% of height (ground to hip)
+ * - Torso length: ~32-34% of height
+ * - Head size: ~12.5% of height (8-head proportion)
+ * - Shoulder width: ~23-27% of height for males
+ *
+ * ## Weight Composition
+ *
+ * For athletic males:
+ * - Muscle mass: 35-45% of body weight
+ * - Fat mass: 10-20% for athletes, 15-25% for average
+ * - Bone/organs: ~40-45% of weight
+ *
+ * @module utils/physicalAttributeValidation
+ * @category Validation
+ * @korean 신체속성검증
+ */
+import type { PhysicalAttributes } from "../types";
+/**
+ * Anatomical proportion ranges for Korean adult males.
+ *
+ * @korean 해부학적비율범위
+ */
+export declare const ANATOMICAL_RANGES: {
+    readonly ARM_LENGTH_RATIO: {
+        readonly min: 0.4;
+        readonly max: 0.47;
+        readonly typical: 0.43;
+    };
+    readonly LEG_LENGTH_RATIO: {
+        readonly min: 0.48;
+        readonly max: 0.56;
+        readonly typical: 0.52;
+    };
+    readonly TORSO_LENGTH_RATIO: {
+        readonly min: 0.3;
+        readonly max: 0.36;
+        readonly typical: 0.33;
+    };
+    readonly HEAD_SIZE_RATIO: {
+        readonly min: 0.11;
+        readonly max: 0.14;
+        readonly typical: 0.125;
+    };
+    readonly NECK_LENGTH_RATIO: {
+        readonly min: 0.045;
+        readonly max: 0.065;
+        readonly typical: 0.055;
+    };
+    readonly SHOULDER_WIDTH_RATIO: {
+        readonly min: 0.22;
+        readonly max: 0.3;
+        readonly typical: 0.255;
+    };
+    readonly MUSCLE_MASS_RATIO: {
+        readonly min: 0.35;
+        readonly max: 0.52;
+        readonly typical: 0.43;
+    };
+    readonly FAT_MASS_RATIO: {
+        readonly min: 0.08;
+        readonly max: 0.25;
+        readonly typical: 0.15;
+    };
+    readonly SOFT_TISSUE_RATIO: {
+        readonly min: 0.5;
+        readonly max: 0.7;
+        readonly typical: 0.58;
+    };
+    readonly BMI: {
+        readonly min: 18.5;
+        readonly max: 30;
+        readonly typical: 23.5;
+    };
+};
+/**
+ * Validation result for a single attribute.
+ */
+export interface AttributeValidation {
+    readonly attribute: string;
+    readonly value: number;
+    readonly expected: {
+        min: number;
+        max: number;
+        typical: number;
+    };
+    readonly isValid: boolean;
+    readonly deviation: number;
+    readonly suggestion?: string;
+}
+/**
+ * Complete validation result for physical attributes.
+ */
+export interface ValidationResult {
+    readonly isValid: boolean;
+    readonly validations: readonly AttributeValidation[];
+    readonly summary: string;
+}
+/**
+ * Calculate expected arm length from height.
+ *
+ * Formula: armLength = height * 0.43 (typical Korean male)
+ * Arm span is roughly equal to height; each arm is ~43% from shoulder.
+ *
+ * @param height - Total height in cm
+ * @returns Expected arm length in cm
+ * @korean 예상팔길이계산
+ */
+export declare function calculateExpectedArmLength(height: number): number;
+/**
+ * Calculate expected leg length from height.
+ *
+ * Formula: legLength = height * 0.52 (typical, can vary 0.48-0.56)
+ * Korean adults tend toward longer leg proportions.
+ *
+ * @param height - Total height in cm
+ * @returns Expected leg length in cm
+ * @korean 예상다리길이계산
+ */
+export declare function calculateExpectedLegLength(height: number): number;
+/**
+ * Calculate expected torso length from height.
+ *
+ * Formula: torsoLength = height * 0.33
+ *
+ * @param height - Total height in cm
+ * @returns Expected torso length in cm
+ * @korean 예상몸통길이계산
+ */
+export declare function calculateExpectedTorsoLength(height: number): number;
+/**
+ * Calculate expected shoulder width from height.
+ *
+ * Formula: shoulderWidth = height * 0.255 (males)
+ *
+ * @param height - Total height in cm
+ * @returns Expected shoulder width in cm
+ * @korean 예상어깨너비계산
+ */
+export declare function calculateExpectedShoulderWidth(height: number): number;
+/**
+ * Calculate expected muscle mass from weight (for athletes).
+ *
+ * Formula: muscleMass = weight * 0.43 (trained male athlete)
+ *
+ * @param weight - Body weight in kg
+ * @returns Expected muscle mass in kg
+ * @korean 예상근육량계산
+ */
+export declare function calculateExpectedMuscleMass(weight: number): number;
+/**
+ * Calculate BMI from height and weight.
+ *
+ * Formula: BMI = weight / (height in meters)²
+ *
+ * @param height - Total height in cm
+ * @param weight - Body weight in kg
+ * @returns BMI value
+ * @korean BMI계산
+ */
+export declare function calculateBMI(height: number, weight: number): number;
+/**
+ * Validate physical attributes against anatomical formulas.
+ *
+ * @param attrs - Physical attributes to validate
+ * @returns Validation result with details
+ * @korean 신체속성검증
+ */
+export declare function validatePhysicalAttributes(attrs: PhysicalAttributes): ValidationResult;
+/**
+ * Suggest corrections for physical attributes.
+ *
+ * @param attrs - Physical attributes to correct
+ * @returns Suggested corrected attributes
+ * @korean 신체속성교정제안
+ */
+export declare function suggestCorrectedAttributes(attrs: PhysicalAttributes): Partial<PhysicalAttributes>;
+/**
+ * Print validation report to console.
+ *
+ * @param name - Archetype name
+ * @param attrs - Physical attributes
+ * @korean 검증리포트출력
+ */
+export declare function printValidationReport(name: string, attrs: PhysicalAttributes): void;
+//# sourceMappingURL=physicalAttributeValidation.d.ts.map

package/lib/utils/physicalAttributeValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physicalAttributeValidation.d.ts","sourceRoot":"","sources":["../../src/utils/physicalAttributeValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBpB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnE;AAoCD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,GACxB,gBAAgB,CAwIlB;AAUD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CA+B7B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,kBAAkB,GACxB,IAAI,CA2BN"}

package/lib/utils/player3DHelpers.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Utility functions for Player3D component integration
+ *
+ * Converts PlayerState from combat system to Player3DUnifiedProps for rendering
+ * with SkeletalPlayer3D (28-bone articulated body model).
+ *
+ * @module utils/player3DHelpers
+ * @category Utilities
+ * @korean 플레이어3D도우미
+ */
+import type { PlayerState } from "../systems";
+import type { AnimationState } from "../systems/animation/core/types";
+import type { BalanceState, Player3DUnifiedProps, PlayerAnimation } from "../types/player-visual";
+/**
+ * Convert AnimationState to PlayerAnimation
+ *
+ * Maps the animation system's state types to SkeletalPlayer3D's animation types.
+ *
+ * @param animState - Animation state from the animation system
+ * @returns Corresponding PlayerAnimation type
+ * @korean 애니메이션상태변환
+ */
+export declare function animationStateToPlayerAnimation(animState: AnimationState): PlayerAnimation;
+/**
+ * Convert balance number (0-100) to BalanceState enum
+ *
+ * @param balance - Balance value from PlayerState (0-100)
+ * @returns BalanceState enum value
+ * @korean 균형상태변환
+ */
+export declare function getBalanceState(balance: number): BalanceState;
+/**
+ * Get current animation state from PlayerState
+ *
+ * Returns stance-specific idle animations when player is in idle/recovering state.
+ * This ensures each trigram stance displays the correct guard pose with proper
+ * leg positioning and breathing animation.
+ *
+ * @param player - Current player state
+ * @returns PlayerAnimation enum value (stance-specific for idle states)
+ * @korean 애니메이션상태가져오기
+ */
+export declare function getPlayerAnimation(player: PlayerState): PlayerAnimation;
+/**
+ * Converts PlayerState to Player3DUnifiedProps for visual rendering.
+ *
+ * Note: This function converts base PlayerState properties used in combat.
+ * Training-specific stats (misses, accuracy, comboCount) are optional in PlayerState
+ * and handled separately in training contexts.
+ *
+ * @param player - The player state to convert
+ * @param position - 3D position [x, y, z]
+ * @param rotation - Rotation in radians
+ * @param options - Display and behavior options
+ * @returns Props for SkeletalPlayer3D component (28-bone articulated body model)
+ * @korean 플레이어상태변환
+ *
+ * @example
+ * ```tsx
+ * const playerProps = convertPlayerStateToProps(
+ *   playerState,
+ *   [-3, 0, 0],
+ *   0,
+ *   { isMobile: false, showVitalPoints: false }
+ * );
+ *
+ * <SkeletalPlayer3D {...playerProps} />
+ * ```
+ */
+export declare function convertPlayerStateToProps(player: PlayerState, position: [number, number, number], rotation: number, options?: {
+    readonly isMobile?: boolean;
+    readonly facing?: "left" | "right";
+    readonly scale?: number;
+    readonly showDetails?: boolean;
+    readonly showHealthBar?: boolean;
+    readonly showStanceIndicator?: boolean;
+    readonly onAnimationComplete?: () => void;
+    readonly enableFacialExpressions?: boolean;
+    readonly enableEyeTracking?: boolean;
+    readonly opponentPosition?: [number, number, number];
+}): Player3DUnifiedProps;
+//# sourceMappingURL=player3DHelpers.d.ts.map

package/lib/utils/player3DHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player3DHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/player3DHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAgFhC;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,cAAc,GACxB,eAAe,CAEjB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAK7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAoBvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IAE1C,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACjD,GACL,oBAAoB,CA0CtB"}

package/lib/utils/player3DHelpers.js

@@ -0,0 +1,176 @@
+//#region src/utils/player3DHelpers.ts
+/**
+* Static mapping from AnimationState to PlayerAnimation
+*
+* Stance guard animations map to "idle" since SkeletalPlayer3D
+* will handle the stance-specific guard rendering.
+* Tactical steps now use dedicated step animations with guard maintenance.
+*
+* @korean 애니메이션상태맵
+*/
+var ANIMATION_STATE_MAP = {
+	idle: "idle",
+	walk: "walk",
+	run: "run",
+	attack: "attack",
+	defend: "defend",
+	defend_block_success: "defend",
+	defend_parry: "defend",
+	defend_guard_break: "defend",
+	defend_recovery: "defend",
+	hit: "hit",
+	stance_change: "stance_change",
+	stance_side_switch: "stance_change",
+	ko: "death",
+	stance_guard_geon: "stance_geon",
+	stance_guard_tae: "stance_tae",
+	stance_guard_li: "stance_li",
+	stance_guard_jin: "stance_jin",
+	stance_guard_son: "stance_son",
+	stance_guard_gam: "stance_gam",
+	stance_guard_gan: "stance_gan",
+	stance_guard_gon: "stance_gon",
+	step_forward: "step_forward",
+	step_back: "step_back",
+	step_left: "step_left",
+	step_right: "step_right",
+	step_forward_left: "step_forward_left",
+	step_forward_right: "step_forward_right",
+	step_back_left: "step_back_left",
+	step_back_right: "step_back_right",
+	fall_forward: "fall_forward",
+	fall_backward: "fall_backward",
+	fall_side_left: "fall_side_left",
+	fall_side_right: "fall_side_right",
+	ground_prone: "idle",
+	ground_supine: "idle",
+	ground_side_left: "idle",
+	ground_side_right: "idle",
+	turn_left: "stance_change",
+	turn_right: "stance_change",
+	footwork_circular_left: "walk",
+	footwork_circular_right: "walk",
+	footwork_pivot_left: "walk",
+	footwork_pivot_right: "walk",
+	footwork_slide_forward: "walk",
+	footwork_slide_back: "walk",
+	footwork_slide_left: "walk",
+	footwork_slide_right: "walk",
+	footwork_shuffle: "walk",
+	recovery_prone_standup: "idle",
+	recovery_supine_standup: "idle",
+	recovery_roll: "walk",
+	recovery_defensive: "defend",
+	grapple_entry: "attack",
+	grapple_control: "defend",
+	grapple_struggle: "hit",
+	grapple_escape: "attack"
+};
+/**
+* Convert AnimationState to PlayerAnimation
+*
+* Maps the animation system's state types to SkeletalPlayer3D's animation types.
+*
+* @param animState - Animation state from the animation system
+* @returns Corresponding PlayerAnimation type
+* @korean 애니메이션상태변환
+*/
+function animationStateToPlayerAnimation(animState) {
+	return ANIMATION_STATE_MAP[animState];
+}
+/**
+* Convert balance number (0-100) to BalanceState enum
+*
+* @param balance - Balance value from PlayerState (0-100)
+* @returns BalanceState enum value
+* @korean 균형상태변환
+*/
+function getBalanceState(balance) {
+	if (balance >= 80) return "READY";
+	if (balance >= 50) return "SHAKEN";
+	if (balance >= 20) return "VULNERABLE";
+	return "HELPLESS";
+}
+/**
+* Get current animation state from PlayerState
+*
+* Returns stance-specific idle animations when player is in idle/recovering state.
+* This ensures each trigram stance displays the correct guard pose with proper
+* leg positioning and breathing animation.
+*
+* @param player - Current player state
+* @returns PlayerAnimation enum value (stance-specific for idle states)
+* @korean 애니메이션상태가져오기
+*/
+function getPlayerAnimation(player) {
+	if (player.isStunned) return "hit";
+	if (player.isBlocking) return "defend";
+	if (player.isCountering) return "counter";
+	switch (player.combatState) {
+		case "attacking": return "attack";
+		case "defending": return "defend";
+		case "stunned": return "hit";
+		default: return `stance_${player.currentStance}`;
+	}
+}
+/**
+* Converts PlayerState to Player3DUnifiedProps for visual rendering.
+*
+* Note: This function converts base PlayerState properties used in combat.
+* Training-specific stats (misses, accuracy, comboCount) are optional in PlayerState
+* and handled separately in training contexts.
+*
+* @param player - The player state to convert
+* @param position - 3D position [x, y, z]
+* @param rotation - Rotation in radians
+* @param options - Display and behavior options
+* @returns Props for SkeletalPlayer3D component (28-bone articulated body model)
+* @korean 플레이어상태변환
+*
+* @example
+* ```tsx
+* const playerProps = convertPlayerStateToProps(
+*   playerState,
+*   [-3, 0, 0],
+*   0,
+*   { isMobile: false, showVitalPoints: false }
+* );
+*
+* <SkeletalPlayer3D {...playerProps} />
+* ```
+*/
+function convertPlayerStateToProps(player, position, rotation, options = {}) {
+	return {
+		playerId: player.id,
+		archetype: player.archetype,
+		stance: player.currentStance,
+		position,
+		rotation,
+		health: player.health,
+		maxHealth: player.maxHealth,
+		stamina: player.stamina,
+		ki: player.ki,
+		pain: player.pain,
+		balance: getBalanceState(player.balance),
+		consciousness: player.consciousness,
+		isBlocking: player.isBlocking,
+		isStunned: player.isStunned,
+		isCountering: player.isCountering,
+		currentAnimation: getPlayerAnimation(player),
+		name: player.name,
+		isMobile: options.isMobile ?? false,
+		facing: options.facing ?? "right",
+		scale: options.scale ?? 1,
+		showDetails: options.showDetails,
+		showHealthBar: options.showHealthBar,
+		showStanceIndicator: options.showStanceIndicator,
+		onAnimationComplete: options.onAnimationComplete,
+		enableFacialExpressions: options.enableFacialExpressions ?? false,
+		enableEyeTracking: options.enableEyeTracking ?? true,
+		opponentPosition: options.opponentPosition
+	};
+}
+//#endregion
+export { animationStateToPlayerAnimation, convertPlayerStateToProps, getBalanceState, getPlayerAnimation };
+
+//# sourceMappingURL=player3DHelpers.js.map

package/lib/utils/player3DHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player3DHelpers.js","names":[],"sources":["../../src/utils/player3DHelpers.ts"],"sourcesContent":["/**\n * Utility functions for Player3D component integration\n *\n * Converts PlayerState from combat system to Player3DUnifiedProps for rendering\n * with SkeletalPlayer3D (28-bone articulated body model).\n *\n * @module utils/player3DHelpers\n * @category Utilities\n * @korean 플레이어3D도우미\n */\n\nimport type { PlayerState } from \"../systems\";\nimport type { AnimationState } from \"../systems/animation/core/types\";\nimport type {\n  BalanceState,\n  Player3DUnifiedProps,\n  PlayerAnimation,\n} from \"../types/player-visual\";\n\n/**\n * Static mapping from AnimationState to PlayerAnimation\n *\n * Stance guard animations map to \"idle\" since SkeletalPlayer3D\n * will handle the stance-specific guard rendering.\n * Tactical steps now use dedicated step animations with guard maintenance.\n *\n * @korean 애니메이션상태맵\n */\nconst ANIMATION_STATE_MAP: Record<AnimationState, PlayerAnimation> = {\n  idle: \"idle\",\n  walk: \"walk\",\n  run: \"run\", // Now uses dedicated RUN_ANIMATION from BasicAnimations\n  attack: \"attack\",\n  defend: \"defend\",\n  // Defensive animations (방어 애니메이션) - map to defend with variations handled by skeletal system\n  defend_block_success: \"defend\",\n  defend_parry: \"defend\",\n  defend_guard_break: \"defend\",\n  defend_recovery: \"defend\",\n  hit: \"hit\",\n  stance_change: \"stance_change\",\n  stance_side_switch: \"stance_change\", // Map to stance_change animation (mirroring guard)\n  ko: \"death\", // Map ko to death\n  // Stance guard animations map to stance-specific idle animations with proper biomechanics\n  stance_guard_geon: \"stance_geon\",\n  stance_guard_tae: \"stance_tae\",\n  stance_guard_li: \"stance_li\",\n  stance_guard_jin: \"stance_jin\",\n  stance_guard_son: \"stance_son\",\n  stance_guard_gam: \"stance_gam\",\n  stance_guard_gan: \"stance_gan\",\n  stance_guard_gon: \"stance_gon\",\n  // Tactical step animations now map to dedicated step animations\n  step_forward: \"step_forward\",\n  step_back: \"step_back\",\n  step_left: \"step_left\",\n  step_right: \"step_right\",\n  step_forward_left: \"step_forward_left\",\n  step_forward_right: \"step_forward_right\",\n  step_back_left: \"step_back_left\",\n  step_back_right: \"step_back_right\",\n  // Fall animations: Now using dedicated FALL_*_ANIMATION from BasicAnimations\n  fall_forward: \"fall_forward\",\n  fall_backward: \"fall_backward\",\n  fall_side_left: \"fall_side_left\",\n  fall_side_right: \"fall_side_right\",\n  // Ground states map to idle with minimal movement\n  ground_prone: \"idle\",\n  ground_supine: \"idle\",\n  ground_side_left: \"idle\",\n  ground_side_right: \"idle\",\n  // 180-degree turn animations map to stance_change (body pivot animation)\n  turn_left: \"stance_change\",\n  turn_right: \"stance_change\",\n  // Footwork patterns (보법) - Korean martial arts specialized footwork\n  footwork_circular_left: \"walk\", // Lateral movement\n  footwork_circular_right: \"walk\",\n  footwork_pivot_left: \"walk\", // Rotation movement\n  footwork_pivot_right: \"walk\",\n  footwork_slide_forward: \"walk\", // Sliding movement\n  footwork_slide_back: \"walk\",\n  footwork_slide_left: \"walk\",\n  footwork_slide_right: \"walk\",\n  footwork_shuffle: \"walk\", // Quick adjustment\n  // Recovery animations (기상 애니메이션) - Getting up from ground states\n  // Map to idle for now, custom 3D recovery animations will be added in future\n  recovery_prone_standup: \"idle\",\n  recovery_supine_standup: \"idle\",\n  recovery_roll: \"walk\", // Rolling motion approximated by walk\n  recovery_defensive: \"defend\", // Guarded getup approximated by defend\n  // Grappling animations (잡기 애니메이션) - map to attack/defend based on action\n  grapple_entry: \"attack\", // Initiating grab uses attack animation\n  grapple_control: \"defend\", // Maintaining control uses defensive stance\n  grapple_struggle: \"hit\", // Struggling escape uses hit reaction\n  grapple_escape: \"attack\", // Successful escape uses attack burst\n};\n\n/**\n * Convert AnimationState to PlayerAnimation\n *\n * Maps the animation system's state types to SkeletalPlayer3D's animation types.\n *\n * @param animState - Animation state from the animation system\n * @returns Corresponding PlayerAnimation type\n * @korean 애니메이션상태변환\n */\nexport function animationStateToPlayerAnimation(\n  animState: AnimationState\n): PlayerAnimation {\n  return ANIMATION_STATE_MAP[animState];\n}\n\n/**\n * Convert balance number (0-100) to BalanceState enum\n *\n * @param balance - Balance value from PlayerState (0-100)\n * @returns BalanceState enum value\n * @korean 균형상태변환\n */\nexport function getBalanceState(balance: number): BalanceState {\n  if (balance >= 80) return \"READY\";\n  if (balance >= 50) return \"SHAKEN\";\n  if (balance >= 20) return \"VULNERABLE\";\n  return \"HELPLESS\";\n}\n\n/**\n * Get current animation state from PlayerState\n *\n * Returns stance-specific idle animations when player is in idle/recovering state.\n * This ensures each trigram stance displays the correct guard pose with proper\n * leg positioning and breathing animation.\n *\n * @param player - Current player state\n * @returns PlayerAnimation enum value (stance-specific for idle states)\n * @korean 애니메이션상태가져오기\n */\nexport function getPlayerAnimation(player: PlayerState): PlayerAnimation {\n  if (player.isStunned) return \"hit\";\n  if (player.isBlocking) return \"defend\";\n  if (player.isCountering) return \"counter\";\n\n  // Check combat state (CombatState enum values are lowercase strings)\n  switch (player.combatState) {\n    case \"attacking\":\n      return \"attack\";\n    case \"defending\":\n      return \"defend\";\n    case \"stunned\":\n      return \"hit\";\n    case \"recovering\":\n    case \"idle\":\n    default:\n      // Use stance-specific idle animation for proper guard pose\n      // This ensures correct leg positioning for each trigram stance\n      return `stance_${player.currentStance}` as PlayerAnimation;\n  }\n}\n\n/**\n * Converts PlayerState to Player3DUnifiedProps for visual rendering.\n *\n * Note: This function converts base PlayerState properties used in combat.\n * Training-specific stats (misses, accuracy, comboCount) are optional in PlayerState\n * and handled separately in training contexts.\n *\n * @param player - The player state to convert\n * @param position - 3D position [x, y, z]\n * @param rotation - Rotation in radians\n * @param options - Display and behavior options\n * @returns Props for SkeletalPlayer3D component (28-bone articulated body model)\n * @korean 플레이어상태변환\n *\n * @example\n * ```tsx\n * const playerProps = convertPlayerStateToProps(\n *   playerState,\n *   [-3, 0, 0],\n *   0,\n *   { isMobile: false, showVitalPoints: false }\n * );\n *\n * <SkeletalPlayer3D {...playerProps} />\n * ```\n */\nexport function convertPlayerStateToProps(\n  player: PlayerState,\n  position: [number, number, number],\n  rotation: number,\n  options: {\n    readonly isMobile?: boolean;\n    readonly facing?: \"left\" | \"right\";\n    readonly scale?: number;\n    readonly showDetails?: boolean;\n    readonly showHealthBar?: boolean;\n    readonly showStanceIndicator?: boolean;\n    readonly onAnimationComplete?: () => void;\n    // Facial expression options - 얼굴 표정 옵션\n    readonly enableFacialExpressions?: boolean;\n    readonly enableEyeTracking?: boolean;\n    readonly opponentPosition?: [number, number, number];\n  } = {}\n): Player3DUnifiedProps {\n  return {\n    playerId: player.id,\n    archetype: player.archetype,\n    stance: player.currentStance,\n    position,\n    rotation,\n\n    // Health and resources\n    health: player.health,\n    maxHealth: player.maxHealth,\n    stamina: player.stamina,\n    ki: player.ki,\n\n    // Combat states\n    pain: player.pain,\n    balance: getBalanceState(player.balance),\n    consciousness: player.consciousness,\n\n    // Combat flags\n    isBlocking: player.isBlocking,\n    isStunned: player.isStunned,\n    isCountering: player.isCountering,\n\n    // Animation (derived from combat state)\n    currentAnimation: getPlayerAnimation(player),\n\n    // Display options\n    name: player.name,\n    isMobile: options.isMobile ?? false,\n    facing: options.facing ?? \"right\",\n    scale: options.scale ?? 1,\n    showDetails: options.showDetails,\n    showHealthBar: options.showHealthBar,\n    showStanceIndicator: options.showStanceIndicator,\n    onAnimationComplete: options.onAnimationComplete,\n\n    // Facial expression options - 얼굴 표정 옵션\n    enableFacialExpressions: options.enableFacialExpressions ?? false,\n    enableEyeTracking: options.enableEyeTracking ?? true,\n    opponentPosition: options.opponentPosition,\n  };\n}\n"],"mappings":";;;;;;;;;;AA4BA,IAAM,sBAA+D;CACnE,MAAM;CACN,MAAM;CACN,KAAK;CACL,QAAQ;CACR,QAAQ;CAER,sBAAsB;CACtB,cAAc;CACd,oBAAoB;CACpB,iBAAiB;CACjB,KAAK;CACL,eAAe;CACf,oBAAoB;CACpB,IAAI;CAEJ,mBAAmB;CACnB,kBAAkB;CAClB,iBAAiB;CACjB,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAElB,cAAc;CACd,WAAW;CACX,WAAW;CACX,YAAY;CACZ,mBAAmB;CACnB,oBAAoB;CACpB,gBAAgB;CAChB,iBAAiB;CAEjB,cAAc;CACd,eAAe;CACf,gBAAgB;CAChB,iBAAiB;CAEjB,cAAc;CACd,eAAe;CACf,kBAAkB;CAClB,mBAAmB;CAEnB,WAAW;CACX,YAAY;CAEZ,wBAAwB;CACxB,yBAAyB;CACzB,qBAAqB;CACrB,sBAAsB;CACtB,wBAAwB;CACxB,qBAAqB;CACrB,qBAAqB;CACrB,sBAAsB;CACtB,kBAAkB;CAGlB,wBAAwB;CACxB,yBAAyB;CACzB,eAAe;CACf,oBAAoB;CAEpB,eAAe;CACf,iBAAiB;CACjB,kBAAkB;CAClB,gBAAgB;CACjB;;;;;;;;;;AAWD,SAAgB,gCACd,WACiB;AACjB,QAAO,oBAAoB;;;;;;;;;AAU7B,SAAgB,gBAAgB,SAA+B;AAC7D,KAAI,WAAW,GAAI,QAAO;AAC1B,KAAI,WAAW,GAAI,QAAO;AAC1B,KAAI,WAAW,GAAI,QAAO;AAC1B,QAAO;;;;;;;;;;;;;AAcT,SAAgB,mBAAmB,QAAsC;AACvE,KAAI,OAAO,UAAW,QAAO;AAC7B,KAAI,OAAO,WAAY,QAAO;AAC9B,KAAI,OAAO,aAAc,QAAO;AAGhC,SAAQ,OAAO,aAAf;EACE,KAAK,YACH,QAAO;EACT,KAAK,YACH,QAAO;EACT,KAAK,UACH,QAAO;EAGT,QAGE,QAAO,UAAU,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8B9B,SAAgB,0BACd,QACA,UACA,UACA,UAYI,EAAE,EACgB;AACtB,QAAO;EACL,UAAU,OAAO;EACjB,WAAW,OAAO;EAClB,QAAQ,OAAO;EACf;EACA;EAGA,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,IAAI,OAAO;EAGX,MAAM,OAAO;EACb,SAAS,gBAAgB,OAAO,QAAQ;EACxC,eAAe,OAAO;EAGtB,YAAY,OAAO;EACnB,WAAW,OAAO;EAClB,cAAc,OAAO;EAGrB,kBAAkB,mBAAmB,OAAO;EAG5C,MAAM,OAAO;EACb,UAAU,QAAQ,YAAY;EAC9B,QAAQ,QAAQ,UAAU;EAC1B,OAAO,QAAQ,SAAS;EACxB,aAAa,QAAQ;EACrB,eAAe,QAAQ;EACvB,qBAAqB,QAAQ;EAC7B,qBAAqB,QAAQ;EAG7B,yBAAyB,QAAQ,2BAA2B;EAC5D,mBAAmB,QAAQ,qBAAqB;EAChD,kBAAkB,QAAQ;EAC3B"}

package/lib/utils/playerUtils.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Player state utilities and helper functions
+ */
+import { PlayerState, StatusEffect } from "../systems";
+import type { BodyFacing } from "../systems/animation/core/types";
+import { PlayerArchetype, Position, TrigramStance } from "../types";
+/**
+ * Create a complete PlayerState from archetype and player index
+ */
+export declare function createPlayerFromArchetype(archetype: PlayerArchetype, playerIndex: number): PlayerState;
+/**
+ * Update player state with partial updates
+ */
+export declare function updatePlayerState(player: PlayerState, updates: Partial<PlayerState>): PlayerState;
+/**
+ * Apply damage to player
+ */
+export declare function applyDamage(player: PlayerState, damage: number, _damageType?: string): PlayerState;
+/**
+ * Apply status effect to player
+ */
+export declare function applyStatusEffect(player: PlayerState, effect: StatusEffect): PlayerState;
+/**
+ * Get vital point by ID (fix return type)
+ */
+export declare function getVitalPointByOnPlayerId(player: PlayerState, vitalPointId: string): {
+    readonly id: string;
+    readonly isHit: boolean;
+    readonly damage: number;
+    readonly lastHitTime: number;
+} | null;
+/**
+ * Check if player can act
+ */
+export declare function canPlayerAct(player: PlayerState): boolean;
+/**
+ * Get player's current stance effectiveness against opponent
+ */
+export declare function getStanceEffectiveness(_playerStance: TrigramStance, // Fix: Add underscore to unused parameter
+_opponentStance: TrigramStance): number;
+/**
+ * Check if player has enough resources for action
+ */
+export declare function hasEnoughResources(player: PlayerState, kiCost: number, staminaCost: number): boolean;
+/**
+ * Get player archetype bonuses
+ */
+export declare function getArchetypeBonuses(archetype: PlayerArchetype): {
+    attackBonus: number;
+    defenseBonus: number;
+    speedBonus: number;
+    techniqueBonus: number;
+};
+/**
+ * Calculate player's current combat effectiveness
+ */
+export declare function calculateCombatEffectiveness(player: PlayerState): number;
+/**
+ * Remove expired status effects
+ */
+export declare function updateStatusEffects(player: PlayerState, currentTime: number): PlayerState;
+/**
+ * Reset player to starting state
+ */
+export declare function resetPlayerState(archetype: PlayerArchetype, playerIndex: number): PlayerState;
+/**
+ * Get archetype asset paths (image, theme music, etc.)
+ *
+ * Note: PlayerArchetype enum values are already lowercase (e.g., MUSA = "musa"),
+ * so the toLowerCase() call is defensive programming for type safety.
+ */
+export declare function getArchetypeAssets(archetype: PlayerArchetype): {
+    readonly id: string;
+    readonly image: string;
+    readonly theme: string;
+    readonly themeId: string;
+    readonly name_korean: string;
+    readonly name_english: string;
+    readonly textureKey: string;
+};
+/**
+ * Initialize body facing for a player based on opponent position
+ *
+ * Calculates initial facing angle to point toward opponent.
+ *
+ * @param playerPosition - Player's position
+ * @param opponentPosition - Opponent's position
+ * @returns Initial BodyFacing state
+ * @korean 몸향하기초기화
+ *
+ * @example
+ * ```typescript
+ * const player = {
+ *   ...basePlayer,
+ *   bodyFacing: initializeBodyFacing(
+ *     { x: 300, y: 400 },
+ *     { x: 500, y: 400 }
+ *   ),
+ * };
+ * ```
+ */
+export declare function initializeBodyFacing(playerPosition: Position, opponentPosition: Position): BodyFacing;
+/**
+ * Toggle the player's stance side (orthodox ↔ southpaw)
+ *
+ * Switches between orthodox (left foot forward) and southpaw (right foot forward).
+ * This is used when executing stance switches or certain techniques.
+ *
+ * @param player - Current player state
+ * @returns Updated player state with toggled stance side
+ * @korean 자세측면전환
+ *
+ * @example
+ * ```typescript
+ * // Switch from orthodox to southpaw
+ * const newState = toggleStanceSide(player);
+ * // newState.stanceSide === 'southpaw'
+ * ```
+ */
+export declare function toggleStanceSide(player: PlayerState): PlayerState;
+/**
+ * Get the lead foot from stance side, defaulting to orthodox if not set
+ *
+ * @param player - Player state
+ * @returns Lead foot ('left' for orthodox, 'right' for southpaw)
+ * @korean 자세측면에서선발발가져오기
+ */
+export declare function getPlayerLeadFoot(player: PlayerState): "left" | "right";
+/**
+ * Get the rear (power) foot for a player
+ *
+ * @param player - Player state
+ * @returns Rear foot ('right' for orthodox, 'left' for southpaw)
+ * @korean 후발발가져오기
+ */
+export declare function getPlayerRearFoot(player: PlayerState): "left" | "right";
+//# sourceMappingURL=playerUtils.d.ts.map

package/lib/utils/playerUtils.d.ts.map

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