TorqueScript Objects

Having covered the basics of the language, it's time to examine some of TorqueScript's more interesting details.

In Torque, every item in the game world is an object, and all game world objects can be accessed via script. For example, Player, WheeledVehicle, Item, etc are all accessible via script, though they are defined in C++.

Objects are created in TorqueScript using the following syntax:

           // In TorqueScript
           %var = new ObjectType(Name : CopySource, arg0, ..., argn) 
               <datablock = DatablockIdentifier;>
               [existing_field0 = InitialValue0;]
               [existing_fieldM = InitialValueM;]
               [dynamic_field0 = InitialValue0;]
               [dynamic_fieldN = InitialValueN;]

This syntax is simpler than it looks. Let's break it down:

  • %var- Is the variable where the object's handle will be stored.
  • new- Is a key word telling the engine to create an instance of the following ObjectType.
  • ObjectType- Is any class declared in the engine or in script that has been derived from SimObject or a subclass of SimObject. SimObject-derived objects are what we were calling "game world objects" above.
  • Name (optional)- Is any expression evaluating to a string, which will be used as the object's name.
  • CopySource (optional)- The name of an object which is previously defined somewhere in script. Existing field values will be copied from CopySource to the new object being created. Any dynamic fields defined in CopySource will also be defined in the new object, and their values will be copied. Note: If CopySource is of a different ObjectType than the object being created, only CopySource's dynamic fields will be copied.
  • arg0, ..., argn (optional)- Is a comma separated list of arguments to the class constructor (if it takes any).
  • datablock- Many objects (those derived from GameBase, or children of GameBase) require datablocks to initialize specific attributes of the new object. Datablocks are discussed below.
  • existing_fieldM- In addition to initializing values with a datablock, you may also initialize existing class members (fields) here. Note: Note: In order to modify a member of a C++-defined class, the member must be exposed to the Console. This concept is discussed in detail later.
  • dynamic_fieldN- Lastly, you may create new fields (which will exist only in Script) for your new object. These will show up as dynamic fields in the World Editor Inspector.

Let's create one object that doesn't use a datablock and one that does:

           // create a SimObject w/o modifying any fields
           $example_object = new SimObject();
           // create a SimObject w/ dynamic fields
           $example_object = new SimObject() 
               a_new_field = "Hello world!";
           // create a StaticShape using a datablock
           datablock StaticShapeData(MyFirstDataBlock) 
               shapeFile = "~/data/shapes/player/player.dts";   
               junkvar = "helloworld";
           new StaticShape() 
               dataBlock = "MyFirstDataBlock";
               position = "0.0 0.0 0.0";
               rotation = "1 0 0 0";
               scale = "1 1 1";