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 CreateEventRecord() 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 DestroyEventRecord(recordHandle) and is included in saved games.
2. Create a status event for every unit that is involved in the battle using AddStatusEvent(recordHandle, unitID, side, wing, line, distance, unitAlias, unitNameIndex, hitsBefore, effecBefore). recordHandle is the handle of a record created with CreateEventRecord. 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). unitNameIndex is the index of a UI string containing the display name of this unit. hitsBefore and effecBefore are the initial status of the unit.
3. For any unit that has been set up using AddStatusEvent, you can optionally call UpdateStatusEvent(recordHandle, unitID, hitsAfter, effecAfter) to indicate the final status of the unit.
4. For every event in the battle, call AddBattleEvent(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). recordHandle and eventNum returned by CreateEventRecord and AddBattleEvent respectively. unitID is the id of a unit set up with AddStatusEvent. hitsDelta and effecDelta are the status to show on this unit. actionType provided instructions for hew the event is displayed (see below).
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);
}

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?