Creating a new SimObject instance

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.

How to do it...

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();

How it works...

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's more...

There are a number of different options when it comes to creating a SimObject derived class. Let's take a look at them.

Creating a new SimObject instance with a globally unique name

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:

String value	Impact on object creation
replaceExisting	This deletes the current object with the same name and replaces it with the new object.
renameNew	This adds a number to the end of the name of the new object. This number starts at one and is incremented until a unique name combination is found.
unnamedNew	This removes the global name from the new object.
postfixNew	This appends a string to the end of the name of the new object. This string is defined in the global variable $Con::redefineBehaviorPostfix and is set to an empty string by default.
oldRedefineBehavior	This indicates the default condition of not creating the new object. This is also the behavior when $Con::redefineBehavior is set to an empty string.

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.

Creating a new SimObject instance with defined properties

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.

Creating a new SimObject instance based on another SimObject instance

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.

See also

• Creating a new internal name only SimObject instance

• Creating a new Datablock object

• Creating a new singleton

• Extending a SimObject instance using the class property