blacktrigram 0.7.2

package/lib/systems/animation/builders/SkeletonRig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkeletonRig.js","names":[],"sources":["../../../../src/systems/animation/builders/SkeletonRig.ts"],"sourcesContent":["/**\n * Skeleton rig implementation for articulated body model\n *\n * Creates and manages humanoid skeletal rig with 28 bones for realistic\n * martial arts animations. Implements bone hierarchy following Korean martial\n * arts body mechanics.\n *\n * Now supports dynamic scaling based on player physical attributes for\n * anatomically accurate body proportions per archetype.\n *\n * @module systems/animation/SkeletonRig\n * @category Animation System\n * @korean 골격시스템\n */\n\nimport { PhysicalAttributes } from \"@/types/common\";\nimport type {\n  Bone,\n  BoneChain,\n  JointConstraint,\n  SkeletalRig,\n} from \"@/types/skeletal\";\nimport { BoneName } from \"@/types/skeletal\";\nimport {\n  calculateSkeletonDimensions,\n  cmToMeters,\n} from \"@/utils/characterScaling\";\nimport * as THREE from \"three\";\n\n/**\n * Create a bone with default rest pose\n *\n * Helper function to create a bone with position, rotation, and scale.\n * Sets up rest pose for animation blending.\n *\n * @param name - Unique bone identifier\n * @param parent - Parent bone (null for root)\n * @param position - Local position relative to parent [x, y, z]\n * @param length - Bone length for rendering\n * @returns Newly created bone\n *\n * @korean 뼈생성\n */\nexport const createBone = (\n  name: string,\n  parent: Bone | null,\n  position: [number, number, number],\n  length = 0.1,\n): Bone => {\n  const pos = new THREE.Vector3(position[0], position[1], position[2]);\n  const rot = new THREE.Euler(0, 0, 0);\n  const scale = new THREE.Vector3(1, 1, 1);\n\n  const bone: Bone = {\n    name,\n    parent,\n    position: pos.clone(),\n    rotation: rot.clone(),\n    scale: scale.clone(),\n    children: [],\n    length,\n    restPosition: pos.clone(),\n    restRotation: rot.clone(),\n  };\n\n  // Add to parent's children\n  if (parent) {\n    parent.children.push(bone);\n  }\n\n  return bone;\n};\n\n/**\n * Create complete humanoid skeletal rig\n *\n * Creates 28-bone humanoid skeleton following Korean martial arts anatomy:\n * - 1 root (pelvis)\n * - 3 spine bones\n * - 2 head bones (neck, head)\n * - 12 arm bones (6 per arm)\n * - 10 leg bones (5 per leg)\n *\n * Total: 28 bones (under 30 bone limit for 60fps performance)\n *\n * @returns Complete skeletal rig with bone hierarchy\n *\n * @example\n * ```typescript\n * const rig = createHumanoidRig();\n * const rightHand = rig.bones.get(BoneName.HAND_R);\n * console.log(`Hand position: ${rightHand?.position}`);\n * ```\n *\n * @korean 인간형골격생성\n */\nexport const createHumanoidRig = (): SkeletalRig => {\n  // Root (pelvis) - center of mass at hip height\n  // Pelvis height = sum of leg segments (hip + thigh + knee + shin + foot)\n  // = 0.1 + 0.3 + 0.3 + 0.3 + 0.1 = 1.1 to have feet at Y=0\n  const root = createBone(BoneName.PELVIS, null, [0, 1.1, 0], 0.15);\n\n  // Spine chain (3 bones)\n  const spine1 = createBone(BoneName.SPINE_LOWER, root, [0, 0.15, 0], 0.2);\n  const spine2 = createBone(BoneName.SPINE_MIDDLE, spine1, [0, 0.2, 0], 0.2);\n  const spine3 = createBone(BoneName.SPINE_UPPER, spine2, [0, 0.2, 0], 0.2);\n\n  // Head chain (2 bones)\n  const neck = createBone(BoneName.NECK, spine3, [0, 0.15, 0], 0.1);\n  const head = createBone(BoneName.HEAD, neck, [0, 0.2, 0], 0.2);\n\n  // Left arm chain (6 bones)\n  const leftShoulder = createBone(\n    BoneName.SHOULDER_L,\n    spine3,\n    [-0.15, 0.1, 0],\n    0.1,\n  );\n  const leftUpperArm = createBone(\n    BoneName.UPPER_ARM_L,\n    leftShoulder,\n    [-0.15, 0, 0],\n    0.25,\n  );\n  const leftElbow = createBone(\n    BoneName.ELBOW_L,\n    leftUpperArm,\n    [-0.25, 0, 0],\n    0.05,\n  );\n  const leftForearm = createBone(\n    BoneName.FOREARM_L,\n    leftElbow,\n    [-0.25, 0, 0],\n    0.25,\n  );\n  const leftWrist = createBone(\n    BoneName.WRIST_L,\n    leftForearm,\n    [-0.15, 0, 0],\n    0.05,\n  );\n  const leftHand = createBone(BoneName.HAND_L, leftWrist, [-0.08, 0, 0], 0.08);\n\n  // Right arm chain (6 bones - mirror of left)\n  const rightShoulder = createBone(\n    BoneName.SHOULDER_R,\n    spine3,\n    [0.15, 0.1, 0],\n    0.1,\n  );\n  const rightUpperArm = createBone(\n    BoneName.UPPER_ARM_R,\n    rightShoulder,\n    [0.15, 0, 0],\n    0.25,\n  );\n  const rightElbow = createBone(\n    BoneName.ELBOW_R,\n    rightUpperArm,\n    [0.25, 0, 0],\n    0.05,\n  );\n  const rightForearm = createBone(\n    BoneName.FOREARM_R,\n    rightElbow,\n    [0.25, 0, 0],\n    0.25,\n  );\n  const rightWrist = createBone(\n    BoneName.WRIST_R,\n    rightForearm,\n    [0.15, 0, 0],\n    0.05,\n  );\n  const rightHand = createBone(BoneName.HAND_R, rightWrist, [0.08, 0, 0], 0.08);\n\n  // Left leg chain (5 bones)\n  const leftHip = createBone(BoneName.HIP_L, root, [-0.1, -0.1, 0], 0.1);\n  const leftThigh = createBone(BoneName.THIGH_L, leftHip, [0, -0.3, 0], 0.3);\n  const leftKnee = createBone(BoneName.KNEE_L, leftThigh, [0, -0.3, 0], 0.05);\n  const leftShin = createBone(BoneName.SHIN_L, leftKnee, [0, -0.3, 0], 0.3);\n  const leftFoot = createBone(BoneName.FOOT_L, leftShin, [0, -0.1, 0.1], 0.15);\n\n  // Right leg chain (5 bones - mirror of left)\n  const rightHip = createBone(BoneName.HIP_R, root, [0.1, -0.1, 0], 0.1);\n  const rightThigh = createBone(BoneName.THIGH_R, rightHip, [0, -0.3, 0], 0.3);\n  const rightKnee = createBone(BoneName.KNEE_R, rightThigh, [0, -0.3, 0], 0.05);\n  const rightShin = createBone(BoneName.SHIN_R, rightKnee, [0, -0.3, 0], 0.3);\n  const rightFoot = createBone(\n    BoneName.FOOT_R,\n    rightShin,\n    [0, -0.1, 0.1],\n    0.15,\n  );\n\n  // Create bone map for fast lookup\n  const bones = new Map<string, Bone>([\n    [BoneName.PELVIS, root],\n    [BoneName.SPINE_LOWER, spine1],\n    [BoneName.SPINE_MIDDLE, spine2],\n    [BoneName.SPINE_UPPER, spine3],\n    [BoneName.NECK, neck],\n    [BoneName.HEAD, head],\n    [BoneName.SHOULDER_L, leftShoulder],\n    [BoneName.UPPER_ARM_L, leftUpperArm],\n    [BoneName.ELBOW_L, leftElbow],\n    [BoneName.FOREARM_L, leftForearm],\n    [BoneName.WRIST_L, leftWrist],\n    [BoneName.HAND_L, leftHand],\n    [BoneName.SHOULDER_R, rightShoulder],\n    [BoneName.UPPER_ARM_R, rightUpperArm],\n    [BoneName.ELBOW_R, rightElbow],\n    [BoneName.FOREARM_R, rightForearm],\n    [BoneName.WRIST_R, rightWrist],\n    [BoneName.HAND_R, rightHand],\n    [BoneName.HIP_L, leftHip],\n    [BoneName.THIGH_L, leftThigh],\n    [BoneName.KNEE_L, leftKnee],\n    [BoneName.SHIN_L, leftShin],\n    [BoneName.FOOT_L, leftFoot],\n    [BoneName.HIP_R, rightHip],\n    [BoneName.THIGH_R, rightThigh],\n    [BoneName.KNEE_R, rightKnee],\n    [BoneName.SHIN_R, rightShin],\n    [BoneName.FOOT_R, rightFoot],\n  ]);\n\n  return {\n    root,\n    bones,\n    boneCount: bones.size,\n  };\n};\n\n/**\n * Create humanoid rig with dynamic scaling based on physical attributes.\n *\n * **Korean**: 신체 속성 기반 골격 생성 (Physical Attributes-Based Skeleton Creation)\n *\n * Creates a 28-bone humanoid skeleton with bone lengths scaled according to\n * the fighter's physical attributes. This allows each archetype to have\n * anatomically accurate body proportions that affect combat hitboxes, vital\n * point positioning, and visual representation.\n *\n * ## Visual Amplification\n *\n * The scaling system applies amplification factors to create distinct visual\n * silhouettes while maintaining anatomical realism:\n *\n * - **2.5x limb amplification**: Makes reach differences clearly visible\n * - **1.15x shoulder amplification**: Creates recognizable body width differences\n * - **1.5x height amplification**: Subtle overall size differences\n *\n * ### Archetype Silhouettes Created\n *\n * The following table shows the effective shoulder span after amplification\n * (full span = offset * 2). Values show raw attribute → amplified visual span.\n *\n * | Archetype | Shoulders (Raw → Amplified Span) | Height | Silhouette |\n * |-----------|----------------------------------|--------|------------|\n * | Hacker    | 43cm → 49.5cm | 175cm | Compact, narrow |\n * | Amsalja   | 44cm → 50.6cm | 186cm | Tall, lean |\n * | Jeongbo   | 45cm → 51.8cm | 179cm | Balanced |\n * | Musa      | 46cm → 52.9cm | 180cm | Athletic |\n * | Jojik     | 54cm → 62.1cm | 188cm | Massive, wide |\n *\n * Note: Amplified span = raw width * 1.15 (shoulder amplification factor)\n * Percentage differences remain constant, but absolute gaps are amplified:\n * - Raw gap: Jojik (54cm) - Hacker (43cm) = 11cm\n * - Amplified gap: 62.1cm - 49.5cm = 12.6cm (15% larger absolute difference)\n *\n * @param attributes - Physical attributes to scale the skeleton\n * @returns Complete skeletal rig with scaled bone dimensions\n *\n * @example\n * ```typescript\n * import { AMSALJA_PHYSICAL } from \"@/data/archetypePhysicalAttributes\";\n *\n * // Create skeleton for lean assassin archetype\n * const amsaljaRig = createScaledHumanoidRig(AMSALJA_PHYSICAL);\n * // Results in taller skeleton with longer limbs, narrower shoulders\n * // Height: 186cm, Legs: 102cm, Arms: 82cm, Shoulders: 44cm\n *\n * // Create skeleton for heavy brawler archetype\n * const jojikRig = createScaledHumanoidRig(JOJIK_PHYSICAL);\n * // Results in stockier skeleton with wider shoulders, thicker torso\n * // Height: 188cm, Legs: 100cm, Arms: 84cm, Shoulders: 54cm (25% wider!)\n * ```\n *\n * @public\n * @korean 크기조정된인간형골격생성\n */\nexport const createScaledHumanoidRig = (\n  attributes: PhysicalAttributes,\n): SkeletalRig => {\n  // Calculate anatomically correct bone dimensions in meters\n  const dims = calculateSkeletonDimensions(attributes);\n\n  // Calculate shoulder offset (half of shoulder width) in meters\n  const shoulderOffsetMeters = cmToMeters(attributes.shoulderWidth) / 2;\n  const hipOffsetMeters = cmToMeters(attributes.shoulderWidth) * 0.35; // Hips are ~70% of shoulder width\n\n  // Root (pelvis) - position at pelvis height (ground + leg length + foot)\n  // This ensures feet are at Y=0\n  const root = createBone(\n    BoneName.PELVIS,\n    null,\n    [0, dims.pelvisHeight, 0],\n    dims.hip,\n  );\n\n  // Spine chain (3 bones) - using actual torso segment lengths\n  const spine1 = createBone(\n    BoneName.SPINE_LOWER,\n    root,\n    [0, dims.spineLower * 0.5, 0], // Start half a segment up from pelvis\n    dims.spineLower,\n  );\n  const spine2 = createBone(\n    BoneName.SPINE_MIDDLE,\n    spine1,\n    [0, dims.spineMiddle, 0],\n    dims.spineMiddle,\n  );\n  const spine3 = createBone(\n    BoneName.SPINE_UPPER,\n    spine2,\n    [0, dims.spineUpper, 0],\n    dims.spineUpper,\n  );\n\n  // Head chain (2 bones) - using actual neck and head sizes\n  const neck = createBone(\n    BoneName.NECK,\n    spine3,\n    [0, dims.neck * 0.5, 0], // Start from top of spine\n    dims.neck,\n  );\n  const head = createBone(\n    BoneName.HEAD,\n    neck,\n    [0, dims.head * 0.75, 0], // Head center offset\n    dims.head,\n  );\n\n  // Left arm chain (6 bones) - using actual arm segment lengths\n  const leftShoulder = createBone(\n    BoneName.SHOULDER_L,\n    spine3,\n    [-shoulderOffsetMeters * 0.7, dims.neck * 0.3, 0], // Shoulder starts inward from edge\n    dims.shoulder,\n  );\n  const leftUpperArm = createBone(\n    BoneName.UPPER_ARM_L,\n    leftShoulder,\n    [-dims.shoulder, 0, 0], // Extend outward by shoulder length\n    dims.upperArm,\n  );\n  const leftElbow = createBone(\n    BoneName.ELBOW_L,\n    leftUpperArm,\n    [-dims.upperArm, 0, 0], // End of upper arm\n    dims.elbow,\n  );\n  const leftForearm = createBone(\n    BoneName.FOREARM_L,\n    leftElbow,\n    [-dims.elbow, 0, 0], // Past elbow joint\n    dims.forearm,\n  );\n  const leftWrist = createBone(\n    BoneName.WRIST_L,\n    leftForearm,\n    [-dims.forearm, 0, 0], // End of forearm\n    dims.wrist,\n  );\n  const leftHand = createBone(\n    BoneName.HAND_L,\n    leftWrist,\n    [-dims.wrist, 0, 0], // Past wrist\n    dims.hand,\n  );\n\n  // Right arm chain (6 bones - mirror of left)\n  const rightShoulder = createBone(\n    BoneName.SHOULDER_R,\n    spine3,\n    [shoulderOffsetMeters * 0.7, dims.neck * 0.3, 0],\n    dims.shoulder,\n  );\n  const rightUpperArm = createBone(\n    BoneName.UPPER_ARM_R,\n    rightShoulder,\n    [dims.shoulder, 0, 0],\n    dims.upperArm,\n  );\n  const rightElbow = createBone(\n    BoneName.ELBOW_R,\n    rightUpperArm,\n    [dims.upperArm, 0, 0],\n    dims.elbow,\n  );\n  const rightForearm = createBone(\n    BoneName.FOREARM_R,\n    rightElbow,\n    [dims.elbow, 0, 0],\n    dims.forearm,\n  );\n  const rightWrist = createBone(\n    BoneName.WRIST_R,\n    rightForearm,\n    [dims.forearm, 0, 0],\n    dims.wrist,\n  );\n  const rightHand = createBone(\n    BoneName.HAND_R,\n    rightWrist,\n    [dims.wrist, 0, 0],\n    dims.hand,\n  );\n\n  // Left leg chain (5 bones) - using actual leg segment lengths\n  const leftHip = createBone(\n    BoneName.HIP_L,\n    root,\n    [-hipOffsetMeters, -dims.hip * 0.5, 0],\n    dims.hip,\n  );\n  const leftThigh = createBone(\n    BoneName.THIGH_L,\n    leftHip,\n    [0, -dims.hip, 0], // Drop down from hip\n    dims.thigh,\n  );\n  const leftKnee = createBone(\n    BoneName.KNEE_L,\n    leftThigh,\n    [0, -dims.thigh, 0], // End of thigh\n    dims.knee,\n  );\n  const leftShin = createBone(\n    BoneName.SHIN_L,\n    leftKnee,\n    [0, -dims.knee, 0], // Past knee\n    dims.shin,\n  );\n  const leftFoot = createBone(\n    BoneName.FOOT_L,\n    leftShin,\n    [0, -dims.shin, dims.foot * 0.5], // End of shin, slight forward for foot\n    dims.foot,\n  );\n\n  // Right leg chain (5 bones - mirror of left)\n  const rightHip = createBone(\n    BoneName.HIP_R,\n    root,\n    [hipOffsetMeters, -dims.hip * 0.5, 0],\n    dims.hip,\n  );\n  const rightThigh = createBone(\n    BoneName.THIGH_R,\n    rightHip,\n    [0, -dims.hip, 0],\n    dims.thigh,\n  );\n  const rightKnee = createBone(\n    BoneName.KNEE_R,\n    rightThigh,\n    [0, -dims.thigh, 0],\n    dims.knee,\n  );\n  const rightShin = createBone(\n    BoneName.SHIN_R,\n    rightKnee,\n    [0, -dims.knee, 0],\n    dims.shin,\n  );\n  const rightFoot = createBone(\n    BoneName.FOOT_R,\n    rightShin,\n    [0, -dims.shin, dims.foot * 0.5],\n    dims.foot,\n  );\n\n  // Create bone map for fast lookup\n  const bones = new Map<string, Bone>([\n    [BoneName.PELVIS, root],\n    [BoneName.SPINE_LOWER, spine1],\n    [BoneName.SPINE_MIDDLE, spine2],\n    [BoneName.SPINE_UPPER, spine3],\n    [BoneName.NECK, neck],\n    [BoneName.HEAD, head],\n    [BoneName.SHOULDER_L, leftShoulder],\n    [BoneName.UPPER_ARM_L, leftUpperArm],\n    [BoneName.ELBOW_L, leftElbow],\n    [BoneName.FOREARM_L, leftForearm],\n    [BoneName.WRIST_L, leftWrist],\n    [BoneName.HAND_L, leftHand],\n    [BoneName.SHOULDER_R, rightShoulder],\n    [BoneName.UPPER_ARM_R, rightUpperArm],\n    [BoneName.ELBOW_R, rightElbow],\n    [BoneName.FOREARM_R, rightForearm],\n    [BoneName.WRIST_R, rightWrist],\n    [BoneName.HAND_R, rightHand],\n    [BoneName.HIP_L, leftHip],\n    [BoneName.THIGH_L, leftThigh],\n    [BoneName.KNEE_L, leftKnee],\n    [BoneName.SHIN_L, leftShin],\n    [BoneName.FOOT_L, leftFoot],\n    [BoneName.HIP_R, rightHip],\n    [BoneName.THIGH_R, rightThigh],\n    [BoneName.KNEE_R, rightKnee],\n    [BoneName.SHIN_R, rightShin],\n    [BoneName.FOOT_R, rightFoot],\n  ]);\n\n  return {\n    root,\n    bones,\n    boneCount: bones.size,\n  };\n};\n\n/**\n * Joint constraints for anatomically correct movement\n *\n * Defines rotation limits for each joint to prevent unrealistic poses.\n * Based on human anatomy and Korean martial arts biomechanics.\n *\n * @korean 관절제약조건들\n */\nexport const JOINT_CONSTRAINTS: JointConstraint[] = [\n  // Elbow joints - can only bend one direction\n  {\n    boneName: BoneName.ELBOW_L,\n    minRotation: new THREE.Vector3(0, 0, -2.4), // ~-137 degrees\n    maxRotation: new THREE.Vector3(0, 0, 0),\n    canTwist: false,\n  },\n  {\n    boneName: BoneName.ELBOW_R,\n    minRotation: new THREE.Vector3(0, 0, 0),\n    maxRotation: new THREE.Vector3(0, 0, 2.4), // ~137 degrees\n    canTwist: false,\n  },\n\n  // Knee joints - can only bend backward\n  {\n    boneName: BoneName.KNEE_L,\n    minRotation: new THREE.Vector3(-2.4, 0, 0), // ~-137 degrees\n    maxRotation: new THREE.Vector3(0, 0, 0),\n    canTwist: false,\n  },\n  {\n    boneName: BoneName.KNEE_R,\n    minRotation: new THREE.Vector3(-2.4, 0, 0), // ~-137 degrees\n    maxRotation: new THREE.Vector3(0, 0, 0),\n    canTwist: false,\n  },\n\n  // Shoulder joints - full range of motion\n  {\n    boneName: BoneName.SHOULDER_L,\n    minRotation: new THREE.Vector3(-1.5, -1.5, -3.0),\n    maxRotation: new THREE.Vector3(1.5, 1.5, 3.0),\n    canTwist: true,\n  },\n  {\n    boneName: BoneName.SHOULDER_R,\n    minRotation: new THREE.Vector3(-1.5, -1.5, -3.0),\n    maxRotation: new THREE.Vector3(1.5, 1.5, 3.0),\n    canTwist: true,\n  },\n\n  // Hip joints - large range for kicks\n  {\n    boneName: BoneName.HIP_L,\n    minRotation: new THREE.Vector3(-1.8, -0.8, -1.5),\n    maxRotation: new THREE.Vector3(1.8, 0.8, 1.5),\n    canTwist: true,\n  },\n  {\n    boneName: BoneName.HIP_R,\n    minRotation: new THREE.Vector3(-1.8, -0.8, -1.5),\n    maxRotation: new THREE.Vector3(1.8, 0.8, 1.5),\n    canTwist: true,\n  },\n\n  // Neck - moderate range\n  {\n    boneName: BoneName.NECK,\n    minRotation: new THREE.Vector3(-0.5, -0.8, -0.5),\n    maxRotation: new THREE.Vector3(0.5, 0.8, 0.5),\n    canTwist: true,\n  },\n\n  // Spine bones - limited rotation for realism\n  {\n    boneName: BoneName.SPINE_LOWER,\n    minRotation: new THREE.Vector3(-0.3, -0.5, -0.3),\n    maxRotation: new THREE.Vector3(0.3, 0.5, 0.3),\n    canTwist: true,\n  },\n  {\n    boneName: BoneName.SPINE_MIDDLE,\n    minRotation: new THREE.Vector3(-0.3, -0.5, -0.3),\n    maxRotation: new THREE.Vector3(0.3, 0.5, 0.3),\n    canTwist: true,\n  },\n  {\n    boneName: BoneName.SPINE_UPPER,\n    minRotation: new THREE.Vector3(-0.3, -0.5, -0.3),\n    maxRotation: new THREE.Vector3(0.3, 0.5, 0.3),\n    canTwist: true,\n  },\n];\n\n/**\n * Bone chains for IK (Inverse Kinematics)\n *\n * Defines logical bone chains for limbs, used for IK solving\n * and animation retargeting.\n *\n * @korean 뼈체인들\n */\nexport const BONE_CHAINS: BoneChain[] = [\n  // Left arm chain\n  {\n    name: \"left_arm\",\n    startBone: BoneName.SHOULDER_L,\n    endBone: BoneName.HAND_L,\n    bones: [\n      BoneName.SHOULDER_L,\n      BoneName.UPPER_ARM_L,\n      BoneName.ELBOW_L,\n      BoneName.FOREARM_L,\n      BoneName.WRIST_L,\n      BoneName.HAND_L,\n    ],\n  },\n\n  // Right arm chain\n  {\n    name: \"right_arm\",\n    startBone: BoneName.SHOULDER_R,\n    endBone: BoneName.HAND_R,\n    bones: [\n      BoneName.SHOULDER_R,\n      BoneName.UPPER_ARM_R,\n      BoneName.ELBOW_R,\n      BoneName.FOREARM_R,\n      BoneName.WRIST_R,\n      BoneName.HAND_R,\n    ],\n  },\n\n  // Left leg chain\n  {\n    name: \"left_leg\",\n    startBone: BoneName.HIP_L,\n    endBone: BoneName.FOOT_L,\n    bones: [\n      BoneName.HIP_L,\n      BoneName.THIGH_L,\n      BoneName.KNEE_L,\n      BoneName.SHIN_L,\n      BoneName.FOOT_L,\n    ],\n  },\n\n  // Right leg chain\n  {\n    name: \"right_leg\",\n    startBone: BoneName.HIP_R,\n    endBone: BoneName.FOOT_R,\n    bones: [\n      BoneName.HIP_R,\n      BoneName.THIGH_R,\n      BoneName.KNEE_R,\n      BoneName.SHIN_R,\n      BoneName.FOOT_R,\n    ],\n  },\n\n  // Spine chain\n  {\n    name: \"spine\",\n    startBone: BoneName.PELVIS,\n    endBone: BoneName.HEAD,\n    bones: [\n      BoneName.PELVIS,\n      BoneName.SPINE_LOWER,\n      BoneName.SPINE_MIDDLE,\n      BoneName.SPINE_UPPER,\n      BoneName.NECK,\n      BoneName.HEAD,\n    ],\n  },\n];\n\n/**\n * Apply joint constraints to bone rotation\n *\n * Clamps bone rotation to anatomically correct ranges.\n * Prevents unrealistic poses like backward-bending elbows.\n *\n * @param bone - Bone to constrain\n * @param constraints - Joint constraint to apply\n *\n * @korean 관절제약적용\n */\nexport const applyJointConstraint = (\n  bone: Bone,\n  constraint: JointConstraint,\n): void => {\n  // Clamp X rotation\n  bone.rotation.x = Math.max(\n    constraint.minRotation.x,\n    Math.min(constraint.maxRotation.x, bone.rotation.x),\n  );\n\n  // Clamp Y rotation\n  bone.rotation.y = Math.max(\n    constraint.minRotation.y,\n    Math.min(constraint.maxRotation.y, bone.rotation.y),\n  );\n\n  // Clamp Z rotation\n  bone.rotation.z = Math.max(\n    constraint.minRotation.z,\n    Math.min(constraint.maxRotation.z, bone.rotation.z),\n  );\n};\n\n// Reusable matrix objects for world transform calculations (avoid allocations in useFrame)\nconst tempMatrix = new THREE.Matrix4();\nconst tempQuaternion = new THREE.Quaternion();\nconst tempScale = new THREE.Vector3();\n\n/**\n * Get world position of bone\n *\n * Calculates absolute world position by traversing parent chain.\n * Uses proper matrix multiplication to account for parent rotations.\n *\n * @param bone - Bone to get world position for\n * @returns World position as Vector3\n *\n * @korean 뼈의세계위치구하기\n */\nexport const getBoneWorldPosition = (bone: Bone): THREE.Vector3 => {\n  // Build the bone chain from root to this bone\n  const boneChain: Bone[] = [];\n  let currentBone: Bone | null = bone;\n  while (currentBone) {\n    boneChain.unshift(currentBone);\n    currentBone = currentBone.parent;\n  }\n\n  // Compose world matrix by multiplying all local transforms\n  const worldMatrix = new THREE.Matrix4();\n  worldMatrix.identity();\n\n  for (const b of boneChain) {\n    tempMatrix.compose(\n      b.position,\n      tempQuaternion.setFromEuler(b.rotation),\n      b.scale,\n    );\n    worldMatrix.multiply(tempMatrix);\n  }\n\n  // Extract world position from composed matrix\n  const worldPos = new THREE.Vector3();\n  worldMatrix.decompose(worldPos, tempQuaternion, tempScale);\n  return worldPos;\n};\n\n/**\n * Get world rotation of bone\n *\n * Calculates absolute world rotation by traversing parent chain.\n * Uses proper quaternion multiplication for correct rotation composition.\n *\n * @param bone - Bone to get world rotation for\n * @returns World rotation as Euler\n *\n * @korean 뼈의세계회전구하기\n */\nexport const getBoneWorldRotation = (bone: Bone): THREE.Euler => {\n  // Build the bone chain from root to this bone\n  const boneChain: Bone[] = [];\n  let currentBone: Bone | null = bone;\n  while (currentBone) {\n    boneChain.unshift(currentBone);\n    currentBone = currentBone.parent;\n  }\n\n  // Compose world rotation by multiplying quaternions (proper rotation composition)\n  const worldQuat = new THREE.Quaternion();\n  worldQuat.identity();\n\n  for (const b of boneChain) {\n    tempQuaternion.setFromEuler(b.rotation);\n    worldQuat.multiply(tempQuaternion);\n  }\n\n  // Convert back to Euler\n  const worldRot = new THREE.Euler();\n  worldRot.setFromQuaternion(worldQuat);\n  return worldRot;\n};\n\n/**\n * Reset bone to rest pose\n *\n * Resets bone position and rotation to default rest pose.\n * Useful for animation blending and initialization.\n *\n * @param bone - Bone to reset\n *\n * @korean 뼈를기본자세로초기화\n */\nexport const resetBoneToRestPose = (bone: Bone): void => {\n  bone.position.copy(bone.restPosition);\n  bone.rotation.copy(bone.restRotation);\n  bone.scale.set(1, 1, 1);\n};\n\n/**\n * Reset entire rig to rest pose\n *\n * Resets all bones in rig to rest pose.\n *\n * @param rig - Skeletal rig to reset\n *\n * @korean 골격을기본자세로초기화\n */\nexport const resetRigToRestPose = (rig: SkeletalRig): void => {\n  rig.bones.forEach((bone) => {\n    resetBoneToRestPose(bone);\n  });\n};\n\n/**\n * Create hand bones with 5 fingers\n *\n * Creates detailed hand structure with 5 fingers (thumb, index, middle, ring, pinky),\n * attached to an existing hand/palm bone.\n * Each finger has 3-4 bones for realistic animation.\n *\n * Finger bone structure:\n * - Thumb: 3 bones (metacarpal, proximal, distal) - no intermediate\n * - Other fingers: 4 bones (metacarpal, proximal, intermediate, distal)\n *\n * Total created by this function: 19 finger bones per hand (3 thumb + 4*4 other fingers),\n * all attached to the provided hand bone.\n *\n * @param handBone - Parent hand bone (acts as the palm/root for finger bones)\n * @param side - Hand side (\"left\" or \"right\")\n * @returns Map of finger bones added to the rig\n *\n * @korean 손뼈생성\n */\nexport const createHandBones = (\n  handBone: Bone,\n  side: \"left\" | \"right\",\n): Map<string, Bone> => {\n  const fingerBones = new Map<string, Bone>();\n\n  // Hand orientation: left hand extends to -X, right hand extends to +X\n  const sideMultiplier = side === \"left\" ? -1 : 1;\n\n  // Thumb (3 bones) - offset slightly toward palm center and forward\n  const thumbMeta = createBone(\n    `${\n      BoneName[`THUMB_META_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    handBone,\n    [0.015 * sideMultiplier, 0.02, 0.01],\n    0.025,\n  );\n  const thumbProx = createBone(\n    `${\n      BoneName[`THUMB_PROX_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    thumbMeta,\n    [0.015 * sideMultiplier, 0.015, 0.01],\n    0.02,\n  );\n  const thumbDist = createBone(\n    `${\n      BoneName[`THUMB_DIST_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    thumbProx,\n    [0.01 * sideMultiplier, 0.01, 0],\n    0.015,\n  );\n\n  fingerBones.set(thumbMeta.name, thumbMeta);\n  fingerBones.set(thumbProx.name, thumbProx);\n  fingerBones.set(thumbDist.name, thumbDist);\n\n  // Index finger (4 bones)\n  const indexMeta = createBone(\n    `${\n      BoneName[`INDEX_META_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    handBone,\n    [0.015 * sideMultiplier, 0.06, 0],\n    0.03,\n  );\n  const indexProx = createBone(\n    `${\n      BoneName[`INDEX_PROX_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    indexMeta,\n    [0, 0.025, 0],\n    0.025,\n  );\n  const indexInter = createBone(\n    `${\n      BoneName[`INDEX_INTER_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    indexProx,\n    [0, 0.02, 0],\n    0.02,\n  );\n  const indexDist = createBone(\n    `${\n      BoneName[`INDEX_DIST_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    indexInter,\n    [0, 0.015, 0],\n    0.015,\n  );\n\n  fingerBones.set(indexMeta.name, indexMeta);\n  fingerBones.set(indexProx.name, indexProx);\n  fingerBones.set(indexInter.name, indexInter);\n  fingerBones.set(indexDist.name, indexDist);\n\n  // Middle finger (4 bones) - longest finger\n  const middleMeta = createBone(\n    `${\n      BoneName[`MIDDLE_META_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    handBone,\n    [0.005 * sideMultiplier, 0.065, 0],\n    0.035,\n  );\n  const middleProx = createBone(\n    `${\n      BoneName[`MIDDLE_PROX_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    middleMeta,\n    [0, 0.03, 0],\n    0.03,\n  );\n  const middleInter = createBone(\n    `${\n      BoneName[`MIDDLE_INTER_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    middleProx,\n    [0, 0.025, 0],\n    0.025,\n  );\n  const middleDist = createBone(\n    `${\n      BoneName[`MIDDLE_DIST_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    middleInter,\n    [0, 0.02, 0],\n    0.02,\n  );\n\n  fingerBones.set(middleMeta.name, middleMeta);\n  fingerBones.set(middleProx.name, middleProx);\n  fingerBones.set(middleInter.name, middleInter);\n  fingerBones.set(middleDist.name, middleDist);\n\n  // Ring finger (4 bones)\n  const ringMeta = createBone(\n    `${\n      BoneName[`RING_META_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    handBone,\n    [-0.005 * sideMultiplier, 0.06, 0],\n    0.03,\n  );\n  const ringProx = createBone(\n    `${\n      BoneName[`RING_PROX_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    ringMeta,\n    [0, 0.025, 0],\n    0.025,\n  );\n  const ringInter = createBone(\n    `${\n      BoneName[`RING_INTER_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    ringProx,\n    [0, 0.02, 0],\n    0.02,\n  );\n  const ringDist = createBone(\n    `${\n      BoneName[`RING_DIST_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    ringInter,\n    [0, 0.015, 0],\n    0.015,\n  );\n\n  fingerBones.set(ringMeta.name, ringMeta);\n  fingerBones.set(ringProx.name, ringProx);\n  fingerBones.set(ringInter.name, ringInter);\n  fingerBones.set(ringDist.name, ringDist);\n\n  // Pinky finger (4 bones) - shortest finger\n  const pinkyMeta = createBone(\n    `${\n      BoneName[`PINKY_META_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    handBone,\n    [-0.015 * sideMultiplier, 0.05, 0],\n    0.025,\n  );\n  const pinkyProx = createBone(\n    `${\n      BoneName[`PINKY_PROX_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    pinkyMeta,\n    [0, 0.02, 0],\n    0.02,\n  );\n  const pinkyInter = createBone(\n    `${\n      BoneName[`PINKY_INTER_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    pinkyProx,\n    [0, 0.015, 0],\n    0.015,\n  );\n  const pinkyDist = createBone(\n    `${\n      BoneName[`PINKY_DIST_${side.toUpperCase()[0]}` as keyof typeof BoneName]\n    }`,\n    pinkyInter,\n    [0, 0.01, 0],\n    0.01,\n  );\n\n  fingerBones.set(pinkyMeta.name, pinkyMeta);\n  fingerBones.set(pinkyProx.name, pinkyProx);\n  fingerBones.set(pinkyInter.name, pinkyInter);\n  fingerBones.set(pinkyDist.name, pinkyDist);\n\n  return fingerBones;\n};\n\n/**\n * Create humanoid rig with optional hand bones\n *\n * Creates complete skeletal rig with optional detailed hand bones.\n * Hand bones can be excluded for performance (LOD system).\n *\n * @param includeHandBones - Whether to include detailed hand bones (default: false)\n * @returns Complete skeletal rig with or without hand bones\n *\n * @korean 손뼈포함골격생성\n */\nexport const createHumanoidRigWithHands = (\n  includeHandBones: boolean = false,\n): SkeletalRig => {\n  // Create base rig\n  const baseRig = createHumanoidRig();\n\n  // If hand bones not requested, return base rig\n  if (!includeHandBones) {\n    return baseRig;\n  }\n\n  // Get hand bones from base rig\n  const leftHand = baseRig.bones.get(BoneName.HAND_L);\n  const rightHand = baseRig.bones.get(BoneName.HAND_R);\n\n  if (!leftHand || !rightHand) {\n    console.warn(\"Hand bones not found in base rig\");\n    return baseRig;\n  }\n\n  // Create finger bones\n  const leftFingerBones = createHandBones(leftHand, \"left\");\n  const rightFingerBones = createHandBones(rightHand, \"right\");\n\n  // Add finger bones to rig bone map\n  leftFingerBones.forEach((bone, name) => {\n    baseRig.bones.set(name, bone);\n  });\n  rightFingerBones.forEach((bone, name) => {\n    baseRig.bones.set(name, bone);\n  });\n\n  return {\n    ...baseRig,\n    boneCount: baseRig.bones.size,\n  };\n};\n\n/**\n * Torso rotation constraints for anatomically correct upper/lower body movement\n *\n * Defines limits and behavior for independent torso rotation relative to hips,\n * enabling realistic strafing and lateral movement while facing opponent.\n *\n * Korean terminology:\n * - 허리회전 (Heorhwoejeon) - Torso rotation\n * - 해부학적제약 (Haebuhakjeok Jeyak) - Anatomical constraints\n *\n * @public\n * @korean 허리회전제약조건\n */\nexport const TORSO_CONSTRAINTS = {\n  /**\n   * Maximum torso rotation relative to hips (radians)\n   * ±90° = π/2 radians - anatomically safe rotation limit\n   *\n   * @korean 최대회전각도\n   */\n  MAX_ROTATION: Math.PI / 2,\n\n  /**\n   * Minimum torso rotation relative to hips (radians)\n   * -90° = -π/2 radians\n   *\n   * @korean 최소회전각도\n   */\n  MIN_ROTATION: -Math.PI / 2,\n\n  /**\n   * Target interpolation time in seconds\n   * 200ms provides smooth, natural rotation feel\n   *\n   * @korean 보간시간\n   */\n  INTERPOLATION_TIME: 0.2,\n\n  /**\n   * Power modifier range for hip rotation\n   * [min, max] = [10%, 30%] damage bonus from proper hip engagement\n   *\n   * @korean 파워배율범위\n   */\n  POWER_MODIFIER_RANGE: [0.1, 0.3] as const,\n} as const;\n\n/**\n * Calculate torso rotation to face opponent while moving\n *\n * Determines optimal torso rotation angle to keep upper body facing opponent\n * while hips/legs are oriented in movement direction. Enforces anatomical\n * constraints (±90° max rotation).\n *\n * @param currentPosition - Player's current world position\n * @param opponentPosition - Opponent's current world position\n * @param _movementDirection - Direction of player movement (reserved for future use)\n * @param hipRotation - Current hip/pelvis rotation in radians\n * @returns Torso rotation in radians relative to hips (clamped to ±90°)\n *\n * @example\n * ```typescript\n * const playerPos = new THREE.Vector3(0, 0, 0);\n * const opponentPos = new THREE.Vector3(0, 0, 5); // Directly in front along Z+\n * const moveDir = new THREE.Vector3(0, 0, 1); // Moving forward\n * const hipRot = 0; // Hips facing forward (Z+)\n *\n * const torsoRot = calculateTorsoRotation(playerPos, opponentPos, moveDir, hipRot);\n * // Returns 0 (opponent is already aligned with hips)\n * ```\n *\n * @public\n * @korean 상대를향한허리회전계산\n */\nexport function calculateTorsoRotation(\n  currentPosition: THREE.Vector3,\n  opponentPosition: THREE.Vector3,\n  _movementDirection: THREE.Vector3,\n  hipRotation: number,\n): number {\n  // Calculate angle to opponent\n  const directionToOpponent = opponentPosition\n    .clone()\n    .sub(currentPosition)\n    .normalize();\n  // Use atan2(x, z) - X is horizontal, Z is forward/back in Three.js\n  const angleToOpponent = Math.atan2(\n    directionToOpponent.x,\n    directionToOpponent.z,\n  );\n\n  // Calculate torso rotation relative to hips\n  let torsoRotation = angleToOpponent - hipRotation;\n\n  // Normalize to -π to π range\n  while (torsoRotation > Math.PI) torsoRotation -= 2 * Math.PI;\n  while (torsoRotation < -Math.PI) torsoRotation += 2 * Math.PI;\n\n  // Apply anatomical constraints (±90°)\n  torsoRotation = Math.max(\n    TORSO_CONSTRAINTS.MIN_ROTATION,\n    Math.min(TORSO_CONSTRAINTS.MAX_ROTATION, torsoRotation),\n  );\n\n  return torsoRotation;\n}\n\n/**\n * Calculate damage modifier from hip rotation\n *\n * Determines power bonus applied to techniques based on hip rotation angle.\n * Greater hip rotation generates more power through proper biomechanics,\n * with strikes benefiting most from full rotation.\n *\n * @param hipRotationAngle - Hip rotation angle in radians (typically from torso twist)\n * @param techniqueType - Type of technique ('strike', 'throw', or 'joint')\n * @returns Damage multiplier (1.0-1.3 for strikes, 1.0-1.1 for throws/joints)\n *\n * @example\n * ```typescript\n * // Full hip rotation on strike technique\n * const modifier = calculateHipRotationPowerModifier(Math.PI / 2, 'strike');\n * // Returns 1.30 (30% damage bonus)\n *\n * // Half rotation on throw\n * const throwMod = calculateHipRotationPowerModifier(Math.PI / 4, 'throw');\n * // Returns 1.05 (5% damage bonus)\n * ```\n *\n * @public\n * @korean 허리회전으로인한데미지배율계산\n */\nexport function calculateHipRotationPowerModifier(\n  hipRotationAngle: number,\n  techniqueType: \"strike\" | \"throw\" | \"joint\",\n): number {\n  // Normalize rotation to 0-1 range (0 = no rotation, 1 = max rotation)\n  // Clamp to max rotation first to handle any values exceeding ±90°\n  const clampedAngle = Math.max(\n    -TORSO_CONSTRAINTS.MAX_ROTATION,\n    Math.min(TORSO_CONSTRAINTS.MAX_ROTATION, Math.abs(hipRotationAngle)),\n  );\n  const normalizedRotation = clampedAngle / TORSO_CONSTRAINTS.MAX_ROTATION;\n\n  // Strikes benefit most from hip rotation (up to 30% bonus)\n  // Throws get moderate benefit (up to 10% bonus)\n  // Joint locks get minimal benefit (up to 10% bonus)\n  const baseModifier = techniqueType === \"strike\" ? 0.3 : 0.1;\n\n  return 1.0 + normalizedRotation * baseModifier;\n}\n"],"mappings":"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"}

