Archon Wiki - User contributions [en]

Empires Modding

2019-08-08T15:11:38Z

Andrewg: /* Advanced Modding */

= Modding Guide =

== Getting Started ==

Empires saves user files in your Documents\My Games\FieldOfGloryEmpires folder, which will be referred to as your 'user' folder. In addition to saved games, logs, and options files, this is where user created mods are located. Editing files directly in the game install folder (ex C:\Program Files (x86)\Slitherine\Field of Glory Empires) is NOT recommended, doing so may prevent multiplayer games from working correctly and interfere with game updates.

Before you begin modding, you may wish to open the USER.TXT file in your user folder and the following line to enable additional debugging tools:
<nowiki>DEBUGMODE 1</nowiki>

See [[Empires Version]] for additional topics.

== Create a Scenario ==

Empires currently only support mods by the creation of a new, modified scenario. The quickest way to create a new scenario and get started modding is to copy an existing scenario. For example, to start with the grand campaign, browse to the Scenarios folder in your game install folder (ex. C:\Program Files (x86)\Slitherine\Field of Glory Empires\Scenarios). Copy the d310BCGrandCampaign folder into the SCENARIOS folder of your user folder (ex Documents\My Games\FieldOfGloryEmpires\SCENARIOS). Rename the pasted folder to something new (it is recommended the new folder name not contain spaces). You should also make sure this new folder and its contents are not Read-Only. Inside this folder, you should see a number of files:
<nowiki>MYSCENARIO
│ SCENARIO.BSF
│ TEXT1.TXT
│ TEXT1_FRE.TXT
│ TEXT1_GER.TXT
│ TEXT1_SPA.TXT
│ SCENARIO.TXT
├───DATA
│ │ SETUP.csv
│ │ SETUP_FACTIONS.csv
│ │ REGIONS.csv
│ │ SETUP_GROUPS.csv
│ └───SCRIPTS
│ Events_Plugin.BSF</nowiki>
A good place to start would be to open TEXT1.TXT in a text editor. Here you can give your mod a unique name, description, and starting message. See [[Modding#Custom_Text]] for details on modifying string files in the Archon engine. TEXT1_FRE.TXT, TEXT1_GER.TXT, and TEXT1_SPA.TXT contain the translations of the strings in TEXT1.TXT. If you do not plan to translate your mod into other languages, you should just remove these three files and the strings entered in TEXT1.TXT will be used for all languages.

SCENARIO.BSF is another place you can make some quick edits to you scenario. Refer to [[Scripting]] for a description of the Archon scripting language. The InitScenario function near the beginning of this file sets up a number of parameters for your scenario, try changing gTurnInfos.dateFirstTurn to adjust the starting date for your mod.

If you start the game and select Scenarios, your modified scenario should now appear near the bottom of the list and be selectable for play.

== Changing the Scenario Setup ==

Three files of particular interest when changing the setup of the scenario are found in the DATA folder - SETUP.csv, SETUP_FACTIONS.csv, and REGIONS.csv. These files are semi-colon separated CSVs and can be opened and edited in most spreadsheet software (ex Excel, OpenOffice), be sure to save them in the same format.

=== SETUP_FACTIONS.CSV ===

This file defines which factions are available in your scenario.

Coming soon...

=== REGIONS.CSV ===

This file specifies the basic properties of each region on the map.
* Alias: This is used as a reference to this region elsewhere. It is not recommended that you change this column, as it is used to associate this region with an area in the map used by this scenario.
* Name: This is a reference to the name used for this region. To edit the name, do not change the reference itself, but create a new entry with this id in the TEXT1.TXT file you edited above.
* Terrain: This is the terrain type of this region. For a list of valid terrain types, see DATA\TERRAINS.CSV, although some terrain types are not valid to assign directly to a region. Note that the reference must begin with $. This is generally the case when referring to an Alias from another CSV.
* Res[0], Res[1], Res[2], Res[3]: These are the natural resources present in the region. For a list of possible resources, see DATA\RESOURCES.CSV.
* Disabled: This controls which regions defined in the map are included in the scenario.
* Faction: This is the faction which initially owns this region (see SETUP_FACTIONS.CSV)
* CitizensID[0], CitizensAmount[0]: CitizensID[0] is the ethnicity of a the citizens to add, see DATA\ETHNICS.CSV for a list of possible ethnicities. CitizensAmount[0] is the number of citizens of the given ethnicity to add. Citizens will initially be distributed among the four possible jobs. To add citizens of multiple ethnicities, use CitizensID[1-3] and CitizensAmount[1-3].
* SlavesID[0], SlavesAmount[0]: add slaves to the region, similar to citizens above, although they will only be initially assigned to Agriculture or Infrastructure.
* City_Name: This is a reference to the name of the city in this region. As with the region name, you can override the name by adding a new entry to your TEXT1.TXT file.

=== SETUP.CSV ===

This file defines the initial placement of structures and groups (armies and navies) in your scenario.

Coming soon...

== Adding Units ==

Before starting, if your custom scenario doesn't already contain these files, copy them from the game install folder (as above, do not edit them directly in your game installation):
* DATA\UNITS.CSV
* DATA\UNITVISUALS.CSV
* DATA\FACTIONS.CSV

To add a new unit, start by adding a new row to your UNITS.CSV, or copying the row describing a similar unit. You must fill in these fields:
* ID - This must be a unique number greater than zero, start with something well beyond the range of values in the standard unit list to avoid conflicts later, ex 10000.
* Alias - This must be a unique and descriptive string starting with "ID_UNI_" that you will use to identify this unit later in other data files.
* Name - This is a reference to the name used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_NAME_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.
* Text - This is a reference to the description used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_TEXT_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.

To complete your new unit, or if you are simply modifying an existing unit, also set these fields:
* FOG2_Name - This is the type of unit this will be exported as when a battle is exported to Field of Glory 2. This must match a value in the Name column of Field of Glory II\Data\Squads.csv, or copy a value from a similar unit if you are unsure.
* FOG2_QualityMOD - When exported to Field of Glory 2, this is the base quality of a unit relative to the type given above, as a percentage. Set this to 100 if you are unsure.
* AGEOD_Cost - When exported to Field of Glory 2, this is used in the calculation of how many units are created in FOG2 for each Empires unit.
* Family - The category of this unit, possibly values are: $famInfantry, $famHvyInfantry, $famArcher, $famSkirmisher, $famLtCavalry, $famSkirmisherCavalry, $famCavalry, $famHvyCavalry, $famHvyBeast, $famSiege, $famLtWarship, $famWarship, $famHvyWarship, $famTransport
* EvolveFamily - If non-zero - if this unit becomes obsolete it can be replaced by another unit with the same value, or another unit with the same value becomes obsolete it can be replaced by this unit.
* EvolvePriority - If an EvolveFamily is set, it is used to pick the best unit to evolve an obsolete unit to.
* UpdgradeNext - Used in Event/Decision driven unit upgrades.
* MoveSpeed - The movement speed of the unit.
* Hits - The maximum number of Hits of the unit.
* Effectiveness - The maximum Effectiveness value of the unit.
* Attack - The base Attack value of the unit.
* Defense - The base Defense value of the unit.
* IsSupport - Does the unit behave as a support unit in combat.
* DistanceToCenter - Low values will cause a unit to be deployed near the center of combat, high values will deploy the unit near the flanks.
* AssaultDistanceToCenter - As DistanceToCenter, but used during assaults.
* Siege - The Siege value of the unit.
* SiegeResist - The Siege Resist value of the unit.
* SupplyUsage - The amount of supply consumed by the unit per turn (1 food typically provides 5 supply, before bonuses and penalties).
* AttackingRange - During the ranged attack phase of combat, can the unit target the opponent front line (0), support line (1), or reserves (2).
* RangedAttack - The Ranged Attack score of the unit, or 0 for units without a ranged attack.
* RangedDefense - The Ranged Defense score of the unit.
* RangedMaxDamages - The limit of Effectiveness damage done by the unit during the ranged attack phase.
* FlankingModifier - A bonus used when calculating flanking or pursuit damage inflicted by this unit.
* Modifier[0 - 3] - Modifiers for this unit, a reference to a row in DATA\MODIFIERS.CSV.
* NotBuildable - If set to 1, this unit will not be recruitable normally (ex. units that only appear in garrisons).
* BuildPointsCost, ManpowerCost, MoneyCost, MetalCost - Equipment, Manpower, Money and Metal costs to recruit.
* ManpowerUpkeep, MoneyUpkeep, MetalUpkeep - Manpower, Money, and Metal maintenance costs.
* MoneyInflationCost - The increase in Money cost per unit of this type.
* ShipyardNeed - The level of shipyard needed in a region to recruit the unit.
* Recruit_Weight - A weight given to this unit when doing randomized unit recruitment.
* RecruitArea - Optionally limits recruitment of this unit to a specific group or regions, a reference to a row in DATA\AREAS.CSV
* RequiredStructures - If a structure or | separated list of structures is given, the unit can only be recruited in regions where at least one of the structures is present. The structures are references to rows in DATA\STRUCTURES.CSV
* NationalUnique - If non-zero, a faction cannot recruit the unit if it already has one.
* ProgRate - The experience points required to reach Experience Level 1.
* InitialXPLevel - The base initial Experience Level for this unit.
* Garrison_Category - For units which can be recruited as automatic garrisons, this must correspond to one of the Garrison_Category entries of the structure which provides the garrison, in DATA\STRUCTURES.CSV.

Next, in your UNITVISUALS.CSV, you will need to have an entry for added units. Each unit type must have at least one 'garment' specified:
* Unit - A reference to the Alias of the unit in UNITS.CSV.
* Garment - Allows the same type of unit to have different appearances in different factions. This value is either $GARMENT_DEFAULT if it is the default appearance, or a match to the Garment entry for a faction in DATA\FACTIONS.CSV.
* Asset - Specifies the 3D model used for this unit, this is a reference to a row in DATA\SQUADS.CSV (note this is not prefixed with a $ as most references are). Typically, this corresponds to a model in DATA\ASSETS\UNITS in S4F format which is a proprietary Slitherine model and animation format.
* TextureSet - Used to control which color and pattern variation to use for this unit. Unit models typically have multiple sets of possible textures, you can preview these by viewing the 'diffuse' textures in DATA\ASSETS\UNITS. Texture set 0 is found in the root of that folder. Other texture sets are found in the texture# subfolders.
* TextureVariant - Within each texture set are up to 4 variants (cavalry and other complex units may only have 2 or 1 variants per set). 0 is the top left variant, 1 is the top right, 2 is the bottom left, and 3 is the bottom right. For example, TextureSet 1, Texture Variant 3 of the african_spearmen, uses the lower right quadrant of DATA\ASSETS\UNITS\texture1\African_Spearman_Diffuse.dds when drawing the unit.

Finally, new units will need to be added to the pool of factions that they are available to. In your FACTIONS.CSV, update:
* UnitsAge1 - a | separated list of unit references for units available to the faction in the lowest category of government (Horde, Tyranny, Kingdom, Oligarchy, or Sect).
* UnitsAge2 - a | separated list of unit references for units available to the faction in the second category of government (Tribe, City State, Monarchy, Republic, or Hierocracy).
* UnitsAge3 - a | separated list of unit references for units available to the faction in the third category of government (Confederation, Commonwealth, Empire, Federation, or Theocracy).

You should now be able to start your scenario and have your new or modified units available.

=== Advanced ===

If an existing modifier doesn't suit your unit, you can create a new modifier by copying MODIFIERS.CSV from the DATA folder of the game installation to the DATA folder of your custom scenario. Then add a new modifier following the pattern of the existing modifiers. You can now refer to this new modifier from your unit.

Modifiers refer to effects to apply statistical bonuses or penalties. These effects are defined in DATA/EFFECTS.CSV, so as above you can create a new effect by copying the shared EFFECTS.CSV to your scenario's DATA folder and creating a new effect.

Many unit effects only apply in specific terrain categories (indicated if the effect terrains column is 1). In that case, the modifier will specify the terrains as the fourth parameter associated with that effect, using a combination of 1: Open, 2: Forest, 4: Arid, 8: Rough, 16: Swampy, 32: Assault, 64: Coastal Water, 128: Open Water, 256: Steppe, 512: Mountainous. For example:

ID_MOD_UNIT_MOUNTAINMEN has multiple effects, effectID[0] is $MOD_EFFECT_MOVE_BONUS, which is means the first effect is a movement speed bonus. params0[3] is 520, which is 512 + 8, indicating that this bonus applies in Mountainous and Rough terrain. Referring to the terrain categories in DATA/TERRAINS.CSV, we see that the Mountainous category includes both Mountain and Alpine terrain types, and the Rough category includes Hills and Arid Hills.

If you wish to create your own 'skin' for an existing unit model, you can add a new texture set for the unit by using an existing texture set as a template and following the naming of the texture exactly (although you may use a TGA file with the .tga extension instead of a DDS file) in the correct location for the next texture set within your scenario. For example, the Hoplite_vet_arm model uses the Hoplite_Vet_Diffuse.dds texture. The highest numbered texture set defined in the game is DATA\ASSETS\UNITS\Hoplite_Vet_Diffuse.dds, texture set 5. If you create a new texture set and place it within your scenario at DATA\ASSETS\UNITS\texture6\Hoplite_Vet_Arm_Diffuse.tga, you can then refer to Asset Hoplite_Vet_Arm and TextureSet 6 in UNITVISUALS.CSV and it will use your new texture set. If specular and normal maps aren't provided for a texture set, the versions from set 0 for that model will be used.

If you have a new 3D model in the S4F format, you will need to add a row in a copy of DATA/SQUADS.CSV that refers to that model before you can use it in your UNITVISUALS.CSV.

== Adding Structures ==

Coming soon...

== Adding Events ==

If you copied an existing scenario as above, your scenario should already contain a DATA\SCRIPTS\Events_Plugin.BSF containing one function, Event_EntryPoint(). Standard Empires events are found the Data\scripts\Events.BSF in the game installation folder. You may refer to the events in this file as a reference when creating events.

At the bottom of Events_Plugin, create a new function for your event, this function will be called at the end of each turn and will determine if the event should occur, what factions are affected, and apply the gameplay effects of the event. By convention, the function name should start with EventCustom_ followed by a descriptive name for the event. Once you have written your event function, add a call to it in the Event_EntryPoint function at the top of your Events_Plugin.

For example, if you want to create an event that will give 100 metal once during the scenario to each faction with a 1% chance each turn, your file should like this:

<nowiki>FUNCTION Event_EntryPoint()
{
EventCustom_MetalStrike();
}

//// METAL STRIKE ////

// turn to start checking for the event (0 based)
#define EVTCUSTOM_METALSTRIKE_TURNSTART 1

// % chance per turn per faction
#define EVTCUSTOM_METALSTRIKE_CHANCE 1

// amount of resource given
#define EVTCUSTOM_METALSTRIKE_AMOUNT 100

// record of which factions have received the event
int EvtCustom_MetalStrike[FACTION_MAX];

FUNCTION EventCustom_MetalStrike()
{
int facCount;
int facIndex;
int factionID;

if (GetTurn() >= EVTCUSTOM_METALSTRIKE_TURNSTART)
{
// iterate over all factions
facCount = GetNumFactions();
for (facIndex = 0; facIndex < facCount; facIndex++)
{
// has this faction already received this event (by index)
if (EvtCustom_MetalStrike[facIndex] == FALSE)
{
// get the ID of this function
factionID = GetFactionID(facIndex);

// only applies to active factions, excluding independents
if (Faction_IsWorldFactionOrInactive(factionID) == FALSE)
{
// has a chance to get a metal strike this turn
if (Dice(100) <= EVTCUSTOM_METALSTRIKE_CHANCE)
{
// add the metal to the faction's stockpile
Faction_AddResource(factionID, gResourceMetal, EVTCUSTOM_METALSTRIKE_AMOUNT);

// send a message to the receiving faction
Message_Faction_ChangeResourcePrivate(factionID, Faction_Politic_SeatOfPower(factionID), EVTCUSTOM_METALSTRIKE_AMOUNT, MSG_IMP_TOP, "IDS_MSG_EVENT_METAL_STRIKE");

// remember that this faction has already had a metal strike
EvtCustom_MetalStrike[facIndex] = TRUE;
}
}
}
}
}
}</nowiki>

You will also need to add the string to display for this event to your scenario's TEXT1.TXT file:

<nowiki>IDS_MSG_EVENT_METAL_STRIKE, "Prospectors discover metal deposits in %{1}u totalling %{0}u metal.",</nowiki>

== Advanced Modding ==

Many files not specifically covered elsewhere can still be overridden in a modified scenario. Generally, if a file is found anywhere in the Data folder of the game installation, you can place a modified version of that file in the same relative location of the DATA folder of your modified scenario and your scenario will use that instead.

When modding gameplay scripts from Data\Scripts, you must also copy Data\Scripts\MAP.BSF to your modified scenario to ensure your changes are included, even if you do not require changes to MAP.BSF.

== The Editor ==

Empires contains a rudimentary editor for modifying or creating BAM files, which control the map. If you have started by copying the Grand Campaign, your scenario will be set up to load the shared Empires map, Data\Maps\AEP.BAM in the game install folder. If you open your scenario in the editor, changes you make will be saved to Data\Maps\AEP.BAM within your custom scenario. Note, you currently need to create an empty Maps folder within the Data folder of your scenario before you save the first time.

If you have enabled DebugMode above, when you open the Options screen from the Main Menu the will be an Editor button at the top of the screen. This editor has a small number of useful features. Select your scenario when prompted and click OK.

Please note that there is no Undo feature in the Editor and saving and backing up frequently is strongly recommended if you are making multiple edits.

=== Region Mode ===

The default editor mode is Region Mode. When you left click on the map to select a region, it will be highlighted in red and details will be displayed in the Region Properties panel on the right.

The top section of Region Properties specifies which row in REGIONS.CSV corresponds to the selected region on the map. Generally you will not need to change this unless you are creating a new map from scratch.

The second section lists a number of properties of the region. They cannot be edited here, they are specified by REGIONS.CSV or other setup files described above.

The third section is used to edit the connections between this region and its neighbors. On the map, the connections to the selected region are visualized with colored arrows.

If you right click on a region that is already connected to the current selection, it will be highlighted in purple and the Region Properties panel will update to let you Disconnect that region or change the connection 'terrain'. Although all terrains are offered, the relevant choices are:
* Strait - for crossing between nearby land regions without transporting through the water region which separates them
* Big River Crossing - indicates regions are separated by a large river
* River Crossing - indicates regions are separated by a smaller river
* Land Interdiction - prevents land units from moving between regions when the rules would otherwise allow it
* Naval Interdiction - prevents naval units from moving between regions when the rules would otherwise allow it
* No Cost - standard connection, there is no extra cost or limitation for moving between regions

See TERRAINS.CSV for the exact costs associated with the different connection types.

If you right click on a region that is not connected to the current region, it will be highlighted in green and you will be able to Connect it from the Region Properties panel and then set the connection terrain.

The bottom section of the Region Properties panel describes the anchor points defined for the selected region. Anchor points are used to set the locations of many dynamic objects during the game. The default anchor assignment is:
* 0: city
* 1: harbor
* 2: allied or neutral army
* 3: external wonder, 3d notifications, visual effects
* 4: second external wonder, second visual effect
* 5: icon
* 6: volcano
* 7: player army
* 8: overlay text
* 9: enemy army

The anchor locations are displayed for the current region as either a yellow triangle, or another 3D model that indicates its use. To move an anchor, first select it either by clicking on its representation on the map or selecting it from the list. Then drag and drop it to the desired location.

=== Border Mode ===

The Border Mode contains a number of rudimentary tools for creating or modifying the boundaries of a region. The border mode has a palette of four tools, which perform a variety of related operations depending on the context, button, and key modifiers. The exact functionality is described on the left of the editor when you select the different tools.

=== Unit Mode ===

Unit Mode allows you to visualize initial armies created during scenario initialization as described above. You may select an army to view its details. The armies are not edited here, this is done in [[Empires_Modding#SETUP.CSV]]

=== Scenario Properties ===

This mode lists miscellaneous read only information about the scenario, determined by the setup files.

=== Advanced ===

In some cases, the map file could have a different name. The SCENARIO.TXT file at the root of your scenario contains a line specifying the name of the BAM file.

See [[Empires_Terrain#Creating_a_Scenario]] for information on creating a new map using the editor.

== Sharing Mods ==

As mods are self-contained scenarios, you can share a mod simply by packing and distributing your custom scenario's subfolder from your user folder, which is then placed on the equivalent location in another player's user folder.

Empires also supports the CPF and LST files in the same format as some previous Slitherine games to make installation easier for other players. To create a CPF file, select Editor, select the scenario to package from the list of custom scenarios, and then press the Create Campaign Package File (CPF) button. The CPF will be saved to your user SCENARIOS folder.

See http://www.slitherinebravo.net/GameWiki/doku.php?id=mod_older_hot#share_unofficial_user_scenarios_on_any_platform for more information.

Empires Modding

2019-07-10T01:14:00Z

Andrewg: /* The Editor */

= Modding Guide =

== Getting Started ==

Empires saves user files in your Documents\My Games\FieldOfGloryEmpires folder, which will be referred to as your 'user' folder. In addition to saved games, logs, and options files, this is where user created mods are located. Editing files directly in the game install folder (ex C:\Program Files (x86)\Slitherine\Field of Glory Empires) is NOT recommended, doing so may prevent multiplayer games from working correctly and interfere with game updates.

Before you begin modding, you may wish to open the USER.TXT file in your user folder and the following line to enable additional debugging tools:
<nowiki>DEBUGMODE 1</nowiki>

See [[Empires Version]] for additional topics.

== Create a Scenario ==

Empires currently only support mods by the creation of a new, modified scenario. The quickest way to create a new scenario and get started modding is to copy an existing scenario. For example, to start with the grand campaign, browse to the Scenarios folder in your game install folder (ex. C:\Program Files (x86)\Slitherine\Field of Glory Empires\Scenarios). Copy the d310BCGrandCampaign folder into the SCENARIOS folder of your user folder (ex Documents\My Games\FieldOfGloryEmpires\SCENARIOS). Rename the pasted folder to something new (it is recommended the new folder name not contain spaces). You should also make sure this new folder and its contents are not Read-Only. Inside this folder, you should see a number of files:
<nowiki>MYSCENARIO
│ SCENARIO.BSF
│ TEXT1.TXT
│ TEXT1_FRE.TXT
│ TEXT1_GER.TXT
│ TEXT1_SPA.TXT
│ SCENARIO.TXT
├───DATA
│ │ SETUP.csv
│ │ SETUP_FACTIONS.csv
│ │ REGIONS.csv
│ │ SETUP_GROUPS.csv
│ └───SCRIPTS
│ Events_Plugin.BSF</nowiki>
A good place to start would be to open TEXT1.TXT in a text editor. Here you can give your mod a unique name, description, and starting message. See [[Modding#Custom_Text]] for details on modifying string files in the Archon engine. TEXT1_FRE.TXT, TEXT1_GER.TXT, and TEXT1_SPA.TXT contain the translations of the strings in TEXT1.TXT. If you do not plan to translate your mod into other languages, you should just remove these three files and the strings entered in TEXT1.TXT will be used for all languages.

SCENARIO.BSF is another place you can make some quick edits to you scenario. Refer to [[Scripting]] for a description of the Archon scripting language. The InitScenario function near the beginning of this file sets up a number of parameters for your scenario, try changing gTurnInfos.dateFirstTurn to adjust the starting date for your mod.

If you start the game and select Scenarios, your modified scenario should now appear near the bottom of the list and be selectable for play.

== Changing the Scenario Setup ==

Three files of particular interest when changing the setup of the scenario are found in the DATA folder - SETUP.csv, SETUP_FACTIONS.csv, and REGIONS.csv. These files are semi-colon separated CSVs and can be opened and edited in most spreadsheet software (ex Excel, OpenOffice), be sure to save them in the same format.

=== SETUP_FACTIONS.CSV ===

This file defines which factions are available in your scenario.

Coming soon...

=== REGIONS.CSV ===

This file specifies the basic properties of each region on the map.
* Alias: This is used as a reference to this region elsewhere. It is not recommended that you change this column, as it is used to associate this region with an area in the map used by this scenario.
* Name: This is a reference to the name used for this region. To edit the name, do not change the reference itself, but create a new entry with this id in the TEXT1.TXT file you edited above.
* Terrain: This is the terrain type of this region. For a list of valid terrain types, see DATA\TERRAINS.CSV, although some terrain types are not valid to assign directly to a region. Note that the reference must begin with $. This is generally the case when referring to an Alias from another CSV.
* Res[0], Res[1], Res[2], Res[3]: These are the natural resources present in the region. For a list of possible resources, see DATA\RESOURCES.CSV.
* Disabled: This controls which regions defined in the map are included in the scenario.
* Faction: This is the faction which initially owns this region (see SETUP_FACTIONS.CSV)
* CitizensID[0], CitizensAmount[0]: CitizensID[0] is the ethnicity of a the citizens to add, see DATA\ETHNICS.CSV for a list of possible ethnicities. CitizensAmount[0] is the number of citizens of the given ethnicity to add. Citizens will initially be distributed among the four possible jobs. To add citizens of multiple ethnicities, use CitizensID[1-3] and CitizensAmount[1-3].
* SlavesID[0], SlavesAmount[0]: add slaves to the region, similar to citizens above, although they will only be initially assigned to Agriculture or Infrastructure.
* City_Name: This is a reference to the name of the city in this region. As with the region name, you can override the name by adding a new entry to your TEXT1.TXT file.

=== SETUP.CSV ===

This file defines the initial placement of structures and groups (armies and navies) in your scenario.

Coming soon...

== Adding Units ==

Before starting, if your custom scenario doesn't already contain these files, copy them from the game install folder (as above, do not edit them directly in your game installation):
* DATA\UNITS.CSV
* DATA\UNITVISUALS.CSV
* DATA\FACTIONS.CSV

To add a new unit, start by adding a new row to your UNITS.CSV, or copying the row describing a similar unit. You must fill in these fields:
* ID - This must be a unique number greater than zero, start with something well beyond the range of values in the standard unit list to avoid conflicts later, ex 10000.
* Alias - This must be a unique and descriptive string starting with "ID_UNI_" that you will use to identify this unit later in other data files.
* Name - This is a reference to the name used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_NAME_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.
* Text - This is a reference to the description used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_TEXT_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.

To complete your new unit, or if you are simply modifying an existing unit, also set these fields:
* FOG2_Name - This is the type of unit this will be exported as when a battle is exported to Field of Glory 2. This must match a value in the Name column of Field of Glory II\Data\Squads.csv, or copy a value from a similar unit if you are unsure.
* FOG2_QualityMOD - When exported to Field of Glory 2, this is the base quality of a unit relative to the type given above, as a percentage. Set this to 100 if you are unsure.
* AGEOD_Cost - When exported to Field of Glory 2, this is used in the calculation of how many units are created in FOG2 for each Empires unit.
* Family - The category of this unit, possibly values are: $famInfantry, $famHvyInfantry, $famArcher, $famSkirmisher, $famLtCavalry, $famSkirmisherCavalry, $famCavalry, $famHvyCavalry, $famHvyBeast, $famSiege, $famLtWarship, $famWarship, $famHvyWarship, $famTransport
* EvolveFamily - If non-zero - if this unit becomes obsolete it can be replaced by another unit with the same value, or another unit with the same value becomes obsolete it can be replaced by this unit.
* EvolvePriority - If an EvolveFamily is set, it is used to pick the best unit to evolve an obsolete unit to.
* UpdgradeNext - Used in Event/Decision driven unit upgrades.
* MoveSpeed - The movement speed of the unit.
* Hits - The maximum number of Hits of the unit.
* Effectiveness - The maximum Effectiveness value of the unit.
* Attack - The base Attack value of the unit.
* Defense - The base Defense value of the unit.
* IsSupport - Does the unit behave as a support unit in combat.
* DistanceToCenter - Low values will cause a unit to be deployed near the center of combat, high values will deploy the unit near the flanks.
* AssaultDistanceToCenter - As DistanceToCenter, but used during assaults.
* Siege - The Siege value of the unit.
* SiegeResist - The Siege Resist value of the unit.
* SupplyUsage - The amount of supply consumed by the unit per turn (1 food typically provides 5 supply, before bonuses and penalties).
* AttackingRange - During the ranged attack phase of combat, can the unit target the opponent front line (0), support line (1), or reserves (2).
* RangedAttack - The Ranged Attack score of the unit, or 0 for units without a ranged attack.
* RangedDefense - The Ranged Defense score of the unit.
* RangedMaxDamages - The limit of Effectiveness damage done by the unit during the ranged attack phase.
* FlankingModifier - A bonus used when calculating flanking or pursuit damage inflicted by this unit.
* Modifier[0 - 3] - Modifiers for this unit, a reference to a row in DATA\MODIFIERS.CSV.
* NotBuildable - If set to 1, this unit will not be recruitable normally (ex. units that only appear in garrisons).
* BuildPointsCost, ManpowerCost, MoneyCost, MetalCost - Equipment, Manpower, Money and Metal costs to recruit.
* ManpowerUpkeep, MoneyUpkeep, MetalUpkeep - Manpower, Money, and Metal maintenance costs.
* MoneyInflationCost - The increase in Money cost per unit of this type.
* ShipyardNeed - The level of shipyard needed in a region to recruit the unit.
* Recruit_Weight - A weight given to this unit when doing randomized unit recruitment.
* RecruitArea - Optionally limits recruitment of this unit to a specific group or regions, a reference to a row in DATA\AREAS.CSV
* RequiredStructures - If a structure or | separated list of structures is given, the unit can only be recruited in regions where at least one of the structures is present. The structures are references to rows in DATA\STRUCTURES.CSV
* NationalUnique - If non-zero, a faction cannot recruit the unit if it already has one.
* ProgRate - The experience points required to reach Experience Level 1.
* InitialXPLevel - The base initial Experience Level for this unit.
* Garrison_Category - For units which can be recruited as automatic garrisons, this must correspond to one of the Garrison_Category entries of the structure which provides the garrison, in DATA\STRUCTURES.CSV.

Next, in your UNITVISUALS.CSV, you will need to have an entry for added units. Each unit type must have at least one 'garment' specified:
* Unit - A reference to the Alias of the unit in UNITS.CSV.
* Garment - Allows the same type of unit to have different appearances in different factions. This value is either $GARMENT_DEFAULT if it is the default appearance, or a match to the Garment entry for a faction in DATA\FACTIONS.CSV.
* Asset - Specifies the 3D model used for this unit, this is a reference to a row in DATA\SQUADS.CSV (note this is not prefixed with a $ as most references are). Typically, this corresponds to a model in DATA\ASSETS\UNITS in S4F format which is a proprietary Slitherine model and animation format.
* TextureSet - Used to control which color and pattern variation to use for this unit. Unit models typically have multiple sets of possible textures, you can preview these by viewing the 'diffuse' textures in DATA\ASSETS\UNITS. Texture set 0 is found in the root of that folder. Other texture sets are found in the texture# subfolders.
* TextureVariant - Within each texture set are up to 4 variants (cavalry and other complex units may only have 2 or 1 variants per set). 0 is the top left variant, 1 is the top right, 2 is the bottom left, and 3 is the bottom right. For example, TextureSet 1, Texture Variant 3 of the african_spearmen, uses the lower right quadrant of DATA\ASSETS\UNITS\texture1\African_Spearman_Diffuse.dds when drawing the unit.

Finally, new units will need to be added to the pool of factions that they are available to. In your FACTIONS.CSV, update:
* UnitsAge1 - a | separated list of unit references for units available to the faction in the lowest category of government (Horde, Tyranny, Kingdom, Oligarchy, or Sect).
* UnitsAge2 - a | separated list of unit references for units available to the faction in the second category of government (Tribe, City State, Monarchy, Republic, or Hierocracy).
* UnitsAge3 - a | separated list of unit references for units available to the faction in the third category of government (Confederation, Commonwealth, Empire, Federation, or Theocracy).

You should now be able to start your scenario and have your new or modified units available.

=== Advanced ===

If an existing modifier doesn't suit your unit, you can create a new modifier by copying MODIFIERS.CSV from the DATA folder of the game installation to the DATA folder of your custom scenario. Then add a new modifier following the pattern of the existing modifiers. You can now refer to this new modifier from your unit.

Modifiers refer to effects to apply statistical bonuses or penalties. These effects are defined in DATA/EFFECTS.CSV, so as above you can create a new effect by copying the shared EFFECTS.CSV to your scenario's DATA folder and creating a new effect.

Many unit effects only apply in specific terrain categories (indicated if the effect terrains column is 1). In that case, the modifier will specify the terrains as the fourth parameter associated with that effect, using a combination of 1: Open, 2: Forest, 4: Arid, 8: Rough, 16: Swampy, 32: Assault, 64: Coastal Water, 128: Open Water, 256: Steppe, 512: Mountainous. For example:

ID_MOD_UNIT_MOUNTAINMEN has multiple effects, effectID[0] is $MOD_EFFECT_MOVE_BONUS, which is means the first effect is a movement speed bonus. params0[3] is 520, which is 512 + 8, indicating that this bonus applies in Mountainous and Rough terrain. Referring to the terrain categories in DATA/TERRAINS.CSV, we see that the Mountainous category includes both Mountain and Alpine terrain types, and the Rough category includes Hills and Arid Hills.

If you wish to create your own 'skin' for an existing unit model, you can add a new texture set for the unit by using an existing texture set as a template and following the naming of the texture exactly (although you may use a TGA file with the .tga extension instead of a DDS file) in the correct location for the next texture set within your scenario. For example, the Hoplite_vet_arm model uses the Hoplite_Vet_Diffuse.dds texture. The highest numbered texture set defined in the game is DATA\ASSETS\UNITS\Hoplite_Vet_Diffuse.dds, texture set 5. If you create a new texture set and place it within your scenario at DATA\ASSETS\UNITS\texture6\Hoplite_Vet_Arm_Diffuse.tga, you can then refer to Asset Hoplite_Vet_Arm and TextureSet 6 in UNITVISUALS.CSV and it will use your new texture set. If specular and normal maps aren't provided for a texture set, the versions from set 0 for that model will be used.

If you have a new 3D model in the S4F format, you will need to add a row in a copy of DATA/SQUADS.CSV that refers to that model before you can use it in your UNITVISUALS.CSV.

== Adding Structures ==

Coming soon...

== Adding Events ==

If you copied an existing scenario as above, your scenario should already contain a DATA\SCRIPTS\Events_Plugin.BSF containing one function, Event_EntryPoint(). Standard Empires events are found the Data\scripts\Events.BSF in the game installation folder. You may refer to the events in this file as a reference when creating events.

At the bottom of Events_Plugin, create a new function for your event, this function will be called at the end of each turn and will determine if the event should occur, what factions are affected, and apply the gameplay effects of the event. By convention, the function name should start with EventCustom_ followed by a descriptive name for the event. Once you have written your event function, add a call to it in the Event_EntryPoint function at the top of your Events_Plugin.

For example, if you want to create an event that will give 100 metal once during the scenario to each faction with a 1% chance each turn, your file should like this:

<nowiki>FUNCTION Event_EntryPoint()
{
EventCustom_MetalStrike();
}

//// METAL STRIKE ////

// turn to start checking for the event (0 based)
#define EVTCUSTOM_METALSTRIKE_TURNSTART 1

// % chance per turn per faction
#define EVTCUSTOM_METALSTRIKE_CHANCE 1

// amount of resource given
#define EVTCUSTOM_METALSTRIKE_AMOUNT 100

// record of which factions have received the event
int EvtCustom_MetalStrike[FACTION_MAX];

FUNCTION EventCustom_MetalStrike()
{
int facCount;
int facIndex;
int factionID;

if (GetTurn() >= EVTCUSTOM_METALSTRIKE_TURNSTART)
{
// iterate over all factions
facCount = GetNumFactions();
for (facIndex = 0; facIndex < facCount; facIndex++)
{
// has this faction already received this event (by index)
if (EvtCustom_MetalStrike[facIndex] == FALSE)
{
// get the ID of this function
factionID = GetFactionID(facIndex);

// only applies to active factions, excluding independents
if (Faction_IsWorldFactionOrInactive(factionID) == FALSE)
{
// has a chance to get a metal strike this turn
if (Dice(100) <= EVTCUSTOM_METALSTRIKE_CHANCE)
{
// add the metal to the faction's stockpile
Faction_AddResource(factionID, gResourceMetal, EVTCUSTOM_METALSTRIKE_AMOUNT);

// send a message to the receiving faction
Message_Faction_ChangeResourcePrivate(factionID, Faction_Politic_SeatOfPower(factionID), EVTCUSTOM_METALSTRIKE_AMOUNT, MSG_IMP_TOP, "IDS_MSG_EVENT_METAL_STRIKE");

// remember that this faction has already had a metal strike
EvtCustom_MetalStrike[facIndex] = TRUE;
}
}
}
}
}
}</nowiki>

You will also need to add the string to display for this event to your scenario's TEXT1.TXT file:

<nowiki>IDS_MSG_EVENT_METAL_STRIKE, "Prospectors discover metal deposits in %{1}u totalling %{0}u metal.",</nowiki>

== Advanced Modding ==

Many files not specifically covered elsewhere can still be overridden in a modified scenario. Generally, if a file is found anywhere in the Data folder of the game installation, you can place a modified version of that file in the same relative location of the DATA folder of your modified scenario and your scenario will use that instead.

== The Editor ==

Empires contains a rudimentary editor for modifying or creating BAM files, which control the map. If you have started by copying the Grand Campaign, your scenario will be set up to load the shared Empires map, Data\Maps\AEP.BAM in the game install folder. If you open your scenario in the editor, changes you make will be saved to Data\Maps\AEP.BAM within your custom scenario. Note, you currently need to create an empty Maps folder within the Data folder of your scenario before you save the first time.

If you have enabled DebugMode above, when you open the Options screen from the Main Menu the will be an Editor button at the top of the screen. This editor has a small number of useful features. Select your scenario when prompted and click OK.

Please note that there is no Undo feature in the Editor and saving and backing up frequently is strongly recommended if you are making multiple edits.

=== Region Mode ===

The default editor mode is Region Mode. When you left click on the map to select a region, it will be highlighted in red and details will be displayed in the Region Properties panel on the right.

The top section of Region Properties specifies which row in REGIONS.CSV corresponds to the selected region on the map. Generally you will not need to change this unless you are creating a new map from scratch.

The second section lists a number of properties of the region. They cannot be edited here, they are specified by REGIONS.CSV or other setup files described above.

The third section is used to edit the connections between this region and its neighbors. On the map, the connections to the selected region are visualized with colored arrows.

If you right click on a region that is already connected to the current selection, it will be highlighted in purple and the Region Properties panel will update to let you Disconnect that region or change the connection 'terrain'. Although all terrains are offered, the relevant choices are:
* Strait - for crossing between nearby land regions without transporting through the water region which separates them
* Big River Crossing - indicates regions are separated by a large river
* River Crossing - indicates regions are separated by a smaller river
* Land Interdiction - prevents land units from moving between regions when the rules would otherwise allow it
* Naval Interdiction - prevents naval units from moving between regions when the rules would otherwise allow it
* No Cost - standard connection, there is no extra cost or limitation for moving between regions

See TERRAINS.CSV for the exact costs associated with the different connection types.

If you right click on a region that is not connected to the current region, it will be highlighted in green and you will be able to Connect it from the Region Properties panel and then set the connection terrain.

The bottom section of the Region Properties panel describes the anchor points defined for the selected region. Anchor points are used to set the locations of many dynamic objects during the game. The default anchor assignment is:
* 0: city
* 1: harbor
* 2: allied or neutral army
* 3: external wonder, 3d notifications, visual effects
* 4: second external wonder, second visual effect
* 5: icon
* 6: volcano
* 7: player army
* 8: overlay text
* 9: enemy army

The anchor locations are displayed for the current region as either a yellow triangle, or another 3D model that indicates its use. To move an anchor, first select it either by clicking on its representation on the map or selecting it from the list. Then drag and drop it to the desired location.

=== Border Mode ===

The Border Mode contains a number of rudimentary tools for creating or modifying the boundaries of a region. The border mode has a palette of four tools, which perform a variety of related operations depending on the context, button, and key modifiers. The exact functionality is described on the left of the editor when you select the different tools.

=== Unit Mode ===

Unit Mode allows you to visualize initial armies created during scenario initialization as described above. You may select an army to view its details. The armies are not edited here, this is done in [[Empires_Modding#SETUP.CSV]]

=== Scenario Properties ===

This mode lists miscellaneous read only information about the scenario, determined by the setup files.

=== Advanced ===

In some cases, the map file could have a different name. The SCENARIO.TXT file at the root of your scenario contains a line specifying the name of the BAM file.

See [[Empires_Terrain#Creating_a_Scenario]] for information on creating a new map using the editor.

== Sharing Mods ==

As mods are self-contained scenarios, you can share a mod simply by packing and distributing your custom scenario's subfolder from your user folder, which is then placed on the equivalent location in another player's user folder.

Empires also supports the CPF and LST files in the same format as some previous Slitherine games to make installation easier for other players. To create a CPF file, select Editor, select the scenario to package from the list of custom scenarios, and then press the Create Campaign Package File (CPF) button. The CPF will be saved to your user SCENARIOS folder.

See http://www.slitherinebravo.net/GameWiki/doku.php?id=mod_older_hot#share_unofficial_user_scenarios_on_any_platform for more information.

Empires Modding

2019-07-09T22:36:54Z

Andrewg:

= Modding Guide =

== Getting Started ==

Empires saves user files in your Documents\My Games\FieldOfGloryEmpires folder, which will be referred to as your 'user' folder. In addition to saved games, logs, and options files, this is where user created mods are located. Editing files directly in the game install folder (ex C:\Program Files (x86)\Slitherine\Field of Glory Empires) is NOT recommended, doing so may prevent multiplayer games from working correctly and interfere with game updates.

Before you begin modding, you may wish to open the USER.TXT file in your user folder and the following line to enable additional debugging tools:
<nowiki>DEBUGMODE 1</nowiki>

See [[Empires Version]] for additional topics.

== Create a Scenario ==

Empires currently only support mods by the creation of a new, modified scenario. The quickest way to create a new scenario and get started modding is to copy an existing scenario. For example, to start with the grand campaign, browse to the Scenarios folder in your game install folder (ex. C:\Program Files (x86)\Slitherine\Field of Glory Empires\Scenarios). Copy the d310BCGrandCampaign folder into the SCENARIOS folder of your user folder (ex Documents\My Games\FieldOfGloryEmpires\SCENARIOS). Rename the pasted folder to something new (it is recommended the new folder name not contain spaces). You should also make sure this new folder and its contents are not Read-Only. Inside this folder, you should see a number of files:
<nowiki>MYSCENARIO
│ SCENARIO.BSF
│ TEXT1.TXT
│ TEXT1_FRE.TXT
│ TEXT1_GER.TXT
│ TEXT1_SPA.TXT
│ SCENARIO.TXT
├───DATA
│ │ SETUP.csv
│ │ SETUP_FACTIONS.csv
│ │ REGIONS.csv
│ │ SETUP_GROUPS.csv
│ └───SCRIPTS
│ Events_Plugin.BSF</nowiki>
A good place to start would be to open TEXT1.TXT in a text editor. Here you can give your mod a unique name, description, and starting message. See [[Modding#Custom_Text]] for details on modifying string files in the Archon engine. TEXT1_FRE.TXT, TEXT1_GER.TXT, and TEXT1_SPA.TXT contain the translations of the strings in TEXT1.TXT. If you do not plan to translate your mod into other languages, you should just remove these three files and the strings entered in TEXT1.TXT will be used for all languages.

SCENARIO.BSF is another place you can make some quick edits to you scenario. Refer to [[Scripting]] for a description of the Archon scripting language. The InitScenario function near the beginning of this file sets up a number of parameters for your scenario, try changing gTurnInfos.dateFirstTurn to adjust the starting date for your mod.

If you start the game and select Scenarios, your modified scenario should now appear near the bottom of the list and be selectable for play.

== Changing the Scenario Setup ==

Three files of particular interest when changing the setup of the scenario are found in the DATA folder - SETUP.csv, SETUP_FACTIONS.csv, and REGIONS.csv. These files are semi-colon separated CSVs and can be opened and edited in most spreadsheet software (ex Excel, OpenOffice), be sure to save them in the same format.

=== SETUP_FACTIONS.CSV ===

This file defines which factions are available in your scenario.

Coming soon...

=== REGIONS.CSV ===

This file specifies the basic properties of each region on the map.
* Alias: This is used as a reference to this region elsewhere. It is not recommended that you change this column, as it is used to associate this region with an area in the map used by this scenario.
* Name: This is a reference to the name used for this region. To edit the name, do not change the reference itself, but create a new entry with this id in the TEXT1.TXT file you edited above.
* Terrain: This is the terrain type of this region. For a list of valid terrain types, see DATA\TERRAINS.CSV, although some terrain types are not valid to assign directly to a region. Note that the reference must begin with $. This is generally the case when referring to an Alias from another CSV.
* Res[0], Res[1], Res[2], Res[3]: These are the natural resources present in the region. For a list of possible resources, see DATA\RESOURCES.CSV.
* Disabled: This controls which regions defined in the map are included in the scenario.
* Faction: This is the faction which initially owns this region (see SETUP_FACTIONS.CSV)
* CitizensID[0], CitizensAmount[0]: CitizensID[0] is the ethnicity of a the citizens to add, see DATA\ETHNICS.CSV for a list of possible ethnicities. CitizensAmount[0] is the number of citizens of the given ethnicity to add. Citizens will initially be distributed among the four possible jobs. To add citizens of multiple ethnicities, use CitizensID[1-3] and CitizensAmount[1-3].
* SlavesID[0], SlavesAmount[0]: add slaves to the region, similar to citizens above, although they will only be initially assigned to Agriculture or Infrastructure.
* City_Name: This is a reference to the name of the city in this region. As with the region name, you can override the name by adding a new entry to your TEXT1.TXT file.

=== SETUP.CSV ===

This file defines the initial placement of structures and groups (armies and navies) in your scenario.

Coming soon...

== Adding Units ==

Before starting, if your custom scenario doesn't already contain these files, copy them from the game install folder (as above, do not edit them directly in your game installation):
* DATA\UNITS.CSV
* DATA\UNITVISUALS.CSV
* DATA\FACTIONS.CSV

To add a new unit, start by adding a new row to your UNITS.CSV, or copying the row describing a similar unit. You must fill in these fields:
* ID - This must be a unique number greater than zero, start with something well beyond the range of values in the standard unit list to avoid conflicts later, ex 10000.
* Alias - This must be a unique and descriptive string starting with "ID_UNI_" that you will use to identify this unit later in other data files.
* Name - This is a reference to the name used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_NAME_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.
* Text - This is a reference to the description used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_TEXT_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.

To complete your new unit, or if you are simply modifying an existing unit, also set these fields:
* FOG2_Name - This is the type of unit this will be exported as when a battle is exported to Field of Glory 2. This must match a value in the Name column of Field of Glory II\Data\Squads.csv, or copy a value from a similar unit if you are unsure.
* FOG2_QualityMOD - When exported to Field of Glory 2, this is the base quality of a unit relative to the type given above, as a percentage. Set this to 100 if you are unsure.
* AGEOD_Cost - When exported to Field of Glory 2, this is used in the calculation of how many units are created in FOG2 for each Empires unit.
* Family - The category of this unit, possibly values are: $famInfantry, $famHvyInfantry, $famArcher, $famSkirmisher, $famLtCavalry, $famSkirmisherCavalry, $famCavalry, $famHvyCavalry, $famHvyBeast, $famSiege, $famLtWarship, $famWarship, $famHvyWarship, $famTransport
* EvolveFamily - If non-zero - if this unit becomes obsolete it can be replaced by another unit with the same value, or another unit with the same value becomes obsolete it can be replaced by this unit.
* EvolvePriority - If an EvolveFamily is set, it is used to pick the best unit to evolve an obsolete unit to.
* UpdgradeNext - Used in Event/Decision driven unit upgrades.
* MoveSpeed - The movement speed of the unit.
* Hits - The maximum number of Hits of the unit.
* Effectiveness - The maximum Effectiveness value of the unit.
* Attack - The base Attack value of the unit.
* Defense - The base Defense value of the unit.
* IsSupport - Does the unit behave as a support unit in combat.
* DistanceToCenter - Low values will cause a unit to be deployed near the center of combat, high values will deploy the unit near the flanks.
* AssaultDistanceToCenter - As DistanceToCenter, but used during assaults.
* Siege - The Siege value of the unit.
* SiegeResist - The Siege Resist value of the unit.
* SupplyUsage - The amount of supply consumed by the unit per turn (1 food typically provides 5 supply, before bonuses and penalties).
* AttackingRange - During the ranged attack phase of combat, can the unit target the opponent front line (0), support line (1), or reserves (2).
* RangedAttack - The Ranged Attack score of the unit, or 0 for units without a ranged attack.
* RangedDefense - The Ranged Defense score of the unit.
* RangedMaxDamages - The limit of Effectiveness damage done by the unit during the ranged attack phase.
* FlankingModifier - A bonus used when calculating flanking or pursuit damage inflicted by this unit.
* Modifier[0 - 3] - Modifiers for this unit, a reference to a row in DATA\MODIFIERS.CSV.
* NotBuildable - If set to 1, this unit will not be recruitable normally (ex. units that only appear in garrisons).
* BuildPointsCost, ManpowerCost, MoneyCost, MetalCost - Equipment, Manpower, Money and Metal costs to recruit.
* ManpowerUpkeep, MoneyUpkeep, MetalUpkeep - Manpower, Money, and Metal maintenance costs.
* MoneyInflationCost - The increase in Money cost per unit of this type.
* ShipyardNeed - The level of shipyard needed in a region to recruit the unit.
* Recruit_Weight - A weight given to this unit when doing randomized unit recruitment.
* RecruitArea - Optionally limits recruitment of this unit to a specific group or regions, a reference to a row in DATA\AREAS.CSV
* RequiredStructures - If a structure or | separated list of structures is given, the unit can only be recruited in regions where at least one of the structures is present. The structures are references to rows in DATA\STRUCTURES.CSV
* NationalUnique - If non-zero, a faction cannot recruit the unit if it already has one.
* ProgRate - The experience points required to reach Experience Level 1.
* InitialXPLevel - The base initial Experience Level for this unit.
* Garrison_Category - For units which can be recruited as automatic garrisons, this must correspond to one of the Garrison_Category entries of the structure which provides the garrison, in DATA\STRUCTURES.CSV.

Next, in your UNITVISUALS.CSV, you will need to have an entry for added units. Each unit type must have at least one 'garment' specified:
* Unit - A reference to the Alias of the unit in UNITS.CSV.
* Garment - Allows the same type of unit to have different appearances in different factions. This value is either $GARMENT_DEFAULT if it is the default appearance, or a match to the Garment entry for a faction in DATA\FACTIONS.CSV.
* Asset - Specifies the 3D model used for this unit, this is a reference to a row in DATA\SQUADS.CSV (note this is not prefixed with a $ as most references are). Typically, this corresponds to a model in DATA\ASSETS\UNITS in S4F format which is a proprietary Slitherine model and animation format.
* TextureSet - Used to control which color and pattern variation to use for this unit. Unit models typically have multiple sets of possible textures, you can preview these by viewing the 'diffuse' textures in DATA\ASSETS\UNITS. Texture set 0 is found in the root of that folder. Other texture sets are found in the texture# subfolders.
* TextureVariant - Within each texture set are up to 4 variants (cavalry and other complex units may only have 2 or 1 variants per set). 0 is the top left variant, 1 is the top right, 2 is the bottom left, and 3 is the bottom right. For example, TextureSet 1, Texture Variant 3 of the african_spearmen, uses the lower right quadrant of DATA\ASSETS\UNITS\texture1\African_Spearman_Diffuse.dds when drawing the unit.

Finally, new units will need to be added to the pool of factions that they are available to. In your FACTIONS.CSV, update:
* UnitsAge1 - a | separated list of unit references for units available to the faction in the lowest category of government (Horde, Tyranny, Kingdom, Oligarchy, or Sect).
* UnitsAge2 - a | separated list of unit references for units available to the faction in the second category of government (Tribe, City State, Monarchy, Republic, or Hierocracy).
* UnitsAge3 - a | separated list of unit references for units available to the faction in the third category of government (Confederation, Commonwealth, Empire, Federation, or Theocracy).

You should now be able to start your scenario and have your new or modified units available.

=== Advanced ===

If an existing modifier doesn't suit your unit, you can create a new modifier by copying MODIFIERS.CSV from the DATA folder of the game installation to the DATA folder of your custom scenario. Then add a new modifier following the pattern of the existing modifiers. You can now refer to this new modifier from your unit.

Modifiers refer to effects to apply statistical bonuses or penalties. These effects are defined in DATA/EFFECTS.CSV, so as above you can create a new effect by copying the shared EFFECTS.CSV to your scenario's DATA folder and creating a new effect.

Many unit effects only apply in specific terrain categories (indicated if the effect terrains column is 1). In that case, the modifier will specify the terrains as the fourth parameter associated with that effect, using a combination of 1: Open, 2: Forest, 4: Arid, 8: Rough, 16: Swampy, 32: Assault, 64: Coastal Water, 128: Open Water, 256: Steppe, 512: Mountainous. For example:

ID_MOD_UNIT_MOUNTAINMEN has multiple effects, effectID[0] is $MOD_EFFECT_MOVE_BONUS, which is means the first effect is a movement speed bonus. params0[3] is 520, which is 512 + 8, indicating that this bonus applies in Mountainous and Rough terrain. Referring to the terrain categories in DATA/TERRAINS.CSV, we see that the Mountainous category includes both Mountain and Alpine terrain types, and the Rough category includes Hills and Arid Hills.

If you wish to create your own 'skin' for an existing unit model, you can add a new texture set for the unit by using an existing texture set as a template and following the naming of the texture exactly (although you may use a TGA file with the .tga extension instead of a DDS file) in the correct location for the next texture set within your scenario. For example, the Hoplite_vet_arm model uses the Hoplite_Vet_Diffuse.dds texture. The highest numbered texture set defined in the game is DATA\ASSETS\UNITS\Hoplite_Vet_Diffuse.dds, texture set 5. If you create a new texture set and place it within your scenario at DATA\ASSETS\UNITS\texture6\Hoplite_Vet_Arm_Diffuse.tga, you can then refer to Asset Hoplite_Vet_Arm and TextureSet 6 in UNITVISUALS.CSV and it will use your new texture set. If specular and normal maps aren't provided for a texture set, the versions from set 0 for that model will be used.

If you have a new 3D model in the S4F format, you will need to add a row in a copy of DATA/SQUADS.CSV that refers to that model before you can use it in your UNITVISUALS.CSV.

== Adding Structures ==

Coming soon...

== Adding Events ==

If you copied an existing scenario as above, your scenario should already contain a DATA\SCRIPTS\Events_Plugin.BSF containing one function, Event_EntryPoint(). Standard Empires events are found the Data\scripts\Events.BSF in the game installation folder. You may refer to the events in this file as a reference when creating events.

At the bottom of Events_Plugin, create a new function for your event, this function will be called at the end of each turn and will determine if the event should occur, what factions are affected, and apply the gameplay effects of the event. By convention, the function name should start with EventCustom_ followed by a descriptive name for the event. Once you have written your event function, add a call to it in the Event_EntryPoint function at the top of your Events_Plugin.

For example, if you want to create an event that will give 100 metal once during the scenario to each faction with a 1% chance each turn, your file should like this:

<nowiki>FUNCTION Event_EntryPoint()
{
EventCustom_MetalStrike();
}

//// METAL STRIKE ////

// turn to start checking for the event (0 based)
#define EVTCUSTOM_METALSTRIKE_TURNSTART 1

// % chance per turn per faction
#define EVTCUSTOM_METALSTRIKE_CHANCE 1

// amount of resource given
#define EVTCUSTOM_METALSTRIKE_AMOUNT 100

// record of which factions have received the event
int EvtCustom_MetalStrike[FACTION_MAX];

FUNCTION EventCustom_MetalStrike()
{
int facCount;
int facIndex;
int factionID;

if (GetTurn() >= EVTCUSTOM_METALSTRIKE_TURNSTART)
{
// iterate over all factions
facCount = GetNumFactions();
for (facIndex = 0; facIndex < facCount; facIndex++)
{
// has this faction already received this event (by index)
if (EvtCustom_MetalStrike[facIndex] == FALSE)
{
// get the ID of this function
factionID = GetFactionID(facIndex);

// only applies to active factions, excluding independents
if (Faction_IsWorldFactionOrInactive(factionID) == FALSE)
{
// has a chance to get a metal strike this turn
if (Dice(100) <= EVTCUSTOM_METALSTRIKE_CHANCE)
{
// add the metal to the faction's stockpile
Faction_AddResource(factionID, gResourceMetal, EVTCUSTOM_METALSTRIKE_AMOUNT);

// send a message to the receiving faction
Message_Faction_ChangeResourcePrivate(factionID, Faction_Politic_SeatOfPower(factionID), EVTCUSTOM_METALSTRIKE_AMOUNT, MSG_IMP_TOP, "IDS_MSG_EVENT_METAL_STRIKE");

// remember that this faction has already had a metal strike
EvtCustom_MetalStrike[facIndex] = TRUE;
}
}
}
}
}
}</nowiki>

You will also need to add the string to display for this event to your scenario's TEXT1.TXT file:

<nowiki>IDS_MSG_EVENT_METAL_STRIKE, "Prospectors discover metal deposits in %{1}u totalling %{0}u metal.",</nowiki>

== Advanced Modding ==

Many files not specifically covered elsewhere can still be overridden in a modified scenario. Generally, if a file is found anywhere in the Data folder of the game installation, you can place a modified version of that file in the same relative location of the DATA folder of your modified scenario and your scenario will use that instead.

== The Editor ==

See [[Empires Terrain]] to get started with the editor.

More coming soon...

== Sharing Mods ==

As mods are self-contained scenarios, you can share a mod simply by packing and distributing your custom scenario's subfolder from your user folder, which is then placed on the equivalent location in another player's user folder.

Empires also supports the CPF and LST files in the same format as some previous Slitherine games to make installation easier for other players. To create a CPF file, select Editor, select the scenario to package from the list of custom scenarios, and then press the Create Campaign Package File (CPF) button. The CPF will be saved to your user SCENARIOS folder.

See http://www.slitherinebravo.net/GameWiki/doku.php?id=mod_older_hot#share_unofficial_user_scenarios_on_any_platform for more information.

Empires Modding

2019-07-08T21:03:03Z

Andrewg:

Empires Version

2019-07-08T21:00:47Z

Andrewg:

* [[Empires Modding]]
* [[Empires Scripting]]
* [[Empires Callbacks]]
* [[Empires BattleBoard]]
* [[Empires Terrain]]
* [[Empires Hotkeys]]

AEP Modding

2019-07-08T21:00:24Z

Andrewg: Andrewg moved page AEP Modding to Empires Modding

#REDIRECT [[Empires Modding]]

Empires Modding

2019-07-08T21:00:23Z

Andrewg: Andrewg moved page AEP Modding to Empires Modding

Empires Version

2019-07-08T20:59:46Z

Andrewg:

* [[AEP Modding]]
* [[Empires Scripting]]
* [[Empires Callbacks]]
* [[Empires BattleBoard]]
* [[Empires Terrain]]
* [[Empires Hotkeys]]

AEP Hotkeys

2019-07-08T20:59:26Z

Andrewg: Andrewg moved page AEP Hotkeys to Empires Hotkeys

#REDIRECT [[Empires Hotkeys]]

Empires Hotkeys

2019-07-08T20:59:25Z

Andrewg: Andrewg moved page AEP Hotkeys to Empires Hotkeys

* Shift+F11 - open script debugger
* Shift+F12 - toggle object inspector
* F - cycle through terrain display modes (normal, hide FOW effect, hide weather effect, hide both)
* Ctrl+Shift+I - rerun the AI for the current turn
* Shift+Home - toggle script profiler
* Shift+End - reset script profiler
* Ctrl+F11 - reload shaders, edit and continue supported
* Ctrl+F12 - reload scripts, edit and continue supported
* Ctrl+Home - reload textures which have changes since loading
* Ctrl+End - reload UI and string files
* PrtScn - take a screenshot (saved in My Games\FieldOfGloryEmpires\SCREENS)
* Ctrl+Shift+P - start or stop recording a video (slideshow)

Many dev hotkeys require debug mode to be active

See Key Mapping in the game Options UI for more keys.

Empires Hotkeys

2019-07-08T20:59:14Z

Andrewg:

Empires Terrain

2019-07-08T20:56:28Z

Andrewg:

= Empires Map and Terrain =

== Creating a Scenario ==
To create a new scenario, click Editor from Options Screen and then the quill (Create a brand new campaign) button from the scenario selection screen. Enter the scenario folder name and display name for the scenario.

To use an existing map for this scenario, click Use map: <New Map> and choose a [[#BAM|BAM]] file.

To create a new map, specify the following:
* [[#Map_Image|Map Image]]
* [[#Height_Map_Image|Height Map Image]]
* Height Scale - a multiplier applied to the height map values
* Logical Map Width - this is how large the map will appear to be in game, it is independent of the resolution of the map textures
* Logical Map Height - may be set smaller than the width to create a non-square map, the upper portion of the map textures will be used
* Import Borders from SVG (Advanced) - optionally specify an SVG file that contains border polygons to create initial borders. Note: SVG importing ONLY supports a list of polygons indicating a list of bordered regions. There are many other ways a map could be constructed and saved in an SVG that will not be imported, if you are planning to use SVG importing, be sure that your software and approach results in this particular format.

If you have not imported borders, or wish to edit borders, choose Border mode from the upper left palette in the editor and follow the directions below the palette.

Before a map can be played, you will also need to associate the bordered regions with entries in an existing Regions.CSV file located in the Data folder in either the current scenario folder or the game folder. Switch to the Region mode from the palette. When you select a region, the Region Properties panel will be displayed. To associate the region to a row in the table, select the row by name from the Template list. You may also need to add or remove connections between regions to allow movement on the map (importing an SVG automatically creates connections between regions which share two or more consecutive border points). This is also edited in the Region mode under Connections in the Region Properties panel. The anchor points within a region can also be edited, the meanings of the anchors are specified by script and can be used to indicate city location, army locations, etc.

The Unit mode and Scenario Properties modes of the editor are read-only modes displaying properties set by other CSV or script files.

== Files ==

Unless otherwise specified, all map related files are located in either the Data/Maps folder within the current scenario folder (highest priority) or in the Data/Maps folder of the game folder (in which case they may be shared by multiple scenarios).

=== SCENARIO.TXT ===
Each scenario requires a SCENARIO.TXT file in its root folder. This file contains an entry which specifies which [[#BAM|BAM]] file to use as the map for the scenario. It is created automatically when a scenario is created in the editor, and may be edited manually if required.

=== BAM ===
The BAM file contains the map data. It is created automatically by the editor. Some fields in the [MAP] chunk of the file corresponding to the new map settings in [[#Creating_a_Scenario|Scenario Creation]] may be safely edited by hand. Otherwise, the editor will normally be used to edit this file.

=== Map Image ===
The map image is the base texture for the map and may be in any supported image format. The RGB channels of this texture determine the color of the terrain (land and water). If the [[#Detail_Map|terrain detail shader]] is used, the alpha channel is used to indicate which regions of the map are treated as land and which are treated as water. Alpha 0 is water, alpha max is land. If a smoother transition is required, providing intermediate alpha values will fade out water or terrain detail effects.

=== Height Map Image ===
The height map image is used to determine the height values for the terrain. It may be either a 32 bit TGA file (height is taken from the blue channel) or a RAW file.

=== Normal Map ===
Optional. Normal map applied over the entire map. The filename is based on the map image filename <map_image>_N.ext. It may be in any supported image format.

=== Detail Map ===
Optional, requires a normal and specular map. A map of the [[#Detail_Textures|terrain detail textures]] to be applied over the entire map. The filename is based on the map image filename <map_image>_D.ext. It may be in any supported image format (although good results may require an uncompressed format). The red channel of the texture is used to indicate which of 8 detail textures to use.
* detail0: Red values 0 to 17 / 255
* detail1: Red values 18 to 53 / 255
* detail2: Red values 54 to 91 / 255
* detail3: Red values 92 to 127 / 255
* detail4: Red values 128 to 163 / 255
* detail5: Red values 164 to 201 / 255
* detail6: Red values 202 to 237 / 255
* detail7: Red values 238 to 255 / 255

For best results and performance, detail0 - detail3 should be exactly the same resolution and detail4 - detail7 should be exactly the same resolution.

=== Detail Textures ===
Optional. Detail textures blended with the [[#Map_Image|global map image]] and [[#Normal_Map|global normal map]] to provide additional terrain detail at high zoom levels without requiring a massive map images. They are named detail0.tga to detail7.tga and detail0_N.tga to detail7_N.tga. Only tga format is supported. The detail textures are treated as greyscale images (only the red channel is used) and are tiled over the map image based on the [[#Detail_Map|detail map texture]] on land areas of the map.

=== Alternate Weather Image ===
Optional. An alternate weather texture substituted for the [[#Map_Image|global map image]] based on gameplay values. The filename is based on the map image filename <map_image>_Weather.ext.

=== CAMPAIGNVIEW.TXT ===
This file is located one level higher, in the shared or scenario Data folder. Refer to Data/CAMPAIGNVIEW.TXT in the game installation for reference. It allows several cosmetic changes to how the map is presented:
* ZOOM: default camera zoom distance
* ZOOMINLIMIT: closest camera zoom distance
* ZOOMLIMIT: farthest camera zoom distance
* CAMERAPITCH: camera pitch at the default zoom distance
* CAMERAPITCHMIN: camera pitch at the closest zoom distance
* CAMERAPITCHMAX: camera pitch at the farthest zoom distance, overrides CAMERAOVERHEAD
* CAMERAOVERHEAD: zoom distance to set the camera to be looking straight down, if CAMERAPITCHMAX is NOT specified
* FARPLANE: max draw distance
* CLEARCOLOUR: clear color in hex behind the map
* TERRAINSHADOW: non-0 to enable shadows cast by the terrain (useful if the Map Image doesn't contain prebaked shadows)
* TERRAINSHINE: glossiness of the map (0 to 1)
* OVERLAYWEIGHT: the strength of the map overlays (0 to 1)
* BANNERSCALE: the scale of the army banners on the map
* BANNEROFFSET: the distance (x and y) of the army banners from the army model
* BARRERSTEP: the distance (x and y) between banners at the same anchor point
* WORLDLIGHT: controls an ambient light (AMBIENT) and directional light (DIRECTION and COLOUR) for the map
* CLOUD#: controls a layer of cloud shown over the map
** COUNT: the number of clouds
** MIN_HEIGHT: the bottom of the cloud layer
** MAX_HEIGHT: the top of the cloud layer
** SIZE: average size of each cloud
** SPEED: average rotation speed of each cloud
** VARIATION: amount of variation between clouds (0 to 1)
** UNIFORM: if 0, the clouds are more dense near the edges of the map
** TEXTURE: the texture containing the cloud images
** ATLAS_SIZE: the number of images in TEXTURE to select from, vertically and horizontally (ie 2 means TEXTURE is a 2 x 2 atlas)
* DECORATION#: specifies the name file (FILE), size (SIZE), position (ANCHOR), and spin speed and direction (SPIN) of the 'decorations' shown on the map using SetRegionDecoration (ex objective markers)
* ROADS
** ANCHOR: which anchor point within the regions the road network goes through
** SIZE: the width of the roads in the road network overlay
** REQUIRED_TRANSPORT: the minimum TRANSPORT level in a pair of connected regions required to draw a road in the network overlay
* CITIES
** ANCHOR: which anchor point within the regions the city is drawn at
** SIZE: the scale for the city models

== Slicing ==
Experimental. To support very high resolution textures, the Map Image, Normal Map, Specular Map, and Height Map Images may be sliced into multiple tiles. The naming of these files is based on the untiled filename. The top-left corner has the same name as the untiled filename, the remaining files have the x and y coordinates appended with _x_y. For example, if the BAM specifies a map image texture of "map.dds", the 2x2 tiled versions are:
* map.dds: top left (0,0)
* map_0_1.dds: lower left (0,1)
* map_1_0.dds: upper right (1,0)
* map_1_1.dds: lower right (1,1)

If slicing is used, Map Image, Normal Map, Specular Map, and Alternate Weather Image must all use the same number of tiles. Height Map Image tiling is independent.

Empires Version

2019-07-08T20:55:45Z

Andrewg:

* [[AEP Modding]]
* [[Empires Scripting]]
* [[Empires Callbacks]]
* [[Empires BattleBoard]]
* [[Empires Terrain]]
* [[AEP Hotkeys]]

AEP Terrain

2019-07-08T20:55:24Z

Andrewg: Andrewg moved page AEP Terrain to Empires Terrain

#REDIRECT [[Empires Terrain]]

Empires Terrain

2019-07-08T20:55:23Z

Andrewg: Andrewg moved page AEP Terrain to Empires Terrain

= AEP Map and Terrain =

== Creating a Scenario ==
To create a new scenario, click Editor from Options Screen and then the quill (Create a brand new campaign) button from the scenario selection screen. Enter the scenario folder name and display name for the scenario.

To use an existing map for this scenario, click Use map: <New Map> and choose a [[#BAM|BAM]] file.

To create a new map, specify the following:
* [[#Map_Image|Map Image]]
* [[#Height_Map_Image|Height Map Image]]
* Height Scale - a multiplier applied to the height map values
* Logical Map Width - this is how large the map will appear to be in game, it is independent of the resolution of the map textures
* Logical Map Height - may be set smaller than the width to create a non-square map, the upper portion of the map textures will be used
* Import Borders from SVG (Advanced) - optionally specify an SVG file that contains border polygons to create initial borders. Note: SVG importing ONLY supports a list of polygons indicating a list of bordered regions. There are many other ways a map could be constructed and saved in an SVG that will not be imported, if you are planning to use SVG importing, be sure that your software and approach results in this particular format.

If you have not imported borders, or wish to edit borders, choose Border mode from the upper left palette in the editor and follow the directions below the palette.

Before a map can be played, you will also need to associate the bordered regions with entries in an existing Regions.CSV file located in the Data folder in either the current scenario folder or the game folder. Switch to the Region mode from the palette. When you select a region, the Region Properties panel will be displayed. To associate the region to a row in the table, select the row by name from the Template list. You may also need to add or remove connections between regions to allow movement on the map (importing an SVG automatically creates connections between regions which share two or more consecutive border points). This is also edited in the Region mode under Connections in the Region Properties panel. The anchor points within a region can also be edited, the meanings of the anchors are specified by script and can be used to indicate city location, army locations, etc.

The Unit mode and Scenario Properties modes of the editor are read-only modes displaying properties set by other CSV or script files.

== Files ==

Unless otherwise specified, all map related files are located in either the Data/Maps folder within the current scenario folder (highest priority) or in the Data/Maps folder of the game folder (in which case they may be shared by multiple scenarios).

=== SCENARIO.TXT ===
Each scenario requires a SCENARIO.TXT file in its root folder. This file contains an entry which specifies which [[#BAM|BAM]] file to use as the map for the scenario. It is created automatically when a scenario is created in the editor, and may be edited manually if required.

=== BAM ===
The BAM file contains the map data. It is created automatically by the editor. Some fields in the [MAP] chunk of the file corresponding to the new map settings in [[#Creating_a_Scenario|Scenario Creation]] may be safely edited by hand. Otherwise, the editor will normally be used to edit this file.

=== Map Image ===
The map image is the base texture for the map and may be in any supported image format. The RGB channels of this texture determine the color of the terrain (land and water). If the [[#Detail_Map|terrain detail shader]] is used, the alpha channel is used to indicate which regions of the map are treated as land and which are treated as water. Alpha 0 is water, alpha max is land. If a smoother transition is required, providing intermediate alpha values will fade out water or terrain detail effects.

=== Height Map Image ===
The height map image is used to determine the height values for the terrain. It may be either a 32 bit TGA file (height is taken from the blue channel) or a RAW file.

=== Normal Map ===
Optional. Normal map applied over the entire map. The filename is based on the map image filename <map_image>_N.ext. It may be in any supported image format.

=== Detail Map ===
Optional, requires a normal and specular map. A map of the [[#Detail_Textures|terrain detail textures]] to be applied over the entire map. The filename is based on the map image filename <map_image>_D.ext. It may be in any supported image format (although good results may require an uncompressed format). The red channel of the texture is used to indicate which of 8 detail textures to use.
* detail0: Red values 0 to 17 / 255
* detail1: Red values 18 to 53 / 255
* detail2: Red values 54 to 91 / 255
* detail3: Red values 92 to 127 / 255
* detail4: Red values 128 to 163 / 255
* detail5: Red values 164 to 201 / 255
* detail6: Red values 202 to 237 / 255
* detail7: Red values 238 to 255 / 255

For best results and performance, detail0 - detail3 should be exactly the same resolution and detail4 - detail7 should be exactly the same resolution.

=== Detail Textures ===
Optional. Detail textures blended with the [[#Map_Image|global map image]] and [[#Normal_Map|global normal map]] to provide additional terrain detail at high zoom levels without requiring a massive map images. They are named detail0.tga to detail7.tga and detail0_N.tga to detail7_N.tga. Only tga format is supported. The detail textures are treated as greyscale images (only the red channel is used) and are tiled over the map image based on the [[#Detail_Map|detail map texture]] on land areas of the map.

=== Alternate Weather Image ===
Optional. An alternate weather texture substituted for the [[#Map_Image|global map image]] based on gameplay values. The filename is based on the map image filename <map_image>_Weather.ext.

=== CAMPAIGNVIEW.TXT ===
This file is located one level higher, in the shared or scenario Data folder. Refer to Data/CAMPAIGNVIEW.TXT in the game installation for reference. It allows several cosmetic changes to how the map is presented:
* ZOOM: default camera zoom distance
* ZOOMINLIMIT: closest camera zoom distance
* ZOOMLIMIT: farthest camera zoom distance
* CAMERAPITCH: camera pitch at the default zoom distance
* CAMERAPITCHMIN: camera pitch at the closest zoom distance
* CAMERAPITCHMAX: camera pitch at the farthest zoom distance, overrides CAMERAOVERHEAD
* CAMERAOVERHEAD: zoom distance to set the camera to be looking straight down, if CAMERAPITCHMAX is NOT specified
* FARPLANE: max draw distance
* CLEARCOLOUR: clear color in hex behind the map
* TERRAINSHADOW: non-0 to enable shadows cast by the terrain (useful if the Map Image doesn't contain prebaked shadows)
* TERRAINSHINE: glossiness of the map (0 to 1)
* OVERLAYWEIGHT: the strength of the map overlays (0 to 1)
* BANNERSCALE: the scale of the army banners on the map
* BANNEROFFSET: the distance (x and y) of the army banners from the army model
* BARRERSTEP: the distance (x and y) between banners at the same anchor point
* WORLDLIGHT: controls an ambient light (AMBIENT) and directional light (DIRECTION and COLOUR) for the map
* CLOUD#: controls a layer of cloud shown over the map
** COUNT: the number of clouds
** MIN_HEIGHT: the bottom of the cloud layer
** MAX_HEIGHT: the top of the cloud layer
** SIZE: average size of each cloud
** SPEED: average rotation speed of each cloud
** VARIATION: amount of variation between clouds (0 to 1)
** UNIFORM: if 0, the clouds are more dense near the edges of the map
** TEXTURE: the texture containing the cloud images
** ATLAS_SIZE: the number of images in TEXTURE to select from, vertically and horizontally (ie 2 means TEXTURE is a 2 x 2 atlas)
* DECORATION#: specifies the name file (FILE), size (SIZE), position (ANCHOR), and spin speed and direction (SPIN) of the 'decorations' shown on the map using SetRegionDecoration (ex objective markers)
* ROADS
** ANCHOR: which anchor point within the regions the road network goes through
** SIZE: the width of the roads in the road network overlay
** REQUIRED_TRANSPORT: the minimum TRANSPORT level in a pair of connected regions required to draw a road in the network overlay
* CITIES
** ANCHOR: which anchor point within the regions the city is drawn at
** SIZE: the scale for the city models

== Slicing ==
Experimental. To support very high resolution textures, the Map Image, Normal Map, Specular Map, and Height Map Images may be sliced into multiple tiles. The naming of these files is based on the untiled filename. The top-left corner has the same name as the untiled filename, the remaining files have the x and y coordinates appended with _x_y. For example, if the BAM specifies a map image texture of "map.dds", the 2x2 tiled versions are:
* map.dds: top left (0,0)
* map_0_1.dds: lower left (0,1)
* map_1_0.dds: upper right (1,0)
* map_1_1.dds: lower right (1,1)

If slicing is used, Map Image, Normal Map, Specular Map, and Alternate Weather Image must all use the same number of tiles. Height Map Image tiling is independent.

Empires Terrain

2019-07-08T20:55:10Z

Andrewg:

Empires Version

2019-07-08T20:10:20Z

Andrewg:

* [[Empires Scripting]]
* [[Empires Callbacks]]
* [[Empires BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP Modding]]

BattleBoard

2019-07-08T20:09:58Z

Andrewg: Andrewg moved page BattleBoard to Empires BattleBoard

#REDIRECT [[Empires BattleBoard]]

Empires BattleBoard

2019-07-08T20:09:57Z

Andrewg: Andrewg moved page BattleBoard to 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:

<nowiki>[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
</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)
* 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.

Empires Version

2019-07-08T20:07:54Z

Andrewg:

* [[Empires Scripting]]
* [[Empires Callbacks]]
* [[BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP Modding]]

AEP Callbacks

2019-07-08T20:07:32Z

Andrewg: Andrewg moved page AEP Callbacks to Empires Callbacks

#REDIRECT [[Empires Callbacks]]

Empires Callbacks

2019-07-08T20:07:31Z

Andrewg: Andrewg moved page AEP Callbacks to Empires Callbacks

== Map.bsf callbacks ==

=== InitMap ===
Called when a new game is started. Also called each time the scenario is opened in the editor.

=== InitFinal ===
Called when a new game is started, immediately after InitScenario.

=== StartMap(flags) ===
Called each time the scenario is opened (new game, loading a saved game, loading the scenario in the editor).

Under some circumstances, StartMap can be called again during a play session, for example when a snapshot or replay state from an older play session is loaded. Bit 0 of the flags parameter will be set when this is the case, although generally the game should respond the same way.

=== StartTurn ===
Called at the beginning of the planning phase of each turn.

=== EndTurn ===
Called at the end of the resolution phase of each turn. Happens during the TurnResolveComplete command.

=== UpdateMap(tick) ===
Called each frame. If the tick parameter is 0, it means that this is an 'extra' frame because the game is rendering faster than its 'logical' framerate (30 fps). Things that should happen at a constant speed (such turn resolution) should only happen if tick is 1, things that should happen as fast as possible (such as UI handling) should happen regardless of tick. In practice, there should be very few places you need to look at the tick parameter.

=== UpdateAI(faction) ===
Called for each AI controlled faction until it returns a non-zero value. It is expected to run a small slice AI planning each call. Called after UpdateScenario. AI factions which have the INACTIVE attribute set to non-zero will be skipped.

=== RenderMap ===
Called each frame after all of the update callbacks. Primarily used for drawing UI elements over the map

=== StartGroupVisuals(id) ===
Expected to set up the visuals for a group (including call SetGroupAsset). Called at various points during game flow (expect it to be called multiple times as needed for the same group). Must not modify gameplay values for object.

=== StartStructureVisuals(id) ===
Expected to set up the visuals for a structure (including call SetStructureAsset). Called at various points during game flow (expect it to be called multiple times as needed for the same structure). Must not modify gameplay values for object.

=== PathfindingData(region, group, ...) ===
Request for connection info for a group leaving a region. For each region the group can enter from the requested region, the script must call SetPathfindingData.

=== UI_UPDATE_GROUP(groupID, zoom, mouseX, mouseY, buttons) ===
Called once per frame for each group visible on the map to update the UIGroup layout for the current frame. zoom is the height of the camera above the ground. Return <= 0 if there is nothing to be drawn. If the mouse is over any visible component of the UI, GetMouseGroup will return that group ID as it would if the mouse was over the group's on-map 3d object. The root of the UI is automatically placed to draw immediately below the base of the group's on-map 3d object.

== Scenario.bsf callbacks ==

=== InitScenario ===
Called when a new game is started, immediately after InitMap.

=== StartScenario(flags) ===
Called each time the scenario is opened (new game, loading a saved game), immediately after StartMap. The flags parameter has the same meaning as in StartMap.

=== StartTurn ===
Call each turn, immediately after Map.bsf StartTurn

=== EndTurn ===
Called each turn, immediately before Map.bsf EndTurn. Happens during the TurnResolveComplete command.

=== UpdateScenario ===
Called each frame, immediately after UpdateMap

=== RenderScenario ===
Called each frame after, immediately after RenderMap

== Callback sequence ==

=== New Game Example ===

# InitMap
# InitScenario
# InitFinal
# StartMap
# StartScenario
# StartRegionVisuals x N
# StartGroupVisuals x N
# show PreScenario UI (single player)
## UpdateMap
## UpdateScenario
## repeat until script calls StartScenario command
# StartTurn in Map.bsf
# StartTurn in Scenario.bsf
# UpdateMap
# UpdateScenario
# RenderMap
# RenderScenario
# UpdateMap
# ...
# UpdateMap
# UpdateScenario
# UpdateAI
# ...
# EndTurn in Scenario.bsf
# EndTurn in Map.bsf
# StartTurn in Map.bsf
# StartTurn in Scenario.bsf
# UpdateMap
# ...

=== Loading Saved Game Example ===

# StartMap
# StartScenario
# StartStructureVisuals x X
# StartGroupVisuals x X
# UpdateMap
# UpdateScenario
# RenderMap
# RenderScenario
# UpdateMap
# ...

Empires Callbacks

2019-07-08T20:07:18Z

Andrewg:

Empires Version

2019-07-08T20:04:13Z

Andrewg:

* [[Empires Scripting]]
* [[AEP Callbacks]]
* [[BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP Modding]]

AEP Scripting

2019-07-08T20:03:41Z

Andrewg: Andrewg moved page AEP Scripting to Empires Scripting

#REDIRECT [[Empires Scripting]]

Empires Scripting

2019-07-08T20:03:41Z

Andrewg: Andrewg moved page AEP Scripting to Empires Scripting

See the general [[Scripting]] page for a description of the Archon scripting language. See My Games\FieldOfGloryEmpires\AUTODOCS\BATTLESCRIPT.TXT for definitive script command descriptions relevant to Empires.

Also output to the AUTODOCS folder is ARCHON.XML, a language definition compatible with Notepad++ (note that if the language definition is updated, the defined language must be removed and re-imported into Np++, it will not reload it automatically).

== Pathfinding ==

=== GetRoute ===

The main entry point is GetRoute(startRegion, destRegion, workArray, groupID, ...). It returns the total cost of the route and the route itself is stored in the temporary work array. The steps in the route are accessed using GetArray(step). For example to get the route from current to destination into the array route:

int route[32];
int i;
cost = GetRoute(current, destination, 0, group);
if (cost >= 0)
{
for (i = 0; i < 32; i++)
{
route[i] = GetArray(i);
if (route[i] == -1)
{
i = 32; // done
}
}
}

Internally, there are a number of callbacks during pathfinding so that the costs can be dynamically determined by scripts. The sequence is something like this:

/- GetRoute(startRegion, targetRegion, workArray, groupID, ...) BATTLESCRIPT command
| / | \
| v v v
| PathfindingData(region, neighbour, groupID, ...) Map.BSF function
| |
| v
| SetPathfindingData(region, neighbour, cost, [speed]) BATTLESCRIPT command
|
\-> GetRoute returns total cost

PathfindingData is a function implemented in Map.BSF that tells the engine the cost of moving from one region to its neighbour them. Simple calculations based on region and group properties can be used to determine the cost. PathfindingData calls SetPathfindingData to return the cost and, optionally the speed used to take the step, if it is valid in the situation. The base connection graph is determined internally based on the $REGION_CONNECTIONS attribute and assuming that legal movement costs are always > 0. It is possible to pass additional parameters to the PathfindingData callback by adding more parameters to the function, and then padding them as additional parameters to GetRoute after the groupID.

Internally, data is cached so that if you make consecutive calls to GetRoute for the same startRegion and groupID within the same frame, the result will be found much faster. A loop with one group evaluating N destinations will be much faster than N groups evaluating one destination.

If non-zero speeds are provided to SetPathfindingData, the engine will include the calculation of unused movement points not carried over between turns in the cost. The speed expected is the speed used if a turn starts in 'region', pathfinding internally will determine whether to use that speed or continue with the previous speed.

There is an alternate version of the command, GetRouteWithLimit, that takes a maximum cost which can be more efficient when long routes are not of interest.

=== GetRouteEx ===

GetRouteEx is a more advanced way to access pathfinding, GetRouteEx(sourceRegion, destRegion, [dynArrayHandle], [maxCost], [callback], [data...]).

The primary difference is that the name of the callback function can be provided to GetRouteEx. The first parameter to the callback function will always be the region ID that data is requested for, all additional integer parameters will be passed through from the GetRouteExcall to the callback. Also, it uses a dynamic array for results (you can pass a dynamic array handle of 0 to get the cost of the route if you do not require the route itself). Finally, it take a maximum cost like GetRouteWithLimit (or <= 0 if cost is unlimited).

For example, to get the optimal path from startID to destID up to a cost of 12 using the same callback as GetRoute uses:
handle = CreateDyamicArray();
GetRouteEx(startID, destID, 12, handle, "PathfindingData", groupID);
...
DestroyDynamicArray(handle);

To use a callback that uses different criteria or a different calculation, define another callback function:
FUNCTION PathfindingDataByKind(regionID, neighbourID, kind, faction)
{
int cost;

cost = myCost(neighbourID, kind, faction);
SetPathfindingData(regionID, neighbourID, cost);
}
And then provide the name and expected parameters to the search:
GetRouteEx(startID, destID, 12, handle, "PathfindingDataByKind", kind, factionID);

If the callback name and parameters are omitted, the search will be done without script callbacks based on the Connections attribute of the regions with a fixed cost of 1 for each step.

=== GetRegionsInRange ===

Pathfinding can also be used to find a list of regions in range of another. The entry point for this is GetRegionsInRange(sourceRegion, maxCost, dynArrayHandle, [callback], [data...]).

The parameters have the same meaning as in GetRouteEx. For example, to get all regions within a cost of 12 of startID using the same callback as GetRoute uses:
handle = CreateDyamicArray();
GetRegionsInRange(startID, 12, handle, "PathfindingData", groupID);
...
DestroyDynamicArray(handle);

Empires Scripting

2019-07-08T20:03:17Z

Andrewg:

Empires Scripting

2019-07-08T18:43:52Z

Andrewg:

See the general [[Scripting]] page for a description of the Archon scripting language. See My Games\FieldOfGloryEmpires\AUTODOCS\BATTLESCRIPT.TXT for definitive script command descriptions relevant to Empires.

Also output to the AUTODOCS folder is ARCHON.XML, a language definition compatible with Notepad++ (note that if the language definition is updated, the defined language must be removed and re-imported into Np++, it will not reload it automatically).

== Pathfinding ==

=== GetRoute ===

The main entry point is GetRoute(startRegion, destRegion, workArray, groupID, ...). It returns the total cost of the route and the route itself is stored in the temporary work array. The steps in the route are accessed using GetArray(step). For example to get the route from current to destination into the array route:

int route[32];
int i;
cost = GetRoute(current, destination, 0, group);
if (cost >= 0)
{
for (i = 0; i < 32; i++)
{
route[i] = GetArray(i);
if (route[i] == -1)
{
i = 32; // done
}
}
}

Internally, there are a number of callbacks during pathfinding so that the costs can be dynamically determined by scripts. The sequence is something like this:

/- GetRoute(startRegion, targetRegion, workArray, groupID, ...) BATTLESCRIPT command
| / | \
| v v v
| PathfindingData(region, neighbour, groupID, ...) Map.BSF function
| |
| v
| SetPathfindingData(region, neighbour, cost, [speed]) BATTLESCRIPT command
|
\-> GetRoute returns total cost

PathfindingData is a function implemented in Map.BSF that tells the engine the cost of moving from one region to its neighbour them. Simple calculations based on region and group properties can be used to determine the cost. PathfindingData calls SetPathfindingData to return the cost and, optionally the speed used to take the step, if it is valid in the situation. The base connection graph is determined internally based on the $REGION_CONNECTIONS attribute and assuming that legal movement costs are always > 0. It is possible to pass additional parameters to the PathfindingData callback by adding more parameters to the function, and then padding them as additional parameters to GetRoute after the groupID.

Internally, data is cached so that if you make consecutive calls to GetRoute for the same startRegion and groupID within the same frame, the result will be found much faster. A loop with one group evaluating N destinations will be much faster than N groups evaluating one destination.

If non-zero speeds are provided to SetPathfindingData, the engine will include the calculation of unused movement points not carried over between turns in the cost. The speed expected is the speed used if a turn starts in 'region', pathfinding internally will determine whether to use that speed or continue with the previous speed.

There is an alternate version of the command, GetRouteWithLimit, that takes a maximum cost which can be more efficient when long routes are not of interest.

=== GetRouteEx ===

=== GetRegionsInRange ===

Pathfinding can also be used to find a list of regions in range of another. The entry point for this is GetRegionsInRange(sourceRegion, maxCost, dynArrayHandle, [callback], [data...]).

Similar to GetRoute, evaluating a GetRegionsInRange request will result in a number of calls to a callback function which must call SetPathfindingData to provide costs to the engine. The difference is that the name of the callback function can be provided to GetRegionsInRange. The first parameter to the callback function will always be the region ID that data is requested for, all additional integer parameters will be passed through from the GetRegionsInRange call to the callback.

For example, to get all regions within a cost of 12 of startID using the same callback as GetRoute uses:
handle = CreateDyamicArray();
GetRegionsInRange(startID, 12, handle, "PathfindingData", groupID);
...
DestroyDynamicArray(handle);

To use a callback that uses different criteria or a different calculation, define another callback function:
FUNCTION PathfindingDataByKind(regionID, neighbourID, kind, faction)
{
int cost;

cost = myCost(neighbourID, kind, faction);
SetPathfindingData(regionID, neighbourID, cost);
}
And then provide the name and expected parameters to the search:
GetRegionsInRange(startID, 12, handle, "PathfindingDataByKind", kind, factionID);

If the callback name and parameters are omitted, the search will be done without script callbacks based on the Connections attribute of the regions with a fixed cost of 1 for each step.

Flavour Specific Documentation

2019-07-08T18:37:10Z

Andrewg:

[[Tile Turn Based Version]]

[[Hex Turn Based Version|Steel Tigers Version]]

[[Empires Version]]

[[RTS Version]]

AEP Version

2019-07-08T18:36:35Z

Andrewg: Andrewg moved page AEP Version to Empires Version

#REDIRECT [[Empires Version]]

Empires Version

2019-07-08T18:36:35Z

Andrewg: Andrewg moved page AEP Version to Empires Version

* [[AEP Scripting]]
* [[AEP Callbacks]]
* [[BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP Modding]]

Empires Modding

2019-06-10T17:57:20Z

Andrewg: /* Sharing Mods */

Empires Modding

2019-06-10T17:56:54Z

Andrewg:

Empires Modding

2019-06-05T23:57:39Z

Andrewg: /* Advanced */

Empires Modding

2019-06-05T22:02:43Z

Andrewg: /* Adding Units */

Empires Modding

2019-06-05T21:57:25Z

Andrewg: /* Adding Units */

Empires Modding

2019-06-05T21:14:54Z

Andrewg: /* Adding Units */

Empires Modding

2019-06-05T21:01:19Z

Andrewg: /* Adding Units */

Empires Modding

2019-06-05T20:36:53Z

Andrewg: /* Adding Units */

Empires Modding

2019-05-29T21:27:41Z

Andrewg: /* Modding Guide */

Empires Modding

2019-05-29T21:10:39Z

Andrewg: /* Changing the Scenario Setup */

Empires Modding

2019-05-29T20:03:53Z

Andrewg: /* Modding Guide */

Empires Modding

2019-05-29T20:00:41Z

Andrewg:

Empires Version

2019-05-28T23:50:10Z

Andrewg:

* [[AEP Scripting]]
* [[AEP Callbacks]]
* [[BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP Modding]]

Empires Modding

2019-05-28T20:54:51Z

Andrewg: Created page with "= Modding Guide = == Getting Started == Empires saves user files in your Documents\My Games\FieldOfGloryEmpires folder, which will be referred to as your 'user' folder. In..."

Empires Version

2019-05-28T20:44:45Z

Andrewg:

* [[AEP Scripting]]
* [[AEP Callbacks]]
* [[BattleBoard]]
* [[AEP Terrain]]
* [[AEP Hotkeys]]
* [[AEP_Modding]]

UI

2019-01-23T17:42:24Z

Andrewg: Corrected documentation of BARSIZE tag, no change to engine behaviour.

== Introduction ==
UI Screens are defined in text files which define the objects and actions of UI screens. They are made up for 2 main sections, animations and objects. Animations are defined first in the file, followed by objects. Animations are not required for the correct operation of most UI screens.

You can include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. Lines must be of the form
#include "file.txt"
or
include "file.txt"
You can also add a prefix to an include line. The prefix is applied to all chunk strings in the file, as well as all PARENT entries. So an include of the form
#include "file.txt" Prefix
would cause all the chunks in the include file to be parsed as
[PrefixChunkName]
and any PARENT entries as
PARENT PrefixParentName
This allows for reuse of UI controls in multiple screens (with some careful naming).

Include files must be in the same folder as the UI file (in which case you should <b>NOT</b> use a .txt extension unless you are sure the system will not try and load the include file as a normal UI file (as would happen in CORE/UI or DATA/UI for example) or in DATA/UI/TEMPLATES. Files are searched for in this order. Also, you cannot next includes, i.e. included files cannot have #include statements in them.

== Objects ==
All objects are defined by a minimal data chunk of the form:

<nowiki>
[<objectName>]
TYPE <type>
X <x>
Y <y>
WIDTH <w>
HEIGHT <h></nowiki>

the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.

== The Parent Object ==

The first object defined in a file is assumed to be the screen parent object. Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.

The screen parent object has a number of unique tags which can be set:

<nowiki>
HANDLER <handlerName> // handler tags hook in to the code and so should be used with caution.
//In most cases you will want to keep handler values as they are already set in existing/equivalent files.
MODAL // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack.
LEVEL <level> // each screen is created at a fixed level in the screen layers. It is the order in which screens are displayed.</nowiki>

There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child. Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children. When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.

== Additional Common Tags ==
<nowiki>
DRAGGABLE <size> // denotes that an object is draggable. Size is the height of draggable top border.
FOCUS // can this object have focus (be moused over, clicked on, etc). Some objects (e.g. buttons) are always focus-able.
SFXFOCUS <id> // play the sound (based on the position in the sound list) when the object is moused over.
TOOLTIP <stringID>
ALWAYSTOOL // always display the tooltip text at the bottom of the object
ALWAYSTOOLX <offset> // x display offset for ALWAYSTOOL display
ALWAYSTOOLY <offset> // y display offset for ALWAYSTOOL display
CLIPPING //
DX <x> // horizontal position relative to parent (overrides X)
DY <y> // vertical position relative to parent (overrides Y)
PARENT <parentName> // see The Parent Object
ATTACH <tags> // attach an object to a screen edge, with an optional (unscaled) offset. See below.
SQUAREASPECT // see below</nowiki>
SQUAREASPECT tells controls to maintain their aspect, along with all their children. This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE). Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates. So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size. Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.

Attach takes a single composited string using LRTB for the left, right, top, and bottom screen edges respectively. An optional offset can be included. E.g.
ATTACH RB // attach to the bottom right of the screen
ATTACH R20B10 // attach to the bottom right, with a 20 pixel offset from the right, and 10 up from the bottom.

== Object Types ==
=== Map Display [DEPRECATED] ===
<b>This UI object is currently not supported</b>
The Map Display control allows the use of 3D heightmapped maps which can be scrolled and broken into territories. For details see the detailed documentation.
[[MapDisplayUIControl|Map Display Documentation]]

=== Core Object Types ===
==== OBJECT ====
This is a generic UI object. It is neither visible nor interactable.

==== IMAGE ====
An image object is simply a displayed texture. Valid tags are:

<nowiki>
FILE <filename> // the filename of the texture. The root path is DATA\UI\TEXTURES.

You can show just a portion of a texture by using the additional tags below:

IMAGELEFT <value>
IMAGETOP <value>
IMAGEWIDTH <value>
IMAGEHEIGHT <value>

These values are in pixels, so if the texture is resized, they will need to be re-evaluated.

ANIMSPEED <speed>
ANIMFADE <value>
COLOUR <colour> // anywhere colours are specified, they may either be ARGB hex values (ex. ffff0000) or named colours specified in the COLOURDICTIONARY chunk of DATA/UISETTINGS.TXT
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 0
BACKDROP // when the screen aspect ratio is below 21:9, the texture will be cropped horizontally (ie if a 21:9 background texture is displayed in a 1024 by 768 IMAGE object with BACKDROP, it will fill the screen and
// maintain the correct aspect ratio at all screen ratios up to 21:9, with the left and right edges of the image removed as required)
MODULATE // use a modulate blend when rendering, multiplying (darkening) the screen based on the source image colours
SLICED <pixels> <size> // use a 9-sliced setup for the image. pixels is the size in pixels of a corner slice in the texture. size is the 1024-space size of a corner in the UI Image onscreen</nowiki>

==== DISPLAY ====

A display object is a non interactive display. It draws a simple window using a window template texture.

Valid tags:
<nowiki>
FILE <filename> // texture filename

The window template is laid as as follows (generally it is assumed the texture will be 256x256). The corner 1/16ths of the texture are the corners of the window - these are drawn at 64x64. The top and bottom and left and right center halves are the frames (these are stretched to size) and then the middle of the texture is stretch to cover the remaining center of the window.

STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>

Used to display a window title when used.</nowiki>

==== BUTTON ====

Button objects are displayed using a texture file. This file must contain 4 versions of the button. These are arranged as follows:

* Normal - top left
* Moused Over - top right
* Pressed - bottom left
* Inactive (greyed) - bottom right

Valid tags:
<nowiki>
FILE <filename> // texture name
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
IMAGEU <u>
IMAGEV <v>
GROUP <group> // the number of the group this button belongs to (for use with Get/SetUIGroupSelection commands)
GROUPINDEX <groupIndex> // the index within a group for this button (for use with Get/SetUIGroupSelection commands)
SIMPLEIMAGE <0/1> // treat the FILE as a single image rather than the 4 images described above
TEXTLEFT <x> // placement values for the text within the button (absolute if object is placed absolutely, relative to self if object is placed relatively)
TEXTTOP <y>
TEXTWIDTH <w>
TEXTHEIGHT <h>
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 1
MULTILINE <0/1> // allow wrapped, multiline text on the button, default 0
CENTER <0/1> // horizontally center text on the button, default 1
VCENTER <0/1> // vertically center text on the button, default 1
HOTKEY <key> // define a key which will also trigger the button. Valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN, F1 - F12
CHECKBOX <0,1> // render this button as a checkbox. Should be paired with CHECKBOXTICK
CHECKBOXTICK <filename> // the name of the image containing the tick used when drawing a checkbox-style button
MARQUEE <0,1> // if text is too long for button, scroll horizontally over time (cannot be used with MULTILINE)</nowiki>

==== TEXT ====

A static text object used to display information to the user.

Valid tags:
<nowiki>
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
CENTER // Causes the text to be centered horizontally in the rectangle.
VCENTER // causes the text to be vertically centered in the rectangle
WINDOWEDBACK
RESCALE
RESCALEMAX <value> // Sets the maximum height for RESCALE. If used in conjunction with SCROLLING, the text object will start to Scroll when it reaches the set maximum height.
RESCALELOCK <byte value> // lock growth direction for RESCALE. 0 centered (default), 1 grow down, 2 grow up.
FILE <filename>
TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list within the main object window.
SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX)
BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified (default 16)
SCROLLBOUNCE <0/1> // bounce when scrolling to the limit of the text (default 1)</nowiki>

==== LISTBOX ====

A listbox allowing the user to scroll through and select lines.

Valid tags:
<nowiki>
CONTROLTEX <filename>
Required, contains all the various listbox controls. The texture is laid out as follows:
Up scroll arrow - top left
Down scroll arrow - top right
Scrollbar - bottom left (this is stretched to the height of the listbox)
Scroll nub - bottom right

FRAMETEX <filename> - used for the listbox frame
SELTEX <filename> - selection display, this is stretched across the width of the selection box
BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type

TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively

FONT <fontname> - the font of the listbox item text
COLOUR <colour> - the colour of the listbox item text.
BARSIZE <value> - Sets the size of the scrollbar. Default value is 1/3 the horizontal resolution of the CONTROLTEX texture.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
ITEMKEEPSQUARE - causes the scaling of ITEMSPACING and ITEMSIZE to maintain the item layout aspect ratio at non-4:3 resolutions
HORIZONTAL - causes the items to be displayed horizontally across the listbox, only the arrow elements of CONTROLTEX are used (and rotated) for left/right scrolling
MULTISELECT - allows multiselection in list with standard Ctrl and Shift click modifiers, use IsUIListboxItemSelected to test selections
AUTOSCROLL - scroll to the bottom of the list when new items are added
MAXSCROLL <value> - limit on the number of lines scrolled by the mouse wheel
TEXTMODE - mode for showing multiline text entries

MULTILINE <0/1> - allow wrapped, multiline text in listbox items, default 0 (note, this is different than a TEXTMODE listbox,
you will likely need to adjust ITEMSIZE to actually make room to display multiple lines in a single item)
CENTER <0/1> - horizontally center text on listbox items, default 0 unless a BUTTONTEX is also given
VCENTER <0/1> - vertically center text on listbox items, default 0 unless a BUTTONTEX is also given
AUTOTOOLTIP <0/1> - if an item is too wide to display in the listbox using standard drawing and no tooltip is given,
automatically show the item string as the tooltip
TABLE <headerID> - Draw the listbox as a table with a header and aligned columns. Item strings (and optionally, their tooltips) and the
string referenced by headerID are treated as tab (\t) delimited rows. Behaviour may also be activated or updated
using the SetUIListboxTable command.
LISTALIGN <alignment> - when there are not enough items to fill the visible listbox, align the items to the "CENTER" or "BOTTOM" (or
"RIGHT") of the listbox
MARQUEE <0,1> - if text is too long for item, scroll horizontally over time (cannot be used with MULTILINE)
TEXTINSET <value> - inset the item text horizontally by a given value (in addition to restrictions set by TEXTLEFT, TEXTWIDTH)
COLUMNS <value> - use more than one column in the list box. The items are displayed left to right then top to bottom. Does not work for horizontal listboxes.</nowiki>
You can also define a custom item rendering callback
FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)
which operates for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name, pass is zero prior to default rendering, and 1 after. Returning non-zero will prevent default item rendering.

In the case of wanting to block a list box selection event use
FUNCTION UI_LISTBOX_SELECTION_VALIDATE(data, event, id, name)
If the function returns 0 the select event will not be passed. Good for disabled buttons and states which shouldn't be selected with custom rendering.

==== EDITBOX ====

A single line text entry box.

Valid tags:
<nowiki>
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
Defines the display of the listbox item text.</nowiki>

==== REGIONMAP ====

A specialist control for representing a map of distinct regions.

Valid Tags
<nowiki>
FILE <texture>

The texture for the region map must be crafted in a specific way. It should be a 4 channel TGA file.
The channels in the file are used in the following way:

R - a monochrome image layer. A region is coloured with its owning sides colour modulated with this channel.
G - selected layer. The currently selected region has this layer coloured with the defined selection colour and
blended with the normal map pixels.
B - currently unused
A - region layer. The alpha value of each pixel denotes which region the pixel belongs to.
Value 255 is a special value for invalid pixels which belong to no region.

You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours. These are of the format:

SELECT <hexcolour>
COL0 <hexcolour>
COL1 <hexcolour>
...

e.g.

SELECT FFFF00
COL0 FFFFFF
COL1 FF00FF

Enhanced Graphics
You can also provide enhanced graphical files if you desire. There are two ways of doing this, which all interoperate correctly.

You can provide a single drawn image by using the tag in the global chunk

HANDDRAWN <texture>

This image is used in place of the monochrome channel from the main texture file. The alpha channel determines how the side
colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour,
and other values blending the modulated colour with the original image.

You can also provide pre-created images for each side. That is, when a side owns an area then if an image for that side
exists, the system will display that section of the drawn image with no colouration or other changes. These are
defined by the tag in the global chunk

DRAWN<N> <texture>

e.g.

DRAWN0 side0.tga

sets the texture to be shown when an area is owned by side zero.

Per-Area Data
You can also set up data for each area in their own chunk. Valid tags are:

X <x>
Y <y>
DATA <a> [<b> <c> <d>]

Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768
coordinates using the RegionMapGetX/Y functions). DATA can be used for preset data on each area to be used in the script.
There can be up to 4 data elements in the list.

NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that
this region data is NOT saved as part of a save game and so the Set function should only be used for data which
can be rebuilt when the screen is activated etc.

e.g.

[44] // chunk header should contain the index of the area
X 100
Y 300
DATA 100 4 5 // unset data is initialised to zero</nowiki>

==== VARIABLEEDIT ====

This is a control specially built to enable quick and simple editing of data stored in a script structure. The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.

The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit. The logic attempts to ensure the same layout irrespective of resolution.

Valid Tags
<nowiki>
FONT <fontname>

The commands used to set up and control a VariableEdit control are

//set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details.
VariableEditSetStruct(objectName, structName, [customFilename])

//fill the edit control with the values from the given variable. Requires the variable name string, not the variable itself.
VariableEditSetVariable(objectName, variableName)

//use the edit control to set the values of a given variable. Requires the variable name string, not the variable itself.
VariableEditGetVariable(objectName, variableName)

The custom layout file has a syntax as below

<elementName> I
<elementName> R <x> <y> <width> <height> [<editbox width>]
<elementName> C <hexColour>
<elementName> F <fontname>
<elementName> B<sizePercent>:<buttonTextureName>

The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows

type I // ignore the type element of the structure
type* I // ignore the type element and any other elements which start with type
type? I // ignore all array entries for the type element

Examples of usage are

type R 10 10 100 40
// all in 1024x768 coordinate space

type C FFFF00FF
// magenta fully opaque
type F smallFont

type B50:plain_button.tga
// rather than an edit box, have a button taking up 50% of the width of the area

By default the edit boxes are set up to only accept numeric input.</nowiki>

==== TABSET ====

Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.

Valid tags
<nowiki>
FONT <fontname>
COLOUR <hex colour>
MAXWIDTH <maximum button width>
FILE <button texture filename>

The control creates a button for each of its direct child objects. The button order is the reverse of the order the objects are defined in the UI file.

The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form

TAB_<objectname>

and this will be used.</nowiki>

==== 3DVIEW ====

Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

<nowiki>//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera. Optionally change the zoom. xyz are in 100ths
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view. 0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)

//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)

//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)

//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])</nowiki>

==== BARCHART ====

A vertical bar graph.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
BARTEX <filename> - texture for the bars of the graph (optional, otherwise will be drawn in a solid colour)
TILED <0/1> - if 1, BARTEX will be tiled vertically on the bars, otherwise it will be stretched (default 0)
COLOUR - the colour for the text and axis lines
BORDER - the colour for the text outline and bar outlines
STRING - the title of the graph
HLABEL - the label for the horizontal axis of the graph
VLABEL - the label for the vertical axis of the graph
STACKED <0/1> - if 1, multiple bars within a category will be drawn stacked vertically, otherwise they will be placed beside each other (default 0)
MAXBARWIDTH - limit on the width of bars
COLOUR0 to COLOUR9 - the colours used for bars within a category
KEY0 to KEY9 - the descriptions of the bars within a category displayed in the key (if there are multiple bars) and tooltip</nowiki>

Special commands:
<nowiki>
//add or update data to a BARCHART UI object, multiple values can be given to show multiple bars in a category, category name is taken from UI string 0
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the bar within a category of a BARCHART UI, the text description of the bar is taken from string 0
SetUIChartColours(objectName, index, colour)

//set the title, horizontal label, and vertical label for a chart
SetUIChartLabels(objectName, titleStringTag, horizLabelStringTag, vertLabelStringTag)

//sort existing data in a BARCHART UI by category. direction: 0 ascending (default), 1 descending. numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a BARCHART UI object
ClearUIChartData(objectName)</nowiki>

==== PIECHART ====

A pie chart.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
COLOUR - the colour for the text
BORDER - the colour for the text outline and slice outlines
STRING - the title of the graph
COLOUR0 to COLOUR15 - the colours used for slices (more colours can be set from script after data is added)</nowiki>

Special commands:
<nowiki>
//add or update data for a PIECHART UI object, category name is taken from UI string 0, returns the index of the slice,
//optional value# parameters not relevant to pie charts
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the slice of a PIECHART UI by index
SetUIChartColours(objectName, index, colour)

//sort existing data in a PIECHAT UI by category. direction: 0 ascending (default), 1 descending.
//numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a PIECHART UI object
ClearUIChartData(objectName)</nowiki>

== Object Commands ==

All objects can have one or more commands attached to them. Commands are inbuilt UI commands to allow for simple actions to occur. While any object can have a command attached to it, not all are able to trigger nor respond to them.

Available commands are:
<nowiki>
COMMAND ENABLE <screen>
COMMAND DISABLE <screen>
COMMAND PRESS <UIObject>
COMMAND SHOWBOX <stringID>
COMMAND CLOSEGAMEANDOPENLINK <url>
COMMAND CUSTOM <value> // send a custom value to a code-defined handler in the game
COMMAND KEY <key> // simulate a key press. Can be any alphanumeric key value, or the special TAB value for the tab key. </nowiki>

for example
<nowiki>
COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F </nowiki>

All commands are checked for validity (that is, that the objects they reference are defined) during UI system loading. Screens are defined by the name of the root objects defined in them.

Current command triggers are:

* BUTTON - commands triggered on press
* EDITBOX - commands triggered on RETURN key

== Animations ==
Animations are defined at the top of a UI file, and their chunks all start with a # symbol as shown below. An animation with the name #START will be played whenever the screen is activated. Other named animations can be triggered from scripts etc. All animation commands work on a tick-based timer which is always reset to zero when an animation is played.

<nowiki>
[#<name>]
ANIM PLACE <object> <time> <x> <y>
// place the object at the given coordinates on the given tick
ANIM MOVE <object> <time> <x> <y> <steps>
// move the object from its current position to a new set of coordinates over a given number of steps
ANIM SCROLL <object> <time> <dx> <dy> <startx> <starty> <endx> <endy> <loop>
// move an object from one point to another in steps of dx,dy. If loop is not zero then it will loop indefinitely.
ANIM BOUNCE <object> <time> <startScale> <endScale> <steps>
// cause the object to 'bounce' scale up in size and then back over time. The scales are in 1000ths, so to bounce an object without changing its size, you would use 1000 1000.
ANIM OFF <object>
// disable an screen via its parent object name. Only works on top level objects.
ANIM SFX <object> <time> <soundID> [<bank>]
// play a UI SFX at the given time. The soundID is the position in the sound list.
ANIM TIME <object> <time> <delta>
// change the 'time' for a given object. Each object can have its own flow of time, and this allows (e.g.) a single object on a screen to execute its animations over and over (if delta is <0, moving time back and allowing an object to execute its animations again.
ANIM FADE <object> <time> <startColour> <endColour> <steps>
// change the colour (including alpha) of an object over time. Colours should be defined as hex values in AARRGGBB order, e.g. FFFFFFFF for fully opaque white.
ANIM SCALE <object> <time> <startH> <startV> <endH> <endV> <steps>
// change the scale of an object over time.
ANIM ROTATE <object> <time> <startRot> <endRot> <steps> <loop>
// rotate an object over time
ANIM SHOW <object> <time> <show>
// set the visiblity of an object. show == 0 will hide the object, otherwise it will be shown </nowiki>

== Strings ==

To allow for localization, strings displayed in UIs are referenced by IDs corresponding to entries in string files, typically DATA/TEXT/TEXT#.TXT or TEXT#.TXT in the current campaign directory. Text may also be assigned to UI components at runtime by scripts.

Some formatting of strings is possible using tags embedded in strings, similar to HTML.
* <nowiki><b>bold</b></nowiki>
* <nowiki><i>italics</i></nowiki>
* <nowiki>line break: <br></nowiki>
* <nowiki><h1>heading</h1></nowiki>
* <nowiki><colour=0xffffff>colour (red)</colour></nowiki>
* <nowiki>inline image: <img=filename.tga></nowiki> If you place a # ahead of the filename it will scale the output to match the image's aspect ratio rather than being square
* <nowiki>tinted inline image: <img=filename.tga colour=0xff0000></nowiki>
* <nowiki>inline image with backdrop: <img=filename.tga|backdrop.tga></nowiki> Note the backdrop is always rendered to the same rect as the main image
* <nowiki><c>small caps string</c></nowiki>
* <nowiki><fN>another font</f></nowiki> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
* <nowiki><a>This is horizontally centered</a></nowiki> Centers the given line(s) horizontally in the text box.
* a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
* <nowiki>for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script</nowiki>

You can embed clickable links in a string by using
<nowiki><html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html></nowiki>
for a url link (which will close the game and open the link in a browser if clicked), or a custom link (which will be caught in a UI script with event==1024 and the data parameter containing the 4 digit decimal value following the = sign). Custom strings must always start with =NNNN. Display strings can be shown rather than the links by using the | seperator, link first followed by the display string. Note you can add a LINKCOLOUR entry to a text object to change the colour that a link shows as when moused over.

== UI Scripting ==
You can attach a script to any UI control using the SCRIPT tag. Events propagate up the UI object hierarchy to any attached script. Generally you will use root object level scripts for general screen logic, and child-object scripts for more specific rendering components.

The hook functions for UI scripts are:
<nowiki>FUNCTION UI_OBJ_INIT()</nowiki>
Called once when the screen is loaded.
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)</nowiki>
Called when a screen is activated (shown) by the game.
<nowiki>FUNCTION UI_OBJ_DEACTIVATE(id)</nowiki>
Called when a screen is deactivated (hidden) by the game.
<nowiki>FUNCTION UI_OBJ_RENDER(x, y, width, height, pass, name, flags)</nowiki>
Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after. Returning 9999 will prevent the default rendering of the control. flags - bit 0: pressed or selected (button only), bit 1: mouse over, bit 2: disabled, bit 3: invisible.
<nowiki>FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right.
The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).
<nowiki>FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags, data)</nowiki>
Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. data is the control-specific data value, currently only listboxes return a value (the index of the currently moused over item, -1 if none). Other control types always set this to zero.
The flags value can be one of the following values:

0 - normal per tick update
1 - the dragging object has just been dropped
<nowiki>FUNCTION UI_OBJ_EVENT(id, event, data)</nowiki>
This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.

== Tutorial Popups ==
You can set up automated, one-time tutorial messages when screens are shown, or when a control is actioned. These should be set up in DATA/TUT.TXT, with entries of the form:

<nowiki>[<object or screen name>]
POPUP <poupname> // optional, name of the screen used for the popup, defaults to TUTORIAL
STRING <string tag> // required string ID for the string to be shown (see below)
TEX <texture name> // optional texture to be applied to the popup when used (see below)
TAG <value> // optional tag value. Only show this popup when a TAG value is set in the mission chunk in the current campaign and the values match.

e.g.

[MainMenu] // this is a screen
STRING IDS_WELCOME_MESSAGE

[ScenEdUnitMode] // this is a button
POPUP MyCustomPopup
STRING IDS_EXPLAIN_UNIT_EDITING
TEX MyCustomTexture</nowiki>

The popup should have controls in it with names of the form <base>String, <base>Image, and <base>Quit - for example you will see that the default CORE/TUTORIAL.TXT file has controls TutorialString and TutorialQuit - the String and Image controls are optional, but Quit is always required and the game will throw an error if it is missing (as there would be no way to close the tutorial message). The string and texture entries from the entry are applied to the String and Image controls respectively.

You may set up a chunk for a given control or screen more than once, which will lead to them showing the first defined entry the first time it is seen/used, and the second the next time the player uses the control or enters the screen. Each time an entry is shown this state is saved (in a local TUT.INF file) to prevent the tutorial popup being shown more than once. Because of this state saving, you should always add new tutorial entries to the end of the file to avoid going out of sync with the saved data.

= UI Defaults =
Certain UI global values are set via UI settings files. The default values are in SYSTEM/UIDEFAULTS.TXT. They are listed below. Note that this file also includes any COLOURDICTIONARY chunk.

<nowiki>TOOLTIPCOLOUR // default tooltip colour
TOOLTIPOFFSETX // X offset of the tooltip from the cursor
TOOLTIPOFFSETY // Y offset of the tooltip from the cursor
TOOLTIPBORDER // width of the border around the tooltip text
TOOLTIP9SLICESIZE // 9 slice corner size in texture pixels
TOOLTIP9SLICEDRAWSIZE // draw size for 9 slice corner

UI

2018-12-13T21:01:39Z

Andrewg: /* BARCHART */

== Introduction ==
UI Screens are defined in text files which define the objects and actions of UI screens. They are made up for 2 main sections, animations and objects. Animations are defined first in the file, followed by objects. Animations are not required for the correct operation of most UI screens.

You can include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. Lines must be of the form
#include "file.txt"
or
include "file.txt"
You can also add a prefix to an include line. The prefix is applied to all chunk strings in the file, as well as all PARENT entries. So an include of the form
#include "file.txt" Prefix
would cause all the chunks in the include file to be parsed as
[PrefixChunkName]
and any PARENT entries as
PARENT PrefixParentName
This allows for reuse of UI controls in multiple screens (with some careful naming).

Include files must be in the same folder as the UI file (in which case you should <b>NOT</b> use a .txt extension unless you are sure the system will not try and load the include file as a normal UI file (as would happen in CORE/UI or DATA/UI for example) or in DATA/UI/TEMPLATES. Files are searched for in this order. Also, you cannot next includes, i.e. included files cannot have #include statements in them.

== Objects ==
All objects are defined by a minimal data chunk of the form:

<nowiki>
[<objectName>]
TYPE <type>
X <x>
Y <y>
WIDTH <w>
HEIGHT <h></nowiki>

the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.

== The Parent Object ==

The first object defined in a file is assumed to be the screen parent object. Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.

The screen parent object has a number of unique tags which can be set:

<nowiki>
HANDLER <handlerName> // handler tags hook in to the code and so should be used with caution.
//In most cases you will want to keep handler values as they are already set in existing/equivalent files.
MODAL // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack.
LEVEL <level> // each screen is created at a fixed level in the screen layers. It is the order in which screens are displayed.</nowiki>

There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child. Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children. When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.

== Additional Common Tags ==
<nowiki>
DRAGGABLE <size> // denotes that an object is draggable. Size is the height of draggable top border.
FOCUS // can this object have focus (be moused over, clicked on, etc). Some objects (e.g. buttons) are always focus-able.
SFXFOCUS <id> // play the sound (based on the position in the sound list) when the object is moused over.
TOOLTIP <stringID>
ALWAYSTOOL // always display the tooltip text at the bottom of the object
ALWAYSTOOLX <offset> // x display offset for ALWAYSTOOL display
ALWAYSTOOLY <offset> // y display offset for ALWAYSTOOL display
CLIPPING //
DX <x> // horizontal position relative to parent (overrides X)
DY <y> // vertical position relative to parent (overrides Y)
PARENT <parentName> // see The Parent Object
ATTACH <tags> // attach an object to a screen edge, with an optional (unscaled) offset. See below.
SQUAREASPECT // see below</nowiki>
SQUAREASPECT tells controls to maintain their aspect, along with all their children. This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE). Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates. So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size. Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.

Attach takes a single composited string using LRTB for the left, right, top, and bottom screen edges respectively. An optional offset can be included. E.g.
ATTACH RB // attach to the bottom right of the screen
ATTACH R20B10 // attach to the bottom right, with a 20 pixel offset from the right, and 10 up from the bottom.

== Object Types ==
=== Map Display [DEPRECATED] ===
<b>This UI object is currently not supported</b>
The Map Display control allows the use of 3D heightmapped maps which can be scrolled and broken into territories. For details see the detailed documentation.
[[MapDisplayUIControl|Map Display Documentation]]

=== Core Object Types ===
==== OBJECT ====
This is a generic UI object. It is neither visible nor interactable.

==== IMAGE ====
An image object is simply a displayed texture. Valid tags are:

<nowiki>
FILE <filename> // the filename of the texture. The root path is DATA\UI\TEXTURES.

You can show just a portion of a texture by using the additional tags below:

IMAGELEFT <value>
IMAGETOP <value>
IMAGEWIDTH <value>
IMAGEHEIGHT <value>

These values are in pixels, so if the texture is resized, they will need to be re-evaluated.

ANIMSPEED <speed>
ANIMFADE <value>
COLOUR <colour> // anywhere colours are specified, they may either be ARGB hex values (ex. ffff0000) or named colours specified in the COLOURDICTIONARY chunk of DATA/UISETTINGS.TXT
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 0
BACKDROP // when the screen aspect ratio is below 21:9, the texture will be cropped horizontally (ie if a 21:9 background texture is displayed in a 1024 by 768 IMAGE object with BACKDROP, it will fill the screen and
// maintain the correct aspect ratio at all screen ratios up to 21:9, with the left and right edges of the image removed as required)
MODULATE // use a modulate blend when rendering, multiplying (darkening) the screen based on the source image colours
SLICED <pixels> <size> // use a 9-sliced setup for the image. pixels is the size in pixels of a corner slice in the texture. size is the 1024-space size of a corner in the UI Image onscreen</nowiki>

==== DISPLAY ====

A display object is a non interactive display. It draws a simple window using a window template texture.

Valid tags:
<nowiki>
FILE <filename> // texture filename

The window template is laid as as follows (generally it is assumed the texture will be 256x256). The corner 1/16ths of the texture are the corners of the window - these are drawn at 64x64. The top and bottom and left and right center halves are the frames (these are stretched to size) and then the middle of the texture is stretch to cover the remaining center of the window.

STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>

Used to display a window title when used.</nowiki>

==== BUTTON ====

Button objects are displayed using a texture file. This file must contain 4 versions of the button. These are arranged as follows:

* Normal - top left
* Moused Over - top right
* Pressed - bottom left
* Inactive (greyed) - bottom right

Valid tags:
<nowiki>
FILE <filename> // texture name
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
IMAGEU <u>
IMAGEV <v>
GROUP <group> // the number of the group this button belongs to (for use with Get/SetUIGroupSelection commands)
GROUPINDEX <groupIndex> // the index within a group for this button (for use with Get/SetUIGroupSelection commands)
SIMPLEIMAGE <0/1> // treat the FILE as a single image rather than the 4 images described above
TEXTLEFT <x> // placement values for the text within the button (absolute if object is placed absolutely, relative to self if object is placed relatively)
TEXTTOP <y>
TEXTWIDTH <w>
TEXTHEIGHT <h>
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 1
MULTILINE <0/1> // allow wrapped, multiline text on the button, default 0
CENTER <0/1> // horizontally center text on the button, default 1
VCENTER <0/1> // vertically center text on the button, default 1
HOTKEY <key> // define a key which will also trigger the button. Valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN, F1 - F12
CHECKBOX <0,1> // render this button as a checkbox. Should be paired with CHECKBOXTICK
CHECKBOXTICK <filename> // the name of the image containing the tick used when drawing a checkbox-style button
MARQUEE <0,1> // if text is too long for button, scroll horizontally over time (cannot be used with MULTILINE)</nowiki>

==== TEXT ====

A static text object used to display information to the user.

Valid tags:
<nowiki>
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
CENTER // Causes the text to be centered horizontally in the rectangle.
VCENTER // causes the text to be vertically centered in the rectangle
WINDOWEDBACK
RESCALE
RESCALEMAX <value> // Sets the maximum height for RESCALE. If used in conjunction with SCROLLING, the text object will start to Scroll when it reaches the set maximum height.
RESCALELOCK <byte value> // lock growth direction for RESCALE. 0 centered (default), 1 grow down, 2 grow up.
FILE <filename>
TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list within the main object window.
SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX)
BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified
SCROLLBOUNCE <0/1> // bounce when scrolling to the limit of the text (default 1)</nowiki>

==== LISTBOX ====

A listbox allowing the user to scroll through and select lines.

Valid tags:
<nowiki>
CONTROLTEX <filename>
Required, contains all the various listbox controls. The texture is laid out as follows:
Up scroll arrow - top left
Down scroll arrow - top right
Scrollbar - bottom left (this is stretched to the height of the listbox)
Scroll nub - bottom right

FRAMETEX <filename> - used for the listbox frame
SELTEX <filename> - selection display, this is stretched across the width of the selection box
BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type

TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively

FONT <fontname> - the font of the listbox item text
COLOUR <colour> - the colour of the listbox item text.
BARSIZE <value> - Sets the size of the scrollbar. Default value is 32.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
ITEMKEEPSQUARE - causes the scaling of ITEMSPACING and ITEMSIZE to maintain the item layout aspect ratio at non-4:3 resolutions
HORIZONTAL - causes the items to be displayed horizontally across the listbox, only the arrow elements of CONTROLTEX are used (and rotated) for left/right scrolling
MULTISELECT - allows multiselection in list with standard Ctrl and Shift click modifiers, use IsUIListboxItemSelected to test selections
AUTOSCROLL - scroll to the bottom of the list when new items are added
MAXSCROLL <value> - limit on the number of lines scrolled by the mouse wheel
TEXTMODE - mode for showing multiline text entries

MULTILINE <0/1> - allow wrapped, multiline text in listbox items, default 0 (note, this is different than a TEXTMODE listbox,
you will likely need to adjust ITEMSIZE to actually make room to display multiple lines in a single item)
CENTER <0/1> - horizontally center text on listbox items, default 0 unless a BUTTONTEX is also given
VCENTER <0/1> - vertically center text on listbox items, default 0 unless a BUTTONTEX is also given
AUTOTOOLTIP <0/1> - if an item is too wide to display in the listbox using standard drawing and no tooltip is given,
automatically show the item string as the tooltip
TABLE <headerID> - Draw the listbox as a table with a header and aligned columns. Item strings (and optionally, their tooltips) and the
string referenced by headerID are treated as tab (\t) delimited rows. Behaviour may also be activated or updated
using the SetUIListboxTable command.
LISTALIGN <alignment> - when there are not enough items to fill the visible listbox, align the items to the "CENTER" or "BOTTOM" (or
"RIGHT") of the listbox
MARQUEE <0,1> - if text is too long for item, scroll horizontally over time (cannot be used with MULTILINE)
TEXTINSET <value> - inset the item text horizontally by a given value (in addition to restrictions set by TEXTLEFT, TEXTWIDTH)
COLUMNS <value> - use more than one column in the list box. The items are displayed left to right then top to bottom. Does not work for horizontal listboxes.</nowiki>
You can also define a custom item rendering callback
FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)
which operates for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name, pass is zero prior to default rendering, and 1 after. Returning non-zero will prevent default item rendering.

In the case of wanting to block a list box selection event use
FUNCTION UI_LISTBOX_SELECTION_VALIDATE(data, event, id, name)
If the function returns 0 the select event will not be passed. Good for disabled buttons and states which shouldn't be selected with custom rendering.

==== EDITBOX ====

A single line text entry box.

Valid tags:
<nowiki>
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
Defines the display of the listbox item text.</nowiki>

==== REGIONMAP ====

A specialist control for representing a map of distinct regions.

Valid Tags
<nowiki>
FILE <texture>

The texture for the region map must be crafted in a specific way. It should be a 4 channel TGA file.
The channels in the file are used in the following way:

R - a monochrome image layer. A region is coloured with its owning sides colour modulated with this channel.
G - selected layer. The currently selected region has this layer coloured with the defined selection colour and
blended with the normal map pixels.
B - currently unused
A - region layer. The alpha value of each pixel denotes which region the pixel belongs to.
Value 255 is a special value for invalid pixels which belong to no region.

You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours. These are of the format:

SELECT <hexcolour>
COL0 <hexcolour>
COL1 <hexcolour>
...

e.g.

SELECT FFFF00
COL0 FFFFFF
COL1 FF00FF

Enhanced Graphics
You can also provide enhanced graphical files if you desire. There are two ways of doing this, which all interoperate correctly.

You can provide a single drawn image by using the tag in the global chunk

HANDDRAWN <texture>

This image is used in place of the monochrome channel from the main texture file. The alpha channel determines how the side
colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour,
and other values blending the modulated colour with the original image.

You can also provide pre-created images for each side. That is, when a side owns an area then if an image for that side
exists, the system will display that section of the drawn image with no colouration or other changes. These are
defined by the tag in the global chunk

DRAWN<N> <texture>

e.g.

DRAWN0 side0.tga

sets the texture to be shown when an area is owned by side zero.

Per-Area Data
You can also set up data for each area in their own chunk. Valid tags are:

X <x>
Y <y>
DATA <a> [<b> <c> <d>]

Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768
coordinates using the RegionMapGetX/Y functions). DATA can be used for preset data on each area to be used in the script.
There can be up to 4 data elements in the list.

NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that
this region data is NOT saved as part of a save game and so the Set function should only be used for data which
can be rebuilt when the screen is activated etc.

e.g.

[44] // chunk header should contain the index of the area
X 100
Y 300
DATA 100 4 5 // unset data is initialised to zero</nowiki>

==== VARIABLEEDIT ====

This is a control specially built to enable quick and simple editing of data stored in a script structure. The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.

The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit. The logic attempts to ensure the same layout irrespective of resolution.

Valid Tags
<nowiki>
FONT <fontname>

The commands used to set up and control a VariableEdit control are

//set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details.
VariableEditSetStruct(objectName, structName, [customFilename])

//fill the edit control with the values from the given variable. Requires the variable name string, not the variable itself.
VariableEditSetVariable(objectName, variableName)

//use the edit control to set the values of a given variable. Requires the variable name string, not the variable itself.
VariableEditGetVariable(objectName, variableName)

The custom layout file has a syntax as below

<elementName> I
<elementName> R <x> <y> <width> <height> [<editbox width>]
<elementName> C <hexColour>
<elementName> F <fontname>
<elementName> B<sizePercent>:<buttonTextureName>

The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows

type I // ignore the type element of the structure
type* I // ignore the type element and any other elements which start with type
type? I // ignore all array entries for the type element

Examples of usage are

type R 10 10 100 40
// all in 1024x768 coordinate space

type C FFFF00FF
// magenta fully opaque
type F smallFont

type B50:plain_button.tga
// rather than an edit box, have a button taking up 50% of the width of the area

By default the edit boxes are set up to only accept numeric input.</nowiki>

==== TABSET ====

Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.

Valid tags
<nowiki>
FONT <fontname>
COLOUR <hex colour>
MAXWIDTH <maximum button width>
FILE <button texture filename>

The control creates a button for each of its direct child objects. The button order is the reverse of the order the objects are defined in the UI file.

The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form

TAB_<objectname>

and this will be used.</nowiki>

==== 3DVIEW ====

Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

<nowiki>//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera. Optionally change the zoom. xyz are in 100ths
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view. 0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)

//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)

//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)

//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])</nowiki>

==== BARCHART ====

A vertical bar graph.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
BARTEX <filename> - texture for the bars of the graph (optional, otherwise will be drawn in a solid colour)
TILED <0/1> - if 1, BARTEX will be tiled vertically on the bars, otherwise it will be stretched (default 0)
COLOUR - the colour for the text and axis lines
BORDER - the colour for the text outline and bar outlines
STRING - the title of the graph
HLABEL - the label for the horizontal axis of the graph
VLABEL - the label for the vertical axis of the graph
STACKED <0/1> - if 1, multiple bars within a category will be drawn stacked vertically, otherwise they will be placed beside each other (default 0)
MAXBARWIDTH - limit on the width of bars
COLOUR0 to COLOUR9 - the colours used for bars within a category
KEY0 to KEY9 - the descriptions of the bars within a category displayed in the key (if there are multiple bars) and tooltip</nowiki>

Special commands:
<nowiki>
//add or update data to a BARCHART UI object, multiple values can be given to show multiple bars in a category, category name is taken from UI string 0
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the bar within a category of a BARCHART UI, the text description of the bar is taken from string 0
SetUIChartColours(objectName, index, colour)

//set the title, horizontal label, and vertical label for a chart
SetUIChartLabels(objectName, titleStringTag, horizLabelStringTag, vertLabelStringTag)

//sort existing data in a BARCHART UI by category. direction: 0 ascending (default), 1 descending. numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a BARCHART UI object
ClearUIChartData(objectName)</nowiki>

==== PIECHART ====

A pie chart.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
COLOUR - the colour for the text
BORDER - the colour for the text outline and slice outlines
STRING - the title of the graph
COLOUR0 to COLOUR15 - the colours used for slices (more colours can be set from script after data is added)</nowiki>

Special commands:
<nowiki>
//add or update data for a PIECHART UI object, category name is taken from UI string 0, returns the index of the slice,
//optional value# parameters not relevant to pie charts
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the slice of a PIECHART UI by index
SetUIChartColours(objectName, index, colour)

//sort existing data in a PIECHAT UI by category. direction: 0 ascending (default), 1 descending.
//numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a PIECHART UI object
ClearUIChartData(objectName)</nowiki>

== Object Commands ==

All objects can have one or more commands attached to them. Commands are inbuilt UI commands to allow for simple actions to occur. While any object can have a command attached to it, not all are able to trigger nor respond to them.

Available commands are:
<nowiki>
COMMAND ENABLE <screen>
COMMAND DISABLE <screen>
COMMAND PRESS <UIObject>
COMMAND SHOWBOX <stringID>
COMMAND CLOSEGAMEANDOPENLINK <url>
COMMAND CUSTOM <value> // send a custom value to a code-defined handler in the game
COMMAND KEY <key> // simulate a key press. Can be any alphanumeric key value, or the special TAB value for the tab key. </nowiki>

for example
<nowiki>
COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F </nowiki>

All commands are checked for validity (that is, that the objects they reference are defined) during UI system loading. Screens are defined by the name of the root objects defined in them.

Current command triggers are:

* BUTTON - commands triggered on press
* EDITBOX - commands triggered on RETURN key

== Animations ==
Animations are defined at the top of a UI file, and their chunks all start with a # symbol as shown below. An animation with the name #START will be played whenever the screen is activated. Other named animations can be triggered from scripts etc. All animation commands work on a tick-based timer which is always reset to zero when an animation is played.

<nowiki>
[#<name>]
ANIM PLACE <object> <time> <x> <y>
// place the object at the given coordinates on the given tick
ANIM MOVE <object> <time> <x> <y> <steps>
// move the object from its current position to a new set of coordinates over a given number of steps
ANIM SCROLL <object> <time> <dx> <dy> <startx> <starty> <endx> <endy> <loop>
// move an object from one point to another in steps of dx,dy. If loop is not zero then it will loop indefinitely.
ANIM BOUNCE <object> <time> <startScale> <endScale> <steps>
// cause the object to 'bounce' scale up in size and then back over time. The scales are in 1000ths, so to bounce an object without changing its size, you would use 1000 1000.
ANIM OFF <object>
// disable an screen via its parent object name. Only works on top level objects.
ANIM SFX <object> <time> <soundID> [<bank>]
// play a UI SFX at the given time. The soundID is the position in the sound list.
ANIM TIME <object> <time> <delta>
// change the 'time' for a given object. Each object can have its own flow of time, and this allows (e.g.) a single object on a screen to execute its animations over and over (if delta is <0, moving time back and allowing an object to execute its animations again.
ANIM FADE <object> <time> <startColour> <endColour> <steps>
// change the colour (including alpha) of an object over time. Colours should be defined as hex values in AARRGGBB order, e.g. FFFFFFFF for fully opaque white.
ANIM SCALE <object> <time> <startH> <startV> <endH> <endV> <steps>
// change the scale of an object over time.
ANIM ROTATE <object> <time> <startRot> <endRot> <steps> <loop>
// rotate an object over time
ANIM SHOW <object> <time> <show>
// set the visiblity of an object. show == 0 will hide the object, otherwise it will be shown </nowiki>

== Strings ==

To allow for localization, strings displayed in UIs are referenced by IDs corresponding to entries in string files, typically DATA/TEXT/TEXT#.TXT or TEXT#.TXT in the current campaign directory. Text may also be assigned to UI components at runtime by scripts.

Some formatting of strings is possible using tags embedded in strings, similar to HTML.
* <nowiki><b>bold</b></nowiki>
* <nowiki><i>italics</i></nowiki>
* <nowiki>line break: <br></nowiki>
* <nowiki><h1>heading</h1></nowiki>
* <nowiki><colour=0xffffff>colour (red)</colour></nowiki>
* <nowiki>inline image: <img=filename.tga></nowiki> If you place a # ahead of the filename it will scale the output to match the image's aspect ratio rather than being square
* <nowiki>tinted inline image: <img=filename.tga colour=0xff0000></nowiki>
* <nowiki>inline image with backdrop: <img=filename.tga|backdrop.tga></nowiki> Note the backdrop is always rendered to the same rect as the main image
* <nowiki><c>small caps string</c></nowiki>
* <nowiki><fN>another font</f></nowiki> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
* <nowiki><a>This is horizontally centered</a></nowiki> Centers the given line(s) horizontally in the text box.
* a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
* <nowiki>for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script</nowiki>

You can embed clickable links in a string by using
<nowiki><html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html></nowiki>
for a url link (which will close the game and open the link in a browser if clicked), or a custom link (which will be caught in a UI script with event==1024 and the data parameter containing the 4 digit decimal value following the = sign). Custom strings must always start with =NNNN. Display strings can be shown rather than the links by using the | seperator, link first followed by the display string. Note you can add a LINKCOLOUR entry to a text object to change the colour that a link shows as when moused over.

== UI Scripting ==
You can attach a script to any UI control using the SCRIPT tag. Events propagate up the UI object hierarchy to any attached script. Generally you will use root object level scripts for general screen logic, and child-object scripts for more specific rendering components.

The hook functions for UI scripts are:
<nowiki>FUNCTION UI_OBJ_INIT()</nowiki>
Called once when the screen is loaded.
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)</nowiki>
Called when a screen is activated (shown) by the game.
<nowiki>FUNCTION UI_OBJ_DEACTIVATE(id)</nowiki>
Called when a screen is deactivated (hidden) by the game.
<nowiki>FUNCTION UI_OBJ_RENDER(x, y, width, height, pass, name, flags)</nowiki>
Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after. Returning 9999 will prevent the default rendering of the control. flags - bit 0: pressed or selected (button only), bit 1: mouse over, bit 2: disabled, bit 3: invisible.
<nowiki>FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right.
The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).
<nowiki>FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags, data)</nowiki>
Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. data is the control-specific data value, currently only listboxes return a value (the index of the currently moused over item, -1 if none). Other control types always set this to zero.
The flags value can be one of the following values:

0 - normal per tick update
1 - the dragging object has just been dropped
<nowiki>FUNCTION UI_OBJ_EVENT(id, event, data)</nowiki>
This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.

== Tutorial Popups ==
You can set up automated, one-time tutorial messages when screens are shown, or when a control is actioned. These should be set up in DATA/TUT.TXT, with entries of the form:

<nowiki>[<object or screen name>]
POPUP <poupname> // optional, name of the screen used for the popup, defaults to TUTORIAL
STRING <string tag> // required string ID for the string to be shown (see below)
TEX <texture name> // optional texture to be applied to the popup when used (see below)
TAG <value> // optional tag value. Only show this popup when a TAG value is set in the mission chunk in the current campaign and the values match.

e.g.

[MainMenu] // this is a screen
STRING IDS_WELCOME_MESSAGE

[ScenEdUnitMode] // this is a button
POPUP MyCustomPopup
STRING IDS_EXPLAIN_UNIT_EDITING
TEX MyCustomTexture</nowiki>

The popup should have controls in it with names of the form <base>String, <base>Image, and <base>Quit - for example you will see that the default CORE/TUTORIAL.TXT file has controls TutorialString and TutorialQuit - the String and Image controls are optional, but Quit is always required and the game will throw an error if it is missing (as there would be no way to close the tutorial message). The string and texture entries from the entry are applied to the String and Image controls respectively.

You may set up a chunk for a given control or screen more than once, which will lead to them showing the first defined entry the first time it is seen/used, and the second the next time the player uses the control or enters the screen. Each time an entry is shown this state is saved (in a local TUT.INF file) to prevent the tutorial popup being shown more than once. Because of this state saving, you should always add new tutorial entries to the end of the file to avoid going out of sync with the saved data.

= UI Defaults =
Certain UI global values are set via UI settings files. The default values are in SYSTEM/UIDEFAULTS.TXT. They are listed below. Note that this file also includes any COLOURDICTIONARY chunk.

<nowiki>TOOLTIPCOLOUR // default tooltip colour
TOOLTIPOFFSETX // X offset of the tooltip from the cursor
TOOLTIPOFFSETY // Y offset of the tooltip from the cursor
TOOLTIPBORDER // width of the border around the tooltip text
TOOLTIP9SLICESIZE // 9 slice corner size in texture pixels
TOOLTIP9SLICEDRAWSIZE // draw size for 9 slice corner

UI

2018-11-21T00:51:40Z

Andrewg: /* LISTBOX */

== Introduction ==
UI Screens are defined in text files which define the objects and actions of UI screens. They are made up for 2 main sections, animations and objects. Animations are defined first in the file, followed by objects. Animations are not required for the correct operation of most UI screens.

You can include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. Lines must be of the form
#include "file.txt"
or
include "file.txt"
You can also add a prefix to an include line. The prefix is applied to all chunk strings in the file, as well as all PARENT entries. So an include of the form
#include "file.txt" Prefix
would cause all the chunks in the include file to be parsed as
[PrefixChunkName]
and any PARENT entries as
PARENT PrefixParentName
This allows for reuse of UI controls in multiple screens (with some careful naming).

Include files must be in the same folder as the UI file (in which case you should <b>NOT</b> use a .txt extension unless you are sure the system will not try and load the include file as a normal UI file (as would happen in CORE/UI or DATA/UI for example) or in DATA/UI/TEMPLATES. Files are searched for in this order. Also, you cannot next includes, i.e. included files cannot have #include statements in them.

== Objects ==
All objects are defined by a minimal data chunk of the form:

<nowiki>
[<objectName>]
TYPE <type>
X <x>
Y <y>
WIDTH <w>
HEIGHT <h></nowiki>

the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.

== The Parent Object ==

The first object defined in a file is assumed to be the screen parent object. Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.

The screen parent object has a number of unique tags which can be set:

<nowiki>
HANDLER <handlerName> // handler tags hook in to the code and so should be used with caution.
//In most cases you will want to keep handler values as they are already set in existing/equivalent files.
MODAL // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack.
LEVEL <level> // each screen is created at a fixed level in the screen layers. It is the order in which screens are displayed.</nowiki>

There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child. Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children. When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.

== Additional Common Tags ==
<nowiki>
DRAGGABLE <size> // denotes that an object is draggable. Size is the height of draggable top border.
FOCUS // can this object have focus (be moused over, clicked on, etc). Some objects (e.g. buttons) are always focus-able.
SFXFOCUS <id> // play the sound (based on the position in the sound list) when the object is moused over.
TOOLTIP <stringID>
ALWAYSTOOL // always display the tooltip text at the bottom of the object
ALWAYSTOOLX <offset> // x display offset for ALWAYSTOOL display
ALWAYSTOOLY <offset> // y display offset for ALWAYSTOOL display
CLIPPING //
DX <x> // horizontal position relative to parent (overrides X)
DY <y> // vertical position relative to parent (overrides Y)
PARENT <parentName> // see The Parent Object
ATTACH <tags> // attach an object to a screen edge, with an optional (unscaled) offset. See below.
SQUAREASPECT // see below</nowiki>
SQUAREASPECT tells controls to maintain their aspect, along with all their children. This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE). Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates. So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size. Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.

Attach takes a single composited string using LRTB for the left, right, top, and bottom screen edges respectively. An optional offset can be included. E.g.
ATTACH RB // attach to the bottom right of the screen
ATTACH R20B10 // attach to the bottom right, with a 20 pixel offset from the right, and 10 up from the bottom.

== Object Types ==
=== Map Display [DEPRECATED] ===
<b>This UI object is currently not supported</b>
The Map Display control allows the use of 3D heightmapped maps which can be scrolled and broken into territories. For details see the detailed documentation.
[[MapDisplayUIControl|Map Display Documentation]]

=== Core Object Types ===
==== OBJECT ====
This is a generic UI object. It is neither visible nor interactable.

==== IMAGE ====
An image object is simply a displayed texture. Valid tags are:

<nowiki>
FILE <filename> // the filename of the texture. The root path is DATA\UI\TEXTURES.

You can show just a portion of a texture by using the additional tags below:

IMAGELEFT <value>
IMAGETOP <value>
IMAGEWIDTH <value>
IMAGEHEIGHT <value>

These values are in pixels, so if the texture is resized, they will need to be re-evaluated.

ANIMSPEED <speed>
ANIMFADE <value>
COLOUR <colour> // anywhere colours are specified, they may either be ARGB hex values (ex. ffff0000) or named colours specified in the COLOURDICTIONARY chunk of DATA/UISETTINGS.TXT
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 0
BACKDROP // when the screen aspect ratio is below 21:9, the texture will be cropped horizontally (ie if a 21:9 background texture is displayed in a 1024 by 768 IMAGE object with BACKDROP, it will fill the screen and
// maintain the correct aspect ratio at all screen ratios up to 21:9, with the left and right edges of the image removed as required)
MODULATE // use a modulate blend when rendering, multiplying (darkening) the screen based on the source image colours
SLICED <pixels> <size> // use a 9-sliced setup for the image. pixels is the size in pixels of a corner slice in the texture. size is the 1024-space size of a corner in the UI Image onscreen</nowiki>

==== DISPLAY ====

A display object is a non interactive display. It draws a simple window using a window template texture.

Valid tags:
<nowiki>
FILE <filename> // texture filename

The window template is laid as as follows (generally it is assumed the texture will be 256x256). The corner 1/16ths of the texture are the corners of the window - these are drawn at 64x64. The top and bottom and left and right center halves are the frames (these are stretched to size) and then the middle of the texture is stretch to cover the remaining center of the window.

STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>

Used to display a window title when used.</nowiki>

==== BUTTON ====

Button objects are displayed using a texture file. This file must contain 4 versions of the button. These are arranged as follows:

* Normal - top left
* Moused Over - top right
* Pressed - bottom left
* Inactive (greyed) - bottom right

Valid tags:
<nowiki>
FILE <filename> // texture name
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
IMAGEU <u>
IMAGEV <v>
GROUP <group> // the number of the group this button belongs to (for use with Get/SetUIGroupSelection commands)
GROUPINDEX <groupIndex> // the index within a group for this button (for use with Get/SetUIGroupSelection commands)
SIMPLEIMAGE <0/1> // treat the FILE as a single image rather than the 4 images described above
TEXTLEFT <x> // placement values for the text within the button (absolute if object is placed absolutely, relative to self if object is placed relatively)
TEXTTOP <y>
TEXTWIDTH <w>
TEXTHEIGHT <h>
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 1
MULTILINE <0/1> // allow wrapped, multiline text on the button, default 0
CENTER <0/1> // horizontally center text on the button, default 1
VCENTER <0/1> // vertically center text on the button, default 1
HOTKEY <key> // define a key which will also trigger the button. Valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN, F1 - F12
CHECKBOX <0,1> // render this button as a checkbox. Should be paired with CHECKBOXTICK
CHECKBOXTICK <filename> // the name of the image containing the tick used when drawing a checkbox-style button
MARQUEE <0,1> // if text is too long for button, scroll horizontally over time (cannot be used with MULTILINE)</nowiki>

==== TEXT ====

A static text object used to display information to the user.

Valid tags:
<nowiki>
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
CENTER // Causes the text to be centered horizontally in the rectangle.
VCENTER // causes the text to be vertically centered in the rectangle
WINDOWEDBACK
RESCALE
RESCALEMAX <value> // Sets the maximum height for RESCALE. If used in conjunction with SCROLLING, the text object will start to Scroll when it reaches the set maximum height.
RESCALELOCK <byte value> // lock growth direction for RESCALE. 0 centered (default), 1 grow down, 2 grow up.
FILE <filename>
TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list within the main object window.
SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX)
BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified
SCROLLBOUNCE <0/1> // bounce when scrolling to the limit of the text (default 1)</nowiki>

==== LISTBOX ====

A listbox allowing the user to scroll through and select lines.

Valid tags:
<nowiki>
CONTROLTEX <filename>
Required, contains all the various listbox controls. The texture is laid out as follows:
Up scroll arrow - top left
Down scroll arrow - top right
Scrollbar - bottom left (this is stretched to the height of the listbox)
Scroll nub - bottom right

FRAMETEX <filename> - used for the listbox frame
SELTEX <filename> - selection display, this is stretched across the width of the selection box
BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type

TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively

FONT <fontname> - the font of the listbox item text
COLOUR <colour> - the colour of the listbox item text.
BARSIZE <value> - Sets the size of the scrollbar. Default value is 32.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
ITEMKEEPSQUARE - causes the scaling of ITEMSPACING and ITEMSIZE to maintain the item layout aspect ratio at non-4:3 resolutions
HORIZONTAL - causes the items to be displayed horizontally across the listbox, only the arrow elements of CONTROLTEX are used (and rotated) for left/right scrolling
MULTISELECT - allows multiselection in list with standard Ctrl and Shift click modifiers, use IsUIListboxItemSelected to test selections
AUTOSCROLL - scroll to the bottom of the list when new items are added
MAXSCROLL <value> - limit on the number of lines scrolled by the mouse wheel
TEXTMODE - mode for showing multiline text entries

MULTILINE <0/1> - allow wrapped, multiline text in listbox items, default 0 (note, this is different than a TEXTMODE listbox,
you will likely need to adjust ITEMSIZE to actually make room to display multiple lines in a single item)
CENTER <0/1> - horizontally center text on listbox items, default 0 unless a BUTTONTEX is also given
VCENTER <0/1> - vertically center text on listbox items, default 0 unless a BUTTONTEX is also given
AUTOTOOLTIP <0/1> - if an item is too wide to display in the listbox using standard drawing and no tooltip is given,
automatically show the item string as the tooltip
TABLE <headerID> - Draw the listbox as a table with a header and aligned columns. Item strings (and optionally, their tooltips) and the
string referenced by headerID are treated as tab (\t) delimited rows. Behaviour may also be activated or updated
using the SetUIListboxTable command.
LISTALIGN <alignment> - when there are not enough items to fill the visible listbox, align the items to the "CENTER" or "BOTTOM" (or
"RIGHT") of the listbox
MARQUEE <0,1> - if text is too long for item, scroll horizontally over time (cannot be used with MULTILINE)
TEXTINSET <value> - inset the item text horizontally by a given value (in addition to restrictions set by TEXTLEFT, TEXTWIDTH)
COLUMNS <value> - use more than one column in the list box. The items are displayed left to right then top to bottom. Does not work for horizontal listboxes.</nowiki>
You can also define a custom item rendering callback
FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)
which operates for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name, pass is zero prior to default rendering, and 1 after. Returning non-zero will prevent default item rendering.

In the case of wanting to block a list box selection event use
FUNCTION UI_LISTBOX_SELECTION_VALIDATE(data, event, id, name)
If the function returns 0 the select event will not be passed. Good for disabled buttons and states which shouldn't be selected with custom rendering.

==== EDITBOX ====

A single line text entry box.

Valid tags:
<nowiki>
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
Defines the display of the listbox item text.</nowiki>

==== REGIONMAP ====

A specialist control for representing a map of distinct regions.

Valid Tags
<nowiki>
FILE <texture>

The texture for the region map must be crafted in a specific way. It should be a 4 channel TGA file.
The channels in the file are used in the following way:

R - a monochrome image layer. A region is coloured with its owning sides colour modulated with this channel.
G - selected layer. The currently selected region has this layer coloured with the defined selection colour and
blended with the normal map pixels.
B - currently unused
A - region layer. The alpha value of each pixel denotes which region the pixel belongs to.
Value 255 is a special value for invalid pixels which belong to no region.

You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours. These are of the format:

SELECT <hexcolour>
COL0 <hexcolour>
COL1 <hexcolour>
...

e.g.

SELECT FFFF00
COL0 FFFFFF
COL1 FF00FF

Enhanced Graphics
You can also provide enhanced graphical files if you desire. There are two ways of doing this, which all interoperate correctly.

You can provide a single drawn image by using the tag in the global chunk

HANDDRAWN <texture>

This image is used in place of the monochrome channel from the main texture file. The alpha channel determines how the side
colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour,
and other values blending the modulated colour with the original image.

You can also provide pre-created images for each side. That is, when a side owns an area then if an image for that side
exists, the system will display that section of the drawn image with no colouration or other changes. These are
defined by the tag in the global chunk

DRAWN<N> <texture>

e.g.

DRAWN0 side0.tga

sets the texture to be shown when an area is owned by side zero.

Per-Area Data
You can also set up data for each area in their own chunk. Valid tags are:

X <x>
Y <y>
DATA <a> [<b> <c> <d>]

Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768
coordinates using the RegionMapGetX/Y functions). DATA can be used for preset data on each area to be used in the script.
There can be up to 4 data elements in the list.

NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that
this region data is NOT saved as part of a save game and so the Set function should only be used for data which
can be rebuilt when the screen is activated etc.

e.g.

[44] // chunk header should contain the index of the area
X 100
Y 300
DATA 100 4 5 // unset data is initialised to zero</nowiki>

==== VARIABLEEDIT ====

This is a control specially built to enable quick and simple editing of data stored in a script structure. The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.

The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit. The logic attempts to ensure the same layout irrespective of resolution.

Valid Tags
<nowiki>
FONT <fontname>

The commands used to set up and control a VariableEdit control are

//set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details.
VariableEditSetStruct(objectName, structName, [customFilename])

//fill the edit control with the values from the given variable. Requires the variable name string, not the variable itself.
VariableEditSetVariable(objectName, variableName)

//use the edit control to set the values of a given variable. Requires the variable name string, not the variable itself.
VariableEditGetVariable(objectName, variableName)

The custom layout file has a syntax as below

<elementName> I
<elementName> R <x> <y> <width> <height> [<editbox width>]
<elementName> C <hexColour>
<elementName> F <fontname>
<elementName> B<sizePercent>:<buttonTextureName>

The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows

type I // ignore the type element of the structure
type* I // ignore the type element and any other elements which start with type
type? I // ignore all array entries for the type element

Examples of usage are

type R 10 10 100 40
// all in 1024x768 coordinate space

type C FFFF00FF
// magenta fully opaque
type F smallFont

type B50:plain_button.tga
// rather than an edit box, have a button taking up 50% of the width of the area

By default the edit boxes are set up to only accept numeric input.</nowiki>

==== TABSET ====

Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.

Valid tags
<nowiki>
FONT <fontname>
COLOUR <hex colour>
MAXWIDTH <maximum button width>
FILE <button texture filename>

The control creates a button for each of its direct child objects. The button order is the reverse of the order the objects are defined in the UI file.

The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form

TAB_<objectname>

and this will be used.</nowiki>

==== 3DVIEW ====

Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

<nowiki>//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera. Optionally change the zoom. xyz are in 100ths
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view. 0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)

//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)

//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)

//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])</nowiki>

==== BARCHART ====

A vertical bar graph.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
BARTEX <filename> - texture for the bars of the graph (optional, otherwise will be drawn in a solid colour)
TILED <0/1> - if 1, BARTEX will be tiled vertically on the bars, otherwise it will be stretched (default 0)
COLOUR - the colour for the text and axis lines
BORDER - the colour for the text outline and bar outlines
STRING - the title of the graph
HLABEL - the label for the horizontal axis of the graph
VLABEL - the label for the vertical axis of the graph
STACKED <0/1> - if 1, multiple bars within a category will be drawn stacked vertically, otherwise they will be placed beside each other (default 0)
COLOUR0 to COLOUR9 - the colours used for bars within a category
KEY0 to KEY9 - the descriptions of the bars within a category displayed in the key (if there are multiple bars) and tooltip</nowiki>

Special commands:
<nowiki>
//add or update data to a BARCHART UI object, multiple values can be given to show multiple bars in a category, category name is taken from UI string 0
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the bar within a category of a BARCHART UI, the text description of the bar is taken from string 0
SetUIChartColours(objectName, index, colour)

//set the title, horizontal label, and vertical label for a chart
SetUIChartLabels(objectName, titleStringTag, horizLabelStringTag, vertLabelStringTag)

//sort existing data in a BARCHART UI by category. direction: 0 ascending (default), 1 descending. numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a BARCHART UI object
ClearUIChartData(objectName)</nowiki>

==== PIECHART ====

A pie chart.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
COLOUR - the colour for the text
BORDER - the colour for the text outline and slice outlines
STRING - the title of the graph
COLOUR0 to COLOUR15 - the colours used for slices (more colours can be set from script after data is added)</nowiki>

Special commands:
<nowiki>
//add or update data for a PIECHART UI object, category name is taken from UI string 0, returns the index of the slice,
//optional value# parameters not relevant to pie charts
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the slice of a PIECHART UI by index
SetUIChartColours(objectName, index, colour)

//sort existing data in a PIECHAT UI by category. direction: 0 ascending (default), 1 descending.
//numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a PIECHART UI object
ClearUIChartData(objectName)</nowiki>

== Object Commands ==

All objects can have one or more commands attached to them. Commands are inbuilt UI commands to allow for simple actions to occur. While any object can have a command attached to it, not all are able to trigger nor respond to them.

Available commands are:
<nowiki>
COMMAND ENABLE <screen>
COMMAND DISABLE <screen>
COMMAND PRESS <UIObject>
COMMAND SHOWBOX <stringID>
COMMAND CLOSEGAMEANDOPENLINK <url>
COMMAND CUSTOM <value> // send a custom value to a code-defined handler in the game
COMMAND KEY <key> // simulate a key press. Can be any alphanumeric key value, or the special TAB value for the tab key. </nowiki>

for example
<nowiki>
COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F </nowiki>

All commands are checked for validity (that is, that the objects they reference are defined) during UI system loading. Screens are defined by the name of the root objects defined in them.

Current command triggers are:

* BUTTON - commands triggered on press
* EDITBOX - commands triggered on RETURN key

== Animations ==
Animations are defined at the top of a UI file, and their chunks all start with a # symbol as shown below. An animation with the name #START will be played whenever the screen is activated. Other named animations can be triggered from scripts etc. All animation commands work on a tick-based timer which is always reset to zero when an animation is played.

<nowiki>
[#<name>]
ANIM PLACE <object> <time> <x> <y>
// place the object at the given coordinates on the given tick
ANIM MOVE <object> <time> <x> <y> <steps>
// move the object from its current position to a new set of coordinates over a given number of steps
ANIM SCROLL <object> <time> <dx> <dy> <startx> <starty> <endx> <endy> <loop>
// move an object from one point to another in steps of dx,dy. If loop is not zero then it will loop indefinitely.
ANIM BOUNCE <object> <time> <startScale> <endScale> <steps>
// cause the object to 'bounce' scale up in size and then back over time. The scales are in 1000ths, so to bounce an object without changing its size, you would use 1000 1000.
ANIM OFF <object>
// disable an screen via its parent object name. Only works on top level objects.
ANIM SFX <object> <time> <soundID> [<bank>]
// play a UI SFX at the given time. The soundID is the position in the sound list.
ANIM TIME <object> <time> <delta>
// change the 'time' for a given object. Each object can have its own flow of time, and this allows (e.g.) a single object on a screen to execute its animations over and over (if delta is <0, moving time back and allowing an object to execute its animations again.
ANIM FADE <object> <time> <startColour> <endColour> <steps>
// change the colour (including alpha) of an object over time. Colours should be defined as hex values in AARRGGBB order, e.g. FFFFFFFF for fully opaque white.
ANIM SCALE <object> <time> <startH> <startV> <endH> <endV> <steps>
// change the scale of an object over time.
ANIM ROTATE <object> <time> <startRot> <endRot> <steps> <loop>
// rotate an object over time
ANIM SHOW <object> <time> <show>
// set the visiblity of an object. show == 0 will hide the object, otherwise it will be shown </nowiki>

== Strings ==

To allow for localization, strings displayed in UIs are referenced by IDs corresponding to entries in string files, typically DATA/TEXT/TEXT#.TXT or TEXT#.TXT in the current campaign directory. Text may also be assigned to UI components at runtime by scripts.

Some formatting of strings is possible using tags embedded in strings, similar to HTML.
* <nowiki><b>bold</b></nowiki>
* <nowiki><i>italics</i></nowiki>
* <nowiki>line break: <br></nowiki>
* <nowiki><h1>heading</h1></nowiki>
* <nowiki><colour=0xffffff>colour (red)</colour></nowiki>
* <nowiki>inline image: <img=filename.tga></nowiki>
* <nowiki>tinted inline image: <img=filename.tga colour=0xff0000></nowiki>
* <nowiki><c>small caps string</c></nowiki>
* <nowiki><fN>another font</f></nowiki> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
* <nowiki><a>This is horizontally centered</a></nowiki> Centers the given line(s) horizontally in the text box.
* a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
* <nowiki>for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script</nowiki>

You can embed clickable links in a string by using
<nowiki><html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html></nowiki>
for a url link (which will close the game and open the link in a browser if clicked), or a custom link (which will be caught in a UI script with event==1024 and the data parameter containing the 4 digit decimal value following the = sign). Custom strings must always start with =NNNN. Display strings can be shown rather than the links by using the | seperator, link first followed by the display string. Note you can add a LINKCOLOUR entry to a text object to change the colour that a link shows as when moused over.

== UI Scripting ==
You can attach a script to any UI control using the SCRIPT tag. Events propagate up the UI object hierarchy to any attached script. Generally you will use root object level scripts for general screen logic, and child-object scripts for more specific rendering components.

The hook functions for UI scripts are:
<nowiki>FUNCTION UI_OBJ_INIT()</nowiki>
Called once when the screen is loaded.
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)</nowiki>
Called when a screen is activated (shown) by the game.
<nowiki>FUNCTION UI_OBJ_DEACTIVATE(id)</nowiki>
Called when a screen is deactivated (hidden) by the game.
<nowiki>FUNCTION UI_OBJ_RENDER(x, y, width, height, pass, name, flags)</nowiki>
Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after. Returning 9999 will prevent the default rendering of the control. flags - bit 0: pressed or selected (button only), bit 1: mouse over, bit 2: disabled, bit 3: invisible.
<nowiki>FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right.
The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).
<nowiki>FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags, data)</nowiki>
Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. data is the control-specific data value, currently only listboxes return a value (the index of the currently moused over item, -1 if none). Other control types always set this to zero.
The flags value can be one of the following values:

0 - normal per tick update
1 - the dragging object has just been dropped
<nowiki>FUNCTION UI_OBJ_EVENT(id, event, data)</nowiki>
This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.

== Tutorial Popups ==
You can set up automated, one-time tutorial messages when screens are shown, or when a control is actioned. These should be set up in DATA/TUT.TXT, with entries of the form:

<nowiki>[<object or screen name>]
POPUP <poupname> // optional, name of the screen used for the popup, defaults to TUTORIAL
STRING <string tag> // required string ID for the string to be shown (see below)
TEX <texture name> // optional texture to be applied to the popup when used (see below)
TAG <value> // optional tag value. Only show this popup when a TAG value is set in the mission chunk in the current campaign and the values match.

e.g.

[MainMenu] // this is a screen
STRING IDS_WELCOME_MESSAGE

[ScenEdUnitMode] // this is a button
POPUP MyCustomPopup
STRING IDS_EXPLAIN_UNIT_EDITING
TEX MyCustomTexture</nowiki>

The popup should have controls in it with names of the form <base>String, <base>Image, and <base>Quit - for example you will see that the default CORE/TUTORIAL.TXT file has controls TutorialString and TutorialQuit - the String and Image controls are optional, but Quit is always required and the game will throw an error if it is missing (as there would be no way to close the tutorial message). The string and texture entries from the entry are applied to the String and Image controls respectively.

You may set up a chunk for a given control or screen more than once, which will lead to them showing the first defined entry the first time it is seen/used, and the second the next time the player uses the control or enters the screen. Each time an entry is shown this state is saved (in a local TUT.INF file) to prevent the tutorial popup being shown more than once. Because of this state saving, you should always add new tutorial entries to the end of the file to avoid going out of sync with the saved data.

= UI Defaults =
Certain UI global values are set via UI settings files. The default values are in SYSTEM/UIDEFAULTS.TXT. They are listed below. Note that this file also includes any COLOURDICTIONARY chunk.

<nowiki>TOOLTIPCOLOUR // default tooltip colour
TOOLTIPOFFSETX // X offset of the tooltip from the cursor
TOOLTIPOFFSETY // Y offset of the tooltip from the cursor
TOOLTIPBORDER // width of the border around the tooltip text
TOOLTIP9SLICESIZE // 9 slice corner size in texture pixels
TOOLTIP9SLICEDRAWSIZE // draw size for 9 slice corner

UI

2018-09-29T01:00:06Z

Andrewg: /* LISTBOX */

== Introduction ==
UI Screens are defined in text files which define the objects and actions of UI screens. They are made up for 2 main sections, animations and objects. Animations are defined first in the file, followed by objects. Animations are not required for the correct operation of most UI screens.

You can include other files in UI files. Note this should be used with care as objects with the same names are still prohibited. Lines must be of the form
#include "file.txt"
or
include "file.txt"
You can also add a prefix to an include line. The prefix is applied to all chunk strings in the file, as well as all PARENT entries. So an include of the form
#include "file.txt" Prefix
would cause all the chunks in the include file to be parsed as
[PrefixChunkName]
and any PARENT entries as
PARENT PrefixParentName
This allows for reuse of UI controls in multiple screens (with some careful naming).

Include files must be in the same folder as the UI file (in which case you should <b>NOT</b> use a .txt extension unless you are sure the system will not try and load the include file as a normal UI file (as would happen in CORE/UI or DATA/UI for example) or in DATA/UI/TEMPLATES. Files are searched for in this order. Also, you cannot next includes, i.e. included files cannot have #include statements in them.

== Objects ==
All objects are defined by a minimal data chunk of the form:

<nowiki>
[<objectName>]
TYPE <type>
X <x>
Y <y>
WIDTH <w>
HEIGHT <h></nowiki>

the different types of UI objects and their capabilities, defined using additional tags in the chunk, are described below. All x,y and width, height values are assumed to be based on a 1024x768 screen.

== The Parent Object ==

The first object defined in a file is assumed to be the screen parent object. Any other object in the file without an explicit PARENT definition is assumed to be a child of the screen parent object.

The screen parent object has a number of unique tags which can be set:

<nowiki>
HANDLER <handlerName> // handler tags hook in to the code and so should be used with caution.
//In most cases you will want to keep handler values as they are already set in existing/equivalent files.
MODAL // if set, this says that the screen is modal and prevents interaction with any screens below it in the display stack.
LEVEL <level> // each screen is created at a fixed level in the screen layers. It is the order in which screens are displayed.</nowiki>

There can be a hierarchy of parent / child objects below the screen parent object indicated by the PARENT tag on the child. Child objects are drawn in front of their parents and some properties (for example visibility) of a parent will automatically propagate to their children. When two sibling objects overlap visually, the object appearing first in the layout is drawn in front.

== Additional Common Tags ==
<nowiki>
DRAGGABLE <size> // denotes that an object is draggable. Size is the height of draggable top border.
FOCUS // can this object have focus (be moused over, clicked on, etc). Some objects (e.g. buttons) are always focus-able.
SFXFOCUS <id> // play the sound (based on the position in the sound list) when the object is moused over.
TOOLTIP <stringID>
ALWAYSTOOL // always display the tooltip text at the bottom of the object
ALWAYSTOOLX <offset> // x display offset for ALWAYSTOOL display
ALWAYSTOOLY <offset> // y display offset for ALWAYSTOOL display
CLIPPING //
DX <x> // horizontal position relative to parent (overrides X)
DY <y> // vertical position relative to parent (overrides Y)
PARENT <parentName> // see The Parent Object
ATTACH <tags> // attach an object to a screen edge, with an optional (unscaled) offset. See below.
SQUAREASPECT // see below</nowiki>
SQUAREASPECT tells controls to maintain their aspect, along with all their children. This differs from the KEEPSQUARE logic in that the actual positioning of child objects will retain a constant aspect (rather than just their control dimensions, as with KEEPSQUARE). Effectively, setting SQUAREASPECT on a control will cause it to be centered around it's usual position, with all its children positions as they would have been in their 1024x768 defined coordinates. So a popup (for example) will have the same look and layout all screen resolutions, but will scale uniformly to the appropriate size. Note that while it is possible to turn off SQUAREASPECT on child objects of SQUAREASPECT parents, the results will likely be undesired.

Attach takes a single composited string using LRTB for the left, right, top, and bottom screen edges respectively. An optional offset can be included. E.g.
ATTACH RB // attach to the bottom right of the screen
ATTACH R20B10 // attach to the bottom right, with a 20 pixel offset from the right, and 10 up from the bottom.

== Object Types ==
=== Map Display [DEPRECATED] ===
<b>This UI object is currently not supported</b>
The Map Display control allows the use of 3D heightmapped maps which can be scrolled and broken into territories. For details see the detailed documentation.
[[MapDisplayUIControl|Map Display Documentation]]

=== Core Object Types ===
==== OBJECT ====
This is a generic UI object. It is neither visible nor interactable.

==== IMAGE ====
An image object is simply a displayed texture. Valid tags are:

<nowiki>
FILE <filename> // the filename of the texture. The root path is DATA\UI\TEXTURES.

You can show just a portion of a texture by using the additional tags below:

IMAGELEFT <value>
IMAGETOP <value>
IMAGEWIDTH <value>
IMAGEHEIGHT <value>

These values are in pixels, so if the texture is resized, they will need to be re-evaluated.

ANIMSPEED <speed>
ANIMFADE <value>
COLOUR <colour> // anywhere colours are specified, they may either be ARGB hex values (ex. ffff0000) or named colours specified in the COLOURDICTIONARY chunk of DATA/UISETTINGS.TXT
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 0
BACKDROP // when the screen aspect ratio is below 21:9, the texture will be cropped horizontally (ie if a 21:9 background texture is displayed in a 1024 by 768 IMAGE object with BACKDROP, it will fill the screen and
// maintain the correct aspect ratio at all screen ratios up to 21:9, with the left and right edges of the image removed as required)
MODULATE // use a modulate blend when rendering, multiplying (darkening) the screen based on the source image colours
SLICED <pixels> <size> // use a 9-sliced setup for the image. pixels is the size in pixels of a corner slice in the texture. size is the 1024-space size of a corner in the UI Image onscreen</nowiki>

==== DISPLAY ====

A display object is a non interactive display. It draws a simple window using a window template texture.

Valid tags:
<nowiki>
FILE <filename> // texture filename

The window template is laid as as follows (generally it is assumed the texture will be 256x256). The corner 1/16ths of the texture are the corners of the window - these are drawn at 64x64. The top and bottom and left and right center halves are the frames (these are stretched to size) and then the middle of the texture is stretch to cover the remaining center of the window.

STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>

Used to display a window title when used.</nowiki>

==== BUTTON ====

Button objects are displayed using a texture file. This file must contain 4 versions of the button. These are arranged as follows:

* Normal - top left
* Moused Over - top right
* Pressed - bottom left
* Inactive (greyed) - bottom right

Valid tags:
<nowiki>
FILE <filename> // texture name
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
IMAGEU <u>
IMAGEV <v>
GROUP <group> // the number of the group this button belongs to (for use with Get/SetUIGroupSelection commands)
GROUPINDEX <groupIndex> // the index within a group for this button (for use with Get/SetUIGroupSelection commands)
SIMPLEIMAGE <0/1> // treat the FILE as a single image rather than the 4 images described above
TEXTLEFT <x> // placement values for the text within the button (absolute if object is placed absolutely, relative to self if object is placed relatively)
TEXTTOP <y>
TEXTWIDTH <w>
TEXTHEIGHT <h>
KEEPSQUARE <0/1> // keep the object aspect ratio from the layout when scaling to non 4:3 resolutions, default 1
MULTILINE <0/1> // allow wrapped, multiline text on the button, default 0
CENTER <0/1> // horizontally center text on the button, default 1
VCENTER <0/1> // vertically center text on the button, default 1
HOTKEY <key> // define a key which will also trigger the button. Valid key values are A-Z and 0-9 as well as TAB, SPACE, RETURN, BACKSPACE, ESC, LEFT, RIGHT, UP, DOWN, F1 - F12
CHECKBOX <0,1> // render this button as a checkbox. Should be paired with CHECKBOXTICK
CHECKBOXTICK <filename> // the name of the image containing the tick used when drawing a checkbox-style button
MARQUEE <0,1> // if text is too long for button, scroll horizontally over time (cannot be used with MULTILINE)</nowiki>

==== TEXT ====

A static text object used to display information to the user.

Valid tags:
<nowiki>
STRING <stringID>
FONT <fontname>
COLOUR <colour>
BORDER <colour>
CENTER // Causes the text to be centered horizontally in the rectangle.
VCENTER // causes the text to be vertically centered in the rectangle
WINDOWEDBACK
RESCALE
RESCALEMAX <value> // Sets the maximum height for RESCALE. If used in conjunction with SCROLLING, the text object will start to Scroll when it reaches the set maximum height.
RESCALELOCK <byte value> // lock growth direction for RESCALE. 0 centered (default), 1 grow down, 2 grow up.
FILE <filename>
TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list within the main object window.
SCROLLING <filename> // adds a scrollbar to the text of needed, filename is the name for the scrolling control texture (equivalent to CONTROLTEX on a LISTBOX)
BARSIZE <size> // this size of the scrollbar is a SCROLLING control texture is specified
SCROLLBOUNCE <0/1> // bounce when scrolling to the limit of the text (default 1)</nowiki>

==== LISTBOX ====

A listbox allowing the user to scroll through and select lines.

Valid tags:
<nowiki>
CONTROLTEX <filename>
Required, contains all the various listbox controls. The texture is laid out as follows:
Up scroll arrow - top left
Down scroll arrow - top right
Scrollbar - bottom left (this is stretched to the height of the listbox)
Scroll nub - bottom right

FRAMETEX <filename> - used for the listbox frame
SELTEX <filename> - selection display, this is stretched across the width of the selection box
BUTTONTEX <filename> - applied to element in the listbox, texture layout is the same as a BUTTON type

TEXTLEFT <value>
TEXTTOP <value>
TEXTWIDTH <value>
TEXTHEIGHT <value>
Screen placement values for the actual text list, absolute if list is placed absolutely, relative to list if object is placed relatively

FONT <fontname> - the font of the listbox item text
COLOUR <colour> - the colour of the listbox item text.
BARSIZE <value> - Sets the size of the scrollbar. Default value is 32.
ITEMSPACING <value> - spacing between listbox items (vertical or horizontal depending on type of listbox), default value is 0
ITEMSIZE <value> - the size of the listbox items (vertical or horizontal depending on type of listbox), default is the height of one line of text for vertical listboxes and the max width to fit all items for horizontal listboxes
ITEMKEEPSQUARE - causes the scaling of ITEMSPACING and ITEMSIZE to maintain the item layout aspect ratio at non-4:3 resolutions
HORIZONTAL - causes the items to be displayed horizontally across the listbox, only the arrow elements of CONTROLTEX are used (and rotated) for left/right scrolling
MULTISELECT - allows multiselection in list with standard Ctrl and Shift click modifiers, use IsUIListboxItemSelected to test selections
AUTOSCROLL - scroll to the bottom of the list when new items are added
MAXSCROLL <value> - limit on the number of lines scrolled by the mouse wheel
TEXTMODE - mode for showing multiline text entries

MULTILINE <0/1> - allow wrapped, multiline text in listbox items, default 0 (note, this is different than a TEXTMODE listbox,
you will likely need to adjust ITEMSIZE to actually make room to display multiple lines in a single item)
CENTER <0/1> - horizontally center text on listbox items, default 0 unless a BUTTONTEX is also given
VCENTER <0/1> - vertically center text on listbox items, default 0 unless a BUTTONTEX is also given
AUTOTOOLTIP <0/1> - if an item is too wide to display in the listbox using standard drawing and no tooltip is given,
automatically show the item string as the tooltip
TABLE <headerID> - draw the listbox as a table with a header and aligned columns, items and the string referenced by headerID are
treated as tab (\t) delimited rows, behaviour may also be activated or updated using the SetUIListboxTable command
LISTALIGN <alignment> - when there are not enough items to fill the visible listbox, align the items to the "CENTER" or "BOTTOM" (or
"RIGHT") of the listbox
MARQUEE <0,1> - if text is too long for item, scroll horizontally over time (cannot be used with MULTILINE)
TEXTINSET <value> - inset the item text horizontally by a given value (in addition to restrictions set by TEXTLEFT, TEXTWIDTH)</nowiki>
You can also define a custom item rendering callback
FUNCTION UI_OBJ_RENDER_ITEM(x,y,width,height,pass,flags, item, name)
which operates for each listbox item. The flags param has bits set for selection (bit 0) and mouseover (bit 1), item is the index of the item in the listbox, name is the UI object name, pass is zero prior to default rendering, and 1 after. Returning non-zero will prevent default item rendering.

In the case of wanting to block a list box selection event use
FUNCTION UI_LISTBOX_SELECTION_VALIDATE(data, event, id, name)
If the function returns 0 the select event will not be passed. Good for disabled buttons and states which shouldn't be selected with custom rendering.

==== EDITBOX ====

A single line text entry box.

Valid tags:
<nowiki>
FONT <fontname>
COLOUR <colour>
MAXCHARS <count>
Defines the display of the listbox item text.</nowiki>

==== REGIONMAP ====

A specialist control for representing a map of distinct regions.

Valid Tags
<nowiki>
FILE <texture>

The texture for the region map must be crafted in a specific way. It should be a 4 channel TGA file. The channels in the file are used in the following way:

R - a monochrome image layer. A region is coloured with its owning sides colour modulated with this channel.
G - selected layer. The currently selected region has this layer coloured with the defined selection colour and blended with the normal map pixels.
B - currently unused
A - region layer. The alpha value of each pixel denotes which region the pixel belongs to. Value 255 is a special value for invalid pixels which belong to no region.

You can also provide a .DAT file (with the same name as the texture file) to define the owner and selection colours. These are of the format:

SELECT <hexcolour>
COL0 <hexcolour>
COL1 <hexcolour>
...

e.g.

SELECT FFFF00
COL0 FFFFFF
COL1 FF00FF

Enhanced Graphics
You can also provide enhanced graphical files if you desire. There are two ways of doing this, which all interoperate correctly.

You can provide a single drawn image by using the tag in the global chunk

HANDDRAWN <texture>

This image is used in place of the monochrome channel from the main texture file. The alpha channel determines how the side colours are blended with the image colour, with zero meaning that the image colours are fully modulated with the side colour, and other values blending the modulated colour with the original image.

You can also provide pre-created images for each side. That is, when a side owns an area then if an image for that side exists, the system will display that section of the drawn image with no colouration or other changes. These are defined by the tag in the global chunk

DRAWN<N> <texture>

e.g.

DRAWN0 side0.tga

sets the texture to be shown when an area is owned by side zero.

Per-Area Data
You can also set up data for each area in their own chunk. Valid tags are:

X <x>
Y <y>
DATA <a> [<b> <c> <d>]

Where X and Y are the region map image pixel coordinates of the center point of the area (retrieved in script as 1024x768 coordinates using the RegionMapGetX/Y functions). DATA can be used for preset data on each area to be used in the script. There can be up to 4 data elements in the list.
NOTE: While there are both Get and Set functions (RegionMapGetData/RegionMapSetData) it is important to note that this region data is NOT saved as part of a save game and so the Set function should only be used for data which can be rebuilt when the screen is activated etc.

e.g.

[44] // chunk header should contain the index of the area
X 100
Y 300
DATA 100 4 5 // unset data is initialised to zero</nowiki>

==== VARIABLEEDIT ====

This is a control specially built to enable quick and simple editing of data stored in a script structure. The UI file itself only contains the basic positioning details of the control, with scripting being used to set up the structure type to be edited and any custom layout functionality.

The default behaviour is to list all the structure elements arranged to fill the control area, or centered horizontally if all elements will fit. The logic attempts to ensure the same layout irrespective of resolution.

Valid Tags
<nowiki>
FONT <fontname>

The commands used to set up and control a VariableEdit control are

//set up a variable edit control with the structure you want to edit. The customFilename points to a file which allows setup of custom entry positioning/fonts and other details.
VariableEditSetStruct(objectName, structName, [customFilename])

//fill the edit control with the values from the given variable. Requires the variable name string, not the variable itself.
VariableEditSetVariable(objectName, variableName)

//use the edit control to set the values of a given variable. Requires the variable name string, not the variable itself.
VariableEditGetVariable(objectName, variableName)

The custom layout file has a syntax as below

<elementName> I
<elementName> R <x> <y> <width> <height> [<editbox width>]
<elementName> C <hexColour>
<elementName> F <fontname>
<elementName> B<sizePercent>:<buttonTextureName>

The elementName can be either an explicit name, a wildcard string name, or apply to all members of an array, as follows

type I // ignore the type element of the structure
type* I // ignore the type element and any other elements which start with type
type? I // ignore all array entries for the type element

Examples of usage are

type R 10 10 100 40
// all in 1024x768 coordinate space

type C FFFF00FF
// magenta fully opaque
type F smallFont

type B50:plain_button.tga
// rather than an edit box, have a button taking up 50% of the width of the area

By default the edit boxes are set up to only accept numeric input.</nowiki>

==== TABSET ====

Creates a set of buttons which automatically enable or disable other objects in the screen based on which is currently active.

Valid tags
<nowiki>
FONT <fontname>
COLOUR <hex colour>
MAXWIDTH <maximum button width>
FILE <button texture filename>

The control creates a button for each of its direct child objects. The button order is the reverse of the order the objects are defined in the UI file.

The text on the buttons defaults to the name of the UI object, but you can add a text file entry of the form

TAB_<objectname>

and this will be used.</nowiki>

==== 3DVIEW ====

Creates a 3D viewport into which you can load 3D models for viewing. The COLOUR tag for this control sets the background clear colour (use zero for a transparent background, FF000000 for black).

Script commands to control this are:

<nowiki>//if filename starts with # then defaults to standard unit loading paths.
UIObject3DLoad(objectName, filename, [texturePath])

//automatically set the zoom and camera origin to the size of the currently loaded object
UIObject3DAuto(objectName)

//set the origin position and vertical angle of the camera. Optionally change the zoom. xyz are in 100ths
SetUIObject3DCamera(objectName, x,y,z,angle,[zoom])

//set the options for the view. 0 for off, nonzero for on.
SetUIObject3DOptions(objectName, allowZoom, allowHorizontalRotate, allowVerticalRotate)

//set the rotation angle for the 3D view
SetUIObject3DRotation(objectName, angle)

//set the zoom for the given 3D view
SetUIObject3DZoom(objectName, zoom)

//play an animation, which must be set up in the standard text file. If index then it will play a specific anim (if it exists) otherwise random. Loops if loop is != 0, defaults on
SetUIObject3DAnim(objectName, animName, [loop, index])</nowiki>

==== BARCHART ====

A vertical bar graph.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
BARTEX <filename> - texture for the bars of the graph (optional, otherwise will be drawn in a solid colour)
TILED <0/1> - if 1, BARTEX will be tiled vertically on the bars, otherwise it will be stretched (default 0)
COLOUR - the colour for the text and axis lines
BORDER - the colour for the text outline and bar outlines
STRING - the title of the graph
HLABEL - the label for the horizontal axis of the graph
VLABEL - the label for the vertical axis of the graph
STACKED <0/1> - if 1, multiple bars within a category will be drawn stacked vertically, otherwise they will be placed beside each other (default 0)
COLOUR0 to COLOUR9 - the colours used for bars within a category
KEY0 to KEY9 - the descriptions of the bars within a category displayed in the key (if there are multiple bars) and tooltip</nowiki>

Special commands:
<nowiki>
//add or update data to a BARCHART UI object, multiple values can be given to show multiple bars in a category, category name is taken from UI string 0
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the bar within a category of a BARCHART UI, the text description of the bar is taken from string 0
SetUIChartColours(objectName, index, colour)

//set the title, horizontal label, and vertical label for a chart
SetUIChartLabels(objectName, titleStringTag, horizLabelStringTag, vertLabelStringTag)

//sort existing data in a BARCHART UI by category. direction: 0 ascending (default), 1 descending. numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a BARCHART UI object
ClearUIChartData(objectName)</nowiki>

==== PIECHART ====

A pie chart.

Tags:
<nowiki>
FILE <filename> - background image, windowed (optional)
COLOUR - the colour for the text
BORDER - the colour for the text outline and slice outlines
STRING - the title of the graph
COLOUR0 to COLOUR15 - the colours used for slices (more colours can be set from script after data is added)</nowiki>

Special commands:
<nowiki>
//add or update data for a PIECHART UI object, category name is taken from UI string 0, returns the index of the slice,
//optional value# parameters not relevant to pie charts
SetUIChartData(objectName, value, [valueN], ...)

//set the colour for the slice of a PIECHART UI by index
SetUIChartColours(objectName, index, colour)

//sort existing data in a PIECHAT UI by category. direction: 0 ascending (default), 1 descending.
//numeric: 0 sort category names alphabetically (default), 1 treat category names as numbers (ie "2" < "10")
SortUIChartData(objectName, [direction], [numeric])

//clear data from a PIECHART UI object
ClearUIChartData(objectName)</nowiki>

== Object Commands ==

All objects can have one or more commands attached to them. Commands are inbuilt UI commands to allow for simple actions to occur. While any object can have a command attached to it, not all are able to trigger nor respond to them.

Available commands are:
<nowiki>
COMMAND ENABLE <screen>
COMMAND DISABLE <screen>
COMMAND PRESS <UIObject>
COMMAND SHOWBOX <stringID>
COMMAND CLOSEGAMEANDOPENLINK <url>
COMMAND CUSTOM <value> // send a custom value to a code-defined handler in the game
COMMAND KEY <key> // simulate a key press. Can be any alphanumeric key value, or the special TAB value for the tab key. </nowiki>

for example
<nowiki>
COMMAND ENABLE MAINMENU
COMMAND DISABLE POPUP
COMMAND PRESS POPUPOKBUTTON
COMMAND SHOWBOX IDS_HELPFUL_MESSAGE
COMMAND CLOSEGAMEANDOPENLINK someurlonslitherine.html
COMMAND CUSTOM 55
COMMAND KEY F </nowiki>

All commands are checked for validity (that is, that the objects they reference are defined) during UI system loading. Screens are defined by the name of the root objects defined in them.

Current command triggers are:

* BUTTON - commands triggered on press
* EDITBOX - commands triggered on RETURN key

== Animations ==
Animations are defined at the top of a UI file, and their chunks all start with a # symbol as shown below. An animation with the name #START will be played whenever the screen is activated. Other named animations can be triggered from scripts etc. All animation commands work on a tick-based timer which is always reset to zero when an animation is played.

<nowiki>
[#<name>]
ANIM PLACE <object> <time> <x> <y>
// place the object at the given coordinates on the given tick
ANIM MOVE <object> <time> <x> <y> <steps>
// move the object from its current position to a new set of coordinates over a given number of steps
ANIM SCROLL <object> <time> <dx> <dy> <startx> <starty> <endx> <endy> <loop>
// move an object from one point to another in steps of dx,dy. If loop is not zero then it will loop indefinitely.
ANIM BOUNCE <object> <time> <startScale> <endScale> <steps>
// cause the object to 'bounce' scale up in size and then back over time. The scales are in 1000ths, so to bounce an object without changing its size, you would use 1000 1000.
ANIM OFF <object>
// disable an screen via its parent object name. Only works on top level objects.
ANIM SFX <object> <time> <soundID> [<bank>]
// play a UI SFX at the given time. The soundID is the position in the sound list.
ANIM TIME <object> <time> <delta>
// change the 'time' for a given object. Each object can have its own flow of time, and this allows (e.g.) a single object on a screen to execute its animations over and over (if delta is <0, moving time back and allowing an object to execute its animations again.
ANIM FADE <object> <time> <startColour> <endColour> <steps>
// change the colour (including alpha) of an object over time. Colours should be defined as hex values in AARRGGBB order, e.g. FFFFFFFF for fully opaque white.
ANIM SCALE <object> <time> <startH> <startV> <endH> <endV> <steps>
// change the scale of an object over time.
ANIM ROTATE <object> <time> <startRot> <endRot> <steps> <loop>
// rotate an object over time
ANIM SHOW <object> <time> <show>
// set the visiblity of an object. show == 0 will hide the object, otherwise it will be shown </nowiki>

== Strings ==

To allow for localization, strings displayed in UIs are referenced by IDs corresponding to entries in string files, typically DATA/TEXT/TEXT#.TXT or TEXT#.TXT in the current campaign directory. Text may also be assigned to UI components at runtime by scripts.

Some formatting of strings is possible using tags embedded in strings, similar to HTML.
* <nowiki><b>bold</b></nowiki>
* <nowiki><i>italics</i></nowiki>
* <nowiki>line break: <br></nowiki>
* <nowiki><h1>heading</h1></nowiki>
* <nowiki><colour=0xffffff>colour (red)</colour></nowiki>
* <nowiki>inline image: <img=filename.tga></nowiki>
* <nowiki>tinted inline image: <img=filename.tga colour=0xff0000></nowiki>
* <nowiki><c>small caps string</c></nowiki>
* <nowiki><fN>another font</f></nowiki> The numeric value N is the (base zero) index of the font in the fonts file, e.g. <f12>
* <nowiki><a>This is horizontally centered</a></nowiki> Centers the given line(s) horizontally in the text box.
* a double quote character in a string file must be escaped with a additional double quote, ex. "Please use the ""Show preview"" button"
* <nowiki>for line breaks, you may alternatively use a ~ character in the string files or \n in literal strings in script</nowiki>

You can embed clickable links in a string by using
<nowiki><html>http://www.slitherine.com</html>
<html>=0023Custom Link</html>
<html>http://www.slitherine.com|This is display text</html></nowiki>
for a url link (which will close the game and open the link in a browser if clicked), or a custom link (which will be caught in a UI script with event==1024 and the data parameter containing the 4 digit decimal value following the = sign). Custom strings must always start with =NNNN. Display strings can be shown rather than the links by using the | seperator, link first followed by the display string. Note you can add a LINKCOLOUR entry to a text object to change the colour that a link shows as when moused over.

== UI Scripting ==
You can attach a script to any UI control using the SCRIPT tag. Events propagate up the UI object hierarchy to any attached script. Generally you will use root object level scripts for general screen logic, and child-object scripts for more specific rendering components.

The hook functions for UI scripts are:
<nowiki>FUNCTION UI_OBJ_INIT()</nowiki>
Called once when the screen is loaded.
<nowiki>FUNCTION UI_OBJ_ACTIVATE(id)</nowiki>
Called when a screen is activated (shown) by the game.
<nowiki>FUNCTION UI_OBJ_DEACTIVATE(id)</nowiki>
Called when a screen is deactivated (hidden) by the game.
<nowiki>FUNCTION UI_OBJ_RENDER(x, y, width, height, pass, name, flags)</nowiki>
Called to allow scripts to do additional rendering on a control. All screen params are in 1024x768 space. The function is called twice each time the control is rendered, with the pass value set to 0 when called prior to default object rendering, and 1 when called after. Returning 9999 will prevent the default rendering of the control. flags - bit 0: pressed or selected (button only), bit 1: mouse over, bit 2: disabled, bit 3: invisible.
<nowiki>FUNCTION UI_OBJ_HANDLE(data, event, id, name)</nowiki>
Receives events from controls when they are actioned. The data parameter varies depending upon the control type, e.g. it is the region clicked in Region Map controls, or the clicked item in a list in a Listbox control. The event varies, but is generally 0 for a left mouse action, 1 for a right.
The id is the id of the actioned control. Use the IsUIObject system function to map this to a specific object name. The name is the name of the owning object (e.g. the object to which the script is attached).
<nowiki>FUNCTION UI_OBJ_UPDATE(mousex, mousey, buttons, over, dragging, flags, data)</nowiki>
Called on the object update, and providing information on the current mouse position, button states, object the mouse is over, and any object being dragged. The mouse coordinates are in 1024x768. The buttons value is a bitmask, with bit 0 being the left button state, and bit 1 being the right. The over and dragging values are object IDs as per the UI_OBJ_HANDLE function. data is the control-specific data value, currently only listboxes return a value (the index of the currently moused over item, -1 if none). Other control types always set this to zero.
The flags value can be one of the following values:

0 - normal per tick update
1 - the dragging object has just been dropped
<nowiki>FUNCTION UI_OBJ_EVENT(id, event, data)</nowiki>
This is called when a script uses the UIEvent command to trigger and event on another control. This can be used for inter-control communication.

== Tutorial Popups ==
You can set up automated, one-time tutorial messages when screens are shown, or when a control is actioned. These should be set up in DATA/TUT.TXT, with entries of the form:

<nowiki>[<object or screen name>]
POPUP <poupname> // optional, name of the screen used for the popup, defaults to TUTORIAL
STRING <string tag> // required string ID for the string to be shown (see below)
TEX <texture name> // optional texture to be applied to the popup when used (see below)
TAG <value> // optional tag value. Only show this popup when a TAG value is set in the mission chunk in the current campaign and the values match.

e.g.

[MainMenu] // this is a screen
STRING IDS_WELCOME_MESSAGE

[ScenEdUnitMode] // this is a button
POPUP MyCustomPopup
STRING IDS_EXPLAIN_UNIT_EDITING
TEX MyCustomTexture</nowiki>

The popup should have controls in it with names of the form <base>String, <base>Image, and <base>Quit - for example you will see that the default CORE/TUTORIAL.TXT file has controls TutorialString and TutorialQuit - the String and Image controls are optional, but Quit is always required and the game will throw an error if it is missing (as there would be no way to close the tutorial message). The string and texture entries from the entry are applied to the String and Image controls respectively.

You may set up a chunk for a given control or screen more than once, which will lead to them showing the first defined entry the first time it is seen/used, and the second the next time the player uses the control or enters the screen. Each time an entry is shown this state is saved (in a local TUT.INF file) to prevent the tutorial popup being shown more than once. Because of this state saving, you should always add new tutorial entries to the end of the file to avoid going out of sync with the saved data.

= UI Defaults =
Certain UI global values are set via UI settings files. The default values are in SYSTEM/UIDEFAULTS.TXT. They are listed below. Note that this file also includes any COLOURDICTIONARY chunk.

<nowiki>TOOLTIPCOLOUR // default tooltip colour
TOOLTIPOFFSETX // X offset of the tooltip from the cursor
TOOLTIPOFFSETY // Y offset of the tooltip from the cursor
TOOLTIPBORDER // width of the border around the tooltip text
TOOLTIP9SLICESIZE // 9 slice corner size in texture pixels
TOOLTIP9SLICEDRAWSIZE // draw size for 9 slice corner