Adding Variables to Datablocks via source code

Open up ShapeBase.cc. Notice something? There are *two* datablock declarations. The first one

IMPLEMENT_CO_DATABLOCK_V1(ShapeBaseData);

establishes all static declarations of ShapeBaseData, such as the mass, drag, density, etc. All of these variables are sent to each client only once at mission load ("Loading Datablocks") in the packData function. Furthermore, the variables accessible via script are defined in initPersistFields via addField:

addField("shapeFile",      TypeFilename, Offset(shapeName,      ShapeBaseData));

The addField command requires the following parameters.

in_pFieldname (string. This is the name of the datablock field in script.)

in_fieldType (This is the type of variable that will be stored. Filename, bool, int, float, ExplosionDataPtr, whatever).

in_fieldOffset (This is usually two part. Offset(Param1, Param2) where Param1 is the name of the source code variable, and Param2 is the name of the datablock)

in_FieldDoc (String. This is just a quick explanation of what the variable is used for that DOxygen will grab. Please use this if you're going to distribute your changes)

Those are just for a "simple" field, but in many cases, that is all you'll need.

Wait, backup, how exactly does this all work together?

Okay then, let's walk through adding a simple variable to ShapeBase that isn't changed during the course of a mission. We'll call our field "testField". First, open up shapeBase.h. Scroll down until you see the line

struct ShapeBaseData : public GameBaseData {

(Line 370)

Here's where every static ShapeBaseData variable is initially declared. (dyanmic variables are declared under "class ShapeBase : public GameBase") Find a nice spot to add your variable, preferably in a place where it makes sense. For the purpose of this tutorial, let's say that testField is a bool representing some physical property. Therefore, below

F32 repairRate;

add

bool testField;

Congrats, you're done with ShapeBase.h.

Now back in ShapeBase.cc Add a default value for your variable in ShapeBaseData::ShapeBaseData. for example, under

repairRate = 0.0033;

add

testField = false;

Next, go to initPersistFields, and under

addGroup("Misc");

add

addField("testField",   TypeBool,  Offset(testField, ShapeBaseData));

Then, go into packData, and scroll down until you see

stream->writeFlag(renderWhenDestroyed);

Under that, add

stream->writeFlag(testField);

Finally, go to unpackData find

renderWhenDestroyed = stream->readFlag();

and add

testField = stream->readFlag();

Congrats!!! You've now added your own custom variable to ShapeBaseData that is accessible via script. However, this variable can only be set in the datablock declaration, you can't change it after mission load. Adding a variable that can be changed during the course of a missions is a very very similar process. Simply put the variable declaration in the ShapeBaseData() under Implement_CO_NETOBJECT_V1 and instead of writing to the stream in packData, write to it in packUpdate. Fairly simple concept once you get the hang of it, no?

Notes: This is a complete list of how to write thigns to the bit stream. If you're making a multiplayer game, memorize it.

It is *extremely* important that you write to and read from the bit stream in the same order with the same bit counts.

These instructions just used ShapeBase as an example. They will work with any other datablock.

It really isn't too hard to pick this up from other tutorials available, but I figured that having one whose purpose was to explain what is going on was a good idea.