Datablocks

A datablock is a named, immutable-by-convention description shared by many objects. DiscProjectile describes every spinfusor disc ever fired; the individual discs are lightweight Projectile instances pointing at it.

Datablocks are where the overwhelming majority of Tribes 2 modding happens. Change DiscProjectile.damageRadius and every spinfusor in the game changes.

Declaring one

datablock ItemData(Disc)
{
   className = Weapon;
   catagory = "Spawn Items";
   shapeFile = "weapon_disc.dts";
   image = DiscImage;
   mass = 1;
   elasticity = 0.2;
   friction = 0.6;
   pickupRadius = 2;
   pickUpName = "a spinfusor";
   emap = true;
};

Fields the type does not declare become dynamic fields — settable and readable, but ignored by the engine. This is how mods attach their own metadata to stock datablocks.

Inheritance

datablock PlayerData(LightFemaleHumanArmor) : LightMaleHumanArmor
{
   shapeFile = "light_female.dts";
   …
};

The : Parent form copies every field from the parent, then applies the block’s own fields on top. The parent must already exist at declaration time.

47 of the shipped datablocks use inheritance [script]. Two patterns dominate:

Profile blocks — a base datablock holding shared tuning, inherited by concrete ones:

datablock PlayerData(LightMaleHumanArmor)   : LightPlayerDamageProfile  { … };
datablock PlayerData(MediumMaleHumanArmor)  : MediumPlayerDamageProfile { … };
datablock StaticShapeData(DeployedBeacon)   : StaticShapeDamageProfile  { … };

Variants — a near-copy with a few differences:

datablock PlayerData(LightMaleBiodermArmor) : LightMaleHumanArmor { … };
datablock ItemData(HuntersFlag2)            : HuntersFlag1        { … };

For a mod, inheritance is the polite way to add content: derive from the stock datablock, override the handful of fields you care about, and you automatically track any change to the parent.

datablock LinearProjectileData(BigDiscProjectile) : DiscProjectile
{
   indirectDamage   = 0.75;
   damageRadius     = 15.0;
   kickBackStrength = 3000;
};

Declaration order matters

A field that names another datablock is resolved at declaration time. If the referenced block does not exist yet, you get an empty reference and, usually, a runtime failure much later.

This is why CreateServer() carries ordering comments [script]:

exec("scripts/particleEmitter.cs");    // Must exist before item.cs and explosion.cs
exec("scripts/particleDummies.cs");
exec("scripts/projectiles.cs");        // Must exits before item.cs
…
exec("scripts/vehicles/vehicle_spec_fx.cs");    // Must exist before other vehicle files or CRASH BOOM
…
exec("scripts/vehicles/vehicle.cs");            // Must be added after all other vehicle files or EVIL BAD THINGS

And why a weapon file is written bottom-up — effects, then sounds, then explosion, then projectile, then ammo, then the image, then the item. Read scripts/weapons/disc.cs top to bottom and you are reading a dependency order.

flowchart LR
    EFF["EffectProfile<br/>force feedback"] --> SND["AudioProfile"]
    PART["ParticleData"] --> EMIT["ParticleEmitterData"]
    EMIT --> EXP["ExplosionData"]
    SND --> EXP
    EMIT --> SPL["SplashData"]
    EXP --> PROJ["LinearProjectileData"]
    SPL --> PROJ
    PROJ --> IMG["ShapeBaseImageData<br/>the weapon in hand"]
    AMMO["ItemData<br/>className = Ammo"] --> IMG
    IMG --> ITEM["ItemData<br/>className = Weapon"]

Datablocks are transmitted to clients

This is the fact that catches out every newcomer.

Datablocks are not loaded independently by each side. The server sends its datablocks to each client over the network during mission start [script]:

function serverCmdMissionStartPhase1Done(%client, %seq)
{
   …
   // when the datablocks are transmitted, we'll send the ghost always objects
   %client.transmitDataBlocks($missionSequence);
}

