How to Work Faster with Python and Character Extensions, and Slow Mocap in Story Tool

Table of Contents

If you’ve ever built a complex mocap sequence one piece at a time in MotionBuilder, you know how long it can take. Open the environment. Merge the characters. Merge the props. Add a reference camera, a shot camera, set the focal lengths, set the rotation orders, drop everything into Story. Twenty minutes later you’re ready to start animating, hoping you didn’t forget something or load the wrong assets. It’s ok when you’re only working on one shot, but painful when you’ve got 20.

The good news is, MotionBuilder Python can take most of that pain away and give you back animation time.

In this tutorial I’ll show you how you can use MotionBuilder Python to build entire scenes ready for editing; scale clips in Story Tool to create that Matrix slow motion effect, and use Character Extensions to align props in characters’ hands using a single pose. Hopefully, by the end you’ll know how to apply all three to your own sequences, and why each one works the way it does.

Build Scenes Automatically with MotionBuilder Python

In an earlier tutorial we built the opening shot of the lobby shootout in Story Tool by hand: merging the lobby environment, characters and props, building reference and shot cameras, and adding everything into Story. That worked – but it also took around twenty minutes.

Now, if you’ve only got on shot to work on, twenty minutes is fine. But, multiply that by 20 shots for a team of animators and motion editors, and you’ve got a problem. Worse, every shot risks being set up slightly differently by whoever did it. Different camera settings. Wrong asset used. A namespace someone forgot to add. The kind of small inconsistencies that come back to bite you later.

Python solves both. Once you’ve got a script that builds a scene end to end, every shot is set up identically, and the whole thing takes seconds. Better yet, you can hand the script to anyone, even if they’ve never used MotionBuilder before, and they can run it and they’re ready to go.

What the Script Does

I won’t walk through every line, but the idea is worth understanding because it’s what makes the script reusable across shots and sequences. The script is driven by four python dictionaries that you fill in once per shot:

Characters – names and file paths for each character to merge.
Props – names and file paths for each prop.
Scene settings – the master scene file to open, plus all the transport control settings (take name, frame rate, frame range, snap mode, loop playback, video reference file).
Scene setup – the scene ID, which characters belong in this shot, which prop each one is holding, and which hand they’re holding it in.

Fill those in, run the script, and MotionBuilder does the rest. It opens the master scene, merges every character and prop into its own namespace (with auto-incrementing for duplicates), sets the transport controls, builds a video reference camera with the video on the front plate, builds shot cameras with the right aspect ratio and rotation orders, adds a Head-up Display (HUD) to each camera, and drops every character into Story Tool ready to receive the mocap.

💡 Tip: The HUD is useful for showing details like the camera name, take name, current frame, focal length, field of view, and focal distance in the current view port. It updates in real-time so you always know exactly which camera you’re looking through and what its settings are.

A Second Script for Shot Cameras

There’s also a smaller second script that creates a shot camera on demand. Same settings as the manual cameras from the previous tutorial. It sets the correct aspect ratios, default lens, HUD attachment, incremental namespace, and also sets the new camera as the current view in the viewport. One click and it’s in.

💡 Tip: The biggest win of scripting this isn’t just speed, it’s consistency. Every shot in the sequence gets identical camera setups, identical namespaces, identical Story Tool structure. Anyone picking up a shot knows exactly where to find everything.

Choose the Right Frame Rate for Slow Motion

Once the scene is built, the next decision is what frame rate to actually work at. This matters more than people expect. It’s the difference between an action that looks like it’s been slowed down and an action that looks like someone faking it.

The script originally sets the scene to 25 frames per second (FPS) so the playback lines up with the video reference clip. That’s fine for the set-up phase. But before we start scaling clips for the slow motion effect, we want to switch to 120 fps. Here’s why.

Capture Rate vs Delivery Rate

The original mocap on this project was captured on an Xsens MVN system at 240 fps. That’s the capture rate. The frame rate you actually animate and render at is the delivery rate, and it’s usually much lower. Games might be 30 fps. Film and VFX is usually 24 fps.

Most of the time you resample down to delivery rate and never look back. But when you know you want to slow something down for a slo-mo shot, you need to add a step. To scale one second of action to, say, four seconds, you need enough underlying detail in the curves to survive being stretched. And that detail only exists if you captured at a high frame rate to begin with.

Why 120 fps Is the Sweet Spot

