MotionForge for Maya — User Guide

A Maya plug-in that turns one line of text into character motion, moves it onto your own character, and sends it to Cascadeur. It is a port of the MotionForge Blender add-on v0.5.0 to Maya 2027. Every engine runs on your own computer; nothing is sent over the internet.

한국어: KO_index.md

What's new in 0.2.0

Updating from 0.1.0: after installing 0.2.0, press Install Engines in the MotionForge window once. It updates the MotionBricks runtime in your Engine Folder, and the person (SOMA Human) needs it for its model and styles. Check for Updates next to it says what is newer without downloading it.

New

A person joins MotionBricks - The + in the MotionBricks panel asks for a SOMA Human or the Unitree G1 Robot. The person has the same Style, Go, Speed, Generate Motion, Bake, Live and Retarget as the robot. - A person's 14 styles - idle, walk, slow walk, jog, run, injured, stealth, scared, zombie, happy, boxing, gun, and elbow and hand crawling - come with Install Engines. Make Missing in the Styles box makes any that are missing with Kimodo, and Save as Style adds your own from a baked or generated take. - Install Engines also fetches the person's model (380 MB) with NVIDIA's licence. It runs on the CPU, in a mayapy of its own - no GPU needed.

Takes, for the person and the robot - Every character has a list of takes (+ Take / - Take / Show Take). A take has its own style, direction or target, speed, seed and length, and they are saved with the scene. - The takes run one after the other on one timeline - for example frames 1-30, 31-90, 91-135 - and Generate Motion makes all the ticked ones, each starting where the one before ended. Bake writes them into one animation.

Pose to pose - Tick End on Pose Key on a take of a person. Move, turn and pose the character and key it on the frames it should arrive at - say 50 and 100 - and each take is made up to its key, from the pose it starts on. Keys can be 19 to 59 frames apart at 30 fps. - Poses to Use (1 to 4) and Transition Early By let the character flow through its poses without halting. Arrive in a Clip Pose makes a take end in a pose of a style's clip.

MMD characters, both ways - With maya_mmd_tools installed, the Retarget panel has an MMD box: Import MMD Model (PMX) and Import MMD Motion (VMD). - An imported model is a source (MMD: <name> in the list; its VMD keys are copied like any take) and a target (set Rig Type to MMD model; Auto-Detect finds one too). Bones are read by their MMD names, so upperarm_L works as well as left_arm. - The legs are switched to FK for the bake, so the leg IK no longer holds them still: the knees stand as keyed from the first frame, the skin's D-bone legs follow, and the IK controllers ride along with the feet. Reset All switches the IK back on. The arm, elbow, hand and neck solvers are left alone.

Changed

• Install Engines now updates too: a runtime file that differs from the published one is replaced, so a newer Kimodo, ARDY or MotionBricks runtime reaches an older install. A style you made or edited is never overwritten. The person's model and ONNX Runtime are shared with the Blender add-on's install, so one Engine Folder serves both.
• Installation now says exactly how to lay out the folder: rename the unzipped Maya_MotionForge-<version> folder to MotionForge, so MotionForge.mod sits directly inside the folder on MAYA_MODULE_PATH.

Fixed

• MMD target legs. The leg IK used to hold the legs still, bent the knees in the rest pose so the first frame was already folded, and left the skin's D-bone legs reading the idle solver - the body stood stiff while the FK bones moved.
• An MMD model registered as a group (what Set Selected makes) is recognised as an MMD model.
• Each take in the Live Path list has its own length.

1. What you need

2. Installation

2-1. Register the module (once)

The zip holds one folder, Maya_MotionForge-<version>. Unzip it, move that folder somewhere permanent and rename it MotionForge, e.g. C:\Users\<you>\Documents\maya\modules\MotionForge, so that MotionForge.mod sits directly inside it (...\MotionForge\MotionForge.mod, not one folder deeper). Keep MotionForge.mod at the root of that folder: it points at the scripts\ and plug-ins\ folders beside it, so copying the .mod on its own will not work. Any folder will do - if your Documents folder is redirected to OneDrive, use the path Explorer shows you.

Then put that folder on MAYA_MODULE_PATH, one of two ways:

