Simulation Manager

Overview

SimBase (engine/console/simBase.*) defines the foundation SimObject classes that form the basis of the simulation system.

SimObject is the base class for all objects that the console language can create and manipulate. All game classes (Player, InteriorInstance, Terrain, etc.) and GUI classes (GuiCanvas, GuiControl, etc). are all derived from SimObject. SimObject maintains the list of dynamic fields, has name and ID properties, and can register itself with a global object manager, as well as providing several other services.

A SimSet is a simple collection of SimObjects. The set has console methods for adding and removing objects and iterating through the set.

A SimGroup is a derivative of SimSet that "owns" the objects in its collection. When a SimGroup object is destroyed, it destroys all of its members. GuiControl is derived from SimGroup - thus making the GUI a hierarchal set of objects.

SimEvent is a special class objects can use to send time-delayed messages to objects.

SimManager (engine/console/simManager.cc) is a collection of functions for managing all of the objects and events in the simulation.

Accessing Objects within the Simulation

Objects are collected in a hierarchy of SimGroups and can be searched for by name or by object id.

Within TorqueScript, objects can be referenced directly via an object ID (the unique identifier provided by the Simulation Manager when the object was registered with the simulation), or if the object was registered with a unique name, it can be referenced in TorqueScript by the name directly.

Internally, the Console will search through the objects within the Simulation Manager and return a reference to the object if it is found.

This type of search functionality is also available to us in C++, through the use of the call Sim::FindObject(), which returns a pointer to a SimObject if the object searched for was found, or NULL if the object is not registered with the simulation. Since all game world objects derive from the C++ class SimObject, we can then dynamically cast this pointer to any class that is appropriate, and utilize the object returned appropriately.

Persistence and Inspection

Objects in Torque can be saved to a script file using SimObject::save(). This basically dumps the current state of all the object's registered fields and dynamic fields, as well as, in the case of a SimGroup, all of that object's sub objects. GUIs and missions are examples of how the engine's editors save objects.

Objects' fields can also be modified in-game using the inspector, which a GUI window that shows the fields of an object and allows those fields to be changed and saved. Before new field values are to be saved to an object its onPreApply() method will be called, then the fields will be changed, then the object's onPostApply() method will be called.

Useful Console Commands

There are several console commands that are useful to get an idea of what's going on in the system:

trace(true);       // Turns on console trace output, trace(false); to disable it.
tree();            // Displays a graphical hierarchy and object inspector for
                   // all objects currently registered in the system.
object.dump();     // Dumps a list of all console commands and instance variables on an object.
set.listObjects(); // Lists all of the objects in a set.