
1. Compiling

The program uses only standard C++ libraries, so the provided Makefile under src/ should do via

make battle

In addition

make clean

can be used to delete all object files.


2. Running

The program is ran from the commandline with a configuration file name as argument as e.g.

./battle myconfig.cfg

The outpout will be to the console (to see the text-based display of the battlefield, make the console large...). In interactive mode the console takes keyboard input at a command prompt, in automatic mode the program runs through a specified number of iterations of a given battle and reports victory percentages in the end.

A sample of config files is provided in the examples/ folder.

Background reading material and a series of tutorials illustrating the usage of the software is provided at the site http://www.science-and-fiction.org/science/battle.html - this manual only contains a summary of the various options and commands.

3. Config file format

The config file needs to contain both single word and two word instructions. Single keywords delimit blocks, two keywords form a key-value pair that sets a parameter.

Valid block-delimiting keywords are
* config: sets overall configuration options
* unit_type: defines a type of military unit
* unit: defines one specific military unit on a given position
* unit_line: defines a row of individual units as batch command
* battlefield: defines size and resolution of the battlefield
* formation: defines a collection of units to be commanded together
* global_morale_check: defines an event that influences battle morale of other units
* terrain: defines the terrain elevation and/or cover of the battlefield
* event_trigger: creates an element that investigates a condition on the battlefield and returns a true/false value
* event_logic: creates a logical element that combines various event triggers or event logics using AND, OR, XOR or NOT
* event_result: creates a structure that can command a unit whenever an event trigger or logic is true

3.1 Configuration options

The config block contains options that determine how the simulation runs. Valid keywords are:

* run_iterations [number]: the number of iterations the simulation goes through the battle - a value of 1 will enter interactive mode, any other value automatic mode, defaults to 1
* y_limit_1 [number]: the y_position on the battlefield at which units of army 1 will be commanded to turn around to avoid getting off the field accidentially
* y_limit_2 [number]: the y_position on the battlefield at which units of army 2 will be commanded to turn around to avoid getting off the field accidentially
* damage_multiplier: an overall multiplier that sets how much damage is done when units fight - a lower value will make battles longer and less random, defaults to 1.0
* internal_timestep: the time resolution at which motion is processed
* battle_timestep: the time resolution at which battle results are processed 
* battle_verbose [true/false]: whether results of ongoing combat between units are displayed
* battle_terse[true/false]: whether short summary results of ongoing combat between units are displayed
* events_verbose [true/false]: whether significant events like a unit being overrun or fleeing are displayed
* auto_display [true/false]: whether the battlefield is shown after every time evolution step automatically
* colors [true/false]: whether Linux console color coding is used for the battlefield display to show units in contact, units with significant losses or units without ammunition
* check_morale [true/false]: whether battle morale checks are done at all for units
* check_los [true/false]: whether line-of-sight checks are done for ranged attacks

3.2 Unit type definitions

A unit type describes the capabilities of a certain class of military unit with the idea that this type is later instanced by the definition of individual units. Valid options are:

* speed [number]: the movement speed in meters/minute the unit can do in formation
* armour [number]: the level of armour protection of the soldiers
* attack [number]: the overall capability of the unit to fight
* ranged_attack [number]: the overall capability for ranged attacks
* ranged_defense [number]: the overall capability to defend against ranged attacks
* damage [number]: the capability for doing damage to the enemy in close combat
* ranged_damage [number]: the capability for doing damage in ranged attacks
* range [number]: the maximum range in meters for ranged attacks
* shots_per_min [number]: the number of shots per minute available when ranged attacks are done
* turn_deg_per_min [number]: the rate at which the unit can change its direction
* num_shots [number]: the number of shots for the ranged attack mode carried
* num_soldiers [number]: the total number of soldiers serving in the unit (used when not in formation)
* num_ranks [number]: the number of ranks in the formation
* num_files [number]: the number of files in the formation
* penalty_flank_attack [number]: the reduction of the unit's attack value when it is subject to a flank attack
* penalty_rear_attack [number]: the reduction of the unit's attack value when it is subject to a rear attack
* bonus_mounted_charge [number]: the bonus in attack value when the unit conducts a mounted charge (i.e. is above the charge speed threshold)
* mount_weight [number]: the weight of the mount for mounted units
* soldiers_per_mount [number]: the number of soldiers that share a mount
* equiv_combat_power [number]: the equivalent combat power in soldiers of a unit of mount(s) and soldiers
* name [string]: a name for the unit type
* mount[string]: the description of the mount - 'horse', 'elephant' and 'chariot' use pre-defined values and require no mount_weight, soldiers_per_mount or _equiv_combat_power


3.3 Unit definitions

The unit definition specifies a particular instance of a unit type definition at a certain place on the battlefield. Valid keywords are:

* army [1 or 2]: which army the unit serves in
* pos_x [number]: the x-coordinate in m of the unit's position on the battlefield
* pos_y [number]: the y-coordinate in m of the unit's position on the battlefield
* dir_x [number]: the x-coordinate of the direction vector indicating where the unit is facing
* dir_y [number]: the y-coordinate of the direction vector indicating where the unit is facing
* morale [number]: the battle morale of the unit, on a range somewhere between 0 and 20
* tgt_x [number]: the x-coordinate in m of a target to move towards
* tgt_y [number]: the y-coordinate in m of a target to move towards
* assembly_x [number]: the x-coordinate of the assembly point to which the unit moves when it receives a retreat command
* assembly_y [number]: the y-coordinate of the assembly point to which the unit moves when it receives a retreat command
* order_par_1: the first parameter of an order that takes arguments
* order_par_2: the first parameter of an order that takes arguments
* dist_to_engage [number]: the distance in m upon which the unit starts to move to intercept other units if an observation order is given
* dist_to_fire [number]: the distance at which ranged combat is started
* dist_to_disengage [number]: in a hit and run pattern, the distance at which movement away from the target is started
* name [string]: the name of the unit
* tag [string]: a shorthand for commanding the unit and displaying the unit, by default 2 characters long
* type [string]: the unit type (must be the name of a unit type defined elsewhere)
* order [string]: the current order the unit is supposed to carry out (see below)
* secondary_order [string]: the observation order the unit is to carry out (see below)
* upon_contact [string]: the combat order the unit is to do when in contact with an enemy
* upon_position [string]: the order the unit is to carry out when it has reached a specified position
* upon_victory [string]: the order the unit is to carry out after it has won an encounter
* upon_ammo [string]: the order the unit is to carry out when amunition runs out
* upon_target [string]: the order the unit is to carry out when a ranged target is destroyed
* assign_to [string]: the name of the formation (see below) to which the unit is assigned
* target [string]: the tag of another unit that is to be attacked

3.4 Unit line definitions

The unit line is a batch command to specify a large number of units of the same type that are arrayed in a row. Valid keywords are:

* army [1 or 2]: which army the unit serves in
* pos_x [number]: the x-coordinate in m of the unit's position on the battlefield
* pos_y [number]: the y-coordinate in m of the unit's position on the battlefield
* dir_x [number]: the x-coordinate of the direction vector indicating where the unit is facing
* dir_y [number]: the y-coordinate of the direction vector indicating where the unit is facing
* morale [number]: the battle morale of the unit, on a range somewhere between 0 and 20
* num_units [number]: the number of unit contained in the line
* spacing_x [number]: the x-separation in m between units in the line
* spacing_y [number]: the y-separation in m between units in the line
* name [string]: the name of the unit
* tag [string]: a shorthand for commanding the unit and displaying the unit, by default 2 characters long
* type [string]: the unit type (must be the name of a unit type defined elsewhere)
* assign_to [string]: the name of the formation (see below) to which the unit is assigned

3.5 Formations

Formations serve as a 'container' of many different units so they can be commanded in a simple way. A formation is defined via

* name [string]: the name of the formation
* order [string]: the current order the units in the formation are supposed to carry out (see below)
* secondary_order [string]: the observation order the units in the formation are to carry out (see below)
* upon_contact [string]: the combat order the units in the formation are to do when in contact with an enemy
* upon_position [string]: the order the units in the formation are to carry out when it has reached a specified position
* upon_victory [string]: the order the units in the formation are to carry out after it has won an encounter
* upon_ammo [string]: the order the units in the formation are to carry out when amunition runs out
* upon_target [string]: the order the units in the formation are to carry out when a ranged target is destroyed
* order_par_1: the first parameter of an order that takes arguments
* order_par_2: the first parameter of an order that takes arguments

3.6 Terrain

Terrain is mostly defined by loading external files - be it elevation or cover maps or an elevation grid file. The relevant keywords are

* elevation_map [string]: A file containing interpolation points to describe terrain elevation
* elevation_grid [string]: A file containing elevation information on a regular grid identical with the battlefield
* surface_map [string]: A file containing the terrain surface type as an integer index
* surface_atlas [string]: A file mapping a surface type index to surface properties
* terrain_plot_name [string]: A filename into which the 3d plot of the generated terrain is written
* surface_map_size_x [number]: The number of cells in x-direction specified in the map
* surface_map_size_y [number]: The number of cells in y-direction specified in the map

3.7 Event trigger

An event trigger is a structure that changes value to 'true' when a certain condition on the battlefield is met. Relevant keywords are

* id [string]: The unique id of the trigger
* logic [string]: The logic (AND, OR, XOR or NOT) used to merge channels
* formation_destroyed [string]: The name of a formation that is investigated for destruction
* unit_destroyed [string]: The name of a unit that is investigated for destruction
* unit_destroyed_2 (_3.._5) [string]: as above
* line_crossed [string]: The name of a unit that is investigated for a line-crossed event
* line_crossed_2 (_3..5) [string]: as above
* unit_engaged [string]: The name of a unit that is investigaed for battle participation
* unit_engaged_2 (_3.._5) [string]: as above
* unit_destroyed_fraction [number]: The fraction of soldiers to be inactive such that a unit is counted as destroyed
* formation_destroyed_fraction [number]: The fraction of units in a formation to be inactive such that a formation is counted as destroyed
* line_crossed_y [number]: The y-value on the battlefield that a unit must cross
* line_crossed_sign[+1/-1]: The sign that determines whether a line needs to be crossed from above or below