• Environment variable: Windows > System Properties > Environment Variables > New user variable MAYA_MODULE_PATH = C:\Users\<you>\Documents\maya\modules\MotionForge. If it already exists, append ;C:\Users\<you>\Documents\maya\modules\MotionForge.
• Maya.env: add the same line to the Maya.env file of your Maya version (e.g. C:\Users\<you>\Documents\maya\2027\Maya.env):

MAYA_MODULE_PATH = C:\Users\<you>\Documents\maya\modules\MotionForge

Restart Maya.

2-2. Load the plug-in

In Windows > Settings/Preferences > Plug-in Manager, tick Loaded for MotionForge. Tick Auto load too if you want it every session. A MotionForge menu appears in the menu bar.

2-3. Shelf (optional)

Run once in the Script Editor's Python tab:

exec(open(r"C:\Users\<you>\Documents\maya\modules\MotionForge\scripts\motionforge_shelf.py").read())

This creates the MotionForge shelf: Load · Window · Connect · Rig · Generate · Kimodo · MB · Retarget · Reload. Running it again does not duplicate the shelf.

3. First-time setup — the Engine Folder

Choose the Engine Folder with MotionForge > Set Engine Folder.... Inside it:

<Engine Folder>\
├── ardy\          ARDY (bin\ardy-server.exe, models\*.gguf, assets\cskel27\)
├── kimodo\        Kimodo (generator + text encoder)
└── motionbricks\  MotionBricks (DLL + styles)
    └── soma\      the person: ONNX model, ONNX Runtime, 14 styles

MotionForge > Engine Status prints ready (or what is missing) for each engine in the Script Editor.

Updating. Install Engines also updates: a runtime file that differs from the published one is replaced, so a newer Kimodo, ARDY or MotionBricks runtime reaches an older install, and the person's styles are fetched with it. Check for Updates (in the window, or MotionForge > Check for Engine Updates) says what is newer without downloading it, and turns the button into Update Engines when there is something. A style you made or edited is never overwritten. The person's model and ONNX Runtime are shared with the Blender add-on's install, so one Engine Folder serves both.

4. Where things are

The window carries Blender's seven panels in the same order, with the same names, and every control works.

1. MotionForge — engines, connection, rigs, HumanIK
2. Text to Motion — takes from text
3. Live Path — steering in real time
4. Kimodo — the Kimodo engine (several characters)
5. MotionBricks — the walking engine (several characters, live, styles)
6. Retarget — onto your own character
7. Send to Cascadeur — to Cascadeur and back

Every setting and list in the window (takes, waypoints, pose keys, live takes, Kimodo and MotionBricks characters, the Share list) is saved with the scene and comes back when it is reopened.

The line at the top shows what the last button did, or why it failed.

5. Your first animation (5 minutes)

1. MotionForge > Connect ARDY — loads the model (seconds).
2. MotionForge > Create Rig — a 27-joint rig with its body mesh.
3. MotionForge > Generate Motion... — type a person walks forward.
4. The take is keyed and the scene is set to the engine's rate (ARDY: 20 fps) with real-time playback. Play it.

The first generation can take a while while the text encoder warms up (about 100 s on this PC); later ones are quick. The window's Generate buttons run in the background, so Maya stays usable; the status line shows progress.

6. The panels

6-1. MotionForge — engines, connection, rigs

mGear (when installed)

With mGear (open source, MIT) installed in Maya, a MotionForge character can wear mGear's EPIC biped control rig. Generated takes are keyed onto the mGear controls (FK and IK both), and the character follows the controls, so generated motion is polished like any keyframed animation. Without mGear these buttons are greyed out with the reason shown.

• mGear builds one biped per scene. Remove it before rigging another character.
• With knees and elbows bending as hinges, FK and IK both match the original motion within 0.5 cm. IK poles are placed in the plane the limb actually bends in, frame by frame.

6-2. Text to Motion — takes

A take is one generation: its own prompt, length, seed, target rig and path curve. With no takes the panel shows a "Start here" line.

Waypoints — "pass through here on this frame"

