Tool programming in Motion Builder.


The article is devoted to development of add-ons for MotionBuilder software. This program might not have become widespread, in my opinion, because it is not well-known yet and examples and tutorials are scarce (owing to scanty number of examples and tutorials). By means of my work I hope to discover helpful practical aspects of MotionBuilder.

To confirm the significance of the present software I would like to produce a few important for game industry advantages in comparison with other professional 3d software:

  • High speed of data processing. Either for scene capacity (64-bit version of the program is able to deal with 3-4 gigabytes of content) and performing filtering operations
  • Efficient technology for working with mo-cap devices.
  • Easy-to-use story editor for creating game cut-scenes.
  • Hierarchy of transitions between motion clips for character animations. This makes it possible to handle a character before putting it into a game. (Triggering)
  • The program has understandable SDK and huge list of categories of plug-ins. In other words, SDK makes it possible to control nearly all aspects of the program. Python scripting extension is also must be mentioned. Generally speaking, a tool programmer can a lot here.

Main format is *.fbx, which is common at present. This format is free of charge and is supported by developers (I repeatedly turned for help and always received technical support). There is one more important thing: fbx became “a bridge” between such “giants” as Maya, Max, LightWave, XSI, therefore one can always use MotionBuilder at any phase of the work on a project, and would not entail any serious changes in a general organization of development process.

MotionBuilder comes with both Python scripting help and Open Reality SDK help supplement. However, the information in help rarely overstep the limits of bare listing of classes, their methods and attributes with poor explanation. This frightens a lot of programmers off who start to deal with MotionBuilder. At first I faced such a problem myself too. But after getting the feel of this program a bit, I understood that this help is effective for advance users. This fact was exactly one of preconditions for writing this article.

As the scale of inner structure of MotionBuilder is really large, I want to represent the development of a useful tool  and all closely-related theory. The article is a guide to the world of tool programming in MotionBuilder.

The purpose of the article is to add the help and to give sufficient comments and explanations for you for understand everything without any problems. I do not set myself the task to rewrite all the methods and attributes of every class though. The are entirely set forth in the help. Therefore, what I can advise is to use both the article and the help during your studying.


During my explanation of some structure the scripting code will be given. This will make it possible to use it by yourself. I want to make a reservation, It does not matter whether you need Python or not, the names and functions of the classes are the same either for script and SDK. It easier to explain some process through Python, that is why the examples particularly in Python will be given with the theory up to chapter Open Reality SDK. If there is necessity or any distinctions, I resort to using a table, where there are script and C++ source code.

How to use Python? Very easy! One can execute individual lines of script through the Python Console Tool (main menu of MotionBuilder -> Windows -> Python Console Tool). There is a alternative – to write a script  (you can do it even in a wordpad) and save the file with extension *.py to path MotionBuilder\bin\config\scripts. After program startup, MotionBuilder identifies it and put it into the window Assets into section Scripts automatically.

Base structure.

The structure itself is similar for both script and SDK. One can defined the tasks for Python and SDK. If you need a tool for imprinting some algorithm and can be easily done through the script.

Open Reality SDK provides you with ample opportunities such as creating interactive means, creating user interface, using data from devices, creating own import/export, scene manager plug-in, etc.

Note the deference though – using Python it is enough to jot down a couple of lines and you will receive the function you need (necessary function) or automation of certain sequence of actions. Work with SDK, on the other hand, requires planning of your actions and dynamic link library (DLL). In this case you have much more source code and definitely takes more time. On the whole, Python and SDK do not substitute but supplement each other.

The names of classes and the list of methods and attributes are the same both for script and SDK. Here a review of base classes of MotionBuilder environment:

FBPlug – base class for all objects for MotionBuilder environment. Every object, component or property is …

this part is in translation

Player Control

Inner Structure

You can work with time through the class FBTime. It contains the methods for receiving/setting itself value. What is more, you can do it various ways: in frames, in ms, etc.


I would like only to demonstrate how to set the time in frames

# variable for the time

lTime = FBTime()

# set the time – 10 frames

lTime.SetTime( 0,0,0, 10 )

You can get the current frame (read only) through the attribute LocalTime of the class FBSystem.

print FBSystem().LocalTime.GetFrame()

