#include <simObject_ScriptBinding.h>

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

Public Member Functions
void	assignFieldsFrom (SimObject)

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)

Boolean	setEditFieldValue (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] *)

member group Object to Object Events
Raise events for listening objects to consume.
void	startListening (SimObject)

void	stopListening (SimObject)

void	addListener (SimObject)

void	removeListener (SimObject)

void	removeAllListeners ()

void	postEvent (String eventName, String data)

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

◆ addFieldFilter()

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

◆ addListener()

void addListener ( SimObject )

Adds an object so that it receives events from this object.

Parameters

SimObject The object that will be listening to events.

Returns: No return value.

◆ assignFieldsFrom()

void assignFieldsFrom ( SimObject )

Takes all values from one object and puts them into anther object of the same class. This includes dynamic fields.

Returns: No return value.

◆ call()

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

◆ clone()

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.

◆ delete()

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.

◆ dump()

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

◆ dumpClassHierarchy()

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

SimGroup

SimObject
Definition simObject_ScriptBinding.h:23

SimSet
Definition simSet_ScriptBinding.h:192

echo
void echo(text, [...] *)
Definition output_ScriptBinding.h:36

◆ getClassName()

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

◆ getClassNamespace()

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

◆ getDynamicField()

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

◆ getDynamicFieldCount()

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

◆ getField()

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

◆ 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

◆ getFieldType()

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

>

Vector2
type Vector2
Definition core_ScriptBinding.dox:168

◆ getFieldValue()

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

◆ getGroup()

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

◆ getId()

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

◆ getInternalName()

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

◆ getName()

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

@Caveats See setName() for caveats.

See also: setName, getId

◆ getProgenitorFile()

String getProgenitorFile ( )

Gets the progenitor file responsible for this instances creation.

Returns: The progenitor file responsible for this instances creation.

◆ getSuperClassNamespace()

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

◆ getType()

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

◆ isChildOfGroup()

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

◆ isMemberOfClass()

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

SceneObject
Definition SceneObject_ScriptBinding.h:36

◆ isMethod()

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.

◆ isTimerActive()

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.

◆ postEvent()

void postEvent	(	String	eventName,
		String	data
	)

Raises an event on all listening objects.

Parameters

eventName	The name of the event to raise. The actual function called on listeners will begin with "on" followed by the event name.
data	Any data that should be passed on to the listeners.

Returns: No return value.

◆ removeAllListeners()

void removeAllListeners ( )

Removes all listeners from this object.

Returns: No return value.

◆ removeFieldFilter()

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

◆ removeListener()

void removeListener ( SimObject )

Removes an object so that it no longer receives events from this object.

Parameters

SimObject The object that will stop listening to events.

Returns: No return value.

◆ save()

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

◆ schedule()

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

◆ setClassNamespace()

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

◆ setEditFieldValue()

Boolean setEditFieldValue	(	fieldName	,
		value
	)

◆ setFieldValue()

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

◆ setInternalName()

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

◆ setName()

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

◆ setProgenitorFile()

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.

◆ setSuperClassNamespace()

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

◆ startListening()

void startListening ( SimObject )

Starts listening to another object.

Parameters

SimObject The object that will be posting events.

Returns: No return value.

◆ startTimer()

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.

◆ stopListening()

void stopListening ( SimObject )

Stops listening to another object.

Parameters

SimObject The object that will be posting events.

Returns: No return value.

◆ stopTimer()

void stopTimer ( )

Stops the periodic timer for this object.

Returns: No return Value.

Public Member Functions

Detailed Description

Member Function Documentation

◆ addFieldFilter()

◆ addListener()

◆ assignFieldsFrom()

◆ call()

◆ clone()

◆ delete()

◆ dump()

◆ dumpClassHierarchy()

◆ getClassName()

◆ getClassNamespace()

◆ getDynamicField()

◆ getDynamicFieldCount()

◆ getField()

◆ getFieldCount()

◆ getFieldType()

◆ getFieldValue()

◆ getGroup()

◆ getId()

◆ getInternalName()

◆ getName()

◆ getProgenitorFile()

◆ getSuperClassNamespace()

◆ getType()

◆ isChildOfGroup()

◆ isMemberOfClass()

◆ isMethod()

◆ isTimerActive()

◆ postEvent()

◆ removeAllListeners()

◆ removeFieldFilter()

◆ removeListener()

◆ save()

◆ schedule()

◆ setClassNamespace()

◆ setEditFieldValue()

◆ setFieldValue()

◆ setInternalName()

◆ setName()

◆ setProgenitorFile()

◆ setSuperClassNamespace()

◆ startListening()

◆ startTimer()

◆ stopListening()

◆ stopTimer()