Torque2D Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

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

Public Member Functions | List of all members
SimDataBlock Class Reference

`#include <simDatablock.h>`

Inheritance diagram for SimDataBlock:

## Public Member Functions
| SimDataBlock ()
| DECLARE_CONOBJECT (SimDataBlock)
Public Member Functions inherited from SimObject
StringTableEntry | getClassNamespace () const
StringTableEntry | getSuperClassNamespace () const
void | setClassNamespace (const char *classNamespace)
void | setSuperClassNamespace (const char *superClassNamespace)
void | pushScriptCallbackGuard (void)
void | popScriptCallbackGuard (void)
S32 | getScriptCallbackGuard (void)
virtual SimObject * | findObject (const char *name)
Namespace * | getNamespace ()
| Return the object's namespace. More...
const char * | tabComplete (const char *prevText, S32 baseLen, bool)
virtual void | dump ()
virtual void | dumpClassHierarchy ()
SimObject * | clone (const bool copyDynamicFields)
virtual void | copyTo (SimObject *object)
template<typename T >
bool | isType (void)
virtual bool | handlesConsoleMethod (const char *fname, S32 *routingId)
| DECLARE_CONOBJECT (SimObject)
Notify * | removeNotify (void *ptr, Notify::Type)
| Remove a notification from the list. More...
void | deleteNotify (SimObject *obj)
| Notify an object when we are deleted. More...
void | clearNotify (SimObject *obj)
| Notify an object when we are cleared. More...
void | clearAllNotifications ()
| Remove all notifications for this object. More...
void | processDeleteNotifies ()
| Send out deletion notifications. More...
void | registerReference (SimObject **obj)
void | unregisterReference (SimObject **obj)
const char * | getDataField (StringTableEntry slotName, const char *array)
void | setDataField (StringTableEntry slotName, const char *array, const char *value)
const char * | getPrefixedDataField (StringTableEntry fieldName, const char *array)
void | setPrefixedDataField (StringTableEntry fieldName, const char *array, const char *value)
const char * | getPrefixedDynamicDataField (StringTableEntry fieldName, const char *array, const S32 fieldType=-1)
void | setPrefixedDynamicDataField (StringTableEntry fieldName, const char *array, const char *value, const S32 fieldType=-1)
StringTableEntry | getDataFieldPrefix (StringTableEntry fieldName)
U32 | getDataFieldType (StringTableEntry slotName, const char *array)
SimFieldDictionary * | getFieldDictionary ()
void | clearDynamicFields (void)
| Clear all dynamic fields. More...
void | setCanSaveDynamicFields (bool bCanSave)
| Set whether fields created at runtime should be saved. Default is true. More...
bool | getCanSaveDynamicFields (void) const
| Get whether fields created at runtime should be saved. Default is true. More...
void | setInternalName (const char *newname)
StringTableEntry | getInternalName ()
| Get the internal of of this control. More...
virtual bool | save (const char *pcFilePath, bool bOnlySelected=false)
| Save object as a TorqueScript File. More...
virtual bool | isMethod (const char *methodName)
| Check if a method exists in the objects current namespace. More...
SimObjectId | getId (void) const
StringTableEntry | getIdString (void) const
U32 | getType () const
const StringTableEntry | getName (void) const
void | setId (SimObjectId id)
void | assignName (const char *name)
SimGroup * | getGroup () const
bool | isChildOfGroup (SimGroup *pGroup)
bool | isProperlyAdded () const
bool | isDeleted () const
bool | isRemoved () const
bool | isLocked ()
void | setLocked (bool b)
bool | isHidden ()
void | setHidden (bool b)
void | setProgenitorFile (const char *pFile)
StringTableEntry | getProgenitorFile (void) const
void | setPeriodicTimerID (const S32 timerID)
S32 | getPeriodicTimerID (void) const
bool | isPeriodicTimerActive (void) const
bool | isSelected () const
bool | isExpanded () const
void | setSelected (bool sel)
void | setExpanded (bool exp)
void | setModDynamicFields (bool dyn)
void | setModStaticFields (bool sta)
| SimObject ()
virtual | ~SimObject ()
virtual bool | processArguments (S32 argc, const char **argv)
| Process constructor options. (ie, new SimObject(1,2,3)) More...
virtual void | onGroupAdd ()
| Called when the object is added to a SimGroup. More...
virtual void | onGroupRemove ()
| Called when the object is removed from a SimGroup. More...
virtual void | onNameChange (const char *name)
| Called when the object's name is changed. More...
virtual void | inspectPreApply ()
virtual void | inspectPostApply ()
virtual void | onDeleteNotify (SimObject *object)
virtual void | onEditorEnable ()
| Called when the editor is activated. More...
virtual void | onEditorDisable ()
| Called when the editor is deactivated. More...
bool | registerObject ()
bool | registerObject (U32 id)
bool | registerObject (const char *name)
bool | registerObject (const char *name, U32 id)
void | unregisterObject ()
void | deleteObject ()
bool | addToSet (SimObjectId)
bool | addToSet (const char *)
bool | removeFromSet (SimObjectId)
bool | removeFromSet (const char *)
virtual bool | writeField (StringTableEntry fieldname, const char *value)
virtual void | write (Stream &stream, U32 tabStop, U32 flags=0)
virtual void | writeFields (Stream &stream, U32 tabStop)
virtual bool | writeObject (Stream *stream)
virtual bool | readObject (Stream *stream)
virtual void | buildFilterList ()
void | addFieldFilter (const char *fieldName)
void | removeFieldFilter (const char *fieldName)
void | clearFieldFilters ()
bool | isFiltered (const char *fieldName)
void | assignFieldsFrom (SimObject *obj)
void | assignDynamicFieldsFrom (SimObject *obj)
Public Member Functions inherited from ConsoleObject
const AbstractClassRep::Field * | findField (StringTableEntry fieldName) const
| Get a reference to a field by name. More...
virtual AbstractClassRep * | getClassRep () const
| Gets the ClassRep. More...
bool | setField (const char *fieldName, const char *value)
| Set the value of a field. More...
virtual | ~ConsoleObject ()
const AbstractClassRep::FieldList & | getFieldList () const
| Get a list of all the fields. This information cannot be modified. More...
AbstractClassRep::FieldList & | getModifiableFieldList ()
bool & | getDynamicGroupExpand ()
S32 | getClassId (U32 netClassGroup) const
const char * | getClassName () const