If you know at least two common possibilities with the time in the example, it would be quite easy for you to gain an understanding of the rest using the help.

Time range is the class FBTimeRange. This class is intended for situations, when you have to set or to know the time range. The following methods allow to operate with the range:

GetStart(), GetStop() – send the beginning/ending of the range back in the form of variables (for SDK pointers of the variables) of the class FBTime.

Set (, ) – sets the range, where start and stop are the variables of the class FBTime.

The class FBPlayerControl – controlling animation playback. It is quite usefull class and I would like to show some of its methods by the examples.


#It is enough to create the object of the class FBPlayerControl

lPlayerControl = FBPlayerControl()

#recieve the current fps value

Print lPlayControl.GetTransportFpsValue()

#get the opening time

Print lPlayerControl.LoopStart

#get the stop time

Print lPlayerControl.LoopStop

There are a lot of methods and attributes in this class. Look up the help. I don’t think there will be any problems.

By the way, the class FBPlayerControl has attrubutes for getting information about timeline’s markers – NextMarker, PreviousMarker.


Properties play the role of the keeper of the current state of the component: translation, rotation, visibility, … The are itemized in a special list of the component, I described earlier in the section common structure.

External Structure

Let’s load the scene with the character (alien.fbx). Set the character as the current one (after choice it is marked in the picture below) and choose its pelvis effector by clicking on the central icon of the Character Controls dialog.


Now look at the properties of this effector. Open the dialog for properties viewing (main menu->Window->Add Property Editor).


Some of these properties need to be paid attention at:

–          Visibility – checker property, its value is true/false. It’s boolean value. You can notice that boolean type of data takes place here.

–          Translation (Lcl) (local moving) – three values, that make a vector

–          Reach T(IK/Aux) (IK influence) – a real number

–          Size – a real number, different from previous one through. I will explane what difference is later.

–          Color RGB. It is different from vector that color requires one channel more – alpha channel.

There are not all the variety of the property which you can find in the program. Their types of data are clearly understood.

When scripting/programming you have to apply to such kind of properties.

I’d like to draw you attention to the properties Reach and Size. The difference is that Reach is animated. This is an important peculiarity of properties – they can be animated only in case they are dynamic.

Now press the button “Customize” in the properties editor and pass to the second tab. Here is a list of the Mbuilder’s data types, according to which you can create you own variable for the given object. As I’ve already said, the list is incomplete.

Internal structure

Let’s study properties inside.

The property is represented by the FBProperty class which is called-fore and often used one. If can’t find the attribute you need in the help on some class, search it among the properties of given component.

Any class derives FBComponent class contains property list. Present attribute of the FBPropertyManager class makes possible to do search of a property you need and to get their number or a necessary property from the list.


Clear the scene. Open script console and inscribe the following:

lCube = FBModelCube(“box”)

By this action we created a box in a scene, lCube is a variable of the box. The class of the box FBModelCube is made on the basis of FBComponent, i.e. you can apply to the properties.

No output all the properties of the box in the console

for lProp in lCube.PropertyList: print lProp.GetName()

For searching a property the manager contains a method Find


lProp = lCube.PropertyList.Find(“Visibility”)

print lProp.GetName()

I used the method GetName() for getting the property name in the both previous examples. This method refers to the property, i.e. to the FBProperty class.

It is natural that a property in itself is of no interest,- it’s value is important. Getting and setting of value are different in Python and Open Reality SDK.

Python Open Reality
Getting of a property value

lVal = lProp.Data

attribute Data returns the property value


In the previous example we put the property of visibility into lProp. Now let’s output the value on the console.

print lProp.Data

An access to the property can be performed through the functions:

AsInt() – returns a value as a whole number

AsString() – returns a value as string