package/lib/systems/animation/builders/TrigramGuardApplicator.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Trigram Guard Applicator
+ *
+ * Applies full trigram-specific guard poses to animation keyframes.
+ * Unlike the generic `withGuard()` method that only sets arm positions,
+ * this applicator sets the complete body position including:
+ * - Arms (shoulder, elbow, wrist)
+ * - Legs (hip, knee, ankle)
+ * - Torso and pelvis rotation
+ *
+ * This ensures that walk/run/idle animations maintain proper
+ * trigram-specific guard positions for authentic Korean martial arts movement.
+ *
+ * @module systems/animation/builders/TrigramGuardApplicator
+ * @korean 팔괘방어자세적용기
+ */
+import { TrigramStance } from "../../../types/common";
+import type { StanceGuardPose } from "../../../types/skeletal";
+import type { StanceLaterality } from "../../trigram/types";
+import type { KeyframeConfig } from "./KeyframeConfig";
+/**
+ * Direct access to guard poses by trigram stance name
+ * Avoids repeated function calls in animation loops
+ *
+ * @korean 방어자세직접접근맵
+ */
+export declare const TRIGRAM_GUARD_POSES: Readonly<Record<TrigramStance, StanceGuardPose>>;
+/**
+ * Options for applying trigram guard pose
+ *
+ * @korean 팔괘방어자세적용옵션
+ */
+export interface TrigramGuardOptions {
+    /** Apply arm positions (shoulder, elbow, wrist) */
+    readonly includeArms?: boolean;
+    /** Apply leg positions (hip, knee, ankle) */
+    readonly includeLegs?: boolean;
+    /** Apply torso rotation */
+    readonly includeTorso?: boolean;
+    /** Apply pelvis rotation */
+    readonly includePelvis?: boolean;
+    /** Blend factor 0-1 for partial application (locomotion blending) */
+    readonly blendFactor?: number;
+    /** Stance laterality ("left" or "right") */
+    readonly laterality?: StanceLaterality;
+}
+/**
+ * Apply trigram-specific guard pose to a KeyframeConfig
+ *
+ * Sets the complete body position for the specified trigram stance,
+ * including arms, legs, torso, and pelvis. This creates authentic
+ * Korean martial arts posture for each of the eight trigram stances.
+ *
+ * @param config - KeyframeConfig to apply guard pose to
+ * @param stance - Trigram stance (e.g., TrigramStance.GEON)
+ * @param options - Application options
+ *
+ * @example
+ * ```typescript
+ * // Full guard pose application
+ * applyTrigramGuardToConfig(kf, TrigramStance.GEON);
+ *
+ * // Arms only (for locomotion that sets its own leg positions)
+ * applyTrigramGuardToConfig(kf, TrigramStance.GEON, {
+ *   includeLegs: false,
+ *   includePelvis: false
+ * });
+ *
+ * // Blended for walk cycle transitions
+ * applyTrigramGuardToConfig(kf, TrigramStance.TAE, {
+ *   blendFactor: 0.7
+ * });
+ * ```
+ *
+ * @korean 팔괘방어자세설정적용
+ */
+export declare function applyTrigramGuardToConfig(config: KeyframeConfig, stance: TrigramStance, options?: TrigramGuardOptions): void;
+/**
+ * Get guard arm base rotations without swing for a trigram
+ *
+ * Returns the base arm position for the trigram's guard pose.
+ * Use this when you want to manually add swing offsets.
+ *
+ * @param stance - Trigram stance
+ * @returns Left and right arm base rotations
+ *
+ * @korean 팔자세베이스가져오기
+ */
+export declare function getGuardArmBase(stance: TrigramStance): {
+    left: {
+        shoulder: [number, number, number];
+        elbow: [number, number, number];
+    };
+    right: {
+        shoulder: [number, number, number];
+        elbow: [number, number, number];
+    };
+};
+//# sourceMappingURL=TrigramGuardApplicator.d.ts.map