## Datablock Internals
S32 | modifiedKey
static SimObjectId | sNextObjectId = DataBlockObjectIdFirst
static S32 | sNextModifiedKey = 0
S32 | getModifiedKey () const
| Get the modified key for this particular datablock. More...
virtual bool | onAdd ()
| Called when the object is added to the sim. More...
virtual void | onRemove ()
| Called when the object is removed from the sim. More...
virtual void | onStaticModified (const char *slotName, const char *newValue=NULL)
void | assignId ()
static S32 | getNextModifiedKey ()

## Datablock Interface
virtual void | packData (BitStream *stream)
virtual void | unpackData (BitStream *stream)
virtual bool | preload (bool server, char errorBuffer[256])

## Additional Inherited Members
Public Types inherited from SimObject
enum | WriteFlags { SelectedOnly = BIT(0) }
Static Public Member Functions inherited from SimObject
static void | initPersistFields ()
Static Public Member Functions inherited from ConsoleObject
static const char * | lookupClassName (const U32 in_classTag)
| Get the classname from a class tag. More...
static void | initPersistFields ()
static void | consoleInit ()
static ConsoleObject * | create (const char *in_pClassName)
static ConsoleObject * | create (const U32 groupId, const U32 typeId, const U32 in_classId)
static AbstractClassRep * | getStaticClassRep ()
| Get the abstract class information for this class. More...
static AbstractClassRep * | getParentStaticClassRep ()
| Get the abstract class information for this class's superclass. More...
Protected Member Functions inherited from SimObject
virtual void | onTamlPreWrite (void)
| Taml callbacks. More...
virtual void | onTamlPostWrite (void)
| Called after Taml has finished writing the object. More...
virtual void | onTamlPreRead (void)
| Called prior to Taml reading the object. More...
virtual void | onTamlPostRead (const TamlCustomNodes &customNodes)
virtual void | onTamlAddParent (SimObject *pParentObject)
| Called after Taml has finished reading the object and has added the object to any parent. More...
virtual void | onTamlCustomWrite (TamlCustomNodes &customNodes)
| Called during the writing of the object to allow custom properties to be written. More...
virtual void | onTamlCustomRead (const TamlCustomNodes &customNodes)
| Called during the reading of the object to allow custom properties to be read. More...
void | linkNamespaces ()
void | unlinkNamespaces ()
Protected Member Functions inherited from ConsoleObject
| ConsoleObject ()
| ConsoleObject (const ConsoleObject &)
Static Protected Member Functions inherited from SimObject
static bool | setClass (void *obj, const char *data)
static bool | setSuperClass (void *obj, const char *data)
static bool | writeCanSaveDynamicFields (void *obj, StringTableEntry pFieldName)
static bool | writeInternalName (void *obj, StringTableEntry pFieldName)
static bool | setParentGroup (void *obj, const char *data)
static bool | writeParentGroup (void *obj, StringTableEntry pFieldName)
static bool | writeSuperclass (void *obj, StringTableEntry pFieldName)
static bool | writeClass (void *obj, StringTableEntry pFieldName)
static SimObject::Notify * | allocNotify ()
| Get a free Notify structure. More...
static void | freeNotify (SimObject::Notify *)
| Mark a Notify structure as free. More...
Static Protected Member Functions inherited from ConsoleObject
static void | addGroup (const char *in_pGroupname, const char *in_pGroupDocs=NULL)
static void | endGroup (const char *in_pGroupname)
static void | addField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, const U32 in_elementCount=1, EnumTable *in_table=NULL, const char *in_pFieldDocs=NULL)
static void | addField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::WriteDataNotify in_writeDataFn, const U32 in_elementCount=1, EnumTable *in_table=NULL, const char *in_pFieldDocs=NULL)
static void | addField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, const char *in_pFieldDocs)
static void | addField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::WriteDataNotify in_writeDataFn, const char *in_pFieldDocs)
static void | addFieldV (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, ConsoleTypeValidator *v, const char *in_pFieldDocs=NULL)
static void | addProtectedField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, const U32 in_elementCount=1, EnumTable *in_table=NULL, const char *in_pFieldDocs=NULL)
static void | addProtectedField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, AbstractClassRep::WriteDataNotify in_writeDataFn=&defaultProtectedWriteFn, const U32 in_elementCount=1, EnumTable *in_table=NULL, const char *in_pFieldDocs=NULL)
static void | addProtectedField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, const char *in_pFieldDocs=NULL)
static void | addProtectedField (const char *in_pFieldname, const U32 in_fieldType, const dsize_t in_fieldOffset, AbstractClassRep::SetDataNotify in_setDataFn, AbstractClassRep::GetDataNotify in_getDataFn=&defaultProtectedGetFn, AbstractClassRep::WriteDataNotify in_writeDataFn=&defaultProtectedWriteFn, const char *in_pFieldDocs=NULL)
static void | addDepricatedField (const char *fieldName)
static bool | removeField (const char *in_pFieldname)
Protected Attributes inherited from SimObject
SimObjectId | mId
| Id number for this object. More...
StringTableEntry | mIdString
Namespace * | mNameSpace
U32 | mTypeMask
S32 | mScriptCallbackGuard
| Whether the object is executing a script callback. More...
bool | mCanSaveFieldDictionary
| true if dynamic fields (added at runtime) should be saved, defaults to true More...
StringTableEntry | mInternalName
| Stores object Internal Name. More...
StringTableEntry | mClassName
| Stores the class name to link script class namespaces. More...
StringTableEntry | mSuperClassName
| Stores super class name to link script class namespaces. More...
Static Protected Attributes inherited from SimObject
static SimObject::Notify * | mNotifyFreeList = NULL

