SimObject Class Reference#include <simBase.h>
Inheritance diagram for SimObject:
Detailed Description
Base class for objects involved in the simulation.
SimObject is a base class for most of the classes you'll encounter working in Torque. It provides fundamental services allowing "smart" object referencing, creation, destruction, organization, and location. Along with SimEvent, it gives you a flexible event-scheduling system, as well as laying the foundation for the in-game editors, GUI system, and other vital subsystems.
You will spend a lot of your time in Torque subclassing, or working with subclasses of, SimObject. SimObject is designed to be easy to subclass.
You should not need to override anything in a subclass except:
Of course, if you know what you're doing, go nuts! But in most cases, you shouldn't need to touch things not on that list.
When you subclass, you should define a typedef in the class, called Parent, that references the class you're inheriting from.
Then, when you override a method, put in:
Of course, you want to replace onAdd with the appropriate method call.
SimObjects do not live apart. One of the primary benefits of using a SimObject is that you can uniquely identify it and easily find it (using its ID). Torque does this by keeping a global hierarchy of SimGroups - a tree - containing every registered SimObject. You can then query for a given object using Sim::findObject() (or SimSet::findObject() if you want to search only a specific set).
Registering a SimObject performs these tasks:
- Marks the object as not cleared and not removed.
- Assigns the object a unique SimObjectID if it does not have one already.
- Adds the object to the global name and ID dictionaries so it can be found again.
- Calls the object's onAdd() method. Note: SimObject::onAdd() performs some important initialization steps. See here for details" on how to properly subclass SimObject.
- If onAdd() fails (returns false), it calls unregisterObject().
- Checks to make sure that the SimObject was properly initialized (and asserts if not).
Calling registerObject() and passing an ID or a name will cause the object to be assigned that name and/or ID before it is registered.
Congratulations, you have now registered your object! What now?
Well, hopefully, the SimObject will have a long, useful life. But eventually, it must die.
There are a two ways a SimObject can die.
- First, the game can be shut down. This causes the root SimGroup to be unregistered and deleted. When a SimGroup is unregistered, it unregisters all of its member SimObjects; this results in everything that has been registered with Sim being unregistered, as everything registered with Sim is in the root group.
- Second, you can manually kill it off, either by calling unregisterObject() or by calling deleteObject().
When you unregister a SimObject, the following tasks are performed:
- The object is flagged as removed.
- Notifications are cleaned up.
- If the object is in a group, then it removes itself from the group.
- Delete notifications are sent out.
- Finally, the object removes itself from the Sim globals, and tells Sim to get rid of any pending events for it.
If you call deleteObject(), all of the above tasks are performed, in addition to some sanity checking to make sure the object was previously added properly, and isn't in the process of being deleted. After the object is unregistered, it deallocates itself.
SimObjects are one of the building blocks for the in-game editors. They provide a basic interface for the editor to be able to list the fields of the object, update them safely and reliably, and inform the object things have changed.
This interface is implemented in the following areas:
- onNameChange() is called when the object is renamed.
- onStaticModified() is called whenever a static field is modified.
- inspectPreApply() is called before the object's fields are updated, when changes are being applied.
- inspectPostApply() is called after the object's fields are updated.
- onEditorEnable() is called whenever an editor is enabled (for instance, when you hit F11 to bring up the world editor).
- onEditorDisable() is called whenever the editor is disabled (for instance, when you hit F11 again to close the world editor).
(Note: you can check the variable gEditingMission to see if the mission editor is running; if so, you may want to render special indicators. For instance, the fxFoliageReplicator renders inner and outer radii when the mission editor is runnning.)
SimObject extends ConsoleObject by allowing you to to set arbitrary dynamic fields on the object, as well as statically defined fields. This is done through two methods, setDataField and getDataField, which deal with the complexities of allowing access to two different types of object fields.
Static fields take priority over dynamic fields. This is to be expected, as the role of dynamic fields is to allow data to be stored in addition to the predefined fields.
The fields in a SimObject are like properties (or fields) in a class.
Some fields may be arrays, which is what the array parameter is for; if it's non-null, then it is parsed with dAtoI and used as an index into the array. If you access something as an array which isn't, then you get an empty string.
You don't need to read any further than this. Right now, set/getDataField are called a total of 6 times through the entire Torque codebase. Therefore, you probably don't need to be familiar with the details of accessing them. You may want to look at Con::setData instead. Most of the time you will probably be accessing fields directly, or using the scripting language, which in either case means you don't need to do anything special.
The functions to get/set these fields are very straightforward:
For advanced users: There are two flags which control the behavior of these functions. The first is ModStaticFields, which controls whether or not the DataField functions look through the static fields (defined with addField; see ConsoleObject for details) of the class. The second is ModDynamicFields, which controls dynamically defined fields. They are set automatically by the console constructor code.
|
Accessors |
| const char * | getDataField (StringTableEntry slotName, const char *array) |
| | Get the value of a field on the object.
|
| void | setDataField (StringTableEntry slotName, const char *array, const char *value) |
| | Set the value of a field on the object.
|
| SimFieldDictionary * | getFieldDictionary () |
| | Get reference to the dictionary containing dynamic fields.
|
Initialization |
| | SimObject () |
| virtual | ~SimObject () |
| virtual bool | processArguments (S32 argc, const char **argv) |
| | Process constructor options. (ie, new SimObject(1,2,3)).
|
Events |
| virtual bool | onAdd () |
| | Called when the object is added to the sim.
|
| virtual void | onRemove () |
| | Called when the object is removed from the sim.
|
| virtual void | onGroupAdd () |
| | Called when the object is added to a SimGroup.
|
| virtual void | onGroupRemove () |
| | Called when the object is removed from a SimGroup.
|
| virtual void | onNameChange (const char *name) |
| | Called when the object's name is changed.
|
| virtual void | onStaticModified (const char *slotName) |
| | Called when a static field is modified.
|
| virtual void | inspectPreApply () |
| | Called before any property of the object is changed in the world editor.
|
| virtual void | inspectPostApply () |
| | Called after any property of the object is changed in the world editor.
|
| virtual void | onDeleteNotify (SimObject *object) |
| | Called when a SimObject is deleted.
|
| virtual void | onEditorEnable () |
| | Called when the editor is activated.
|
| virtual void | onEditorDisable () |
| | Called when the editor is deactivated.
|
Notification |
| Notify * | removeNotify (void *ptr, Notify::Type) |
| | Remove a notification from the list.
|
| void | deleteNotify (SimObject *obj) |
| | Notify an object when we are deleted.
|
| void | clearNotify (SimObject *obj) |
| | Notify an object when we are cleared.
|
| void | clearAllNotifications () |
| | Remove all notifications for this object.
|
| void | processDeleteNotifies () |
| | Send out deletion notifications.
|
| void | registerReference (SimObject **obj) |
| | Register a reference to this object.
|
| void | unregisterReference (SimObject **obj) |
| | Unregister a reference to this object.
|
Registration |
SimObjects must be registered with the object system.
|
| bool | registerObject () |
| | Register an object with the object system.
|
| bool | registerObject (U32 id) |
| | Register the object, forcing the id.
|
| bool | registerObject (const char *name) |
| | Register the object, assigning the name.
|
| bool | registerObject (const char *name, U32 id) |
| | Register the object, assigning a name and ID.
|
| void | unregisterObject () |
| | Unregister the object from Sim.
|
| void | deleteObject () |
| | Unregister, mark as deleted, and free the object.
|
Accessors |
| SimObjectId | getId () const |
| const char * | getIdString () |
| U32 | getType () const |
| const char * | getName () const |
| void | setId (SimObjectId id) |
| void | assignName (const char *name) |
| SimGroup * | getGroup () const |
| bool | isProperlyAdded () const |
| bool | isDeleted () const |
| bool | isRemoved () const |
| bool | isLocked () |
| void | setLocked (bool b) |
| bool | isHidden () |
| void | setHidden (bool b) |
Sets |
| The object must be properly registered before you can add/remove it to/from a set.
All these functions accept either a name or ID to identify the set you wish to operate on. Then they call addObject or removeObject on the set, which sets up appropriate notifications.
An object may be in multiple sets at a time.
|
| bool | addToSet (SimObjectId) |
| bool | addToSet (const char *) |
| bool | removeFromSet (SimObjectId) |
| bool | removeFromSet (const char *) |
Serialization |
| virtual void | write (Stream &stream, U32 tabStop, U32 flags=0) |
| | Output the TorqueScript to recreate this object.
|
| void | writeFields (Stream &stream, U32 tabStop) |
| | Write the fields of this object in TorqueScript.
|
| void | assignFieldsFrom (SimObject *obj) |
| | Copy fields from another object onto this one.
|
Accessors |
| bool | isSelected () const |
| bool | isExpanded () const |
| void | setSelected (bool sel) |
| void | setExpanded (bool exp) |
| void | setModDynamicFields (bool dyn) |
| void | setModStaticFields (bool sta) |
Initialization |
| virtual void | registerLights (LightManager *lm, bool lightingScene) |
| | Called to register the object's lights, if any, with the LightManager.
|
Notification |
Helper functions for notification code.
|
| static SimObject::Notify * | allocNotify () |
| | Get a free Notify structure.
|
| static void | freeNotify (SimObject::Notify *) |
| | Mark a Notify structure as free.
|
| static SimObject::Notify * | mNotifyFreeList |
Notification |
| Notify * | mNotifyList |
Public Types |
| enum | WriteFlags { SelectedOnly = BIT(0)
} |
Public Member Functions |
| virtual SimObject * | findObject (const char *name) |
| | Find a named sub-object of this object.
|
| Namespace * | getNamespace () |
| | Return the object's namespace.
|
| const char * | tabComplete (const char *prevText, S32 baseLen, bool) |
| | Get next matching item in namespace.
|
| | DECLARE_CONOBJECT (SimObject) |
Static Public Member Functions |
| static void | initPersistFields () |
| | Register dynamic fields in a subclass of ConsoleObject.
|
Protected Attributes |
| SimObjectId | mId |
| | Id number for this object.
|
| Namespace * | mNameSpace |
| U32 | mTypeMask |
Private Types |
| typedef ConsoleObject | Parent |
| enum | {
Deleted = BIT(0),
Removed = BIT(1),
Added = BIT(3),
Selected = BIT(4),
Expanded = BIT(5),
ModStaticFields = BIT(6),
ModDynamicFields = BIT(7)
} |
| | Flags for use in mFlags. More...
|
Private Attributes |
| StringTableEntry | objectName |
| SimObject * | nextNameObject |
| SimObject * | nextManagerNameObject |
| SimObject * | nextIdObject |
| SimGroup * | mGroup |
| | SimGroup we're contained in, if any.
|
| BitSet32 | mFlags |
| SimFieldDictionary * | mFieldDictionary |
| | Storage for dynamic fields.
|
Friends |
| class | SimManager |
| class | SimGroup |
| class | SimNameDictionary |
| class | SimManagerNameDictionary |
| class | SimIdDictionary |
Data Structures |
| struct | Notify |
Member Typedef Documentation
|
|
Reimplemented in AudioEnvironment, AudioSampleEnvironment, AudioDescription, AudioProfile, ConsoleLogger, SimDataBlock, SimSet, SimGroup, FileObject, MaterialPropertyMap, Terraformer, WorldEditor::Selection, AIClient, AIConnection, AIPlayer, AudioEmitter, BanList, CameraData, Camera, DebrisData, Debris, ExplosionData, Explosion, fxFoliageReplicator, fxLightData, fxLight, fxShapeReplicatedStatic, fxShapeReplicator, fxSunLight, LightningData, Lightning, ParticleEmitterNodeData, ParticleEmitterNode, ParticleEmitterData, ParticleEmitter, PrecipitationData, Precipitation, SplashData, Splash, GameBaseData, GameBase, GameConnection, ItemData, Item, MissionArea, MissionMarkerData, MissionMarker, WayPoint, SpawnSphere, HTTPObject, TCPObject, PathCameraData, PathCamera, PhysicalZone, PlayerData, Player, ProjectileData, Projectile, ShapeBaseImageData, ShapeBaseData, ShapeBase, ShowTSShape, StaticShapeData, StaticShape, TriggerData, Trigger, TSStatic, FlyingVehicleData, FlyingVehicle, HoverVehicleData, HoverVehicle, VehicleData, Vehicle, VehicleBlocker, WheeledVehicleTire, WheeledVehicleSpring, WheeledVehicleData, WheeledVehicle, InteriorInstance, InteriorSubObject, MirrorSubObject, PathedInteriorData, PathedInterior, DInputManager, UInputManager, SceneLighting, SceneRoot, ActionMap, DecalData, DecalManager, NetConnection, NetObject, SceneObject, Path, Marker, Sky, Sun, TerrainBlock, WaterBlock, and TSShapeConstructor. |
Member Enumeration Documentation
|
|
Flags for use in mFlags.
- Enumeration values:
-
| Deleted |
This object is marked for deletion. |
| Removed |
This object has been unregistered from the object system. |
| Added |
This object has been registered with the object system. |
| Selected |
This object has been marked as selected. (in editor). |
| Expanded |
This object has been marked as expanded. (in editor). |
| ModStaticFields |
The object allows you to read/modify static fields. |
| ModDynamicFields |
The object allows you to read/modify dynamic fields. |
|
|
|
- Enumeration values:
-
| SelectedOnly |
Passed to SimObject::write to indicate that only objects marked as selected should be outputted.
Used in SimSet. |
|
Constructor & Destructor Documentation
| virtual SimObject::~SimObject |
( |
|
) |
[virtual] |
|
Member Function Documentation
|
|
Mark a Notify structure as free.
|
| const char* SimObject::getDataField |
( |
StringTableEntry |
slotName, |
|
|
const char * |
array |
|
) |
|
|
|
|
Get the value of a field on the object.
See here for a detailed discussion of what this function does.
- Parameters:
-
| slotName | Field to access. |
| array | String containing index into array (if field is an array); if NULL, it is ignored. |
|
|
|
Set the value of a field on the object.
See here for a detailed discussion of what this function does.
- Parameters:
-
| slotName | Field to access. |
| array | String containing index into array; if NULL, it is ignored. |
| value | Value to store. |
|
|
|
Get reference to the dictionary containing dynamic fields.
See here for a detailed discussion of what this function does.
This dictionary can be iterated over using a SimFieldDictionaryIterator. |
| virtual bool SimObject::processArguments |
( |
S32 |
argc, |
|
|
const char ** |
argv |
|
) |
[virtual] |
|
| virtual bool SimObject::onAdd |
( |
|
) |
[virtual] |
|
|
|
Called when the object is added to the sim.
Reimplemented in AudioDescription, AudioProfile, SimDataBlock, AudioEmitter, Camera, DebrisData, Debris, ExplosionData, Explosion, fxFoliageReplicator, fxLightData, fxLight, fxShapeReplicator, fxSunLight, LightningData, Lightning, ParticleEmitterNodeData, ParticleEmitterNode, ParticleEmitterData, ParticleEmitter, PrecipitationData, Precipitation, SplashData, Splash, GameBaseData, GameBase, GameConnection, Item, MissionArea, MissionMarker, WayPoint, SpawnSphere, TCPObject, PathCamera, PhysicalZone, Player, ProjectileData, Projectile, ShapeBaseImageData, ShapeBase, ShowTSShape, StaticShape, TriggerData, Trigger, TSStatic, FlyingVehicle, HoverVehicleData, HoverVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, PathedInterior, DInputManager, UInputManager, ActionMap, NetObject, SceneObject, Path, Marker, Sky, Sun, TerrainBlock, WaterBlock, and TSShapeConstructor. |
| virtual void SimObject::onRemove |
( |
|
) |
[virtual] |
|
|
|
Called when the object is removed from the sim.
Reimplemented in SimSet, SimGroup, AudioEmitter, Camera, Debris, Explosion, fxFoliageReplicator, fxLight, fxShapeReplicator, fxSunLight, Lightning, ParticleEmitterNode, ParticleEmitter, Precipitation, Splash, GameBase, GameConnection, Item, MissionMarker, PathCamera, PhysicalZone, Player, Projectile, ShapeBase, ShowTSShape, StaticShape, Trigger, TSStatic, FlyingVehicle, HoverVehicle, Vehicle, VehicleBlocker, WheeledVehicle, InteriorInstance, PathedInterior, DInputManager, UInputManager, NetConnection, NetObject, SceneObject, Path, Marker, Sky, TerrainBlock, and WaterBlock. |
| virtual void SimObject::onGroupAdd |
( |
|
) |
[virtual] |
|
|
|
Called when the object is added to a SimGroup.
Reimplemented in Marker. |
| virtual void SimObject::onGroupRemove |
( |
|
) |
[virtual] |
|
|
|
Called when the object is removed from a SimGroup.
|
| virtual void SimObject::onNameChange |
( |
const char * |
name |
) |
[virtual] |
|
|
|
Called when the object's name is changed.
|
| virtual void SimObject::onStaticModified |
( |
const char * |
slotName |
) |
[virtual] |
|
|
|
Called when a static field is modified.
Specifically, this is called by setDataField when a static field is modified, see the console details.
Reimplemented in SimDataBlock. |
| virtual void SimObject::inspectPreApply |
( |
|
) |
[virtual] |
|
|
|
Called before any property of the object is changed in the world editor.
The calling order here is:
Reimplemented in AudioEmitter, and InteriorInstance. |
| virtual void SimObject::inspectPostApply |
( |
|
) |
[virtual] |
|
|
|
Called after any property of the object is changed in the world editor.
- See also:
- inspectPreApply
Reimplemented in AudioEmitter, fxFoliageReplicator, fxLight, fxShapeReplicator, fxSunLight, Precipitation, GameBase, MissionMarker, WayPoint, SpawnSphere, InteriorInstance, SceneObject, Marker, Sky, Sun, and WaterBlock. |
| virtual void SimObject::onDeleteNotify |
( |
SimObject * |
object |
) |
[virtual] |
|
| virtual void SimObject::onEditorEnable |
( |
|
) |
[inline, virtual] |
|
| virtual void SimObject::onEditorDisable |
( |
|
) |
[inline, virtual] |
|
| virtual SimObject* SimObject::findObject |
( |
const char * |
name |
) |
[virtual] |
|
|
|
Find a named sub-object of this object.
This is subclassed in the SimGroup and SimSet classes.
For a single object, it just returns NULL, as normal objects cannot have children.
Reimplemented in SimSet, and SimGroup. |
|
|
Remove a notification from the list.
|
|
|
Notify an object when we are deleted.
|
|
|
Notify an object when we are cleared.
|
| void SimObject::clearAllNotifications |
( |
|
) |
|
|
|
|
Remove all notifications for this object.
|
| void SimObject::processDeleteNotifies |
( |
|
) |
|
|
|
|
Send out deletion notifications.
|
|
|
Register a reference to this object.
You pass a pointer to your reference to this object.
When the object is deleted, it will null your pointer, ensuring you don't access old memory.
- Parameters:
-
| obj | Pointer to your reference to the object. |
|
|
|
Unregister a reference to this object.
Remove a reference from the list, so that it won't get nulled inappropriately.
Call this when you're done with your reference to the object, especially if you're going to free the memory. Otherwise, you may erroneously get something overwritten.
- See also:
- registerReference
|
| bool SimObject::registerObject |
( |
|
) |
|
|
|
|
Register an object with the object system.
This must be called if you want to keep the object around. In the rare case that you will delete the object immediately, or don't want to be able to use Sim::findObject to locate it, then you don't need to register it.
registerObject adds the object to the global ID and name dictionaries, after first assigning it a new ID number. It calls onAdd(). If onAdd fails, it unregisters the object and returns false.
If a subclass's onAdd doesn't eventually call SimObject::onAdd(), it will cause an assertion. |
| bool SimObject::registerObject |
( |
U32 |
id |
) |
|
|
|
|
Register the object, forcing the id.
- See also:
- registerObject()
- Parameters:
-
| id | ID to assign to the object. |
|
| bool SimObject::registerObject |
( |
const char * |
name |
) |
|
|
|
|
Register the object, assigning the name.
- See also:
- registerObject()
- Parameters:
-
| name | Name to assign to the object. |
|
| bool SimObject::registerObject |
( |
const char * |
name, |
|
|
U32 |
id |
|
) |
|
|
|
|
Register the object, assigning a name and ID.
- See also:
- registerObject()
- Parameters:
-
| name | Name to assign to the object. |
| id | ID to assign to the object. |
|
| void SimObject::unregisterObject |
( |
|
) |
|
|
|
|
Unregister the object from Sim.
This performs several operations:
- Sets the removed flag.
- Call onRemove()
- Clear out notifications.
- Remove the object from...
- its group, if any. (via getGroup)
- Sim::gNameDictionary
- Sim::gIDDictionary
- Finally, cancel any pending events for this object (as it can't receive them now).
|
| void SimObject::deleteObject |
( |
|
) |
|
|
|
|
Unregister, mark as deleted, and free the object.
This helper function can be used when you're done with the object and don't want to be bothered with the details of cleaning it up. |
| const char* SimObject::getIdString |
( |
|
) |
|
|
| U32 SimObject::getType |
( |
|
) |
const [inline] |
|
| const char* SimObject::getName |
( |
|
) |
const [inline] |
|
| void SimObject::assignName |
( |
const char * |
name |
) |
|
|
| SimGroup* SimObject::getGroup |
( |
|
) |
const [inline] |
|
| bool SimObject::isProperlyAdded |
( |
|
) |
const [inline] |
|
| bool SimObject::isDeleted |
( |
|
) |
const [inline] |
|
| bool SimObject::isRemoved |
( |
|
) |
const [inline] |
|
| bool SimObject::isLocked |
( |
|
) |
|
|
| void SimObject::setLocked |
( |
bool |
b |
) |
|
|
| bool SimObject::isHidden |
( |
|
) |
|
|
| void SimObject::setHidden |
( |
bool |
b |
) |
|
|
| bool SimObject::addToSet |
( |
const char * |
|
) |
|
|
| bool SimObject::removeFromSet |
( |
const char * |
|
) |
|
|
| virtual void SimObject::write |
( |
Stream & |
stream, |
|
|
U32 |
tabStop, |
|
|
U32 |
flags = 0 |
|
) |
[virtual] |
|
|
|
Output the TorqueScript to recreate this object.
This calls writeFields internally. - Parameters:
-
| stream | Stream to output to. |
| tabStop | Indentation level for this object. |
| flags | If SelectedOnly is passed here, then only objects marked as selected (using setSelected) will output themselves. |
Reimplemented in SimSet. |
|
|
Write the fields of this object in TorqueScript.
- Parameters:
-
| stream | Stream for output. |
| tabStop | Indentation level for the fields. |
|
|
|
Copy fields from another object onto this one.
Objects must be of same type. Everything from obj will overwrite what's in this object; extra fields in this object will remain.
- Parameters:
-
|
| Namespace* SimObject::getNamespace |
( |
|
) |
[inline] |
|
|
|
Return the object's namespace.
|
| const char* SimObject::tabComplete |
( |
const char * |
prevText, |
|
|
S32 |
baseLen, |
|
|
bool |
|
|
) |
|
|
| bool SimObject::isSelected |
( |
|
) |
const [inline] |
|
| bool SimObject::isExpanded |
( |
|
) |
const [inline] |
|
| void SimObject::setSelected |
( |
bool |
sel |
) |
[inline] |
|
| void SimObject::setExpanded |
( |
bool |
exp |
) |
[inline] |
|
| void SimObject::setModDynamicFields |
( |
bool |
dyn |
) |
[inline] |
|
| void SimObject::setModStaticFields |
( |
bool |
sta |
) |
[inline] |
|
| virtual void SimObject::registerLights |
( |
LightManager * |
lm, |
|
|
bool |
lightingScene |
|
) |
[inline, virtual] |
|
| static void SimObject::initPersistFields |
( |
|
) |
[static] |
|
|
|
Register dynamic fields in a subclass o | |