For all the rest cases you should use GetData( ,


bool val; lProp->GetData(&val, sizeof(bool));

Setting value

In Python setting of a property value is performed through the attribute Data too


lProp.Data = False

The situation is analogoes to the getting a value



SetData( )


bool val = false;

lProp->SetData( &val );

Animated properties.

There is a method IsAnimatable() in the FBProperty class. It is used for checking whether a given property is animatable. If so, it means that having derive FBProperty given property is a class FBPropertyAnimatable.

FBPropertyAnimatable class makes possible to work with a set of keys of the given animatable property. However, this is not topic of this article.

Here is a small example.

Given code searches a property of an object, gets its value and if it is animatable, the code adds the key with a set value to the current moment of time.

FBProperty *lDampProp = mFinger[0]->PropertyList.Find( mDampName );

if ( lDampProp )


lDampProp->GetData( &temp, sizeof(double) );

temp += value;

if ( lDampProp->IsAnimatable() ) {

FBPropertyAnimatable *lDampAnimatable = (FBPropertyAnimatable*) lDampProp;

FBAnimationNode *lAnimationNode = lDampAnimatable->GetAnimationNode();

if ( lAnimationNode ) {

lAnimationNode->KeyAdd( &temp );



lDampProp->SetInt( (int) temp );


Creation of properties.

Creation a new property for an object is realized through the FBComponent class by the method PropertyCreate(, , , , , ), where

is an enumeration FBPropertyType(kFBPT_int – an integer value, kFBPT_bool – Boolean value, kFBPT_double – double number, etc.

– text name of data type, which is declare in fbdata.h as ANIMATIONNODE_TYPE_…

– Boolean value, it shows if the present property is animatable

– shows if the property is user or dynamic one and joined to a component. By default – false.

– a property, which value refers to. By default NULL

Ex for Python

lProp = lModel.PropertyCreate(“MyProp“, FBPropertyType.kFBPT_double, “Number“, True)

Ex for Open Reality

HFBProperty lProp = lModel->PropertyCreate(“MyProp”, kFBPT_double, ANIMATIONNODE_TYPE_NUMBER, true)

Story Editor

External structure

If you are familiar with MB, this chapter can hardly given you any new information. Pass straight to the inner structure. Then as the article has informative nature, I would like, however, to given some information.

Concerning external strcture I’d like to touch upon some, deserving attention, issues.

Story – scene storyline editor. It is very handy and usefull to develop your animation scene. By the way, game cutscenes are also can  be got ready and the following export to game engine will make possible to see your work. In this article I will set fort the material, which is able to sort out easily, what data are to be used what exactly it is means.

It’s okay if you can’t animate in MB. Use it as a composer of scenes for creating animation reels. It can turn out to be quite useful. At least, editor is really easy to use and fit for such tasks. Moreover, now that extension 2 has appeared, added supporting for 64-bit platform. You’re able to work with enormous scenes, up to 3-4 gigabyte of content.

Here I’ll explaine the actions for you to be able to repeat them and get a result, similar to that, I’ll demonstrate in illustrations. I’m positive, that even with superficial knowledge of MB, it’ll help to сориентироваться.

Well, lets start

  1. A few character animation clips are kept in the article’s attachment. Start up alien.fbx.
  2. MB has a possibility to change layouts of it’s interface therefor let’s choose the third one for this example.

It has the name Edition. You can do that by pressing Ctrl+Shift+3 or through main menu Layout -> Edition.

  1. Now we have all the windows tabs we need in the navigator dialog. Pass on the tab Story.

Switching to the tab, activates this one mode of MB whether Story mode or Motion Blend (non-linear mixing) or Animation triggering.

Please, pay attention to dialog Transport controls in which timeline control takes place. I have to say that timeline slider in MB has a number of advantages. Firstly, it has the possibility to zoom some time range for a current view (like in Maya does), Secondly, pay attention to activated button Story up left. If turn off this mode, story movie isn’t showed in the scene. On the right from Story checked button there is combo box: action (one timeline slider – actions), and Edit (two time sliders). Now in details about it.


To understand the purpose of each timeline you should apply to the contents of an tab Story. Notice, all Story dialog canvas is divided into two parts. In the first part there are all the tracks concerning cameras switching, sound, video background. This first timeline shows a range of actions of this part of story.

The second part of the scale contains tracks of clips. They can be animation of objects, cameras, characters and additional functional possibilities such as constraints and commands (show/hide model in scene).

The first part is considered to be a director one. It states then and which camera is to switch on and when and which sound is to play. Another part is thought to be executive one. There are all the actions at the current moment.

Leave a Reply

Your email address will not be published. Required fields are marked *