TorqueScript Reference

- Main Page
- Related Pages
- Modules
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | List of all members
SimObject Class Reference

Inherited by ActionMap, AssetBase, AssetManager, AssetQuery, AssetTagsManifest, BehaviorInstance, BehaviorTemplate, ConsoleLogger, EventManager, FileDialog, FileObject, Message, ModuleManager, NetObject, ParticleAssetEmitter, PickingSceneController, PNGImage, PopupMenu, RemoteDebuggerBase, RenderProxy, SceneObjectSet, SimComponent, SimSet, SimXMLDocument, StreamObject, Taml, TCPObject, UndoManager, and ZipObject.

## Public Member Functions
Integer | clone ([copyDynamicFields=false]?)
void | delete ()
Identity
Reference an object
Integer | getId ()
void | setName (newName)
String | getName ()
Scoping
Manipulate the object's script-defined `Namespace`
String | getClassNamespace ()
String | getSuperClassNamespace ()
void | setClassNamespace (nameSpace)
void | setSuperClassNamespace ()
Reflection
Methods to query and manipulate the object's class, methods, and fields.
Boolean | isMethod (string methodName)
String | call (methodName, [args]*)
void | dumpClassHierarchy ()
void | dump ()
Boolean | isMemberOfClass (string classname)
String | getClassName ()
String | getFieldValue (fieldName)
Boolean | setFieldValue (fieldName, value)
Integer | getDynamicFieldCount ()
String | getDynamicField (index)
Integer | getFieldCount ()
String | getField (int index)
void | setProgenitorFile (file)
String | getProgenitorFile ()
Integer | getType ()
String | getFieldType (fieldName)
Grouping
Manipulate the (singular) group for this object.
void | setInternalName (string InternalName)
String | getInternalName ()
Boolean | isChildOfGroup (groupID)
Integer | getGroup ()
Timer/Scheduled Events
Perform timed callbacks on the object.
Boolean | startTimer (callbackFunction, float timePeriod, [repeat]?)
void | stopTimer ()
Boolean | isTimerActive ()
Integer | schedule (time, command, [arg]*)
Serialization
Write an object. (Read in with exec()).
Boolean | save (fileName, [selectedOnly]?)
void | addFieldFilter (fieldName)
void | removeFieldFilter (fieldName)

## Detailed Description

SimObject is the base class for all other scripted classes. This means that all other "simulation" classes – be they SceneObjects, Scenes, or plain-old SimObjects – can use the methods and fields of SimObject.

Identity

When we create a SimObject with `new`, it is given a unique id which is returned by `new`. We usually save the id in our own variables. Alternatively, we can give the SimObject a name which we can use to directly manipulate it. This name can be set with the `new` operator or it can be added later.

If we give an object a name, then we can write script methods that are "scoped" to run on this object only. For instance, if we have a SimObject named `MyObject`, and if we call `MyObject.myMethod()`, then this call will be handled by a method we named `MyObject::myMethod` if one exists.

See getId(), getName(), setName()

Static and Dynamic Fields

Each subclass of SimObject will provide important fields. For instance, a SceneObject will have a position, scale, etc. These are known as "static" or "built-in" fields. Additionally, you can add any number of your own fields, for example `myField` or `hitPoints`. These are known as "dynamic" or "add-on" fields. To do so only requires you to set the field directly with `%myObject.myField = myValue;`. Attempting to retrieve a field that does not exist (yet) returns nothing. There is no error or warning.

Note that static fields exist for every object of a class, while dynamic fields are unique to any one instance. Adding `myField` to one SceneObject does not add it to all SceneObjects.

For working with fields more programmatically, see Reflection below.

Script Namespace

We can attach a `Namespace` to an object. Then calls to this object will be handled by the script functions in that Namespace. For instance, if we set `%myObject.class = MyScope` then the call `%myObject.myMethod` will be handled with a method named `MyScope::myMethod()`. (If we also named the object `MyObject`, then if there is a `MyObject::myMethod()` it will run. Otherwise, Torque2D will look for `MyScope::myMethod()` and run that if found.)

Finally there is also a secondary `Namespace` that will receive the call if neither the `Name` nor the primary `Namespace` had a method to handle the call.

Unfortunately, these `Namespaces` are called `Classes` in this context. You set the `class` or `superclass`. But this should not be confused with the SimObject's "real" class which is SimObject or Scene as examples.

See getClassNamespace(), setClassNamespace(), getSuperClassNamespace(), setSuperClassNamespace()

Reflection

