[lang_ru]

Это перевод статьи по программированию в среде MotionBuilder (виден в английской версии сайта). Оригинал принадлежит ресурсу GameDev.RU и расположен здесь http://www.gamedev.ru/community/toolcorner/articles/Motion_Builder

Выражаю огромную благодарность Ольге Степенко за перевод.

[/lang_ru]

[lang_en]

I have moved this article to the special page http://neill3d.com/tool-programming-in-mobu

Introduction

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 (reveal) helpful practical aspects of MotionBuilder.

[/lang_en]

[lang_en]To confirm the significance of the present software I would like to produce (adduce) 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 (not sure in the word permorming with “operation”)
  • Efficient (productive) technology for working with mo-cap devices.
  • Easy-to-use (handy) 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, (is this phrase ok?) 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.

Note

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 MotionBuilderbinconfigscripts. 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…

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.

Example:

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 (<start>, <stop>) – 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.

Example:

#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

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 .

(picture)

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

(picture)

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.

Example

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 <name of a property>

Example…

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

Example

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( <pointer to data buffer>, <size in bytes >

Example

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

Setting value

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

Example

lProp.Data = False

The situation is analogoes to the getting a value

SetInt(<integer number>)

SetString(<string>)

SetData(<point to data buffer>)

Example

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.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
FBProperty *lDampProp = mFinger[0]-&gt;PropertyList.Find( mDampName );
<strong>if</strong> ( lDampProp )
{
  lDampProp-&gt;GetData( &amp;temp, <strong>sizeof</strong>(<strong>double</strong>) );
  temp += value;

  <strong>if</strong> ( lDampProp-&gt;IsAnimatable() ) {
    FBPropertyAnimatable *lDampAnimatable = (FBPropertyAnimatable*) lDampProp;
    FBAnimationNode *lAnimationNode = lDampAnimatable-&gt;GetAnimationNode();
    <strong>if</strong> ( lAnimationNode ) {
      lAnimationNode-&gt;KeyAdd( &amp;temp );
    }
  }

  lDampProp-&gt;SetInt( (<strong>int</strong>) temp );
}

Creation of properties.

Creation a new property for an object is realized through the FBComponent class by the method PropertyCreate(<name>, <property type>, <data type>, <animatable?>, <user?>, <reference to property source>), where

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

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

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

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

<pointer to the source property> – a property, which value refers to. By default NULL

Ex for Python


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

Ex for Open Reality

HFBProperty lProp = lModel->PropertyCreate("MyProp", kFBPT_double,
  ANIMATIONNODE_TYPE_NUMBER, true);

To be continue…

—-

Article is translated from GameDev.RU resource by Olga Stepenko (olyastep@yandex.ru). Original you can find here http://www.gamedev.ru/community/toolcorner/articles/Motion_Builder

[/lang_en]

Tool programming in MotionBuilder. Part 1
Tagged on:             

One thought on “Tool programming in MotionBuilder. Part 1

Leave a Reply

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