A SimObject instance is the base class from which all the other classes that can be accessed using TorqueScript are derived. We don't work with the SimObject class directly, but rather work with one of the derived classes. In this recipe we will see the various ways to construct a new SimObject-based class.
Creating a
SimObject-based class is straightforward and there are a number of options available that we will look into later. Here we will create a ScriptObject instance, the simplest SimObject derived class, and assign it to a variable as follows:
%object = new ScriptObject();
We use the new keyword to create a new SimObject-based class, which returns the new object so it may be stored into a variable for future use.
There are a number of different options when it comes to creating a SimObject derived class. Let's take a look at them.
If we want a SimObject instance to be accessible from anywhere in the script ,we can assign a global name to it. Then when we want to work with the SimObject instance we can just use its name. As an example, we will create a Player class object and
assign a globally unique name to it as follows:
new Player(MyPlayer);
Here we create a new Player class object and give it a globally unique name of MyPlayer. Making use of the return value of the new keyword in a local variable is optional as we can now access this new object with its unique name. For example, this is how we obtain the player's position using the name of the object:
%pos = MyPlayer.getPosition();
What happens if there is already another object that has the same global name as the one we wish to create? Normally Torque 3D will output an error to the console stating Cannot re-declare object and the new object will not be created (the new keyword will return a value of 0). However, this behavior may be modified through the use of the $Con::redefineBehavior global variable. The following table lists the accepted values for this variable:
Modifying $Con::redefineBehavior must be done with care as it affects how the object creation system of Torque 3D operates. It can also
have a non-intuitive impact on the global name of a new object.
We can set up properties of a new SimObject instance at the same time the object is created. This is done by writing a list of properties and their values within curly braces as part of the object creation. Setting properties at the time of object creation saves a lot of typing later on. It also provides immediate values for the properties of an object rather than first having them set to some default value. For example, we can set the properties for a new Player object as follows:
new Player(MyPlayer)
{
datablock = SoldierDatablock;
position = "0 0 10";
size = "1 1 1";
squad = "Bravo";
};In this example we are setting the standard datablock, position, and size properties for the Player class. We are also setting a script-specific property called
squad. This is known as a
dynamic property and only means something to our game play code and not the core Torque 3D engine.
Sometimes we want to create a new SimObject instance whose properties are based on another, previously created
SimObject instance. This previously created SimObject instance is known as the
copy source and is passed-in as part of the creation process of a SimObject instance. For example, we will create a new SimObject instance based on the Player class object that we created in the previous example as follows:
new Player(MyPlayer2 : MyPlayer)
{
position = "2 0 10";
};In this example, the MyPlayer2 object will have all of the same properties (including the dynamic ones) as the MyPlayer object, except for the position property that we've explicitly set. This full-copying of properties only occurs if the copy source object is of the same class as the new SimObject instance. If the copy source is of a different class, only the dynamic properties (if any) will be copied over and not the class-specific ones.
It should also be noted that this is only a copy of properties at the time of object creation. There is no parent/child relationship occurring. In our previous example, modifying a property on the MyPlayer object later on will have no impact on the properties of MyPlayer2.