SimObject supports "reflection" – the run-time inspection of an object's methods, fields, etc. For instance, we can ask an object what class it instantiates, what dynamic fields it has, etc. We can also use this feature to call a method on an object even if we only know the string name of the method.

See getClassName(), isMemberOfClass(), isMethod(), dump(), dumpClassHierarchy(), call()

See getFieldValue(), setFieldValue(), getFieldCount(), getField(), getDynamicFieldCount(), getDynamicField()

Scheduling Callbacks

We can set a SimObject to regularly call its own onTimer() callback. Additionally, we can schedule a single call to any method at any time in the future.

See startTimer(), stopTimer(), isTimerActive(), schedule()

Groups
  TBD

Persistence
  canSaveDynamicFields bool = "1" - Whether a save() shall save the object's Dynamic Fields (member fields created by TorqueScript)

## Member Function Documentation

void addFieldFilter | ( | fieldName |  | ) |

Add the field to the list of fields to exclude during write.

Parameters

  fieldName | The name of the field to filter out.

Returns
  No return value

The field can be static or dynamic.

See also
  FileObject::writeObject, save, removeFieldFilter

String call | ( | methodName | ,
|  | [args] * |
| ) |  |

Dynamically call a method by a string name

Normally you would call a method in the form `object.myMethod(param1, param2)`. Alternatively, you can use `object.call(myMethod, param1, param2)`. This can be useful if, for instance, you don't know which method to call in advance.

Example
  %method = "setClassNamespace";
  %newNamespace = "myNamespace";
  %object.call(%method, %newNamespace);

Integer clone | ( | [copyDynamicFields = false] ? |  | ) |

Clones the object.

Parameters

  copyDynamicFields | Whether the dynamic fields should be copied to the cloned object or not. Optional: Defaults to false.

Returns
  (newObjectID) The newly cloned object's id if successful, otherwise a 0.

void delete | ( |  | ) |

Use the delete method to delete this object. When an object is deleted, it automatically

- Unregisters its ID and name (if it has one) with the engine.
- Removes itself from any SimGroup or SimSet it may be a member of.
- (eventually) returns the memory associated with itself and its non-dynamic members.
- Cancels all pending obj.schedule() events.

For objects in the GameBase, ScriptObject, or GUIControl hierarchies, an object will first: Call the onRemove() method for the object's namespace

Returns
  No return value.

void dump | ( |  | ) |

dump the object to the console.

Use the dump method to display the following information about this object:

- All static and dynamic fields that are non-null
- All engine and script-registered console methods (including superclass methods) for this object
  Returns
    No return value

void dumpClassHierarchy | ( |  | ) |

Write the class hierarchy of an object to the console.

Returns
  no return value

Example
  new SimGroup(sg);
  echo(sg.dumpClassHierarchy());
  > SimGroup ->
  > SimSet ->
  > SimObject

String getClassName | ( |  | ) |

Returns the engine class of this object such as `SimObject` or `SceneObject`

Returns
  class name

Note that this method is defined in SimObject but is inherited by subclasses of SimObject. Subclasses will return the correct subclass name.

Note also, getClassName() is not related to an object's `class` field! The `class` field is a scripting concept that provides a "namespace" to look for user-defined functions (see getClassNamespace()).

Example
  %example = new SimObject()
  {
  class = MyScope;
  };
  echo(%example.getClassName());
  > SimObject
  echo(%example.class);
  > MyScope

String getClassNamespace | ( |  | ) |

Returns the `Namespace` of this object as set by the user.

Returns
  The Namespace as set in the object's `class` field.

The class namespace is a a scripting concept that provides a "namespace" in which the engine looks to find user-defined scripting functions. It can be set, and reset, by the user by using setClassNamespace(). Alternatively, it can be set directly using the `class` field of the object.

Note that this can easily be confused with getClassName(), which is unrelated, and returns the "true" engine class name of an object, such as `SimObject`.

See setClassNamespace() for examples.

See also
  setClassNamespace

String getDynamicField | ( | index |  | ) |

Return the field name of a specific dynamic ("add-on") field by index.

Parameters

  index | the dynamic field for which to retrieve the name

Returns
  the name of the field

You would normally access dynamic fields directly `%object.field` or indirectly `%object.getFieldValue(%field)`. However, you may not know the field's names or otherwise need to iterate over the fields. Use getDynamicFieldCount() to get the number of dynamic fields, and then iterate over them with this function.

Note that only dynamic ("add-on") fields will be surfaced. Static ("built-in") fields like `SimSet.class` will not be counted or listed.

While static and dynamic fields have separate functions to get their counts and names, they share getFieldValue() and setFieldValue() to read and set any field by name.

