#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 (const U8 namespaceLinkMask=LinkSuperClassName\|LinkClassName)

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

Protected Types inherited from SimObject
enum	SimObjectNSLinkType { LinkClassName = BIT(0), LinkSuperClassName = BIT(1) }

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

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...

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...

U8	mNSLinkMask

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:

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

inlinestatic

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

Public Member Functions

Datablock Internals

Datablock Interface

Additional Inherited Members

Detailed Description

Introduction

preload() and File Downloading

Guide To Datablock Code

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation