SimDataBlock

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.