Also note that the order of the fields by an index has no meaning. It is not alphabetical, the order created, or otherwise.

Example
  %count = %example.getDynamicFieldCount();
  for (%i = 0; %i < %count; %i++)
  {
  %fieldName = %example.getDynamicField(%i);
  %fieldValue = %example.getFieldValue(%fieldName);
  echo(%fieldName @ " = " @ %fieldValue);
  }

See also
  getDynamicFieldCount, getField, getFieldCount

Integer getDynamicFieldCount | ( |  | ) |

return the number of dynamic ("add-on") fields.

Returns
  the number of dynamic fields

Note that static (or "built-in") fields are not counted. For instance, `SimObject.class` will not count.

See getDynamicField() for an explanation and examples.

See also
  getDynamicField, getField, getFieldCount

String getField | ( | int | index | ) |

Return the field name of a specific static ("built-in") field by index.

Parameters

  index | the static field for which to retrieve the name

Returns
  the name of the field

You would normally access static fields directly `%object.class` or indirectly `%object.getFieldValue(%field)`. However, you may not know the field's names or otherwise need to iterate over the fields. Use getFieldCount() to get the number of static fields, and then iterate over them with this function.

Note that only static ("built-in") fields will be surfaced. Dynamic ("add-on") fields like `%SimSet.myField` will not be counted or listed.

While static and dynamic fields have separate functions to get their counts and names, they share getFieldValue() and setFieldValue() to read and set any field by name.

Also note that the order of the fields by an index has no meaning. It is not alphabetical, the order created, or otherwise.

Example
  %count = %example.getFieldCount();
  for (%i = 0; %i < %count; %i++)
  {
  %fieldName = %example.getField(%i);
  %fieldValue = %example.getFieldValue(%fieldName);
  echo(%fieldName @ " = " @ %fieldValue);
  }

See also
  getDynamicField, getDynamicFieldCount, getFieldCount

Integer getFieldCount | ( |  | ) |

return the number of static ("built-in") fields.

Returns
  the number of dynamic fields

Note that dynamic (or "add-on") fields are not counted. For instance, `%object.class` will count, but `%object.myField` will not.

See getField() for an explanation and examples.

See also
  getDynamicField, getDynamicFieldCount, getField

String getFieldType | ( | fieldName |  | ) |

return the type of a field, such as "int" for an Integer

Parameters

  fieldName | field of the object to get the type of

Returns
  string name of the type; or nothing if the field isn't found

No warning will be shown if the field isn't found.

Example
  new sprite(s);
  echo(s.getFieldType(frame));
  > int
  echo(s.getFieldType(blendcolor));
  > ColorF
  echo(s.getFieldType(angle));
  > float
  echo(s.getFieldType(position));
  > Vector2
  echo(s.getFieldType(class));
  > string
  echo(s.getFieldType(notAField));
  >

String getFieldValue | ( | fieldName |  | ) |

Return the value of any field. This can be a static ("built-in") field or a dynamic ("add-on") field.

Normally, you would get a field directly as `%object.field`. However, in some cases you may want to use getFieldValue(). For instance, suppose you allow the field name to be passed into a function. You can still get that field with `%object.getFieldValue(%field)`.

Parameters

  fieldName | the name of the field

Returns
  the value of the field

Example
  // create a SimObject and set its 'class' field for our example
  %example = new SimObject()
  {
  class = "MyClass";
  }
  // 'class' is a static "built-in" field. retrieve it directly and with getFieldValue()
  echo(%example.class);
  > MyClass
  echo(%example.getFieldValue(class));
  > MyClass
  // set a dynamic "add-on" field
  %example.myField = "myValue";
  echo(%example.myField);
  > myValue
  echo(%example.getFieldValue(myField));
  > myValue

Integer getGroup | ( |  | ) |

determines if this object is contained in a SimGroup and if so, which one.

Returns
  Returns the ID of the SimGroup this shape is in or zero if the shape is not contained in a SimGroup

See also
  SimGroup, getInternalName, setInternalName, isChildOfGroup

Integer getId | ( |  | ) |

get the unique numeric ID – or "handle" – of this object.

Returns
  Returns the numeric ID.

The id is provided for you by the simulator upon object creation. You can not change it and it likely will not be reused by any other object after this object is deleted.

Example
  new SimObject(example);
  echo(example.getId());
  > 1752

Caveat
  You can not access the id directly. That is, you can not access `%object.id`. If you do set `%object.id` you will only succeed in creating a dynamic field named `id` – an unrelated field to the actual object's id.

