Working with Actors

An actor is a character model loaded into the scene. DanceXR adapts the models’ skeleton on-the-fly to fit the motion, and simulates movements of hair and clothes using the physics system.

You can customize the appearance of the model by changing materials, applying textures, or using the dressing system to toggle outfit pieces. You can also adjust the scale and position of the model, and fine-tune how it interacts with the stage and other actors.

For a glossary of terms used here (actor, selection disc, gizmo cube, dressing system), see Concepts & glossary.

Loading an actor

DanceXR reads two model formats:

• PMX — the MikuMikuDance format. Includes its own bone hierarchy, physics rig, and morph list out of the box.
• XPS — the XNALara / XPS format (.xps, .mesh, .mesh.ascii). Does not include physics or a standard skeleton, so you set those up in DanceXR.

Both formats can also be packaged in a ZIP. See ZIP format for filename rules and encoding.

Two ways to load

• Drag and drop a model file (or zip) onto the DanceXR window. Fast for one-off loads.
• Content library — place models under actors/ in your content library. They appear in the actor menu’s Load Model list.

Replace vs add

By default, loading a model replaces the currently selected actor. Click the + icon next to a model name to add it as an additional actor instead. Multi-actor scenes require a paid build — see Download & editions.

Load options

Loader options control how new actors come in: cache size, texture compression, transition effect, auto actor change.

PMX vs XPS — what differs

Most settings work the same on both formats. The places they diverge are worth knowing:

If something in this guide says “PMX only” or “XPS only”, that is why.

The actor menu

Every actor has a yellow selection disc under its feet. Clicking it opens the actor menu — the central hub for everything per-actor. See Actor menu & tools for the full breakdown.

The menu is grouped into:

• Motion — assigned motion, formation slot and model-specific motion settings.
• Recently modified — quick jumps to the dialogs you just changed. See Recently modified settings.
• Dressing & textures — dressing system, bone mapper (XPS), alternative textures.
• Materials — per-slot settings: skin, hair, eyes, lips, opaque, transparent, custom. See Appearance & materials for how the slots fit together.
• Settings — physics, feet adjustment, facial control, eye contact, troubleshooting.
• Pro (paid builds) — outfit & body paint, accessory, ragdoll, motion override, light ball, advanced physics, NSFW overlays.
• Morph list (PMX only) — PMX blendshape morphs.
• Tools (wrench-and-hammer icon) — favourite, tag, spectator, move up/down, reset, duplicate, reload, 3D snapshot, remove.

Multi-actor scenes

When you have more than one actor on stage, three features handle group behavior:

• Formation — positions actors in patterns (line, grid, custom). Order is set by Move Up / Move Down in the Tools menu.
• Actor playlist — cycles through a list of models over time, optionally synced to music.
• Attach to actor — parents one actor or accessory to another (held items, riders, paired motions).

Use Spectator mode to keep a model on stage but exclude it from auto-assigned motions and formation slots.

Global actor control applies a setting to every actor at once — useful when you want all loaded models to share the same physics tuning, dressing, or material.

Snapshots and presets

Three ways to save what you have built:

• 3D snapshot — exports the current pose as an OBJ for use in other 3D tools.
• Actor presets — saves the actor’s settings (materials, physics, dressing) so you can apply the same look to the same model later, or to a similar one.
• Save scene and scene bundle — captures the entire scene including all actors, motion, stage, and configuration.

When something looks wrong

Symptom-first troubleshooting:

Related pages

• Concepts & glossary
• Appearance & materials
• Physics system
• Motion system
• Actor menu & tools
• Content library