Motion Pipeline

Motion Pipeline Skill

CPU-only motion data processing pipeline for game animation, inspired by Meta's ai4animationpy framework (CC BY-NC 4.0). All operations run on numpy and scipy with no GPU or PyTorch required.

Why standalone implementations?

ai4animationpy's Math/Tensor.py imports torch unconditionally at the top level, which propagates through every module (Animation, Import, IK, Math). This means zero ai4animationpy modules are importable without PyTorch installed. The standalone implementations in scripts/motion-pipeline.py replicate the key algorithms from their source code using only numpy + scipy.

Environment setup

bashCopy code
# Create venv (one-time)
python3 -m venv /home/feedgen/vexjoy-agent/motion-pipeline-env/

# Install CPU-only deps
motion-pipeline-env/bin/pip install numpy scipy pygltflib Pillow

# Verify
motion-pipeline-env/bin/python -c "import numpy; import scipy; import pygltflib; print('OK')"

The venv is gitignored. The skill documents setup; it does not commit the venv.

Commands

All commands output JSON to stdout. Errors go to stderr with exit code 1.

import-bvh

Parse a BVH mocap file and print a motion summary.

bashCopy code
motion-pipeline-env/bin/python scripts/motion-pipeline.py import-bvh FILE \
  [--scale 0.01]   # scale cm->m for CMU/Mixamo files

Output fields: name, num_frames, num_joints, framerate, total_time_seconds, bones[], root_trajectory (x/y/z range).

extract-contacts

Detect ground contact frames per bone (foot, hand) using height + velocity thresholds. Replicates ContactModule.GetContacts() from ai4animationpy.

bashCopy code
motion-pipeline-env/bin/python scripts/motion-pipeline.py extract-contacts FILE \
  --bones LeftFoot RightFoot \
  --height 0.1 \
  --vel 0.5

Output: { "bones": { "<name>": { "contact_frames": [...] } }, "total_frames": N }.

decompose

Split motion into root trajectory (WHERE + HOW) and per-joint local Euler angles (POSE). Implements the RootModule / MotionModule decomposition pattern.

bashCopy code
motion-pipeline-env/bin/python scripts/motion-pipeline.py decompose FILE \
  --hip Hips

Output: root_trajectory.positions[], root_trajectory.velocities[], root_trajectory.facing_directions[], per_joint_euler_zyx_degrees{}.

First 5 frames shown in stdout; full data requires piping to a file.

blend

Blend two BVH clips at a fixed alpha using SLERP rotations and LERP positions. Clips must share the same bone hierarchy.

bashCopy code
motion-pipeline-env/bin/python scripts/motion-pipeline.py blend FILE_A FILE_B \
  --alpha 0.5

Output: summary of the blended motion.

solve-ik

Run FABRIK inverse kinematics on a bone chain at a single frame.

bashCopy code
motion-pipeline-env/bin/python scripts/motion-pipeline.py solve-ik FILE \
  --chain Hips:LeftFoot \
  --target 0.2,0.05,0.3 \
  --frame 10

Output: chain[], target[], initial_positions[], solved_positions[], end_effector_error (metres).

generate-move-ts

Convert a BVH mocap file into a TypeScript MoveFrame function compatible with road-to-aew's wrestlingMoves.ts interface. Outputs keyframe-interpolated TypeScript to stdout (and optionally a file).

bashCopy code
motion-pipeline-env/bin/python scripts/generate-move-ts.py BVH MOVE_NAME \
  [--scale 0.01] \
  [--contact-bones LeftToeBase RightToeBase LeftHand RightHand] \
  [--num-keyframes 12] \
  [--hip-bone Hips] \
  [--output path/to/output.ts]

Implementation note: The script imports motion-pipeline.py as a module via importlib rather than calling it as a subprocess. This bypasses the 5-frame truncation applied by the decompose CLI command, giving access to all frames.

Output structure:

typescriptCopy code
// Generated from roundhouse-kick.bvh on 2026-04-13
// Keyframes: 12, Impact window: 0.45-0.55
const ROUNDHOUSE_KICK_KEYFRAMES = [...] as const;

export function getRoundhouseKick(progress: number): MoveFrame {
  // keyframe lookup + linear interpolation
  // isImpact based on detected contact window
  return { attacker, defender, isImpact };
}

The attacker's offsetX/Y/Z are root trajectory positions normalized to start at origin. Rotations are in radians (converted from the BVH's Euler ZYX degrees). The defender reaction is computed procedurally: pushed backward at impact, eases to mat post-impact.

Impact detection: The script finds the first run of 3+ consecutive contact frames across the specified bones. For strike moves, this captures the moment of hit. For walking/idle clips (feet always down), the window will be frame-0 and isImpact will be nearly never true — this is correct behavior.

Validation: The script prints a summary to stderr including trajectory range, impact window, and a structural syntax check. Exit code 1 if validation fails.

Data architecture pattern

The decomposition from ai4animationpy becomes a design contract for all game animation work:

Copy code
Animation State
  root_trajectory   -- WHERE (position, velocity, facing direction)
  per_joint_euler   -- HOW (local pose in ZYX Euler degrees)
  contact_frames    -- WHAT (contact states for feet, hands)
  [guidance]        -- WHY (intent; handled at game engine layer)

This separation enables:

• Different movement speeds without distorting body pose
• Contact-driven game events (damage triggers, sound, VFX)
• AI/input guidance independent of motion playback

Source reference: ai4animationpy modules adopted

Integration points

Sample BVH for testing

A walking cycle from ai4animationpy demos is available at:

Copy code
/tmp/ai4animationpy/Demos/BVHLoading/WalkingStickLeft_BR.bvh

This is a full-body biped walking clip from the Geno character rig.

Reference: ai4animationpy

• Source: /tmp/ai4animationpy (cloned locally)
• License: CC BY-NC 4.0 (non-commercial; aligned with hobby game projects)
• GitHub: https://github.com/facebookresearch/ai4animationpy
• Key finding: ALL modules require torch at import time via Math/Tensor.py line 5. No conditional import path exists. Standalone implementations are the correct approach.