package/lib/systems/animation/builders/TrigramGuardApplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrigramGuardApplicator.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/builders/TrigramGuardApplicator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAY5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMvD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CACxC,MAAM,CAAC,aAAa,EAAE,eAAe,CAAC,CAU9B,CAAC;AAMX;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,2BAA2B;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+CN;AAwGD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG;IACtD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;IACF,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;CACH,CAoCA"}

package/lib/systems/animation/builders/TrigramGuardApplicator.js

@@ -0,0 +1,185 @@
+import { TrigramStance } from "../../../types/common.js";
+import { BoneName } from "../../../types/skeletal.js";
+import { GAM_WATER_GUARD_POSE, GAN_MOUNTAIN_GUARD_POSE, GEON_HIGH_GUARD_POSE, GON_EARTH_GUARD_POSE, JIN_THUNDER_GUARD_POSE, LI_FIRE_GUARD_POSE, SON_WIND_GUARD_POSE, TAE_FLUID_GUARD_POSE, getGuardPoseForStance } from "../catalogs/StanceGuardPoses.js";
+//#region src/systems/animation/builders/TrigramGuardApplicator.ts
+/**
+* Trigram Guard Applicator
+*
+* Applies full trigram-specific guard poses to animation keyframes.
+* Unlike the generic `withGuard()` method that only sets arm positions,
+* this applicator sets the complete body position including:
+* - Arms (shoulder, elbow, wrist)
+* - Legs (hip, knee, ankle)
+* - Torso and pelvis rotation
+*
+* This ensures that walk/run/idle animations maintain proper
+* trigram-specific guard positions for authentic Korean martial arts movement.
+*
+* @module systems/animation/builders/TrigramGuardApplicator
+* @korean 팔괘방어자세적용기
+*/
+/**
+* Direct access to guard poses by trigram stance name
+* Avoids repeated function calls in animation loops
+*
+* @korean 방어자세직접접근맵
+*/
+var TRIGRAM_GUARD_POSES = {
+	[TrigramStance.GEON]: GEON_HIGH_GUARD_POSE,
+	[TrigramStance.TAE]: TAE_FLUID_GUARD_POSE,
+	[TrigramStance.LI]: LI_FIRE_GUARD_POSE,
+	[TrigramStance.JIN]: JIN_THUNDER_GUARD_POSE,
+	[TrigramStance.SON]: SON_WIND_GUARD_POSE,
+	[TrigramStance.GAM]: GAM_WATER_GUARD_POSE,
+	[TrigramStance.GAN]: GAN_MOUNTAIN_GUARD_POSE,
+	[TrigramStance.GON]: GON_EARTH_GUARD_POSE
+};
+/**
+* Default options for full guard pose application
+*/
+var DEFAULT_OPTIONS = {
+	includeArms: true,
+	includeLegs: true,
+	includeTorso: true,
+	includePelvis: true,
+	blendFactor: 1,
+	laterality: "right"
+};
+/**
+* Apply trigram-specific guard pose to a KeyframeConfig
+*
+* Sets the complete body position for the specified trigram stance,
+* including arms, legs, torso, and pelvis. This creates authentic
+* Korean martial arts posture for each of the eight trigram stances.
+*
+* @param config - KeyframeConfig to apply guard pose to
+* @param stance - Trigram stance (e.g., TrigramStance.GEON)
+* @param options - Application options
+*
+* @example
+* ```typescript
+* // Full guard pose application
+* applyTrigramGuardToConfig(kf, TrigramStance.GEON);
+*
+* // Arms only (for locomotion that sets its own leg positions)
+* applyTrigramGuardToConfig(kf, TrigramStance.GEON, {
+*   includeLegs: false,
+*   includePelvis: false
+* });
+*
+* // Blended for walk cycle transitions
+* applyTrigramGuardToConfig(kf, TrigramStance.TAE, {
+*   blendFactor: 0.7
+* });
+* ```
+*
+* @korean 팔괘방어자세설정적용
+*/
+function applyTrigramGuardToConfig(config, stance, options = {}) {
+	const opts = {
+		...DEFAULT_OPTIONS,
+		...options
+	};
+	const guardPose = opts.laterality === "right" ? TRIGRAM_GUARD_POSES[stance] : getGuardPoseForStance(stance, opts.laterality);
+	if (!guardPose) {
+		console.warn(`[TrigramGuardApplicator] No guard pose found for stance: ${stance}`);
+		return;
+	}
+	const blend = opts.blendFactor;
+	if (opts.includeArms) applyArmsToConfig(config, guardPose, blend);
+	if (opts.includeLegs) applyLegsToConfig(config, guardPose, blend);
+	if (opts.includeTorso) config.rotate(BoneName.SPINE_UPPER, guardPose.torso.x * blend, guardPose.torso.y * blend, guardPose.torso.z * blend);
+	if (opts.includePelvis) config.rotate(BoneName.PELVIS, guardPose.pelvis.x * blend, guardPose.pelvis.y * blend, guardPose.pelvis.z * blend);
+}
+/**
+* Apply arm positions from guard pose to config
+*/
+function applyArmsToConfig(config, guardPose, blend) {
+	config.rotate(BoneName.SHOULDER_L, guardPose.leftArm.shoulder.x * blend, guardPose.leftArm.shoulder.y * blend, guardPose.leftArm.shoulder.z * blend);
+	config.rotate(BoneName.ELBOW_L, guardPose.leftArm.elbow.x * blend, guardPose.leftArm.elbow.y * blend, guardPose.leftArm.elbow.z * blend);
+	config.rotate(BoneName.WRIST_L, guardPose.leftArm.wrist.x * blend, guardPose.leftArm.wrist.y * blend, guardPose.leftArm.wrist.z * blend);
+	config.rotate(BoneName.SHOULDER_R, guardPose.rightArm.shoulder.x * blend, guardPose.rightArm.shoulder.y * blend, guardPose.rightArm.shoulder.z * blend);
+	config.rotate(BoneName.ELBOW_R, guardPose.rightArm.elbow.x * blend, guardPose.rightArm.elbow.y * blend, guardPose.rightArm.elbow.z * blend);
+	config.rotate(BoneName.WRIST_R, guardPose.rightArm.wrist.x * blend, guardPose.rightArm.wrist.y * blend, guardPose.rightArm.wrist.z * blend);
+}
+/**
+* Apply leg positions from guard pose to config
+*/
+function applyLegsToConfig(config, guardPose, blend) {
+	config.rotate(BoneName.HIP_L, guardPose.leftLeg.hip.x * blend, guardPose.leftLeg.hip.y * blend, guardPose.leftLeg.hip.z * blend);
+	config.rotate(BoneName.KNEE_L, guardPose.leftLeg.knee.x * blend, guardPose.leftLeg.knee.y * blend, guardPose.leftLeg.knee.z * blend);
+	config.rotate(BoneName.FOOT_L, guardPose.leftLeg.ankle.x * blend, guardPose.leftLeg.ankle.y * blend, guardPose.leftLeg.ankle.z * blend);
+	config.rotate(BoneName.HIP_R, guardPose.rightLeg.hip.x * blend, guardPose.rightLeg.hip.y * blend, guardPose.rightLeg.hip.z * blend);
+	config.rotate(BoneName.KNEE_R, guardPose.rightLeg.knee.x * blend, guardPose.rightLeg.knee.y * blend, guardPose.rightLeg.knee.z * blend);
+	config.rotate(BoneName.FOOT_R, guardPose.rightLeg.ankle.x * blend, guardPose.rightLeg.ankle.y * blend, guardPose.rightLeg.ankle.z * blend);
+}
+/**
+* Get guard arm base rotations without swing for a trigram
+*
+* Returns the base arm position for the trigram's guard pose.
+* Use this when you want to manually add swing offsets.
+*
+* @param stance - Trigram stance
+* @returns Left and right arm base rotations
+*
+* @korean 팔자세베이스가져오기
+*/
+function getGuardArmBase(stance) {
+	const guardPose = TRIGRAM_GUARD_POSES[stance];
+	if (!guardPose) return {
+		left: {
+			shoulder: [
+				-.6,
+				.4,
+				.3
+			],
+			elbow: [
+				0,
+				0,
+				-1.6
+			]
+		},
+		right: {
+			shoulder: [
+				-.6,
+				-.4,
+				-.3
+			],
+			elbow: [
+				0,
+				0,
+				1.6
+			]
+		}
+	};
+	return {
+		left: {
+			shoulder: [
+				guardPose.leftArm.shoulder.x,
+				guardPose.leftArm.shoulder.y,
+				guardPose.leftArm.shoulder.z
+			],
+			elbow: [
+				guardPose.leftArm.elbow.x,
+				guardPose.leftArm.elbow.y,
+				guardPose.leftArm.elbow.z
+			]
+		},
+		right: {
+			shoulder: [
+				guardPose.rightArm.shoulder.x,
+				guardPose.rightArm.shoulder.y,
+				guardPose.rightArm.shoulder.z
+			],
+			elbow: [
+				guardPose.rightArm.elbow.x,
+				guardPose.rightArm.elbow.y,
+				guardPose.rightArm.elbow.z
+			]
+		}
+	};
+}
+//#endregion
+export { TRIGRAM_GUARD_POSES, applyTrigramGuardToConfig, getGuardArmBase };
+
+//# sourceMappingURL=TrigramGuardApplicator.js.map