function GameConnection::dataBlocksDone( %client, %missionSequence )
{
   echo("GOT DATA BLOCKS DONE FOR: " @ %client);
   …
   %client.setReceivedDataBlocks(true);
   sendTargetsToClient(%client);
   commandToClient(%client, 'MissionStartPhase2', $missionSequence);
}

sequenceDiagram
    participant S as Server
    participant C as Client
    S->>C: MissionStartPhase1
    C->>S: serverCmdMissionStartPhase1Done
    S->>C: transmitDataBlocks() — every datablock, in order
    C->>S: GameConnection::dataBlocksDone
    S->>C: MissionStartPhase2 (lighting)
    Note over S,C: …then ghosting begins

What follows from this:

preload = true on a datablock asks the client to load the referenced resources up front rather than on first use — used on the audio profiles that must not stutter [script]:

datablock AudioProfile(DiscFireSound)
{
   filename    = "fx/weapons/spinfusor_fire.wav";
   description = AudioDefault3d;
   preload = true;
   effect = DiscFireEffect;
};

Modifying a stock datablock

Two approaches, with different consequences.

Assign to its fields at runtime

package MyMod
{
   function DefaultGame::missionLoadDone(%game)
   {
      Parent::missionLoadDone(%game);
      DiscProjectile.damageRadius = 12.0;
   }
};

Simple and composable. But note the timing: the datablock has already been declared, and depending on the field, may already have been transmitted or consumed by the C++ side. Fields read once at load time will not respond to a late assignment. Tuning numbers usually work; structural fields (shape files, state machine entries) usually do not.

Redeclare it

Ship a file that re-declares the datablock with the same name. The later declaration wins.

datablock LinearProjectileData(DiscProjectile)
{
   … full declaration with your changes …
};

Reliable, because it runs through the normal declaration path — but you now own a full copy, and you must arrange for your file to execute after the original. In practice this means shadowing scripts/weapons/disc.cs in your mod folder, which is file shadowing with all its drawbacks. See Mod paths and overrides.

Recommendation: derive a new datablock rather than modifying a stock one, wherever the design allows it. Add BigDisc alongside Disc instead of changing Disc.

The datablock types

Census of the shipped scripts [script], most-used first:

Field references for each are in Datablock classes, and the recipes in 03 · Content Recipes show them in use.

Under the community patches

The datablock system is entirely unchanged — declaration, inheritance, className dispatch, transmission to clients, preload. Every content recipe in this handbook works identically.

Two things around the edges are worth knowing.

Asset downloads change the “client must already have the file” rule

The QoL patch adds enableAssetDownloads(bool), driven by $pref::Net::downloadAssets [patch-script], which lets a server ship missing files to joining clients.

This softens — but does not remove — the constraint in the table above. A datablock naming shapeFile = "my_gun.dts" may now get that file delivered on connect rather than requiring every player to install a client package first.

Do not rely on it. It is a user-toggleable preference, so some clients will have it off, and the exact delivery scope has not been verified here. Ship a client package anyway and treat downloads as a convenience. See Packaging.

The transmission handshake gains progress reporting

The patch packages the two callbacks that fire during the sequence documented above [patch-script]:

ghostAlwaysObjectReceived()
ClientReceivedDataBlock(idx, total)

Both now update LoadingProgress / LoadingProgressTxt and force Canvas.repaint() so the loading screen stays responsive through a long datablock transmission. The handshake itself — transmitDataBlocks, dataBlocksDone, phase ordering — is untouched.

If your mod declares a very large number of datablocks, this is where the user sees the cost.

EffectProfile is inert on the QoL patch

EffectProfile datablocks still parse and are still referenced by AudioProfile.effect, but TribesNEXT’s IFC22.dll stubs the Immersion force-feedback exports [binary], so nothing plays. Declaring them remains harmless. See Audio.

Related

• SimObjects and namespaces — how className drives callbacks
• Boot sequence — when datablock files execute
• Client/server split — the transmission described above, in context
• Weapons — a complete datablock chain, annotated
• 07 · Community Patches — asset downloads and the patch archives