TFE Weapon Data

Weapon data has been externalised to a JSON file in The Force Engine. The data is located in ExternalData\DarkForces\weapons.json.

Altering the data in weapons.json will alter the way that weapons behave. If the JSON file is removed, renamed or corrupted, weapons will not work correctly. (In this case, an error message will be logged.)

Note that all text in the JSON is case insensitive (uppercase, lowercase or a mixture may be used). The weapons and their properties can be listed in any order.

Mods

A customised version of weapons.json can be included in a mod's ZIP file. A modded weapons.json will take precedence over the base version.

Modded versions of weapons.json need to include definitions for all 10 of the weapons plus the gasmask. If any weapon definitions are missing, they will not work when the game is played.

Note about offsets

xPos and yPos offsets are based on a screen with width 320 pixels and height 200 pixels, regardless of what resolution you have set in TFE.

Gasmask

The JSON also contains data for the gasmask.

texture	The texture (BM) to use for the gasmask.
xPos	X (horizontal) offset on the screen.
yPos	Y (vertical) offset on the screen.

Weapon data

Property	Type	Description
frameCount	number (integer)	Number of animation textures. Maximum of 16.
textures	array of string	Textures that are used for the weapon's animation. Number of entries should match frameCount. These textures are referenced by the weapon's animation frames (see below for details)
xPos	array of integers	X offsets for each texture. Number of entries should match frameCount
yPos	array of integers	Y offsets for each texture. Number of entries should match frameCount
wakeupRange	number (integer)	Enemies within this range (in DF units) will be alerted when the weapon fires. Setting this to zero has the effect of creating a "silent" weapon.
variation	number (integer)	Aim variability. A higher number will cause the weapon to "spray" more randomly; lower numbers give greater consistency of aim.
ammo	string	Type of main ammo used by the weapon. The count is shown as the large red numbers in the HUD. Options are ammoEnergy, ammoPower, ammoDetonator, ammoShell, ammoMine, ammoPlasma, ammoMissile
secondaryAmmo	string	Secondary ammo for the Assault Cannon. Same options as above. This ammo count displays as the smaller green numbers on HUD.
primaryFireConsumption	number (integer)	Amount of ammo consumed per primary fire shot.
secondaryFireConsumption	number (integer)	Amount of ammo consumed per secondary fire shot.
animFrames	array of animation frames	Animation frames for primary fire. See below for details.
animFramesSecondary	array of animation frames	Animation frames for secondary fire (repeater, fusion gun, assault cannon). See below for details.

Animation frames

Each weapon has a list of animation frames that are played when the weapon fires. The repeater, fusion gun and assault cannon also have a list of animation frames for their secondary fire.

Each animation frame references a texture by index (starting at 0).

The way that animation frames are used depends on the weapon and type of fire.

Fists Pistol Rifle Repeater secondary Fusion secondary Mortar Concussion Assault cannon secondary	The frames will cycle through in order with each shot fired. The final frame needs to be the weapon's "idle" (non-firing) texture, i.e. texture 0. Additional frames can be inserted into the cycle.
Repeater primary Assault cannon primary	The frames will cycle through in order with each shot fired. An "idle" frame does not need to be included; these weapons are hardcoded to return to their non-firing texture (texture 0) when they stop firing. Additional frames can be inserted into the cycle.
Fusion primary	Frames 1-4 correspond to barrels 1 to 4 when they fire in turn. Frame 0 is the non-firing texture. Additional frames can't be inserted.
Thermal detonator	Frame 0 is shown when the fire button is pressed and held; frame 1 is shown when the button is released and the detonator is thrown. Frames 2-3 are shown after the throw is completed. Frame 4 is shown when there is no more ammo. Additional frames can't be inserted.
Mines	The mines do not use animation frames. The code directly references the 3 textures.

Each animation frame contains the following 4 data items.

Property	Type	Description
texture	number (integer)	Index into the weapon's array of textures (see above). The first item in the array has index 0, the second item has index 1, and so on. A given texture can be referenced multiple times if desired.
light	number (integer)	Amount of extra light for this frame. This is used to create the "muzzle flash" effect when the weapon fires. A higher number gives a brighter flash.
durationSupercharge	number (integer)	Duration in ticks that this frame will display when the weapon supercharge powerup is active. (Typically this will be a shorter duration than normal.)
durationNormal	number (intger)	Duration in ticks that this frame will display normally (no supercharge).

Altering the durations (normal and supercharge) of each animation frame will alter the weapon's rate of fire. Smaller durations will result in more rapid fire. There are 145 ticks per second.

If you are modding the weapons to insert additional animation frames (this is possible where indicated above), you will need to shorten the durations of the existing frames to preserve the original rate of fire.