Exposing Object Classes to Script
In Torque3D, there are several options available that give the gameplay scripts the ability to read and write variables, and call engine-side functionality. This is important for most classes, as a majority of their logic is implemented within the engine code itself for performance reasons.
Below, this article will go over the means you can use to expose the class to script access.
Torque3D provides a powerful, but fairly straightforward way to add modifiable fields to object classes, allowing developers to easily modify properties via the tools and gameplay scripts. This functionality is provided through the
addProtectedFieldfunctions, which are used inside the
initPersistFieldsfunction of an object class.
addFieldfunction is used to define a new field for an object class, which can then be modified in the engine's editors. The basic syntax for using
addFieldis as follows:
addField( name, type, offset(className, fieldName), description );
nameis the name of the field as it will appear in the editors, or used in scripts.
typeis the data type of the field, such as
classNameis the name of the class the field is being exposed for.
fieldNameis the name of the class' attribute variable being exposed.
descriptionis a string that provides a brief description of the field, which will be displayed in the editors.
Let's say we want to add a modifiable field to an object class in Torque3D that exposes the object's height. The following code shows how to do this using the
addField( "height", TypeF32, offset(MyObjectClass, mHeight), "The height of the object" );
In this example, we are adding a new field to the
MyObjectClassobject class, with the data type
TypeF32(floating-point number), defining the offset for the
mHeightvariable, and a description of "The height of the object".
You may be wondering what the offset macro function is for. What this does is tells the C++ code where to look for the mHeight field inside the MyObjectClass in memory. When scripts or editors get or set the value of the
heightscript variable, it can then successfully look up the
mHeightvariable in the
Below is a list of more detailed information on variants of addField that do expanded or more specialized behavior beyond just exposing a class' variable to script.
In Torque3D, the
DefineEngineMethodmacro function provides a powerful tool for adding engine methods to object classes, allowing developers to expose custom functionality to scripts. This functionality can be used to create new actions, calculations, and other operations that can be performed on objects in the engine, where the C++ code is more efficient than script.
DefineEngineMethodmacro function is used to define a new engine method for an object class, which can be called from scripts. The basic syntax for using
DefineEngineMethodis as follows:
DefineEngineMethod( className, methodName, returnType, (argList), (defaultValueList), methodDescription )
// implementation of the method
classNameis the name of the class to add the method to.
methodNameis the name of the method as it will appear in scripts.
returnTypeis the data type of the return value, such as
argumentListis a list of argument names, in the format
(argType argName, argType argName, ...).
defaultValueListis an optional list of default values, matched in order to the
methodDescriptionis a string that provides a brief description of the method, which will be displayed in the engine's documentation.
Let's say we want to add a new engine method to an object class in Torque3D that sets the object's position. The following code shows how to do this using the
void MyObjectClass::setPosition(const float& x, const float& y, const float& z)
mPosition = Point3F(x, y, z);
DefineEngineMethod( MyObjectClass, setPosition, void, (float x, float y, float z), (0,0,0), "Sets the position of the object." )
object->setPosition(x, y, z);
In this example, we are adding a new engine method
MyObjectClassobject class, with a return type of
void, arguments of
zeach with data type
float, and a description of "Sets the position of the object."
It's important to note that while we have default values for each argument here, any and all default values are optional. If no default values are defined, then the enclosing parentheses are removed, like so:
DefineEngineMethod( MyObjectClass, dump, void, (),, "Dumps info about the object to the console" )
The parentheses for the arg list are required, but the empty default values list is not.
If using an Object Class for an argument type, the default must be defined as:
Below is an example of it being called in a script:
%obj = new MyObjectClass();
%obj.setPosition(5, 10, 3);
With this implementation, the engine method can be called from scripts to set the position of an object in the engine, making it easier to control the position of objects in your game.