Empires BattleBoard

UI

There is a custom 3d UI object for displaying a battle board which . It can be added to a UI by adding a "CUSTOM" type object to a UI with the additional tag "BATTLEBOARD" and a number of optional parameters to control formatting and behaviour. For example:

[BattleSummary3D]
TYPE Custom
BattleBoard
WIDTH 868
HEIGHT 618
DX 0
DY 0
MINLINES 3
MINLINELENGTH 4
UNITSPACING 8
CENTERGAP 12
ASSETSCALE 7
EVENTFRAMES 60
EVENTATTACKFRAME 10
EVENTDAMAGEFRAME 18
HITSTEXTCOLOUR $COL_RED
EFFECTEXTCOLOUR $COL_YELLOW
TEXTSTEP 2.5
FONT LARGEFONT

• MINLINES is the minimum number of battle lines per side to show on the battle board regardless of the number of units present (the view will zoom out to show additional lines if required)
• MINLINELENGTH is the minimum number of slots per wing to show on the battle board regardless of the number of units present (the view will zoom out to show additional lines if required)
• UNITSPACING is the distance between units
• CENTERGAP is an additional space between the front lines of opposing armies
• ASSETSCALE is a scale factor for the units (the scale used the AssetScale from UNITS.CSV in thousandths, divided by this value)
• EVENTFRAMES is the number of logical frames (1/30 s) used to display each battle event
• EVENTATTACKFRAME is the frame within a battle event where the attack animation starts
• EVENTDAMAGEFRAME is the frame within a battle event where the damage is applied
• HITSTEXTCOLOUR is the colour used for hit damage text
• EFFECTEXTCOLOUR is the colour used for effec damage text
• FONT is the font used for pop up text
• FILE is the default terrain texture to use (if not specified by script)
• LOGBOX is the name of an existing listbox to output combat log to

Scripting

To display a battle in a battle board UI, you must create and populate an event record in script:

1. Call CreateBattleRecord(factionID0a, factionID0b, factionID1a, factionID1b) to uniquely store events for this battle. A record handle will be returned which you will use to populate and destroy this record. The record will persist until it is destroyed with DestroyBattleRecord(recordHandle) and is included in saved games. Up to two faction IDs can be given for each side in the battle used when displaying faction names on the battle board.
2. Create a status event for every unit that is involved in the battle using AddBattleStatus(recordHandle, unitID, side, wing, line, distance, unitTemplateName, unitNameID, unitNumeral, hitsBefore, effecBefore). recordHandle is the handle of a record created with CreateBattleRecord. unitID is a unique identifier for the unit (although it does not need to be the id of a valid unit object). side [0,1], wing[0,1], line[0,2], and distance [0,16] indicate where the unit is placed on the battle board. unitAlias is the name of a unit template used for visual properties of the unit (including Asset and AssetScale). unitNameID is the string ID of the base unit name and unitNumeral is a numeric ID to prepend to the name (negative values will be interpreted as Roman numerals). hitsBefore and effecBefore are the initial status of the unit.
3. For any unit that has been set up using AddBattleStatus, you can optionally call UpdateBattleStatus(recordHandle, unitID, hitsAfter, effecAfter) to indicate the final status of the unit.
4. For any unit that has been set up using AddBattleStatus, you can optionally call SetBattleTooltipInfo(recordHandle, unitID, advancedInfo) to provide info for the detailed tooltip and combat log. advancedInfo is an array of 32 integers used in the BATTLE_STATUS callback.
5. For every event in the battle, call AddBattleEvent(recordHandle, type) to create the event, it will return an eventNum referenced below. Battle events of type 0 will be played back sequentially in the order they are created. Type 1 events are deferred until the end of the battle and then played simultaneously. No events are required to, for example, just show a preview of a battlefield.
6. For each participant in an event (actor, defender, support, etc.), call AddBattleEventParticipant(recordHandle, eventNum, unitID, hitsDelta, effecDelta, movementType, actionType, turnToFace, [initString], [actionString], [advancedInfo]). recordHandle and eventNum returned by CreateBattleRecord and AddBattleEvent respectively. unitID is the id of a unit set up with AddBattleStatus. hitsDelta and effecDelta are the status to show on this unit. movementType, actionType, and turnToFace provide instructions for hew the event is displayed (see below). initString is the string ID of a static message to display over the unit at the start of the event. actionString is a static message to display at the climax of the event. advancedInfo is an array of 32 integers used in the BATTLE_MESSAGE callback to display advanced combat details.
7. When the UI is about to be activated (for example, in the UI_OBJ_ACTIVATE callback of its parent), set the user data on the UI object to the handle of the record to display. For example:

FUNCTION UI_OBJ_ACTIVATE(id)
{
    SetUIObjectUserData("BattleSummary3D", gBattleDesc.recordHandle);
}

Feedback callbacks (on the UI containing the battle board):

BATTLE_MESSAGE(int event, int action, int side, int wing, int line, int slot)

• Incoming info is stored in work array 0
• String is set in ui string 0, return 1 if there is something to show

FUNCTION BATTLE_STATUS(int event, int action, int side, int wing, int line, int slot)

• Incoming info is stored in work array 0
• String is set in ui string 0, return 1 if there is something to show

Playback can be controlled by calling BattleBoardControl(objectName, command). The following commands are available:

0. Restart

1. Step back one action

2. Pause

3. Play one action and pause

4. Play normally

5. Skip to the end of the battle

Playback status can be polled by calling GetBattleBoardStatus(objectName). The following statuses are possible:

-1: Not playing

0: Paused

1: Playing Single Step

2: Playing

1000: Complete

Event Types

0. Standard

1. Retreat / Pursuit - events of this type are delayed until the end of the battle playback and played simultaneously

Event Participant Parameters

Movement Types

Describes the type of movement an event participant takes at the beginning of the event. Setting the turn to face parameter to 1 will cause the unit to turn toward its target while moving.

0. Stationary - don't more forward, continue to play idle animation

1. Charge - move a large distance forward playing the charge animation

2. Advance - move a small distance forward playing the move animation

Action Types

Describes the type of action an event participant shows after the movement phase

0. Passive - continue to play idle animation

1. Melee - play melee animation

2. Ranged Attack - play fire animation