Empires BattleBoard: Difference between revisions

From Archon Wiki
Jump to navigation Jump to search
No edit summary
m (Andrewg moved page BattleBoard to Empires BattleBoard)
 
(3 intermediate revisions by the same user not shown)
Line 15: 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>


* 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)
Line 28: 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
* 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)
* 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 ==
== 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(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.
# 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.
# 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 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.
# 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.
# 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.
# 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 ===
 
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

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"