README.md

---
license: mit
tags:
  - physics
  - animation
  - reinforcement-learning
  - motion-imitation
  - browser
---

# physgait-weights

Trained locomotion / combat weights for the **Ashen Depths** neural souls demo
([Space](https://huggingface.co/spaces/Quazim0t0/AshenDepths)). These are the
*physics gait* weights: a character that learns to move by driving a rigid-body
ragdoll, rather than by playing back a mocap clip.

![physics gait trainer — all four moves trained in ~16 s](training_viewer.png)

## What the weights are

`player_moves.json` (`physmoves-v1`) stores, per move, a compact policy over an
**XPBD articulated ragdoll**:

- **13 capsule bodies** (pelvis, spine, head, upper/lower arms, upper/lower
  legs, feet) linked by **ball joints** with **compliant angular motors**.
- Each actuated joint carries `P = 11` parameters: motor axis `(x,y,z)`,
  oscillation amplitude, phase `φ`, bias, gain, and four balance-**feedback
  gains** that respond to pelvis tilt / angular velocity.
- Four moves are trained: **walk, attack1, block, roll**.

## How it was trained

DeepMimic-style **motion imitation** on top of Mixamo reference clips, optimised
with the **cross-entropy method (CEM)** — a gradient-free evolutionary search
that fits comfortably in a browser tab:

1. A Mixamo clip is sampled to a per-phase reference pose (`sampleClipTargets`),
   including the reference **pelvis height** at each phase.
2. The ragdoll's joint motors track those reference joint angles; CEM learns a
   **residual correction + feedback gains** per joint so the *simulated* body
   reproduces the clip while staying balanced under gravity and contact.
3. Reward = imitation term (joint-angle match) − upright/height penalties. The
   key fix that killed the ~0.33 m "hopping" artifact was **root-height
   tracking**: the pelvis is unactuated, so its target height is recorded from
   the reference clip per phase and firmly tracked instead of left to a soft
   hover spring (bounce dropped to ~0.08 m, matching the real clip bob).

Training runs entirely client-side in `rlphys.html` (XPBD sim + CEM in
`physbody.js` / `rltrain.js`). As shown above, all four moves converge in
**~16 seconds** to rewards ≈ **walk 3.95 · attack1 3.96 · block 3.96 · roll
3.62**, then export straight to `player_moves.json`.

## Files

| file | description |
|------|-------------|
| `player_moves.json` | trained `physmoves-v1` policy (walk/attack1/block/roll) |
| `training_viewer.png` | the in-browser CEM trainer after a full run |

## Citation

If you use these weights or the Ashen Depths neural-animation work, please cite:

```bibtex
@misc{byrne2025physgait,
  title        = {physgait-weights: Browser-Trained Physics-Gait Weights for Neural Character Animation},
  author       = {Byrne, Dean (Quazim0t0)},
  year         = {2025},
  howpublished = {\url{https://huggingface.co/Quazim0t0/physgait-weights}},
  note         = {Ashen Depths neural souls demo}
}
```

## References

This work draws on ideas from the following papers:

- **AMDM** — Yi Shi, Jingbo Wang, Xuekun Jiang, Bingkun Lin, Bo Dai, Xue Bin Peng.
  *Interactive Character Control with Auto-Regressive Motion Diffusion Models.*
  ACM SIGGRAPH 2024. [project](https://yi-shi94.github.io/amdm_page/) ·
  [pdf](https://xbpeng.github.io/projects/AMDM/AMDM_2024.pdf)
- **TRACE and PACE** — Davis Rempe, Zhengyi Luo, Xue Bin Peng, Ye Yuan, Kris Kitani,
  Karsten Kreis, Sanja Fidler, Or Litany.
  *Trace and Pace: Controllable Pedestrian Animation via Guided Trajectory Diffusion.*
  CVPR 2023 (NVIDIA). [pdf](https://nv-tlabs.github.io/trace-pace/docs/trace_and_pace.pdf)

```bibtex
@inproceedings{shi2024amdm,
  title     = {Interactive Character Control with Auto-Regressive Motion Diffusion Models},
  author    = {Shi, Yi and Wang, Jingbo and Jiang, Xuekun and Lin, Bingkun and Dai, Bo and Peng, Xue Bin},
  booktitle = {ACM SIGGRAPH 2024 Conference Proceedings},
  year      = {2024}
}

@inproceedings{rempe2023trace,
  title     = {Trace and Pace: Controllable Pedestrian Animation via Guided Trajectory Diffusion},
  author    = {Rempe, Davis and Luo, Zhengyi and Peng, Xue Bin and Yuan, Ye and Kitani, Kris and Kreis, Karsten and Fidler, Sanja and Litany, Or},
  booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
  year      = {2023}
}
```

## Related

- Neural character animator (`skeleton_animator.pt`, a phase+action → 20-channel
  MLP) that drives the player in the shipped Space — parsed in-browser by
  `pt_loader.js`.
- Space: [Quazim0t0/AshenDepths](https://huggingface.co/spaces/Quazim0t0/AshenDepths)