package/lib/systems/animation/builders/TrigramGuardApplicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrigramGuardApplicator.js","names":[],"sources":["../../../../src/systems/animation/builders/TrigramGuardApplicator.ts"],"sourcesContent":["/**\n * Trigram Guard Applicator\n *\n * Applies full trigram-specific guard poses to animation keyframes.\n * Unlike the generic `withGuard()` method that only sets arm positions,\n * this applicator sets the complete body position including:\n * - Arms (shoulder, elbow, wrist)\n * - Legs (hip, knee, ankle)\n * - Torso and pelvis rotation\n *\n * This ensures that walk/run/idle animations maintain proper\n * trigram-specific guard positions for authentic Korean martial arts movement.\n *\n * @module systems/animation/builders/TrigramGuardApplicator\n * @korean 팔괘방어자세적용기\n */\n\nimport { TrigramStance } from \"@/types/common\";\nimport type { StanceGuardPose } from \"@/types/skeletal\";\nimport { BoneName } from \"@/types/skeletal\";\nimport type { StanceLaterality } from \"../../trigram/types\";\nimport {\n  GAM_WATER_GUARD_POSE,\n  GAN_MOUNTAIN_GUARD_POSE,\n  GEON_HIGH_GUARD_POSE,\n  getGuardPoseForStance,\n  GON_EARTH_GUARD_POSE,\n  JIN_THUNDER_GUARD_POSE,\n  LI_FIRE_GUARD_POSE,\n  SON_WIND_GUARD_POSE,\n  TAE_FLUID_GUARD_POSE,\n} from \"../catalogs/StanceGuardPoses\";\nimport type { KeyframeConfig } from \"./KeyframeConfig\";\n\n// ═══════════════════════════════════════════════════════════════════════════\n// DIRECT GUARD POSE ACCESS MAP (For performance in locomotion)\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Direct access to guard poses by trigram stance name\n * Avoids repeated function calls in animation loops\n *\n * @korean 방어자세직접접근맵\n */\nexport const TRIGRAM_GUARD_POSES: Readonly<\n  Record<TrigramStance, StanceGuardPose>\n> = {\n  [TrigramStance.GEON]: GEON_HIGH_GUARD_POSE,\n  [TrigramStance.TAE]: TAE_FLUID_GUARD_POSE,\n  [TrigramStance.LI]: LI_FIRE_GUARD_POSE,\n  [TrigramStance.JIN]: JIN_THUNDER_GUARD_POSE,\n  [TrigramStance.SON]: SON_WIND_GUARD_POSE,\n  [TrigramStance.GAM]: GAM_WATER_GUARD_POSE,\n  [TrigramStance.GAN]: GAN_MOUNTAIN_GUARD_POSE,\n  [TrigramStance.GON]: GON_EARTH_GUARD_POSE,\n} as const;\n\n// ═══════════════════════════════════════════════════════════════════════════\n// APPLICATION OPTIONS\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Options for applying trigram guard pose\n *\n * @korean 팔괘방어자세적용옵션\n */\nexport interface TrigramGuardOptions {\n  /** Apply arm positions (shoulder, elbow, wrist) */\n  readonly includeArms?: boolean;\n  /** Apply leg positions (hip, knee, ankle) */\n  readonly includeLegs?: boolean;\n  /** Apply torso rotation */\n  readonly includeTorso?: boolean;\n  /** Apply pelvis rotation */\n  readonly includePelvis?: boolean;\n  /** Blend factor 0-1 for partial application (locomotion blending) */\n  readonly blendFactor?: number;\n  /** Stance laterality (\"left\" or \"right\") */\n  readonly laterality?: StanceLaterality;\n}\n\n/**\n * Default options for full guard pose application\n */\nconst DEFAULT_OPTIONS: Required<TrigramGuardOptions> = {\n  includeArms: true,\n  includeLegs: true,\n  includeTorso: true,\n  includePelvis: true,\n  blendFactor: 1.0,\n  laterality: \"right\",\n} as const;\n\n// ═══════════════════════════════════════════════════════════════════════════\n// CORE APPLICATION FUNCTION\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Apply trigram-specific guard pose to a KeyframeConfig\n *\n * Sets the complete body position for the specified trigram stance,\n * including arms, legs, torso, and pelvis. This creates authentic\n * Korean martial arts posture for each of the eight trigram stances.\n *\n * @param config - KeyframeConfig to apply guard pose to\n * @param stance - Trigram stance (e.g., TrigramStance.GEON)\n * @param options - Application options\n *\n * @example\n * ```typescript\n * // Full guard pose application\n * applyTrigramGuardToConfig(kf, TrigramStance.GEON);\n *\n * // Arms only (for locomotion that sets its own leg positions)\n * applyTrigramGuardToConfig(kf, TrigramStance.GEON, {\n *   includeLegs: false,\n *   includePelvis: false\n * });\n *\n * // Blended for walk cycle transitions\n * applyTrigramGuardToConfig(kf, TrigramStance.TAE, {\n *   blendFactor: 0.7\n * });\n * ```\n *\n * @korean 팔괘방어자세설정적용\n */\nexport function applyTrigramGuardToConfig(\n  config: KeyframeConfig,\n  stance: TrigramStance,\n  options: TrigramGuardOptions = {},\n): void {\n  const opts = { ...DEFAULT_OPTIONS, ...options };\n\n  // Get guard pose for stance and laterality\n  const guardPose =\n    opts.laterality === \"right\"\n      ? TRIGRAM_GUARD_POSES[stance]\n      : getGuardPoseForStance(stance, opts.laterality);\n\n  if (!guardPose) {\n    console.warn(\n      `[TrigramGuardApplicator] No guard pose found for stance: ${stance}`,\n    );\n    return;\n  }\n\n  const blend = opts.blendFactor;\n\n  // Apply arm positions\n  if (opts.includeArms) {\n    applyArmsToConfig(config, guardPose, blend);\n  }\n\n  // Apply leg positions\n  if (opts.includeLegs) {\n    applyLegsToConfig(config, guardPose, blend);\n  }\n\n  // Apply torso rotation\n  if (opts.includeTorso) {\n    config.rotate(\n      BoneName.SPINE_UPPER,\n      guardPose.torso.x * blend,\n      guardPose.torso.y * blend,\n      guardPose.torso.z * blend,\n    );\n  }\n\n  // Apply pelvis rotation\n  if (opts.includePelvis) {\n    config.rotate(\n      BoneName.PELVIS,\n      guardPose.pelvis.x * blend,\n      guardPose.pelvis.y * blend,\n      guardPose.pelvis.z * blend,\n    );\n  }\n}\n\n/**\n * Apply arm positions from guard pose to config\n */\nfunction applyArmsToConfig(\n  config: KeyframeConfig,\n  guardPose: StanceGuardPose,\n  blend: number,\n): void {\n  // Left arm\n  config.rotate(\n    BoneName.SHOULDER_L,\n    guardPose.leftArm.shoulder.x * blend,\n    guardPose.leftArm.shoulder.y * blend,\n    guardPose.leftArm.shoulder.z * blend,\n  );\n  config.rotate(\n    BoneName.ELBOW_L,\n    guardPose.leftArm.elbow.x * blend,\n    guardPose.leftArm.elbow.y * blend,\n    guardPose.leftArm.elbow.z * blend,\n  );\n  config.rotate(\n    BoneName.WRIST_L,\n    guardPose.leftArm.wrist.x * blend,\n    guardPose.leftArm.wrist.y * blend,\n    guardPose.leftArm.wrist.z * blend,\n  );\n\n  // Right arm\n  config.rotate(\n    BoneName.SHOULDER_R,\n    guardPose.rightArm.shoulder.x * blend,\n    guardPose.rightArm.shoulder.y * blend,\n    guardPose.rightArm.shoulder.z * blend,\n  );\n  config.rotate(\n    BoneName.ELBOW_R,\n    guardPose.rightArm.elbow.x * blend,\n    guardPose.rightArm.elbow.y * blend,\n    guardPose.rightArm.elbow.z * blend,\n  );\n  config.rotate(\n    BoneName.WRIST_R,\n    guardPose.rightArm.wrist.x * blend,\n    guardPose.rightArm.wrist.y * blend,\n    guardPose.rightArm.wrist.z * blend,\n  );\n}\n\n/**\n * Apply leg positions from guard pose to config\n */\nfunction applyLegsToConfig(\n  config: KeyframeConfig,\n  guardPose: StanceGuardPose,\n  blend: number,\n): void {\n  // Left leg\n  config.rotate(\n    BoneName.HIP_L,\n    guardPose.leftLeg.hip.x * blend,\n    guardPose.leftLeg.hip.y * blend,\n    guardPose.leftLeg.hip.z * blend,\n  );\n  config.rotate(\n    BoneName.KNEE_L,\n    guardPose.leftLeg.knee.x * blend,\n    guardPose.leftLeg.knee.y * blend,\n    guardPose.leftLeg.knee.z * blend,\n  );\n  config.rotate(\n    BoneName.FOOT_L,\n    guardPose.leftLeg.ankle.x * blend,\n    guardPose.leftLeg.ankle.y * blend,\n    guardPose.leftLeg.ankle.z * blend,\n  );\n\n  // Right leg\n  config.rotate(\n    BoneName.HIP_R,\n    guardPose.rightLeg.hip.x * blend,\n    guardPose.rightLeg.hip.y * blend,\n    guardPose.rightLeg.hip.z * blend,\n  );\n  config.rotate(\n    BoneName.KNEE_R,\n    guardPose.rightLeg.knee.x * blend,\n    guardPose.rightLeg.knee.y * blend,\n    guardPose.rightLeg.knee.z * blend,\n  );\n  config.rotate(\n    BoneName.FOOT_R,\n    guardPose.rightLeg.ankle.x * blend,\n    guardPose.rightLeg.ankle.y * blend,\n    guardPose.rightLeg.ankle.z * blend,\n  );\n}\n\n// ═══════════════════════════════════════════════════════════════════════════\n// GUARD ARM HELPERS\n// ═══════════════════════════════════════════════════════════════════════════\n\n/**\n * Get guard arm base rotations without swing for a trigram\n *\n * Returns the base arm position for the trigram's guard pose.\n * Use this when you want to manually add swing offsets.\n *\n * @param stance - Trigram stance\n * @returns Left and right arm base rotations\n *\n * @korean 팔자세베이스가져오기\n */\nexport function getGuardArmBase(stance: TrigramStance): {\n  left: {\n    shoulder: [number, number, number];\n    elbow: [number, number, number];\n  };\n  right: {\n    shoulder: [number, number, number];\n    elbow: [number, number, number];\n  };\n} {\n  const guardPose = TRIGRAM_GUARD_POSES[stance];\n  if (!guardPose) {\n    // Fallback neutral guard\n    return {\n      left: { shoulder: [-0.6, 0.4, 0.3], elbow: [0, 0, -1.6] },\n      right: { shoulder: [-0.6, -0.4, -0.3], elbow: [0, 0, 1.6] },\n    };\n  }\n\n  return {\n    left: {\n      shoulder: [\n        guardPose.leftArm.shoulder.x,\n        guardPose.leftArm.shoulder.y,\n        guardPose.leftArm.shoulder.z,\n      ],\n      elbow: [\n        guardPose.leftArm.elbow.x,\n        guardPose.leftArm.elbow.y,\n        guardPose.leftArm.elbow.z,\n      ],\n    },\n    right: {\n      shoulder: [\n        guardPose.rightArm.shoulder.x,\n        guardPose.rightArm.shoulder.y,\n        guardPose.rightArm.shoulder.z,\n      ],\n      elbow: [\n        guardPose.rightArm.elbow.x,\n        guardPose.rightArm.elbow.y,\n        guardPose.rightArm.elbow.z,\n      ],\n    },\n  };\n}\n"],"mappings":"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"}