3.8 Event logic

* id [string]: The unique id of the logic element
* type [string]: The logic (AND, OR, XOR or NOT) used to merge channels
* input_1 (_2.._5): The ids of other triggers and logic elements that are processed by the logic

3.9 Event result


* trigger_id [string]: The unique id of a trigger or logic that activates this command when changing to true
* command_formation [string]: The formation to which a command is given
* command_unit [string]: The tag of a unit to which a command is given
* order [string]: The command that is given
* order_par_1 [number]: The (optional) first parameter that is passed with the order
* order_par_2 [number]: The (optional) second parameter that is passed with the order

4. Interactive mode

If only one iteration is requested, the program enters interactive mode and holds to expect input at the command prompt. The user can then enter instructions. Possible are 

* instructions to the simulation
* instructions to a single unit
* instructions to a formation

4.1 Instructions to the simulation

Such instructions are typed directly (i.e. without prefix). Valid commands are:

* show_battlefield: put a text-based rendering of the current situation on the battlefield into the console
* evolve [number]: evolve the simulation for the specified number of minutes
* advance [number]: as above
* go [number]: as above
* report_status: report the current number of active vs. routed soldiers for both armies
* color [scheme]: sets the color scheme of the display (if selected). Valid schemes are 'ammo' (shows remaining ammunition of ranged units), 'type' (shows whether units are ranged, mounted or heavily armored), 'slope' (shows terrain slope) and 'normal' (shows units in contact as well as damage)
* crop [left][right][up][down]: changes what portion of the battlefield is drawn, the numbers are fractions of the currently visible portion
* zoom [number]: set the scale to the selected number in meters per displayed cell (i.e. lower numbers mean higher resolution)
* zoom out: resets draw scale and borders to fill 
* get elevation [x] [y]: Get the terrain elevation at the position
* get elevation [unit name]: Get the terrain elevation at the unit position
* get slope [x] [y] [direction]: Get the terrain slope at the position into the specified direction
* get slope [unit name]: Get the terrain slope at unit position into the direction the unit is facing
* get distance [unit 1] [unit 2]: Get the distance between unit 1 and 2
* end: end the simulation
* exit: end the simulation
* q: end the simulation

4.2 Instructions to a unit

A single unit always needs to be addressed by typing 'unit <tag>' before the actual command, i.e. 'unit G1 advance_to 140 200' is a valid line.

See below for the list of movement orders that can be used.

Using the syntax 'unit [tag] report XX' the following properties can be reported:

* orders: the current set of orders
* damage: a breakdown of wounded and dead soldiers
* composition: number of soldiers, formation and capabilities
* position: the current position on the battlefield
* internal: a number of internal properties for debug purposes

4.3 Instruction to a formation

A formation needs to be addressed by prefixing 'formation <name>' before the actual command, i.e. 'formation greek_center advance' is a valid line. 'formation' may be abbreviated by 'f'. Commands are otherwise identical to those for units.

5. Orders

Orders can be given to units interactively as well as in the form of prior battle plans specified in the config file. There are movement orders telling units where to go, combat orders telling units how to react when engaging an enemy unit and observation orders that put the unit on lookout for certain events. Frequently orders take patameters.

5.1 Movement orders

* slow: move slowly into the current direction
* slow [number]: move slowly into the compass direction <number>
* slow_to [num1][num2]: move slowly to the battlefield position given by the coordinate pair
* advance: move into the current direction
* advance [number]: move into compass direction <number>
* advance_to [num1][num2]: move to the battlefield position given by the coordinate pair
* rush: move quickly into current direction
* rush [number]: move quickly into compass direction <number>
* rush_to [number]: move quickly to the battlefield position given by the coordinate pair
* run: move as fast as possible into current direction
* fall_back: move backwards as formation
* seek_enemy: find the nearest enemy unit and engage
* hit_and_run [num1][num2]: find the nearest enemy, approach to the distance [num1], then retreat to distance [num2], repeat the pattern 
* hit_and_retreat [num]: approach the nearest unit to the distance [num], then retreat to the assembly point for the unit
* engage [tag]: engage the unit with the specified tag

For mounted units the following aliases are possible:

* walk (alias for 'slow')
* trot (alias for 'advance')
* gallop (alias for 'rush')
* charge (alias for 'run')

5.2 Combat orders

* assault: make a dedicated attempt to overrun the enemy position, accepting own losses
* attack: make a normal attack on the enemy position
* hold_line: try to maintain the current position, but do not advance
* yield: fall back under enemy pressure, possibly minimizing own losses
* skirmish: try not to get into close contact with the enemy and rather keep him occupied

5.3 Observation orders

* engage_upon [number]: move towards an enemy unit when it gets closer than <number> meters
* guard: move towards an enemy unit when it gets closer than the pre-defined distance
* fire_upon [number]: start ranged attacks when a unit gets closer than <number> meters
* fire_at [tag]: open fire at the unit denoted by the specified tag


