Motion System
Motion in DanceXR comes from several sources, configured at several levels, and can stack. This page is the map: where motion comes from, where settings live, and how layers combine.
For terms (motion pass, override, dance set, remix, custom inherit), see Concepts & glossary.
Motion sources
There are five places motion can come from:
- A motion file (VMD or BVH) loaded from disk.
- A dance set — one audio file plus one or more motions, automatically detected when grouped in a folder or zip.
- Procedural motion — generated at runtime by Auto Dance, Idle Motion, Catwalk, Lifelike Motions, and Secondary Motion.
- Keyframe animation — manually authored poses in DanceXR.
- Remix — using motion data from one dance set with audio from another.
You can mix these. A typical scene plays a VMD-driven dance with a procedural secondary motion layer on top, plus eye contact and breathing handled by their own systems.
The dance set unit
A dance set is the natural grouping for “a song”. When you place a folder or zip in motion/ containing one audio file and one or more matching VMD/BVH files, DanceXR groups them automatically. A loaded dance set:
- Plays the audio.
- Routes motions to actors (one motion per actor by default; reassignable).
- Optionally drives the camera if a camera VMD is included.
- Has a shared music timing tied to the audio’s BPM.
The set is the unit you load, save, share, and remix. Individual motions still have their own settings (per-motion speed, loop range, etc.), but the dance set keeps them coordinated.
VMD2PNG (added in 2026.3) lets you load motion data from PNG files that encode VMD data — smaller, easier to share, includes a thumbnail.
Settings hierarchy
Motion settings live at three levels. When the same parameter exists at multiple levels, the more specific level wins.
| Level | Page | Scope |
|---|---|---|
| System | Motion settings | Defaults for every motion in the scene |
| Per-actor | Actor motion settings | Overrides for one actor’s motion |
| Per-motion | inside Dance set | Per-motion tuning within the set |
Playback options — speed, loop mode, range — applies at the playback level (the audio/motion timeline as a whole).
Assigning motion
Assigning motion covers the actual mechanics: drag-drop a VMD onto the window, click Assign To in the audio/motion menu, or open the actor menu and pick from already-loaded motions.
Order matters when you have multiple actors. Move Up / Move Down in the actor Tools menu reorders actors, which changes which motion in the dance set they get when auto-assigned.
Spectator mode excludes an actor from auto-assignment.
Layering and override
When you want to combine or modify motions, four pages do related things — pick the right one for the job:
| Want | Use |
|---|---|
| Two motions playing on the same actor at once (e.g. a dance plus a hand wave) | Motion passes |
| Replace specific bones in a motion (fix arm clipping, swap face) | Motion override |
| Author or modify the bone-following relationships PMX inherit-bones use | Custom inherit motion |
| Pair motion from one dance set with audio from another | Remix motion |
Motion passes layer; override masks per-bone; inherit motion changes what counts as following what; remix is a higher-level swap of audio under the same motion.
Procedural motion
Generated at runtime, no source VMD needed:
- Idle motion — breathing and quiet poses when nothing else is playing.
- Catwalk motion — procedural walk cycle.
- Auto Dance 1, Auto Dance 2, Auto Dance 3 — procedural dance generators. Use Auto Dance 3 unless you have a reason to pick an earlier generation; it has rhythm analysis and the strongest variation.
- Lifelike motions — micro-motions that make a paused or idle actor feel alive.
- Secondary motion — procedural layer that runs on top of any motion (sway, breath, follow-through).
- Keyframe animation — author your own poses with manual keyframes.
Idle motion, Auto Dance, Auto Dance 2, and Motion override all expose gizmo cubes for direct posing.
Music timing
Music timing detects (or lets you set) the BPM and beat offset of the loaded audio. Several systems consume this:
- Auto Dance 3 syncs motion changes to beats.
- Auto camera can sync shot transitions to beats and respond to audio sensitivity.
- Auto update can drive any setting from the beat signal.
If procedural dance feels off-tempo, fix music timing first.
Character behavior — the always-on layer
Three systems run continuously, regardless of what motion is playing, to keep characters from looking robotic:
- Blink, breathing & eye contact — eyelid behavior, automatic gaze targeting, breath rise/fall.
- Facial control — manual or automatic facial expression / morph blending.
- Lifelike motions — small idle adjustments.
These compose with whatever motion source you are using.
Common problems
| Symptom | Likely fix |
|---|---|
| Loaded a motion but nothing happened | Motion was loaded but not assigned — see Assigning motion |
| Wrong actor got the dance | Reorder actors with Move Up / Down in Tools menu |
| Motion runs at wrong speed | Check playback options and per-motion speed in dance set |
| Procedural dance is off-beat | Music timing — verify BPM and offset |
| Arm clips through body | Motion override on the offending arm bones |
| Character looks dead between motions | Enable idle motion, eye contact, and lifelike motions |
Related pages
- Concepts & glossary
- Working with actors
- AI in DanceXR — Auto Dance and AI-driven motion
- Cinematic camera — Auto Cam reads music timing too