package/lib/systems/animation/builders/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Builder and pose utilities sub-package
+ *
+ * Fluent builders, keyframe helpers, phase applicators, and rig utilities
+ * for constructing skeletal animations with integrated anatomy state.
+ */
+export { AnimationBuilder, AnimationPatternHelpers, AnimationPresets, BoneRotationHelpers, KeyframeFactories, } from "./AnimationBuilder";
+export * from "./MartialArtsAnimationBuilder";
+export { KeyframeConfig } from "./KeyframeConfig";
+export type { HandHighlightMode } from "./KeyframeConfig";
+export { applyKeyframeToRig, blendKeyframes, easeIn, easeInOut, easeLinear, easeOut, findSurroundingKeyframes, getEasingFunction, getInterpolatedKeyframe, interpolatePosition, interpolateRotation, updateAnimation, } from "./KeyframeInterpolation";
+export { applyHandPoseToConfig, applyHandPoseToKeyframe, } from "./HandPoseApplicator";
+export { applyHighPeakPhaseToConfig, applyKickPhaseToConfig, applyRoundhousePhaseToConfig, applySideKickPhaseToConfig, getKickPhase, } from "./KickPhaseApplicator";
+export type { KickPhaseName, KickSide } from "./KickPhaseApplicator";
+export { applyMartialPoseToConfig, applyMartialPoseToKeyframe, getMartialPose, } from "./MartialPoseApplicator";
+export { applyPunchPhaseToConfig, getPunchPhase } from "./PunchPhaseApplicator";
+export type { PunchPhaseName, PunchSide } from "./PunchPhaseApplicator";
+export { TECHNIQUE_HAND_POSES, createInitialHandAnimationState, getHandPose, getTechniqueHandPose, updateHandAnimationState, } from "./HandPoses";
+export * from "./KoreanGuardPositions";
+export * from "./MartialArtsConstants";
+export { BONE_CHAINS, JOINT_CONSTRAINTS, TORSO_CONSTRAINTS, applyJointConstraint, calculateHipRotationPowerModifier, createBone, createHandBones, createHumanoidRig, createHumanoidRigWithHands, createScaledHumanoidRig, getBoneWorldPosition, getBoneWorldRotation, resetBoneToRestPose, resetRigToRestPose, } from "./SkeletonRig";
+export * from "./AnimationFactoryPresets";
+//# sourceMappingURL=index.d.ts.map

package/lib/systems/animation/builders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,cAAc,+BAA+B,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,MAAM,EACN,SAAS,EACT,UAAU,EACV,OAAO,EACP,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EACL,oBAAoB,EACpB,+BAA+B,EAC/B,WAAW,EACX,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,iCAAiC,EACjC,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,cAAc,2BAA2B,CAAC"}

package/lib/systems/animation/builders/index.js

@@ -0,0 +1,13 @@
+import "./KeyframeInterpolation.js";
+import "./MartialArtsConstants.js";
+import "./KoreanGuardPositions.js";
+import "./KeyframeConfig.js";
+import "./HandPoseApplicator.js";
+import "./KickPhaseApplicator.js";
+import "./MartialPoseApplicator.js";
+import "./PunchPhaseApplicator.js";
+import "./MartialArtsAnimationBuilder.js";
+import "./AnimationBuilder.js";
+import "./HandPoses.js";
+import "./SkeletonRig.js";
+import "./AnimationFactoryPresets.js";