1. Turn on Follow Waypoints.
2. Put the time slider on a frame and press +: an MF_Waypoint_01 locator appears (at the selected object or the origin, facing the way the rig faces).
3. Pick one in the list to change its Frame / Enabled.
4. Face Waypoint Direction makes the character face the locator's +Z.
5. Waypoints are read relative to the rig: put the rig in a group and move or turn the group, and it still walks to where they were placed.

Pose keys — "hold this pose on this frame"

1. Turn on Use Pose Keys.
2. On the frame you want, press +: a copy of the rig, MF_Pose_001, appears.
3. Pose Key (shown as Pose once a key is picked) jumps to the key's frame and selects its rig.
4. IK On gives the arms and legs Maya ikHandles (rotate-plane, with pole vectors) to pose by the hands and feet; IK Off keeps the pose in the joints and removes the handles.
5. Pin: Whole Body holds every joint; Parts holds only the hands and feet ticked (LH · RH · LF · RF) and lets the model make the rest.
6. Generate Take.

6-3. Live Path — steering

The character walks while you drag a cone to steer it. Keys are written only when you Bake.

1. ARDY must be connected.
2. + adds a live take; set its Prompt · Rig · Seed · Enabled.
3. Add Target makes the steering cone MF_Live_Target_1 and selects it.
4. Start Live — drag or turn the cone. Esc or Stop Live ends it.
5. Bake writes the keys, Discard throws them away, Reset All clears the ARDY rigs' keys, puts them back at rest (T-pose) and returns the timeline to its first frame — and puts every character they were retargeted onto back at rest too (6-6).
6. Characters in the Share list (6-6) follow along during the run, posed rather than keyed; Bake fills them with keys.

6-4. Kimodo

Kimodo runs its engine per take; a take takes tens of seconds to minutes and runs in the background.

1. Pick With a Body / With Fingers and press + for a character.
2. Fingers off: 30 joints; on: 77 joints with fingers.
3. Body: ARDY's real skin on the 77, a simple proxy body over the joints on the 30.
4. Each character has its own Enabled · Prompt · Seed (pick it in the list to edit).
5. - takes it out of the list or deletes it (it asks); Add Selected adds a SOMA skeleton picked in the scene, including ones brought in from BVH or FBX.
6. Set Duration · Denoising Steps (20 by default) · Prompt Strength · Constraint Strength · Reduce Foot Skating, then Generate Motion: every enabled character is generated in turn and keyed as it lands. While running the button reads Stop Waiting (the take in progress still finishes).
7. Reset All clears every Kimodo character's keys, puts them back at rest (T-pose) and returns the timeline to its first frame. The characters the takes were retargeted onto (6-6) are reset with them.
8. Export SOMA BVH / Reload Engine.

6-5. MotionBricks — walking

Walks in a style with no prompt. Generate Motion only plans, and the plan plays right away from memory; Bake writes the keys.

Maya has no BVH importer, so MotionForge reads BVH itself (rotation orders and frame rate included).

6-6. Retarget — onto your own character

