name: motion-pipeline\npromoted_to: game-dev\nuser-invocable: false\ndescription: \"CPU-only motion data processing pipeline for game animation: BVH import, contact detection, root decomposition, motion blending, FABRIK IK. No GPU required.\"\nallowed-tools:
\nCPU-only motion data processing pipeline for game animation, inspired by Meta's\nai4animationpy framework (CC BY-NC 4.0). All operations run on numpy and scipy\nwith no GPU or PyTorch required.
\nai4animationpy's Math/Tensor.py imports torch unconditionally at the top\nlevel, which propagates through every module (Animation, Import, IK, Math).\nThis means zero ai4animationpy modules are importable without PyTorch installed.\nThe standalone implementations in scripts/motion-pipeline.py replicate the\nkey algorithms from their source code using only numpy + scipy.
# Create venv (one-time)\npython3 -m venv /home/feedgen/vexjoy-agent/motion-pipeline-env/\n\n# Install CPU-only deps\nmotion-pipeline-env/bin/pip install numpy scipy pygltflib Pillow\n\n# Verify\nmotion-pipeline-env/bin/python -c \"import numpy; import scipy; import pygltflib; print('OK')\"\nThe venv is gitignored. The skill documents setup; it does not commit the venv.
\nAll commands output JSON to stdout. Errors go to stderr with exit code 1.
\nParse a BVH mocap file and print a motion summary.
\nmotion-pipeline-env/bin/python scripts/motion-pipeline.py import-bvh FILE \\\n [--scale 0.01] # scale cm->m for CMU/Mixamo files\nOutput fields: name, num_frames, num_joints, framerate,\ntotal_time_seconds, bones[], root_trajectory (x/y/z range).
Detect ground contact frames per bone (foot, hand) using height + velocity\nthresholds. Replicates ContactModule.GetContacts() from ai4animationpy.
motion-pipeline-env/bin/python scripts/motion-pipeline.py extract-contacts FILE \\\n --bones LeftFoot RightFoot \\\n --height 0.1 \\\n --vel 0.5\nOutput: { \"bones\": { \"<name>\": { \"contact_frames\": [...] } }, \"total_frames\": N }.
Split motion into root trajectory (WHERE + HOW) and per-joint local Euler\nangles (POSE). Implements the RootModule / MotionModule decomposition pattern.
\nmotion-pipeline-env/bin/python scripts/motion-pipeline.py decompose FILE \\\n --hip Hips\nOutput: root_trajectory.positions[], root_trajectory.velocities[],\nroot_trajectory.facing_directions[], per_joint_euler_zyx_degrees{}.
First 5 frames shown in stdout; full data requires piping to a file.
\nBlend two BVH clips at a fixed alpha using SLERP rotations and LERP positions.\nClips must share the same bone hierarchy.
\nmotion-pipeline-env/bin/python scripts/motion-pipeline.py blend FILE_A FILE_B \\\n --alpha 0.5\nOutput: summary of the blended motion.
\nRun FABRIK inverse kinematics on a bone chain at a single frame.
\nmotion-pipeline-env/bin/python scripts/motion-pipeline.py solve-ik FILE \\\n --chain Hips:LeftFoot \\\n --target 0.2,0.05,0.3 \\\n --frame 10\nOutput: chain[], target[], initial_positions[], solved_positions[],\nend_effector_error (metres).
Convert a BVH mocap file into a TypeScript MoveFrame function compatible with\nroad-to-aew's wrestlingMoves.ts interface. Outputs keyframe-interpolated\nTypeScript to stdout (and optionally a file).
motion-pipeline-env/bin/python scripts/generate-move-ts.py BVH MOVE_NAME \\\n [--scale 0.01] \\\n [--contact-bones LeftToeBase RightToeBase LeftHand RightHand] \\\n [--num-keyframes 12] \\\n [--hip-bone Hips] \\\n [--output path/to/output.ts]\n| Argument | \nDefault | \nPurpose | \n
|---|---|---|
BVH | \n— | \nPath to .bvh mocap file | \n
MOVE_NAME | \n— | \nKebab-case name (e.g. roundhouse-kick) used in TS identifiers | \n
--scale | \n0.01 | \nPosition scale; 0.01 converts cm→m for CMU/Mixamo files | \n
--contact-bones | \nLeftToeBase RightToeBase LeftHand RightHand | \nBones used to detect the impact window | \n
--num-keyframes | \n12 | \nKeyframe count in the output array (min 2) | \n
--hip-bone | \nHips | \nRoot bone name for trajectory extraction | \n
--output | \nstdout only | \nWrite TS to this file path in addition to stdout | \n
Implementation note: The script imports motion-pipeline.py as a module\nvia importlib rather than calling it as a subprocess. This bypasses the 5-frame\ntruncation applied by the decompose CLI command, giving access to all frames.
Output structure:
\n// Generated from roundhouse-kick.bvh on 2026-04-13\n// Keyframes: 12, Impact window: 0.45-0.55\nconst ROUNDHOUSE_KICK_KEYFRAMES = [...] as const;\n\nexport function getRoundhouseKick(progress: number): MoveFrame {\n // keyframe lookup + linear interpolation\n // isImpact based on detected contact window\n return { attacker, defender, isImpact };\n}\nThe attacker's offsetX/Y/Z are root trajectory positions normalized to\nstart at origin. Rotations are in radians (converted from the BVH's Euler\nZYX degrees). The defender reaction is computed procedurally: pushed backward\nat impact, eases to mat post-impact.
Impact detection: The script finds the first run of 3+ consecutive contact\nframes across the specified bones. For strike moves, this captures the moment\nof hit. For walking/idle clips (feet always down), the window will be frame-0\nand isImpact will be nearly never true — this is correct behavior.
Validation: The script prints a summary to stderr including trajectory\nrange, impact window, and a structural syntax check. Exit code 1 if validation\nfails.
\nThe decomposition from ai4animationpy becomes a design contract for all\ngame animation work:
\nAnimation State\n root_trajectory -- WHERE (position, velocity, facing direction)\n per_joint_euler -- HOW (local pose in ZYX Euler degrees)\n contact_frames -- WHAT (contact states for feet, hands)\n [guidance] -- WHY (intent; handled at game engine layer)\nThis separation enables:
\n| ai4animationpy module | \nThis script equivalent | \nNotes | \n
|---|---|---|
Import/BVHImporter.BVH | \nload_bvh() | \nSame parsing logic; scipy replaces torch | \n
Animation/Motion | \nMotion dataclass | \nnumpy-only; no torch backend | \n
Animation/ContactModule | \nextract_contacts() | \nHeight + velocity criterion identical | \n
Animation/RootModule | \ndecompose() root section | \nFK decomposition via matrix inverse | \n
Animation/MotionModule | \ndecompose() joint section | \nLocal Euler extraction via scipy | \n
IK/FABRIK | \nsolve_ik_fabrik() | \nAlgorithm identical; no Actor dependency | \n
| Downstream agent | \nData consumed | \n
|---|---|
rive-skeletal-animator | \nper_joint_euler_zyx_degrees from decompose | \n
pixijs-combat-renderer | \ncontact_frames from extract-contacts | \n
combat-effects-upgrade | \ncontact_frames (impact timing) | \n
game-asset-generator | \nProduces source BVH files for this pipeline | \n
A walking cycle from ai4animationpy demos is available at:
\n/tmp/ai4animationpy/Demos/BVHLoading/WalkingStickLeft_BR.bvh\nThis is a full-body biped walking clip from the Geno character rig.
\n/tmp/ai4animationpy (cloned locally)Math/Tensor.py line 5.\nNo conditional import path exists. Standalone implementations are the correct approach.