Example
  %example = SimObject();
  echo(%example.getId());
  > 1753
  // warning! this will fail to change the id!
  // it will also not warn you as it is legal syntax
  %example.id = 50;
  echo(%example.getId());
  > 1753
  echo(%example.id);
  > 50

See also
  getName, setName

String getInternalName | ( |  | ) |

returns the objects "internal" name

Returns
  the internalName used for group access

Not to be confused with the object's `Name`, the internal name is used to find this object within a group. Each object may be in one group, ultimately forming a tree (usually for GUI related classes). See SimGroup for more information.

See also
  SimGroup, setInternalName, isChildOfGroup, getGroup

String getName | ( |  | ) |

Returns the name of the object

Returns
  the "global" name

See setName() for a description of the name field.

Note not to confuse this with the `internalName` which is a name for grouping purposes.

Example
  %example = new SimObject();
  %example.setName("myObject");
  // now we can reference our object with variables and with its name
  %example.getId();
  > 160
  myObject.getId();
  > 160

See setName() for caveats.

See also
  setName, getId

String getProgenitorFile | ( |  | ) |

Gets the progenitor file responsible for this instances creation.

Returns
  The progenitor file responsible for this instances creation.

String getSuperClassNamespace | ( |  | ) |

Return the superclass `Namespace` of this object as set by the user.

An object can have a primary and secondary `Namespace` also known as its `class` and `superclass`. If a user-defined function is not found in the `class` then the `superclass` is searched.

See also
  getClassNamespace

Integer getType | ( |  | ) |

Use the getType method to get the type for this object.

Returns
  Returns a bit mask containing one or more set bits.

This is here for legacy purposes.

This type is an integer value composed of bitmasks. For simplicity, these bitmasks are defined in the engine and exposed for our use as global variables. To simplify the writing of scripts, a set of globals has been provided containing the bit setting for each class corresponding to a particular type.

See also
  getClassName

Boolean isChildOfGroup | ( | groupID |  | ) |

test if this object is in a specified group (or subgroup of it)

Parameters

  groupID | the ID of the group being tested

Returns
  true if we are in the specified simgroup or a subgroup of it; false otherwise

See also
  SimGroup, getInternalName, setInternalName, getGroup

Boolean isMemberOfClass | ( | string | classname | ) |

returns true if this object is of the specified class or a subclass of the specified class

Returns
  true if a class or subclass of the given class

