Units

Custom Formations

Custom formations work using a callback function which sets up the formation data for a given unit's men. The callback function has the form:

FUNCTION FORMATION_CALLBACK(me)

this function will make use of the SetFormationRow function:

//Set the location of the nth man in the unit relative to the center of the tile.  offset is [0, 32], angle is [0, 359].  Only relevant in FORMATION_CALLBACK
SetFormationRow(n, offset, angle)

Unit Order Scripting

The ability to alter the behaviour of the units is one of the most powerful areas of the game scripting. Each unit type can have its own set of scripts and behaviour (although you don't have to do this). As you will see, you can get units to do almost anything with a well written script.

A unit will look for a script which is called <name>.BSF in the DATA\BATTLE\SCRIPTS directory, where <name> is the unit name as denoted by the Name entry in the squads.csv file. If the code cannot find a unique BSF file, it will load up a script called $DEFAULT.BSF to handle all the unit's behaviours.

The approach that the game itself uses is to have all units use a single set of scripts, but to use the unit attributes (as defined in the squads file) to determine what a unit can or cannot do. This has the advantage that abilities can be added or removed from a unit simply by altering data.

On the other hand, you might have units with very disparate abilities, in which case you might be best using individual scripts for each unit, bearing in mind you can always INCLUDE any shared functionality.

Unit Callback Functions

There are a variety of functions which a unit can have which are called at times by the code.

StartTurn

FUNCTION STARTTURN( me )

This function is called at the start of a unit's side's turn. This would be used to reset any per-turn counters or limits. Examples would be a unit's shots, or tick up its morale. STARTTURN is a required function for every unit.

CustomTrigger

FUNCTION CUSTOM_TRIGGER( me, a, b, c, d ) The custom trigger is a low level function used to trigger scripting from the unit animation files. It passes through any of the 4 parameters allowed in the animation file for a unit.

Init Functions

FUNCTION INIT_*( me ) Any function which is named with INIT_ as the first 5 characters will be called on unit creation. You can use this to set up attributes, initialised starting values, etc. Note that if there is more than one INIT_ function then the order they will be called in cannot be guaranteed.

Unit Ability Functions

To actually allow a unit to do anything, it needs to have scripted behaviours. An example can be seen in the Case Study at the end of this document, but the key functionality is described below. Once again we also recommend reading through and editing (in your own custom campaign, never in the main game data!) the existing unit scripts to see how it all hangs together.

There are 3 types of ability, depending upon the contents of the tile you are attempting to action. These are TILE_, ALL_, and UNIT_. TILE_ can operate only on empty tiles, ALL_ will attempt to work on all tiles, and UNIT_ will only operate on a tile with a unit present on it.

The key functions which will allow you to begin creating unit behaviours are described below. Note we will show all examples using the ALL_ tag, but this can be replaced with the TILE_ or UNIT_ tag to simplify the scripting as desired.

Note that for all the functions described here, you can omit any of the parameters you don't use, and that the code will correctly assign them no matter where in the param list they are. Indeed, you can have extra parameters in a function header and they will be set to zero if they are called by the code rather than by you.

Checking

FUNCTION CHECK_ALL_<name>( me, unit, tilex, tiley [, reaction] ) This function is used to determine whether a unit can perform a task. The return value can be either the cost of the action in AP, or -2 if you with the task icon not to be shown, or -1 if you wish to show the icon in a disabled state. See below for details on the optional reaction parameter.

Icon Setup

FUNCTION UISETUP_ALL_<name>( x, y, width, height, me, tilex, tiley ) This function can be used to setup and draw the order icon. The x,y,width,height parameters are the onscreen positions of the button.

Executing

FUNCTION ALL_<name>(me, unit, tilex, tiley) This is the function which is called when the user selects the action for the unit. Note this cannot happen if the check function returns -1 or -2 as the icon will not be selectable.

Reacting

FUNCTION REACT_ALL_<name>(me, unit, tilex, tiley) If you want a unit to be able to react to other units, then you make use of the reaction function. This works in concert with the CHECK_ function for a given command. The system first calls the CHECK_ function to determine whether an action is possible against the reacted-against unit. Note that when CHECK_ is called in this case, the optional reaction parameter is set to 1, rather than 0 as it normally is.

If the check function returns >=0 then this is taken as the AP cost of the action, and the system then calls the REACT_ function. The react function should return a 'score' for this unit using this action to react to the threat. Examples of how to calculate this score we be based on things like chance of success, range to target, etc - as dependent upon the game model. The system will go through all units on the reacting side and then sort the reactions by their scores, and execute them in the 'best' order. Note that returning -1 from a REACT_ function means that you do not want the unit to attempt to react with this action.