1. Source Rig — empty means the rig the newest take went onto; any MotionForge rig can be picked. A live take still waiting is baked first, and a rig with no keys sends the pose it is in.
2. MMD models work both ways, with maya_mmd_tools installed. The MMD box at the top of this panel has Import MMD Model (PMX) and Import MMD Motion (VMD); an imported model appears in this list as MMD: <name>, and its keys are copied like any take. To put a take on an MMD model, set Rig Type to MMD model (Auto-Detect finds one too). Bones are read by their MMD names, so a model that calls its arm upperarm_L works as well as one that calls it left_arm. Torso and limbs are mapped; finger and twist bones are not yet.
3. Select a joint of the receiving character - or its body mesh - and press Set Selected (or type a name). Referenced characters with a namespace (Hero:Hips) work as they are. A skeleton an importer left split under its body mesh (MetaHuman Builder's MMB_bodyShapeBof4|spine_04) is named by the mesh, and every joint under it is retargeted. When the character carries a second skeleton beside the body one (MetaHuman Builder's head rig, bone names and all), the body skeleton is the one driven and the copy follows it - live and baked - instead of the two being mapped onto one another.
4. Rig Type — usually auto-detect. The two control rigs Maya animators work with are in the list: HumanIK Control Rig and mGear EPIC biped. The take is keyed onto their controls (the pelvis and legs onto the HumanIK effectors, whose channels are what that solver reads), and the character follows the controls.
5. Method — MotionForge (joint by joint) / HumanIK (Maya) (both defined as HumanIK characters, driven by Maya's HumanIK, then baked).
6. Retarget to Character.

Share With Characters — one take onto many characters

1. + adds a row for the selected character. Each row: Source (empty = active rig) · Character · Rig Type · Enabled.
2. With Fill Characters After Generating on, rows fill right after every Generate and Bake; Fill Characters does it now.
3. During a live run (ARDY or MotionBricks) the characters follow as poses; a second skeleton on the same character (a MetaHuman head rig) follows with it.

Reset All (in Live Path, Kimodo and MotionBricks) resets these characters along with its rigs: their keys are cut and their own rest pose comes back - Maya's bind pose, what Go to Bind Pose puts back, which on a MetaHuman Builder body is the whole pose it was skinned in (the root keeps -90) rather than every rotate channel at zero, which tipped the character over and dropped it through the floor. The rest is read off the skeleton, not off the pose the character is standing in: a live run sets a follower's bones without keying them, so a character it stopped on carries no animation at all, and taking that pose for its rest sent Reset All walking off to wherever the take had got to. A character whose skeleton carries no bind pose - one MotionForge built and never skinned - goes back to the pose it was found in, or, if it was already keyed before MotionForge saw it, to where its take begins. The rows and Target Rig are saved with the scene, so a character filled in an earlier session is put back too.

SMPL-X body — when the Target Rig is an SMPL-X/SMPL-H skeleton, Export SMPL (.smpl) writes it (pick a Gender; Shape000… blend shapes are saved as the body shape).

6-7. Send to Cascadeur

See chapter 7.

7. Cascadeur

7-1. Install (once)

1. Install Cascadeur Plug-in in the window (or the menu) runs installer\integrations\cascadeur\install_mf_maya.bat. Allow Administrator when asked.
2. It copies two Maya-only files (mf_maya_link.py, mf_maya_apply.py) into Cascadeur.
3. They share neither file names nor ports with the Blender add-on's Cascadeur plug-in; both can be installed and running at once.
4. Restart Cascadeur.
5. In Cascadeur run Animation Scripts > MotionForge Maya Link (port 9574).

What goes across is the selected skeleton — a MotionForge rig or your own character's joints. With nothing selected, the rig the newest take went onto.

7-2. Sending

Order matters: with no character in Cascadeur, send Character and Bones first, then keys, Live or Receive. The send keeps a copy of how the character landed on the rig, so restarting Cascadeur or Maya does not break reading back.

7-3. Live mirror

1. Check the Link tests the link step by step and says where it stops (full report in the Script Editor).
2. Mirror — Follow the Focus (the window you work in sends) / Maya to Cascadeur / Cascadeur to Maya.
3. Bones — Mapped Bones / Whole Skeleton.
4. Live: Mirror This Rig — press again or Esc to stop. Playing back keys every frame over there too.

7-4. Receiving (From Cascadeur)

8. Good to know in Maya

9. Reload — update without restarting Maya

MotionForge > Reload MotionForge (shelf Reload) New code goes live at once. A running Live, MotionBricks live run or Cascadeur mirror is stopped first, and ARDY disconnects. Rigs, takes, waypoints, pose keys, live takes, Kimodo/MotionBricks characters, the Share list and the settings stay. Reopen the window afterwards.

10. How it differs from Blender

Nothing is left unported; every control in the window works. Some parts are done the Maya way:

11. Troubleshooting

12. Licence

MotionForge for Maya is sold under the Chamiseul License, one licence per purchaser. Copying, modifying, redistributing or reselling the plug-in is not permitted; use the files exactly as delivered. The full text is LICENSE.txt in the folder you installed from.

Third-party components (NVIDIA models and sources, ggml) keep their own licences, unmodified: see licenses\ and scripts\motionforge\core\installer\*\licenses\. The Blender add-on's licence does not apply to this product.