Example
  %example = new SceneObject();
  echo(%example.isMemberOfClass(SimObject);
  > 1
  echo(%example.isMemberOfClass(SimSet);
  > 0

Boolean isMethod | ( | string | methodName | ) |

Returns wether the method exists for this object.

Returns
  true if the method exists; false otherwise

The method must be a "built-in" method, or one that is not user-defined in script. It must also be a direct method on the object, and not a behavior defined in a Behavior.

Boolean isTimerActive | ( |  | ) |

Checks whether the periodic timer is active for this object or not.

Returns
  Whether the periodic timer is active for this object or not.

void removeFieldFilter | ( | fieldName |  | ) |

Remove the field from the list of fields to exclude during write

Parameters

  fieldName | The name of the field to stop filtering out.

Returns
  No return value.

The field can be static or dynamic.

See also
  FileObject::writeObject, save, addFieldFilter

Boolean save | ( | fileName | ,
|  | [selectedOnly] ? |
| ) |  |

save this object to a specified file

Parameters

  fileName | the file to save to
  selectedOnly | seems to be for editors to set. not sure how to mark anything as "selected"

Returns
  false if file could not be opened; true otherwise

See also
  FileObject::writeObject, addFieldFilter, removeFieldFilter

Integer schedule | ( | time | ,
|  | command | ,
|  | [arg] * |
| ) |  |

schedule an action to be executed upon this object in the future.

Parameters

  time | Time in milliseconds till action is scheduled to occur.
  command | Name of the command to execute. This command must be scoped to this object (i.e. It must exist in the namespace of the object), otherwise the schedule call will fail.
  arg1...argN | These are optional arguments which will be passed to the command. This version of schedule automatically passes the ID of obj as arg0 to command.

Returns
  Returns an integer schedule ID.

The major difference between this and the schedule() console function is that if this object is deleted prior to the scheduled event, the event is automatically canceled. Times should not be treated as exact since some 'simulation delay' is to be expected. The minimum resolution for a scheduled event is 32 ms, or one tick.

The existence of command is not validated. If you pass an invalid console method name, the schedule() method will still return a schedule ID, but the subsequent event will fail silently.

To manipulate the scheduled event, use the id returned with the system schedule functions.

See also
  schedule

void setClassNamespace | ( | nameSpace |  | ) |

Sets the `Namespace` of this object.

Returns
  no return value

The class namespace is a a scripting concept that provides a "namespace" in which the engine looks to find user-defined scripting functions. It can be set, and reset, by the user using setClassNamespace(). Alternatively, it can be set directly using the `class` field of the object.

The `Namespace` or `class` can then be returned with getClassNamespace(). Note that this can easily be confused with getClassName(), which is unrelated, and returns the "true" engine class name of an object, such as `SimObject`.

Example
  %example = new SimObject()
  {
  class = MyScope;
  };
  echo(%example.class);
  > MyScope
  // set the namespace using setNamespace()
  %example.setClassNamespace(DifferentScope);
  echo(%example.class);
  > DifferentScope
  // set the namespace directly using the field 'class'
  %example.class = YetAnotherScope;
  echo(%example.getClassNamespace());
  > YetAnotherScope

See also
  getClassNamespace

Boolean setFieldValue | ( | fieldName | ,
|  | value |
| ) |  |

Set the value of any field. This can be a static ("built-in") field or a dynamic ("add-on") field.

Normally, you would set a field directly as `%object.field = value`. However, in some cases you may want to use setFieldValue(). For instance, suppose you allow the field name to be passed into a function. You can still set that field with `%object.setFieldValue(field, "myValue")`.

Parameters

  fieldName | the name of the field to set
  value | the value to set

Returns
  always returns true

Example
  // create a SimObject
  %example = new SimObject();
  // 'class' is a static "built-in" field. set it directly and with setFieldValue()
  echo(%example.class);
  >
  %example.class = "MyClass";
  echo(%example.class);
  > MyClass
  %example.setFieldValue(class, "AnotherClass");
  echo(%example.class);
  > AnotherClass
  // set a dynamic "add-on" field
  echo(%example.myField);
  >
  %example.myField = "myValue";
  echo(%example.myField);
  > myValue
  %example.setFieldValue(anotherField, "anotherValue");
  echo(%example.anotherField);
  > anotherValue

void setInternalName | ( | string | InternalName | ) |

sets the objects "internal" name

Parameters

  internalName | the name used for group access

Returns
  nothing returned

Not to be confused with the object's `Name`, the internal name is used to find this object within a group. Each object may be in one group, ultimately forming a tree (usually for GUI related classes). See SimGroup for more information.

See also
  SimGroup, getInternalName, isChildOfGroup, getGroup

void setName | ( | newName |  | ) |

Set the objects name field.

Parameters

  newName | name for objects

Returns
  no return value

Now the object can be invoked by this name. This is different than tracking an object by a variable, such as `%myObject` or `$myObject`.

Only one object can have a specific name. Setting a second object with this name will remove the name from the former object.

Note not to confuse this with the `internalName` which is a name for grouping purposes.

Example
  %obj = new SimObject();
  %obj.setName("MyName");
  // these are now equivalent
  %obj.save();
  MyName.save();

Caveat
  You can not access the name directly. That is, you can not access `%object.name`. If you do set `%object.name` you will only succeed in creating a dynamic field named `name` – an unrelated field to the actual object's name.

Example
  SimObject("example");
  echo(example.getName());
  > example
  // warning! the field `name` does not exist yet
  echo(example.name);
  >
  // warning! this will fail to change the name!
  // it will also not warn you as it is legal syntax
  %example.name = "newExample";
  echo(%example.getName());
  > example
  echo(%example.name);
  > newExample

See also
  setName, getId

void setProgenitorFile | ( | file |  | ) |

Sets the progenitor file responsible for this instances creation.

Parameters

  file | The progenitor file responsible for this instances creation.

Returns
  No return value.

void setSuperClassNamespace | ( |  | ) |

Sets the superclass `Namespace` of this object.

An object can have a primary and secondary `Namespace` also known as its `class` and `superclass`. If a user-defined function is not found in the `class` then the `superclass` is searched.

See also
  setClassNamespace

Boolean startTimer | ( | callbackFunction | ,
|  | float | timePeriod,
|  | [repeat] ? |
| ) |  |

Starts a periodic timer for this object. Sets a timer on the object that, when it expires, will cause the object to execute the given callback function. The timer event will continue to occur at regular intervals until stopTimer() is called or the timer expires.

Parameters

  callbackFunction | The name of the callback function to call for each timer repetition.
  timePeriod | The period of time (in milliseconds) between each callback.
  repeat | The number of times the timer should repeat. If not specified or zero then it will run infinitely.

Returns
  No return Value.

void stopTimer | ( |  | ) |

Stops the periodic timer for this object.

Returns
  No return Value.