From TDN

This page is a Work In Progress.

Note: This document is for TGB versions 1.5 and greater.

Contents 1 Concepts 2 A Sample Behavior 3 Behavior Creation, Start to Finish 4 Conclusion

Concepts

I'm not going to go into to much detail on the theory behind behaviors and how they work, but there are a couple of things that are important to understand.

The main power of behaviors is their ability to define callbacks that are triggered by the engine. A behavior can implement any callback that involves a t2dSceneObject. For example, when a t2dSceneObject collides with another object, any behaviors that it has added to it will receive an onCollision event. For a complete listing of callbacks that behaviors can implement, go here.

Behaviors come in two parts: BehaviorTemplate and BehaviorInstance. BehaviorTemplates contain the actual definition of the behavior, like the methods it defines and its fields. BehaviorInstances are created as instances of BehaviorTemplates and are what is actually added to the scene objects. For the most part, you can ignore BehaviorInstances since the editor deals with them.

The editor will only find behaviors that are defined in the game/behaviors folder of your project. So, if you want the behavior editable, make sure it is defined in a script file in that directory (or a sub-directory of that directory). In iTorque2D as of January 2010 you must put your behaviors in a folder such as 'iTorque2D_1_4/MyProjects/RainyDay/projectFiles/game/scripts/behaviors' in order to see the behaviors in the editor.

In a behavior's callback method, the %this object is the behavior instance itself, not the scene object it is added to. To access the scene object, use %this.owner. This is a very common source of errors. If you're calling a method, the console will more than likely warn you about the problem. But, if you're accessing a field on the object, it won't. So, be wary.

A Sample Behavior

First, I'm just going to dump out a very simple example behavior file. This behavior just sets a velocity on an object when it is clicked on with the mouse.

if (!isObject(MouseDownVelocityBehavior))
{
   %template = new BehaviorTemplate(MouseDownVelocityBehavior);
   
   %template.friendlyName = "Mouse Down Velocity";
   %template.behaviorType = "Input";
   %template.description  = "Set the object's velocity on mouse down";

   %template.addBehaviorField(xVelocity, "The object's horizontal speed", float, 5.0);
   %template.addBehaviorField(yVelocity, "The object's vertical speed", float, 5.0);
}

function MouseDownVelocityBehavior::onBehaviorAdd(%this)
{
   %this.owner.setUseMouseEvents(true);
}

function MouseDownVelocityBehavior::onMouseDown(%this, %modifier, %worldPos)
{
   %this.owner.linearVelocity = %this.xVelocity SPC %this.yVelocity;
}

The first line checks to make sure a different behavior with the same name doesn't already exist. If it does, the template will not be created. This is not entirely necessary, but it is good practice. The next line actually creates a BehaviorTemplate called MouseDownVelocityBehavior. The following three lines set a couple of properties that the editor uses. These are not required, but they make using behaviors in the editor much nicer. And, if you're planning on distributing the behavior to other users, it's definitely a good idea to put quality information here.

• friendlyName: This is the name that will show up in the editor to represent this behavior.
• behaviorType: This is the category that this behavior will appear in in the editor.
• description: This describes what the behavior does. This can be a string, or the filename of a text file that describes the behavior.

The next part of the template definition defines the fields that the behavior uses so the editor can modify them. The parameters to the addBehaviorField are as follows:

• %fieldname: The name of the field.
• %description: The affect of the field on the object. This is used as the tooltip in the editor.
• %type: The type of field. Valid types are string, int, bool, float, Point2F, enum, object, and keybind. This defines what type of edit field will be used by the editor.
• %defaultValue: The value of the field if it is not modified in the editor.
• %typeInfo: This is an optional parameter, and isn't used in the above definition. It specifies additional information for the enum or object types. For an enum type, it is a tab separated list of the allowed values for the field. For the object type, it is the class name of objects that can be set on the field.

For more in depth examples on creating behaviors, see this forum thread.

The rest of the file contains the methods that the behavior implements.

The first method, onBehaviorAdd, is called when the behavior is added to the object. This gets called both in the editor and in the game, so it really should only be used to initialize data. In this particular case, we're enabling mouse events on the owner object. %this.owner is the scene object that the behavior is added to.

The second method just applies the linear velocity as set in the editor to the object when the mouse is clicked.

Behavior Creation, Start to Finish

The first step is creating a new project. Run Torque Game Builder and click on the 'create' button. Name your game and set the desired location on your hard drive, then press the create button. This will generate and open a new project. Browse to the game directory that you just created and go to the game/behaviors folder. This is the folder that all of your behaviors should be defined in. Create a new text file in whatever plain text editor you choose and save it with a .cs file extension.

Copy and paste the code in the above sample behavior into this new file and save it. That should be it for creating the behavior. Now, run Torque Game Builder again (or reopen it if it is already open), and open the project. Drag an image file onto the application window to create an image map to use. Now, drag the image map from the create panel into the scene. Switch to the edit panel and select 'Mouse Down Velocity' from the drop down list in the Behaviors rollout. Then, click on the green add button to the left of the list. Now, you can play the game by clicking on the play button in the toolbar. In the game, click on the object with the mouse and it should start moving.

Conclusion

As you can see, scripting behaviors is almost exactly like scripting without behaviors. The difference is in the ability to more directly control the execution by changing values in the editor. And, it keeps your code organized and self-contained, making it much easier to focus on individual pieces of functionality, and easier to isolate bugs when they crop up.