TOTAL WAR WIKI

Battle XML Documentation

Battle XML

The battle XML for any scripted battle is the effective entry-point for the game to load that battle. Within it are defined the armies and their layout on the battlefield and a link to the script to run. This file lives within the map folder and is required for the battle to run.

Contents

Environment Settings - Do This First

Before beginning the process of creating a scripted battle, some user variables need to be set. These will tell the game to load in a state which provide more features and feedback to the user which are helpful for creating scripted battles. In explorer, browse to the following path:- 

%AppData%\The Creative Assembly\Shogun2\scripts

Here there should be a file called preferences.script.txt. Open it in an editor, and search for the following term:- 

show_debug_ui

If this exists and is set to false, set it to true instead. If it doesn't exist, append the following to the end of the file:- 

show_debug_ui true;

Then save and close the file.

Next, make a copy of preferences.script.txt in the same folder and give the copy the following name:- 

user.script.txt

Open this new file and replace the contents with the following (note: if user.script.txt already exists, the following script may simply be appended to the existing contents of the file):- 

log_lua_errors_to_file;
log_lua_output_to_file;
battle_xml_to_file;

These settings will enable lua and battle xml logging, as well as the debug user interface which will display camera and cursor co-ordinates. They are required for the rest of these instructions to work.

Creating a Battle XML

TEd does not automatically write a battle XML, you have to create one yourself. A sample XML can be found in the example battle.

Copy the example (or any other working xml) into a file called battle.xml in the folder pertaining to your battle in:- 

%AppData%\The Creative Assembly\Shogun2\Maps

Workflow

1. Creating an XML by copying

When creating a new scripted battle, duplicate a working XML from an existing battle and edit it, rather than trying to write your own from scratch.

2. Learn XML comment syntax

Sections of XML can be commented out and prevented from working using the following syntax:- 

<!-- 
	<tag>This tag isn't being read!</tag>
-->

3. Create units by hand

When laying out armies for the first time, do it roughly by hand. Copy and paste the individual units within the XML until the required number is reached, and edit their unit keys and number of men. Do not worry about their positions for the moment.

4. Allowing free deployment on the battlefield

If the <battle_script> tag (within the <battle_description> tag) which specifies the script to run is commented out, the battle script will be prevented from executing and the battle will enter deployment phase when run, allowing deployment of units around the battlefield. This is useful because it allows units to be freely positioned in the desired start positions.   Then, when the Start Battle button is clicked the game will write a version of the XML to the following file:- 

%appdata%\The Creative Assembly\Shogun2\logs\battle.xml

If the player's units are deployed in their desired start position and then the Start Battle button clicked, the XML that gets written will contain the units in those positions. The positions, orientations and widths can then be copied from this output XML into the original source XML in the map folder. It's inadvisable to copy the entire XML in one go, however, as the output process tends to juggle the order of tags around and rewrites some unit special abilities. Instead, copy and paste each individual block of <position>, <orientation> and <width> tags, one at a time, from each outputted unit to the same unit in the source file.

5. Switching Sides

The player always controls the first army of the alliance defined in the battle XML (regardless of its specified id). By re-arranging the order in which the alliances are declared and repeating the above steps, the layout for any allied armies and the enemy alliance may be defined.

Elements of the Battle XML

A valid battle xml contains a heirarchy of objects defined within the xml itself. From a conceptual point of view, the main objects and how they are nested are described in the heirarchy structure below:- 

<battle>
	<alliance>
		<army>
			<unit>
			</unit>
		</army>
	</alliance>

	<battle_description>
	</battle_description>
</battle>

<battle>

This describes the battle as a whole. It must contain:-

  • Two <alliance> objects, laying out the alliances, armies and units on the battlefield.
  • A <battle_description> which gives miscellaneous info about the battle.
  • A <weather> object which mainly determines the sky environment.
  • A <sea_surface_name> which sets out the type of sea to use.

  <sea_surface_name>

Defines the choppiness of sea surface to be used on the battlefield. Valid levels are wind_level_0 to wind_level_2. 

