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
COLOUR 0f200f
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

• COLOUR controls the background colour, use 0 for transparent
• 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

Scripting

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

1. Call CreateBattleRecord() 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.
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, [advancedInfo]). 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. advancedInfo is an array of 32 integers used in the BATTLE_STATUS callback.
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 every event in the battle, call AddBattleStatus(recordHandle, type, roll) to create the event, it will return an eventNum referenced below. Unless otherwise noted, battle events should be created in the order they are to be displayed. type provides instructions for how the event is displayed (see below). roll indicates the roll (or roll difference) associated with the event. No events are required to, for example, just show a preview of a battlefield.
5. For each participant in an event (actor, defender, support, etc.), call AddBattleEventParticipant(recordHandle, eventNum, unitID, hitsDelta, effecDelta, actionType, [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. actionType provided instructions for hew the event is displayed (see below). advancedInfo is an array of 32 integers used in the BATTLE_MESSAGE callback.
6. 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

1000: Complete

Event Types

10. Duel

20. Flanking - attackers will turn to face defenders

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

More to come?

Action Types

0. Passive defense

1. Standard attack - charge forward and play melee attack animation

2. Support attack - advance slightly and play ranged attack animation

More to come?