## Detailed Description

Root DataBlock class.

# Introduction

Another powerful aspect of Torque's networking is the datablock. Datablocks are used to provide relatively static information about entities; for instance, what model a weapon should use to display itself, or how heavy a player class is.

This gives significant gains in network efficiency, because it means that all the datablocks on a server can be transferred over the network at client connect time, instead of being intertwined with the update code for NetObjects.

This makes the network code much simpler overall, as one-time initialization code is segregated from the standard object update code, as well as providing several powerful features, which we will discuss momentarily.

# preload() and File Downloading

Because datablocks are sent over the wire, using SimDataBlockEvent, before gameplay starts in earnest, we gain in several areas. First, we don't have to try to keep up with the game state while working with incomplete information. Second, we can provide the user with a nice loading screen, instead of the more traditional "Connecting..." message. Finally, and most usefully, we can request missing files from the server as we become aware of them, since we are under no obligation to render anything for the user.

The mechanism for this is fairly basic. After a datablock is unpacked, the preload() method is called. If it returns false and sets an error, then the network code checks to see if a file (or files) failed to be located by the ResManager; if so, then it requests those files from the server. If preload returns true, then the datablock is considered loaded. If preload returns false and sets no error, then the connection is aborted.

Once the file(s) is downloaded, the datablock's preload() method is called again. If it fails with the same error, the connection is aborted. If a new error is returned, then the download-retry process is repeated until the preload works.