<sea_surface_name>wind_level_2</sea_surface_name>
<weather>
The weather tag defines the prevailing wind and environment file.
<weather>
	<prevailing_wind x="-5" y="5"/>
	<environment_key>
		Weather\Japan\Sea\Summer\Day\Dry\Default_Summer_Day_Dry.environment
	</environment_key>
</weather>

The <prevailing_wind> tag defines a wind direction. The environment_key must point to an in-built environment file. A list of in-built environment files can be found in the supplied appendix file environments.txt.

<battle_description>

The battle description tag defines a collection of miscellaneous information about the battle. An example is given here:- 

<battle_description>
	<time_of_day>day</time_of_day>
	<season>Summer</season>
	<precipitation_type>dry</precipitation_type>
	<subculture>sc_japanese</subculture>
	<battle_script prepare_for_fade_in="true">script.lua</battle_script>
	<type>land_normal</type>
	<timeout_winning_alliance_index>1</timeout_winning_alliance_index>
	<duration>2400</duration>
</battle_description>
  • The <time_of_day> tag defines whether the battle takes place at day or night (although the lighting settings in the environment file determine the actual look of the battle). Possible values are "day" and "night".
  • The <season> tag defines the season. Possible values are "Spring", "Summer", "Autumn" and "Winter". Changing the season will drastically alter the visual appearance of your battle.
  • The <precipitation_type> alters the type of rain. Possible values are "dry", "rain", "fog" and "snow".
  • The <subculture> tag should be left as "sc_japanese".
  • The <battle_script> tag determines the lua script that should be loaded with the battle. This should be set to script.lua, which should live in the battle folder. The prepare_for_fade_in value sets the screen to start black if true, meaning the battle script will need to fade the camera in manually for the battlefield to become visible.
  • The <type> tag sets up whether the battle takes place at land or sea. Possible values are "land_normal" and "naval_normal".
  • The <timeout_winning_alliance_index> tag determines the alliance id which wins if the battle time ticks to zero. This tag is not required if there is no <duration> tag.
  • The <duration> tag sets the time limit on the battle in seconds.

<alliance>

The <alliance> tag describes each alliance block on the battlefield. An alliance can be made up of one or more armies of potentially different factions. The alliance an army or unit is in determines who it perceives as a friend or enemy on the battlefield.

An alliance object contains:-

  • One or more <army> objects, defining the various armies that make up the alliance,
  • One or more <victory_condition> objects, setting out the conditions under which this alliance wins the battle.
  • A <rout_position> object, which determines which direction men from this alliance will attempt to run when they rout.

<rout_position>

Determines a position on the battlefield which men of this alliance will attempt to run to when routing. 

<rout_position x ="0" y = "1300"></rout_position>

<victory_condition>

This tag defines the set of conditions by which this alliance wins the battle. Each alliance must have at least one victory condition set up. More than one victory condition can be declared for an alliance - in this case, victory will be attained if either of the victory conditions is reached.

Here is an example set of victory conditions, specifying that the subject alliance will win the battle if it wipes out the enemy army or captures the settlement. This is a commonplace set of victory conditions for the attacking alliance in a siege. 

<victory_condition>
	<capture_settlement></capture_settlement>
</victory_condition>
<victory_condition>
	<kill_or_rout_enemy></kill_or_rout_enemy>
</victory_condition>

Supported victory conditions are "capture_settlement", "kill_or_rout_enemy" and " sink_or_surrender_enemy" (for naval battles).   <army> 

The <army> tag defines an army on the battlefield within an alliance. Within it are defined the units or ships the army is comprised of, but also some more general information about the army itself.

An army object contains:-

  • A <faction> tag defining the faction of the army.
  • A <deployment_area> for the army.
  • A <camera_start_position> and <camera_target_position> setting up the opening camera angle.
  • One or more <unit> or <ship> tags.

<faction>

Sets the faction of the army. Use as follows:- 

<faction>mori</faction>

A list of valid faction keys can be found in the reference file Faction keys.xlsx.

