Empires BattleBoard: Difference between revisions

From Archon Wiki
Jump to navigation Jump to search
m (Andrewg moved page BattleBoard to Empires BattleBoard)
 
(4 intermediate revisions by the same user not shown)
Line 10: Line 10:
DX 0
DX 0
DY 0
DY 0
COLOUR 0f200f
MINLINES 3
MINLINES 3
MINLINELENGTH 4
MINLINELENGTH 4
Line 16: Line 15:
CENTERGAP 12
CENTERGAP 12
ASSETSCALE 7
ASSETSCALE 7
EVENTFRAMES 60
GRIDEMPTY BattleGrid.tga
EVENTATTACKFRAME 10
GRIDUNIT BattleGrid.tga
EVENTDAMAGEFRAME 18
GRIDTARGET BattleGridTarget.tga
HITSTEXTCOLOUR $COL_RED
GRIDATTACKER BattleGridAttack.tga
EFFECTEXTCOLOUR $COL_YELLOW
FILE UI_BATTLE/Battlefield_Default.dds
TEXTSTEP 2.5
</nowiki>
FONT LARGEFONT</nowiki>


* 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)
* 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)
* 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)
Line 30: Line 27:
* CENTERGAP is an additional space between the front lines of opposing armies
* 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)
* 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
* GRIDEMPTY, GRIDUNIT, GRIDTARGET, and GRIDATTACKER are textures displayed over the ground to highlight empty grids, inactive units, targetted units, and attacking units respectively
* EVENTATTACKFRAME is the frame within a battle event where the attack animation starts
* FILE is the default terrain texture to use (if not specified by script)
* 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 ==
== Scripting ==


To display a battle in a battle board UI, you must create and populate an event record in script:
See BATTLESCRIPT.TXT for descriptions of commands to set up a BattleBoard UI, add units, play animations, move units, and display text with the units.  Relevant commands start with "Battle3D".
# 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.
# 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.
# 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.
# 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.
# 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.
# 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:
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)
{
    SetUIObjectUserData("BattleSummary3D", gBattleDesc.recordHandle);
}</nowiki>


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


BATTLE_MESSAGE(int event, int action, int side, int wing, int line, int slot)
Battle3DAddUnit takes a squadType, which is the name of a row in SQUADS.CSV which indicates the asset name, squad size, scale, and other display parameters for the 3D model.  This table is also used for displaying groups on the map, although they are always shown as a single unit on the map.
* 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)
Placement of squad members is controlled by FORMATIONS.TXT, there is a chunk for each squad size indicating the placement of the member (x and y coordinates, -1 to 1) in the battle grid.
* 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?

Latest revision as of 20:09, 8 July 2019

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
GRIDEMPTY BattleGrid.tga
GRIDUNIT BattleGrid.tga
GRIDTARGET BattleGridTarget.tga
GRIDATTACKER BattleGridAttack.tga
FILE UI_BATTLE/Battlefield_Default.dds
  • 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)
  • GRIDEMPTY, GRIDUNIT, GRIDTARGET, and GRIDATTACKER are textures displayed over the ground to highlight empty grids, inactive units, targetted units, and attacking units respectively
  • FILE is the default terrain texture to use (if not specified by script)

Scripting

See BATTLESCRIPT.TXT for descriptions of commands to set up a BattleBoard UI, add units, play animations, move units, and display text with the units. Relevant commands start with "Battle3D".

Squads

Battle3DAddUnit takes a squadType, which is the name of a row in SQUADS.CSV which indicates the asset name, squad size, scale, and other display parameters for the 3D model. This table is also used for displaying groups on the map, although they are always shown as a single unit on the map.

Placement of squad members is controlled by FORMATIONS.TXT, there is a chunk for each squad size indicating the placement of the member (x and y coordinates, -1 to 1) in the battle grid.

Retrieved from "https://archonwiki.slitherine.com/index.php?title=Empires_BattleBoard&oldid=517"