# Guide To Datablock Code

To make a datablock subclass, you need to extend three functions:

- preload()
- packData()
- unpackData()

packData() and unpackData() simply read or write data to a network stream. If you add any fields, you need to add appropriate calls to read or write. Make sure that the order of reads and writes is the same in both functions. Make sure to call the Parent's version of these methods in every subclass.

preload() is a bit more complex; it is responsible for taking the raw data read by unpackData() and processing it into a form useful by the datablock's owning object. For instance, the Player class' datablock, PlayerData, gets handles to commonly used nodes in the player model, as well as resolving handles to textures and other resources. Any code which loads files or performs other actions beyond simply reading the data from the packet, such as validation, must reside in preload().

To write your own preload() methods, see any of the existing methods in the codebase; for instance, PlayerData::preload() is an excellent example of error-reporting, data validation, and so forth.

Note
  A useful trick, which is used in several places in the engine, is that of temporarily storing SimObjectIds in the variable which will eventually hold the "real" handle. ShapeImage uses this trick in several pllaces; so do the vehicle classes. See GameBaseData for more on using this trick.

See also
  GameBaseData for some more information on the datablocks used throughout most of the engine.
  http://hosted.tribalwar.com/t2faq/datablocks.shtml for an excellent explanation of the basics of datablocks from script. Note that these comments mostly apply to GameBaseData and its children.

## Constructor & Destructor Documentation

SimDataBlock | ( |  | ) |

## Member Function Documentation

void assignId | ( |  | ) |

DECLARE_CONOBJECT | ( | SimDataBlock |  | ) |

S32 getModifiedKey | ( |  | ) | const
| inline

Get the modified key for this particular datablock.

static S32 getNextModifiedKey | ( |  | ) |
| inline static

Assign a new modified key.

Datablocks are assigned a modified key which is updated every time a static field of the datablock is changed. These are gotten from a global store.

bool onAdd | ( | void |  | ) |
| virtual

Called when the object is added to the sim.

Reimplemented from SimObject.

void onRemove | ( |  | ) |
| virtual

Called when the object is removed from the sim.

Reimplemented from SimObject.

void onStaticModified | ( | const char * | slotName,
|  | const char * | newValue = `NULL`
| ) |  |
| virtual

Called when a static field is modified.

Reimplemented from SimObject.

void packData | ( | BitStream * | stream | ) |
| virtual

Reimplemented in AudioSampleEnvironment, and AudioEnvironment.

bool preload | ( | bool | server,
|  | char | errorBuffer[256]
| ) |  |
| virtual

Called to prepare the datablock for use, after it has been unpacked.

Parameters

  server | Set if we're running on the server (and therefore don't need to load things like textures or sounds).
  errorBuffer | If an error occurs in loading, this is set to a short string describing the error.

Returns
  True if all went well; false if something failed.

See also
  preload() and File Downloading

void unpackData | ( | BitStream * | stream | ) |
| virtual

Reimplemented in AudioSampleEnvironment, and AudioEnvironment.

## Member Data Documentation

S32 modifiedKey
| protected

S32 sNextModifiedKey = 0
| static

SimObjectId sNextObjectId = DataBlockObjectIdFirst
| static

The documentation for this class was generated from the following files:

- sim/simDatablock.h
- sim/simDatablock.cc