<deployment_area>

The deployment area determines the area on the battlefield where an army can initially start. It can be expressed in one of two ways, via individual co-ordinates defining an arbitrary shape or by a centrepoint, a height and a width. Distances are given in metres, with the centre of the battlefield being at (0, 0) and the battlefield extending from -1000 to 1000 in each dimension. However, deployment areas must not come within 50m of any edge of the battlefield.

Example of a deployment area defined by individual points:- 

<deployment_area>
	<position x='-500' y='-500'/>
	<position x='-500' y='-100'/>
	<position x='500' y='-100'/>
	<position x='500' y='-500'/>
	<orientation radians="0.00"/>
</deployment_area>

In the case of individual co-ordinates the points must be specified in a clockwise order.

Centrepoint, height and width:- 

<deployment_area>
	<centre x="0" y="400"/>
	<width metres="1200.0"/>
	<height metres="800.0"/>
	<orientation radians="0.0"/>
</deployment_area>

  <camera_start_position> and <camera_target_position>

Defines the start position for the camera if playing as this alliance. The y co-ordinate is the height:- 

<camera_start_position x="0" y="40" z="500" /> 
<camera_target_position x="0" y="22.5" z="440" />

<unit>

A unit tag defines an individual unit on the battlefield as a member of an army and an alliance. It specifies a number of characteristics about the unit. An example unit tag is given below:- 

<unit num_soldiers="60" script_name="Unit_Oda_01">
	<unit_type type="Inf_Missile_Bow_Ashigaru" />
	<position x="25" y="400"/>
	<orientation radians="3.14"/>
	<width metres="20.00"/>
	<unit_capabilities>
		<special_ability>flaming_arrows_ability</special_ability>
	</unit_capabilities>
<unit_experience level="1"/></unit>

Using the above as a template, a unit tag is made of the following data elements:-

  • num_soldiers defines the number of soldiers in the unit. The default number of soldiers for each unit type is given in Unit types.xlsx, although a different number may be specified.
  • script_name defines a name for the unit which the lua script can be made aware of, which can make things easier when it comes to reference this unit in script. Defining a script name is optional, or it can be left blank.
  • The <unit_type> tag specifies the type of unit. A complete list of the supported unit types can be found in the reference file Unit types.xlsx.
  • The <position> tag defines the position on the battlefield where this unit first spawns. Distances are given in metres, with (0, 0) being the middle of the battlefield.

The <orientation> tag defines the orientation the unit first appears facing in radians. An orientation of 0 makes the unit face north.

  • The <width> tag specifies the width of the unit when it spawns.
  • The <unit_capabilities> tag allows a custom set of unit abilities to be defined. All units have a default set of abilities (general units may be able to rally, archer units may be able to fire flaming arrows etc). Defining other capabilities here means the default set are thrown away and the specified capabilities used instead.

A list of unit capabilities can be found in the reference file unit capabilities.txt. Note that these have to be specified with a <special_ability> tag as-per the example above.

  • The <unit_experience> tag defines the experience of the unit, in an integer range from 0-9.

  <unit> (general)

A unit can also be specified as the general of an army by using the <general> tag, as-per the example below:- 

<unit num_soldiers="40" script_name="Unit_Oda_General">
	<unit_type type="Gen_Oda_Nobunaga"/>
	<position x="-610.95" y="-133.61"/>
	<orientation radians="1.50"/>
	<width metres="23.01"/>
	<unit_capabilities>
	</unit_capabilities>
	<general>
		<name>Oda Nobunaga</name>
		<star_rating level ="5"/>
		<portrait>data/UI/Portraits/custom/cards/Oda_Daimyo.tga</portrait>
	</general>
	<unit_experience level="4"/>
</unit>

A <name> and a <star_rating> for the general can be specified. In addition, a <portrait> can be specified. A list of valid portraits can be found in the reference file portraits.txt.

Retrieved from ‘https://wiki.totalwar.com/index.php?title=Battle_XML_Documentation&oldid=394’