240 fps captured data contains 240 frames of captured data per second. Beautiful for detail, but it can be heavy in the scene, and we’re only going to scale these clips down by a half at most. We don’t need every original key. So we resample to 120 fps, which keeps every other key. Plenty of detail. Half the weight.

So why not just drop straight to 30 fps? Think of a hard impact, like when the character hits the hits into the wall. The original 120 fps version shows a clear double bounce, the kind of micro-motion that reads as a real, physical impact. Resample that action to 30 fps and you lose four keys across that bounce. The curve gets smoothed out. The double bounce disappears.

Now stretch that smoothed curve out for slow motion. You’ve lost the impact. The sudden change in direction and the weight the action had. It start to looks “swimy” – like the characters is weightless and moving in water. All the texture and weight that makes mocap feel like mocap is gone – smoothed out.

At 120 fps that double bounce survives. The curve still matches the original shape. When you scale it out, the detail stretches with it and the slow motion holds up.

💡 Tip: Always check before a shoot whether your mocap will need slowing down later. If the answer might be yes, get the data processed and delivered at a high frame rate so you’ve got detail to work with when you scale it.

MotionBuilder Handles Density

One of the genuine advantages of MotionBuilder is that it’s built for this kind of dense keyframe data. With sixteen seconds of animation plotted at 120 fps across six characters, my viewport is still playing back at over 30 frames per second. Which means I almost never have to render to review something. Make an edit, set a key frame, hit play, adjust again – if you’re used to working in Maya, look away now.

To turn on the playback rate display in the viewport, go to Display → Head-up Display (HUD) → Display Rate or hit Shift+F.

Rescale Clips in Story Tool for Slow Motion

With the scene at 120 fps and the clips in Story Tool, scaling for slow motion is the easy part. We’re going to slow down the shot where our Nigel character runs in, slams into the wall, and drops to a knee. In the video reference he hits the wall after a single step. In our raw mocap clip he takes several steps and then hits the wall, so we need to slow it down.

There are three ways to scale a clip in Story. They all do the same thing. Pick the one that works best for you:

Method 1 – Drag with Loop/Scale Set to Scale

In the Story window toolbar, click the Loop/Scale button and switch it from “Loop” to “Scale”.
Slide the clip along the track to make room for the stretched version if needed.
Drag the right edge of the clip outward to stretch it. The clip displays the scale factor live as you drag, so you can dial in 0.25 for quarter speed, 0.5 for half speed, and so on.
Play back and compare to the video reference. If the timing’s off, tweak the scale.

Quarter speed on this clip gets us close: one step, then the wall hit, then the knee drop. Much closer to the video.

Method 2 – Asset Settings > Clip Speed

Double click the clip to open the Asset Settings window.
Find the Clip Speed field and type a value. 0.75 for three-quarter speed, 0.5 for half speed.
The clip will scale in place. Slide it along the track until the wall hit lands on the right frame in the video reference, then trim the In point if you need to.

Handy when you know the exact value you want to scale the clips by.

Method 3 – Properties Tab

Select the clip in Story Tool.
In the Properties window, find the Speed property and set your value.
Reposition the clip on the track as in the previous methods so the key moments line up with the video reference, and trim if needed.

Same result. Three routes. Use whichever fits the way you prefer to work.

From there it’s just a case of repeating this on the other slow motion clips in the sequence. The two other slo-mo beats in this shot get halved. Played back end to end, the action runs full speed where it should and drops into slow motion at the right beats, with all the texture from the original capture still intact.

Use Character Extensions to Fix Prop Interactions

This is a real time saver when editing mocap like this where a character holds a prop the same way in multiple shots or in-game actions, and it’s one a lot of people don’t know about.

Character Extensions let you add any object into a character’s Control Rig. Wings on a dragon. A tail. Or in our case, a gun. Once an object is part of a Character Extension, it gets included in any pose you create or full-body key you set.

This means we can pose our SWAT character holding a gun correctly in one shot, save that pose, and paste it onto every other SWAT character across the sequence. The gun gets aligned in the correct hand with the fingers wrapped around the grip every time.

💡 Tip: In the previous tutorial “How to Animate 2 Handed Weapons” we aligned the prop and fingers one at a time and created poses. Character Extensions are how you reuse that work and scale up across an entire sequence or move set, using “art directed” poses to make sure everything is consistent.

Create the Character Extension

In Character Controls, select your first SWAT character. Set him to Full Body mode and put him into a T-pose.
With the T-pose still set, find the character’s gun in the scene. Right click and zero its translation and rotation so it sits at the world origin.
In the Scene browser, expand Characters, right click your SWAT character and choose “Create Character Extension”. A new extension appears under the Character Extensions branch.
Open a second viewport and switch it to Schematic View. Find the gun’s handle in the schematic.
Alt-drag the gun handle onto the new Character Extension in the Scene browser. Choose “Add to Extension” from the popup. The gun’s now part of the extension.

Set the Reference Object

The Reference Object is what tells MotionBuilder which part of the character body the prop is associated with. For a gun held in the right hand, use the right hand as the reference – you’re basically saying to MotionBuilder “when I create or paste a pose, the gun’s position should be aligned to this object”.

Select the Character Extension. In the Properties window, find the Reference Object field.
Lock the Properties panel so it doesn’t change when you select something else.
Select the character’s right hand bone in the viewport.
Alt-drag the hand into the Reference Object field. Click OK when the confirmation dialog appears.

Create a Pose with the Prop

Switch back to a single viewport.
Scrub to a frame where the character is holding the gun correctly. Select the character and hit F to focus on him.
Unlock the Properties panel and open Pose Controls.
With the SWAT character selected, set the pose mode to Full Body and click “Create”.

That’s the pose captured, including the gun’s position in the had now the gun is part of character in the Character Extension.

Test the Pose

Quick sanity check before you build the rest. Switch to a new take and put the character back in a T-pose at the world origin. Now paste the pose with Match Translation on and Match Rotation off, so he stays where he is rather than jumping to wherever the original pose was. Double click the saved pose to paste.

The character snaps into the holding-gun pose. Gun in the correct hand. Fingers wrapped round the handle. Now grab the gun and move it across the scene. Paste the pose again. The gun comes back to the hand. The pose is working exactly as we need.

Build a Pose Library

Repeat the process for every weapon-holding pose you need: standing, kneeling, weapon raised, weapon lowered, and so on. For this sequence I’ve created four poses that cover most situations across the lobby shootout.

In the Navigator, expand Poses.
Shift-click to select all the poses you’ve created, making sure nothing else is selected.
Use File → Save Selection to save the poses out as their own .fbx file. That’s your reusable pose library.

Apply the Poses Across the Sequence

Open a scene where the mocap is already plotted onto the Control Rigs but the prop interactions need fixing.
Use File → Merge to bring in the saved pose file. Tidy the poses into a named folder so you can tell at a glance which is which (weapon type and body position).
Select the first SWAT character. Pick a standing pose. Set the pose mode to Full Body so the prop is included, paste, then set a full-body key.
Move to the next character. Apply a kneeling pose if that fits the shot. Key it.
Continue through every SWAT character in the shot, tweaking each pose slightly to add variation so they don’t all look identical.

From there it’s just repetition. Same process on the rest of the SWAT team, then across every other sequence in the lobby shootout. A weapon interaction fix that used to be five minutes a character is now closer to 5 seconds.

Conclusion

Hopefully this has given you a coupe of ideas you can use when you’re working on larger projects and find yourself doing the same things over and over again.

Python scripts can help you build shots that require multiple assets and consistent settings. And the Character Extension poses allow you to create “art-directed” poses that can be applied to multiple characters across different shots or in-game actions to maintain consistency and correct prop interactions.

How do you use Character Extension in your editing? Do you use Python in your own MotionBuilder pipeline, or have you got a different approach to scene building? Let me know in the comments below.

Happy editing!

Frequently Asked Questions

What frame rate should I capture at if I know I’ll need slow motion later?

240 fps on an MVN Link system and 120 fps for an optical system is a good starting point for actions that might need slowing down. The general rule: capture at the highest rate that holds quality, then resample down when you know what you actually need. You can always throw frames away. You can’t invent them later.

Can I use Character Extensions for things other than props?

Yes. Any object you want included in poses or full-body keys can go in. Wings, tails, capes, costume elements, equipment. The Reference Object should be the part of the body whose movement most affects the extension, usually the closest parent bone in the skeleton.

Will a pasted pose move the character to the pose’s original position?

Only if Match Translation is OFF when you paste. Turn Match Translation ON (and Match Rotation off, if you want to keep the current facing direction) to keep the character where they are and only paste the pose itself. This is what you want when fixing prop interactions across a sequence: the character stays put, the gun lands in his hand. You might need to turn Match Translation and Match Rotation OFF when you want to all the poses to have a consistent start or end position, for example for in-game animations.