TOTAL WAR WIKI

Battle Script Documentation

08 April 2015

14:56

 

Battle Scripts

 

Battle scripts allow content creators to specify custom behaviour in a battle. Unit behaviour, the camera, the user-interface and more can all be scripted.

 

 

Creating a Battle Script

TEd does not automatically create a battle script - one must be created manually. The example battle contains a sample script.

Battle scripts should live in one or more files with .lua extensions within the battle folder. A link to the first, main or starter script file (however your script is laid out) is made in the battle XML. For more information on this, see the Battle XML.docx file.

 

 

At a Glance

The battle object model is a LUA-script based system for controlling battles. First, an instance of empire_battle() is created:-

 

battle = empire_battle:new();

 

Use the alliances() collection to gain access to units & ships:-

 

alliances = battle:alliances();

 

The alliances object is the root object in a hierarchy (Alliances,Alliance,Armies,Army) that ultimately yields the list of units and ships for a given army. You can index into this list to get a reference to individual units, by ordinal or by name.

 

-- get a handle to the first alliance

alliance_01 = alliances:item(1);

 

-- get the armies collection from this alliance

armies_01 = alliance_01:armies();

 

-- get the first army within this collection

army_01 = armies_01:item(1);

 

-- get the collection of units from this army

units_01 = army_01:units();

 

-- get the first unit from this collection

unit_01 = units_01:item(1);

 

Various methods can be used on a ship or unit object to query it's current state (e.g. position in the world, number of men alive etc.)

 

if unit_01:number_of_men_alive() == 0 then

  unit_01_has_died();

end;

 

Issue commands to one or more units by creating a unitcontroller object on the army, adding the unit(s) to the controller, and calling command methods on the controller:-

 

uc_01 = army_01:create_unit_controller();

uc_01:add_units(unit_01);

uc_01:halt();

 

Debug text can be printed to the lua logfile by using battle:print():-

 

battle:print("This will appear in %appdata%\The Creative Assembly\Attila\logs\lua.log");

 

Script functions can be triggered in the future by calling battle:register_singleshot_timer():-

 

battle:register_singleshot_timer("test_function", 5000);

 

function test_function()

  battle:print("This will happen in 5000ms");

end;

 

They can also be repeatedly called by using battle:register_repeating_timer():-

 

battle:register_repeating_timer("test_repeat_function", 5000);

 

function test_repeat_function()

  battle:print("This will happen EVERY 5000ms");

end;

 

Positions on the battlefield can be declared with battle_vector:new(), and then set to a co-ordinate using set();

 

pos_test = battle_vector:new();

Pos_test:set(234, 0, -392);

 

 

Script API

Clearing cached files

If the script pulls in script files externally, it may be beneficial to clear these out before referencing them again at the start of the script:-

 

system.ClearRequiredFiles();

 

This probably isn't necessary for simple scripts that live in one file.

 

 

empire_battle

The empire_battle object is the root object for accessing (nearly) all other objects. In order to use it you must first create an instance of this object:-

 

battle = empire_battle:new();

 

This creates a new instance of the empire_battle object, and assigns it to the global LUA variable named battle. Nearly all subsequent object model access then occurs via this object.

 

Methods:

print

nil print(String str)

outputs the string to the lua log file.

 

random_number

number random_number()

Returns a random floating point number in the range 0 to 1.

 

modify_battle_speed

nil modify_battle_speed(Number speed)

Adjusts the games speed pause = 0.0, slow = 0.4, play = 1.0, fwd = 2.0, ffwd = 4.0.

NOTE: using this within a timer event may produce undesirable results, due to them being updated at the battle speed.

 

restore_battle_speed

nil restore_battle_speed()

restores the battle speed to the speed previously stored when modify_battle_speed() was called.

 

change_conflict_time_update_overridden

nil change_conflict_time_update_overridden(bool overridden)

call with overridden = true to stop the timer countdown towards victory; call with overridden = false to leave the clock counting down like normal. Useful if a cutscene is playing where the battle time should not count down.

 

change_victory_countdown_limit

nil change_victory_countdown_limit(Number time)

call with time < 0 to make it infinite. Call with time >= 0 to set the countdown time. This is in seconds. This sets the countdown period from the point the game thinks the battle has been won to the appearance of the battle results screen, which is useful if an outro is required.

 

suspend_contextual_advice

nil suspend_contextual_advice(bool suspend)

Call with suspend=true to suppress contextual advisor message, call with suspend = false to enable contextual advisor messages.

 

show_advisor_message

nil show_advisor_message(String localization_key, String default_message)

Outputs text to the in-game Advisor window UI. For user-created battles only un-localized text is supported.

Example:-

 

battle:show_advisor_message("", "Help help I’m being repressed");

 

close_advisor

nil close_advisor()

Dismisses the currently displayed advice.

 

alliances

alliances alliances()

Returns an Alliances object, which is the root of the unit hierarchy.

 

buildings

buildings buildings()

Returns a Buildings object, which is a collection of all buildings in the scene.

 

assault_equipment

assault_equipment assault_equipment()

Returns an assault_equipment object, which is a collection of all assault equipment (siege equipment, such as rams and ladders) on the battlefield.

 

camera

camera camera()

Returns a Camera object, which can be used to control the camera.

 

register_battle_phase_handler

nil register_battle_phase_handler(string handler_name)

Registers the function named handler_name as the name of the script function that will handle battle phase changes. This is used to start the main body of the script when the battle starts (as opposed to when the battle/script loads).

 

The function is called with an event object as its argument. The get_name() method on this object will return the name of the battle phase. Phase changes are:

Event name	Description
Startup	This event is fired once after the script is loaded. All inline script commands will have been executed. This event may fire after any timers that were registered with inline script.
Deployment	This event is fired at the start of the Deployment phase. Note that if you have disabled deployment in your battle XML, you will not receive this event.
Deployed	This event is fired when deployment has been completed. For battles that have an explicit deployment phase, this event is fired when the player hits the start battle UI button. For battles that skip deployment, this event is fired shortly after the “Startup” phase change event is received.
VictoryCountdown	Battle is complete, and victor has been decided; there is a time that will pass before actually finishing the battle.
Complete	Battle is complete, this is the last event that a script will receive on completion of the battle.

 

An example of all this is given here:-

 

-- phase change handler function

function handle_phase_change(event)

  -- any function registered as the phase change handler will be passed

  -- an event as a single parameter, which it can then inspect as follows

 

  if event:get_name == "Deployment" then

      entering_deployment()         -- we have entered "deployment" phase

  elseif event:get_name == "Deployed" then

      entering_battle();            -- we have entered "deployed" phase (battle start)

  end;

end;

 

-- register the function above as the phase change handler

battle:register_battle_phase_handler("handle_phase_change");

 

function entering_deployment()

  battle:out("Entering deployment phase!");

end;

 

function entering_battle()

  battle:out("Battle has started!");

end;

 

unregister_battle_phase_handler

nil unregister_battle_phase_handler()

Unregisters the current battle phase handler, the currently registered function will no longer be called.

 

register_singleshot_timer

nil register_singleshot_timer(String handler_name, [opt]Number ms_interval)

Registers the function named handler_name as a single shot timer handler. The function will be called once ms_interval milliseconds after the function is registered (actual time may be >= ms_interval). The default interval, if none is provided, is 1000ms (1 second).

The handler function should be declared with one arg, which is the elapsed game time, in milliseconds (scripts generally don't need to refer to this arg).

The handler is called once, when the interval expires.

The function is automatically unregistered prior to calling the handler function.

The handler should be declared as follows:

 

function my_timer_handler()

  -- do stuff

end

 

battle:register_singleshot_timer("my_timer_handler", 5000); -- call my fn in 5 seconds

 

The function must be declared in the source code before the call to register_singleshot_timer(), otherwise a script error will be raised.

 

register_repeating_timer

nil register_repeating_timer(String handler_name, [opt] Number ms_interval)

Registers the function named handler_name as a timer handler. The function will be called repeatedly every ms_interval milliseconds after the function is registered (actual time may be >= ms_interval). The default interval, if none is provided, is 1000ms (1 second).

 

The handler is called repeatedly, until the timer is unregistered.

 

Example, declare a repeating handler and unregister it after five calls.

 

num_calls = 0

 

function my_timer_handler(game_time)

  num_calls = num_calls + 1

  if numcalls == 5 then

      unregister_timer("my_timer_handler")

  end

end

 

battle:register_repeating_timer("my_timer_handler", 2000); -- call my fn every 2 seconds

 

The function must be declared in the source code before the call to register_singleshot_timer(), otherwise a script error will be raised.

 

unregister_timer

nil unregister_timer(String handler_name)

Unregisters the specified timer handler, the currently registered function will no longer be called. This can be used to unregister both singleshot and repeating timers. In the case of singleshot timers, it is only legal to remove them before they have been called, calling unregister_timer on a singleshot timer after the handler function has been called will raise a script error.

steal_escape_key

nil steal_escape_key()

Steals the escape key from the UI to allow lua scripts to detect and process key presses.

Escape key maps directly to a function called “Esc_Key_Pressed()” which you will need to implement in your lua files. Note: you must call release_escape_key when you are finished with it in order for the UI to retain its functionality.

 

release_escape_key

nil release_escape_key()

Releases the escape key back to the UI.

 

steal_input_focus

nil steal_input_focus()

Allows script to capture all input received, effectively disabling the keyboard in game, input focus MUST be released after it is no longer required. Useful for cutscenes.

 

release_input_focus

nil release_input_focus()

Releases the input focus back to the UI.

 

enable_cinematic_ui

nil enable_cinematic_ui(bool cinematic_ui, bool cursor, bool borders)

Enables or disables the cinematic ui and related ui options, which is useful for cutscene creation. Set the first parameter to true to enable the cinematic ui - this makes the regular ui disappear (set to false to achieve the reverse). The second parameter controls the visibility of the cursor, true is visible and false is not. The third parameter controls the visibility of cinematic borders at the top and bottom of the screen - again, true is visible and false is not.

 

Therefore, the following call will disable the regular UI in order to go into a cutscene:-

 

battle:enable_cinematic_ui(true, false, true);

 

This call re-enables the regular ui when coming out again:-

 

battle:enable_cinematic_ui(false, true, false);

 

game_time

Number game_time()

Returns the elapsed game time, in seconds. This is *not* real time, as the returned time incorporates any time multipliers due to the current game speed.

 

suppress_unit_voices

nil suppress_unit_voices(bool suppress)

Call with suppress=true to suppress unit voice over, suppress=false to resume unit voice over. Useful for cutscenes with spoken dialogue.

 

 

Alliances

This object is the root object of a hierarchy of objects that mirror the organization of the units/ships in the battle environment xml file.

The Alliances object is a collection of Alliance objects.

 

count

number count()

Retrieves the count of alliances in the alliance list.

 

item

alliance item(Number n)

Retrieves the n'th Alliance object in the list of alliances, where n is a 1-based index. By convention item(1) is the friendly Alliance, and item(2) is the enemy Alliance.

 

 

Alliance

This object wraps a collection of armies for an alliance.

 

armies

armies armies()

Returns an Armies object, which is collection of Army objects.

 

create_ai_unit_planner

AI_Unit_Planner create_ai_unit_planner()

Create an instance of an AI objective planner. These can be used to give general objectives to groups of units such as "defend this position" or "attack that unit".

 

 

Armies

The armies object is a collection of individual army objects.

 

count

number count()

Retrieves the count of army objects in the armies list.

 

item

army item(Number n)

Retrieves the n'th army object in the list of armies, where n is a 1-based index.

 

 

Army

This object represents an individual Army.

 

units

units units()

Returns a units object, which is a list of all the units in the army.

 

get_reinforcement_units

units get_reinforcement_units()

Returns a units object, containing a list of any reinforcing units to this army.

 

create_unit_controller

unitcontroller create_unit_controller()

Creates a new unitcontroller object, which is used to issue commands to units.

 

is_commander_alive

bool is_commander_alive()

Returns whether the commander of this army is still alive.

 

quit_battle

bool quit_battle()

Instantly tell this army to quit the battle.

 

army_handicap

Number army_handicap()

Returns the handicap for the army, which is based on an enum list:-

Difficulty	Value
Easy	1
Normal	0
Hard	-1
Very Hard	-2

 

 

Units

There is a single unique unit object for every unit in the battle.

The units object is a collection of unit objects. The collection can be queried by ordinal index, or by unit name.

 

count

number count()

Retrieves the count of units in the units list.

 

item

Unit item(number n)

Unit item(string unit_name)

If an integer parameter is given, this function retrieves the n'th unit object in the list of units, where n is a 1-based index. If a string parameter is given the function looks up the unit by name, the name being given in the battle XML.

 

kill_commander

nil kill_commander()

Kills the commanding entity of the current army.

 

 

Unit

Represents an individual unit.

 

name

string name()

Returns the name of the unit. If the unit has a script_name parameter in the battle xml, the return value will be the script_name. If the unit has no script_name attribute, the 1-based index of the unit in it's army will be returned e.g. "1" for the first "10" for the 10th.

 

position

vector position()

Returns a vector object containing the position of the main body of soldiers in the unit.

 

ordered_width

number ordered_width()

Returns the width of the unit; if the unit is moving this will be the width the unit desires.

 

bearing

Number bearing()

Returns the bearing of the unit, in degrees, relative to north.

 

is_moving

bool is_moving()

Returns true if the unit is moving, false otherwise.

 

is_moving_fast

bool is_moving_fast()

Returns true if the unit is moving fast (or routing), false otherwise.

 

is_idle

bool is_idle()

Returns true if the unit has finished their order and are not doing an interrupted action e.g. firing at will.

 

unit_in_range

bool unit_in_range(Unit unit)

Returns true if the enemy unit is in firing range of this unit. This method takes into account the firing arc, orientation etc. of the unit (using exactly the same logic as the AI).

 

initial_number_of_men

number initial_number_of_men()

Returns the number of men initially in the unit.

 

number_of_men_alive

number number_of_men_alive()

Returns the number of men alive in the unit.

 

unary_of_men_alive

number unary_of_men_alive()

Returns the ratio of men alive in the unit, as a float (between 0 - 1).

 

number_of_enemies_killed

number number_of_enemies_killed()

Returns the number of enemies this unit has killed.

 

kill_number_of_men

nil kill_number_of_men(number amount_to_kill)

Kill off a number of men in the unit.

 

position_of_officer

vector position_of_officer()

Returns a Vector object containing the position of the man in charge.

 

is_leaving_battle

bool is_leaving_battle()

Returns true if the unit is leaving the battlefield, false otherwise.

 

is_routing

bool is_routing()

Returns true if the unit is routing, false otherwise.

 

is_shattered

bool is_shattered()

Returns true if the unit is shattered, false otherwise.

 

is_valid_target

bool is_valid_target()

Returns true if the unit is valid to attack, false otherwise.

invalid = leaving or entering battlefield / hidden / dead

 

missile_range

number missile_range()

Returns the distance, in game units (meters) for the range of the unit's currently selected missile.

 

unit_distance

number unit_distance(Unit unit)

Returns the distance, in game units (meters) for distance between both units, taking into account the units bounding box and direction, in order to provide the shortest distance between units as opposed to just going off the centred positions.

 

ammo_left

number ammo_left()

Returns the amount of ammo left for a particular unit.

 

starting_ammo

number starting_ammo()

Returns the amount of ammo a particular unit started with.

 

set_current_ammo_unary

nil set_current_ammo_unary(number unary_amount)

Sets the amount of ammo left, relative to the unit's starting ammo. set_current_ammo_unary(1) would reset the units ammo to the starting amount.

 

is_cavalry

bool is_cavalry()

Returns true if the unit is a cavalry unit, false otherwise.

 

is_currently_garrisoned

bool is_currently_garrisoned()

Returns true if the unit is inside a building.

 

is_infantry

bool is_infantry()

Returns true if the unit is a infantry unit, false otherwise.

 

is_artillery

bool is_artillery()

Returns true if the unit is a artillery unit, false otherwise.

 

is_limbered_artillery

bool is_limbered_artillery()

Returns true if the artillery unit is limbered, false otherwise.

 

can_perform_special_ability

bool can_perform_special_ability(string ability)

Queries the unit to see if the special ability is in its capabilities.

 

current_special_ability

String current_special_ability()

Returns a string containing the units current special ability (if any).

 

deploy_reinforcement

nil deploy_reinforcement(bool manual)

If the unit is a reinforcement that is not yet deployed, setting this to false will prevent it from deploying until it is set to true again (keeping with the current constraints of units being drip fed into a battle), allowing you to be able to delay deployment of reinforcements.

 

 

Unitcontroller

A unitcontroller is a container for unit objects that you want to control of i.e. issue commands to.

 

In order for a unitcontroller to issue commands it must take the unit's it controls out of AI control - to avoid conflicting control. The unitcontroller implicitly takes control of any units it controls prior to issuing a given command. You can explicitly take and release control (back to the AI) using methods on the unitcontroller (take_control() and release_control()).

 

A unitcontroller manages one or more unit groups and a list of individual units. Each group of units that the controller manages moves together - organising themselves into a specific formation. The individual units under control all move autonomously.

Theer are two 'flavours' of command for many of the commands - immediate execution or queued. Any command with the "_q" suffix e.g. "withdraw_q" is a queued variation of the command. Queuing commands is a way of setting up a sequence of actions to be taken - e.g. setting a series of way points.

 

add_units

nil add_units(<list>)

Adds one or more units to the controller as independent autonomous units.

 

take_control

nil take_control()

Takes script control of all units, removing them from AI control. take_control() is called internally prior to issuing any command - so all units in the controller will be under script control until explicitly removed.

 

release_control

nil release_control()

Returns control of units back to the AI. Note that the AI may, in some circumstances, appear behave strangely when they are returned to the AI, as the AI will start to provide orders based on it's own algorithms.

 

clear_all

nil clear_all()

Removes all units from the controller - units are still left under script control unless explicitly released with release_control()

 

halt

nil halt()

Issue the halt command immediately to controlled units. All units will come to a stand-still. Takes script control of all units.

 

withdraw

nil withdraw()

Issues the withdraw command immediately to all units, causing them to retreat. Takes script control of all units.

 

withdraw_q

nil withdraw_q()

Queues a withdraw command to all units, which will be processed after all currently queued commands have been executed. Otherwise identical to withdraw().

 

fire_at_will

nil fire_at_will(bool fire_at_will)

Sets the fire-at-will status of all controlled units to true or false.

 

kill

nil kill()

Instantly kills all controlled units. Units will be rendered in thier dead pose.

 

attack_unit

nil attack_unit(unit target_unit, bool primary_attack, bool move_fast)

Instructs controlled units to immediately attack the target unit.

If primary_atatck is true, units will use their primary attack.

If move_fast is true, units will use fast move speed.

 

attack_unit_q

nil attack_unit_q(unit target_unit, bool primary_attack, bool move_fast)

Queues up an order to attack the target unit.

If primary_attack is true, units will use their primary attack.

If move_fast is true, units will use fast move speed.

 

rotate

nil rotate(number degrees, [optional] bool move_fast)

Order controlled units to rotate about their current heading by the number of degrees. The optional second arg controls whether they move fast, or not.

 

rotate_q

nil rotate_q(number degrees, [optional] bool move_fast)

Queues an order for the controlled units to rotate about their current heading by the number of degrees. The optional second arg controls whether they move fast, or not.

 

step_forward

nil step_forward()

Orders controlled units to take a single step forward.

 

step_backward

nil step_backward()

Orders controlled units to take a single step backward.

 

change_move_speed

nil change_move_speed(bool move_fast)

Orders controlled units to move fast, or at regular speed.

 

increment_formation_width

nil increment_formation_width()

Orders controlled units to increase their formation width by one soldier.

 

decrement_formation_width

nil decrement_formation_width()

Orders controlled units to decrease their formation width by one soldier.

 

change_formation

nil change_formation(string formation_name)

Instructs controlled units to adopt a new named formation. A list of formations can be found in the formations table in the database.

 

change_formation_q

nil change_formation_q(string formation_name)

Queues an order to adopt a new formation.

 

perform_special_ability

nil perform_special_ability(string ability_name)

Orders units to perform a special ability.

Before issuing this command we check that all the special ability is legal for all controlled units. If the ability is not valid for any of the units, a script error results.

 

perform_special_ability_q

nil perform_special_ability_q(string ability_name)

Queues an order to perform a special ability.

 

change_shot_type

nil change_shot_type(string shot_type)

Orders units to change shot type.

Before issuing this command we check that all the shot type is legal for all controlled units. If the shot type is not valid for any of the units, a script error results.

 

change_shot_type_q

nil change_shot_type_q(string shot_type)

Queues an order to perform change of shot_type.

 

skirmish

nil skirmish(bool on_off)

Orders units to go into skirmish mode, or not.

 

goto_location

nil goto_location(vector vector, [optional] bool move_fast)

Orders units to move to a specified position. The optional move_fast arg controls the speed of the move.

 

goto_location_q

nil goto_location_q(vector vector, [optional] bool move_fast)

Queues an order to move to a specified location.

 

attack_location

nil attack_location(vector vector, [optional] bool move_fast)

Orders units to attack a specified position.

This command is intended for ranged missile units, such a cannons, to order them to shell a specific location.

 

attack_location_q

nil attack_location_q(vector vector, [optional] bool move_fast)

Queues an order to attack a specified position.

 

occupy_zone

nil occupy_zone(vector vector, bool move_fast)

Instructs units to occupy a zone near the location specified, if found. A battlefield zone is a defensible position, like a castle wall.

 

occupy_zone_q

nil occupy_zone_q(vector vector, bool move_fast)

Instructs units to occupy a zone near the location specified, if found.

 

attack_building

nil attack_building(building building, [optional] piece index, [optional] bool move_fast)

Instructs units to attack the given building. The optional piece index identifies the piece of the building to attack, as a 1-based index.

 

attack_building_q

nil attack_building_q(Building building, [optional] piece index, [optional] bool move_fast)

Queues an order to attack the given building. The optional piece index identifies the piece of the building to attack, as a 1-based index.

 

climb_building

nil climb_building(Building building, [optional] piece index, [optional] bool move_fast)

Instructs units to scale the given building. The optional piece index identifies the piece of the building to attack, as a 1-based index.

 

climb_building_q

nil climb_building_q(Building building, [optional] piece index, [optional] bool move_fast)

Queues an order to scale the given building. The optional piece index identifies the piece of the building to attack, as a 1-based index.

 

occupy_vehicle

nil occupy_vehicle(vehicle vehicle, [optional] bool move_fast)

Instructs units to occupy the given vehicle.

 

occupy_vehicle_q

nil occupy_vehicle_q(vehicle vehicle, [optional] bool move_fast)

Queues an order to attack the given vehicle.

 

attack_line

nil attack_line(vector start, vector end, [optional] move_fast)

Orders controlled units to attack a given line, running from start to end. The optional move_fast flag controls the speed that they move to attack the line.

 

attack_line_q

nil attack_line_q(vector start, vector end, [optional] move_fast)

Queues an order to attack a given line, running from start to end. The optional move_fast flag controls the speed that they move to attack the line.

 

goto_location_angle_width

nil goto_location_angle_width(vector location, number angle_degrees, number width, [optional] move_fast)

Orders units to go to a given location, and align the formation to angle_degrees, with a formation width of width world units (meters).

 

goto_location_angle_width_q

nil goto_location_angle_width_q(vector location, number angle_degrees, number width, [optional] move_fast)

Queues an order to go to a given location, and align the formation to angle_degrees, with a formation width of width world units (meters).

 

teleport_to_location

nil teleport_to_location(vector location, number angle_degrees, number width )

Tells the controller to go a given location, instantaneously. Align the formation to angle_degrees, with a formation width of width world units (meters).

 

morale_behavior_fearless

nil morale_behavior_fearless()

Causes all units in the controller to behave fearlessly, units will never rout.

 

morale_behavior_rout

nil morale_behavior_rout()

Causes all units in the controller to immediately rout.

 

morale_behavior_default

nil morale_behavior_default()

Switches all units in the controller to default morale behavior, cancelling any previous call to morale_behavior_fearless() or morale_behavior_rout().

 

set_invincible

nil set_invincible(bool invincible)

Call with a true argument to make all units in the controller invincible, set to false to return them to being mortal.

 

set_invisible_to_all

nil set_invisible_to_all(bool invisible, [optional] bool update_ui)

Call with a true argument to make all units in the controller invisible to everyone (including yourself; including on the UI), set to false to return them to being seen normally (including hiding as normal)

The second parameter allow you to not update the UI, defaulting to true. Highly recommended not to change this, except under specific circumstances

 

change_enabled

nil change_enabled(bool visible)

Call with a true argument to make all units in the controller enabled; which is normal behaviour.

Call with false to stop them from taking ANY part in the battle.

 

melee

nil melee(bool active)

Switches all units in the controller between melee and normal.

 

close_formation

nil close_formation(bool close)

Switches all units in the controller between loose and normal (true for close, false for loose).

 

select_deployable_object

nil select_deployable_object(String ability_name)

Allows the units to use deployable objects such as gabionades etc.

 

change_fatigue_amount

nil change_fatigue_amount(number relative amount)

Change the fdatigue omount of the units; relative to their current level

i.e. 0.5 is half, 1.0 is same, 2.0 is double.

NB: don't pass in 0.0, as this would cause divide by 0, just make it something like 0.01

 

 

 

Buildings

A collection of buildings present in the scene, accessed from the battle object.

 

count

number count()

Retrieves the count of buildings in the building list.

 

item

building item(number n)

Retrieves the n'th Building object in the list of buildings, where n is a 1-based index.

 

 

 

Building

A representation of a specific building from the battlefield in script.

 

position

vector position()

Returns a Vector containing the 3D position of the Building in the scene.

 

central_position

vector central_position()

Returns a Vector containing the central position of the Building model, not the pivot point.

 

alliance_owner_id

number alliance_owner_id()

Returns a Number containing the alliance owner's id (-1 if nobody).

 

name

string name()

Returns the name of the building.

 

show

nil show()

Shows the building visually, and adds it from the object-avoidance list – so troops path-find around the hidden building.

 

hide

nil hide()

Hides the building visually, and removes it from the object-avoidance list – so troops can pass right though the hidden building.

 

health

number health()

Returns the current health of the building, floating point value ranging from 0.0 to 1.0.

 

change_on_fire

nil change_on_fire(bool value)

Change whether the building should be on fire.

 

change_immune_to_fire_damage

nil change_immune_to_fire_damage(bool value)

Change whether the building should take damage from being on fire.

 

change_immune_to_catching_fire

nil change_immune_to_catching_fire(bool value)

Change whether the building should be allowed catch fire.

 

change_is_destructible

nil change_is_destructible(bool value)

Change whether the building should take damage.

 

 

Vector

The Vector Object represents a 3D [x,y,z] point on the battlefield. NB the y component is the height of the position above the sea plane, with the x and z components being longitude/latitude from the centre of the map, which is at [0,0]. Thus, a co-ordinate of [-160, 40, 300] is 160m west and 300m north of the centre of the map, and 40m above the sea plane. Note that that doesn't necessarily mean the point is above the ground.

In addition to the methods on the Vector object, Vector objects also obey Vector arithmetic, and so can be added, subtracted, divided and multiplied using standard LUA operators.

Various script methods return a pointer to a Vector object; in addition you can create a new instance of a Vector object in script, using the new() operator, or using the constructor syntax.

e.g.

my_vector = battle_vector:new();

This creates a new instance of a Vector object, and returns a reference to it in the variable named my_vector.

or

battle_vector([optional] [Number x, Number y, Number z] )

Vector constructor, takes either zero or three args. A Vector constructed with zero args is initialized with (0,0,0)

my_vector = battle_vector(2,20,3);

 

get_x

number get_x()

Returns the x property.

 

get_y

number get_y()

Returns the y property.

 

get_z

number get_z()

Returns the z property.

 

set_x

nil set_x(number n)

Sets the x property.

 

set_y

nil set_y(number n)

Sets the y property.

 

set_z

nil set_z(number n)

Sets the z property.

 

set

nil set(number x, number y, number z)

nil set(vector v)

Sets the x,y & z properties simultaneously. Alternatively, pass in another vector to set the subject vector to the same value.

 

distance

number distance(vector from_vector)

Returns the distance from this vector to another vector

 

distance_xz

number distance_xz(vector from_vector)

Returns the distance from this vector to another vector in flat XZ space.

 

to_screen_position

vector to_screen_position()

Returns the screen coordinates of a world-space position, using the current camera to compute the projection.

The returned vector is in screen space coordinates so +1..-1 in screen X & Y, 0..1 in Z space.

 

length

Number length()

Returns the length of this vector, the distance from the origin [0,0,0]

 

length_xz

Number length_xz()

Returns the length of this vector in flat XZ space.

 

 

 

Assault Equipment

A list of all siege vehicles, such as rams and towers, on the map. The list can be queried and handles to individual vehicles can be acquired.

 

vehicle_count

number vehicle_count()

Returns the number of siege vehicles in the assault equipment list.

 

vehicle_item

vehicle vehicle_item(number entry_number)

Returns the vehicle at the given entry in the equipment list. The list has a 1-based index.

 

 

 

Vehicle

A script object representing a siege vehicle.

 

position

vector position()

Returns a vector indicating the position of the siege vehicle.

 

 

 

Camera

The Camera object is used to trigger camera transitions to focus the camera on scripted activity in the battle.

 

look_at

nil look_at(vector point, number transition_duration, [opt] number angle_degrees, [opt] bool linear, [opt] number field_of_view)

Triggers a camera transition which ends with the camera looking at the specified point in the world, from the given angle, if specified. If no angle is specified, the camera’s current facing is used instead.

transition_duration - duration of transition in seconds if positve, scale of auto calculated transition duration if negative.

linear - is transition linear or slow-fast-slow, default is false

field_of_view - field of view in degrees if positive, in game default field of view if zero, use current field of view if negative

 

move_to

nil move_to(vector position, vector target, number duration, [opt] bool linear, [opt] number field_of_view)

Triggers a camera transition which ends with the camera looking at the specified target in the world, from the specified position.

transition_duration - duration of transition in seconds if positve, scale of auto calculated transition duration if negative.

linear - is transition linear or slow-fast-slow, default is false

field_of_view - field of view in degrees if positive, in game default field of view if zero, use current field of view if negative

 

position

Vector position()

Returns the battle cameras position vector.

 

target

Vector target()

Returns the battle cameras look at vector.

 

change_depth_of_field

nil change_depth_of_field(number transition_duration, [opt] number focal_distance, [opt] number focal_length, [opt] number blur_size)

Changes the camera depth of field.

transition_duration - duration of transition in seconds

focal_distance - if ommitted use game defaults for this and all subsequent parameters

focal_length - must be present if focal_distance is present

blur_size - must be present if focal_distance is present

 

fade

nil fade(bool to_black, number transition_duration)

 

to_black - fades out to black if true, fades in if false

transition_duration - duration of transition in seconds

 

change_height_range

nil change_height_range(number min_height, number max_height)

 

Changes the height range of the camera above the ground.

 

min_height - minimum height of the camera above the ground - if negative use game default

max_height - maximum height of the camera above the ground - if negative use game default

 

enable_shake

nil enable_shake()

Enables camera shake.

 

disable_shake

nil disable_shake()

Disables camera shake.

 

enable_anchor_to_army

nil enable_anchor_to_army()

Enables the anchor which restricts the camera to the vicinity of the player's army.

 

disable_anchor_to_army

nil disable_anchor_to_army()

Disables the anchor which restricts the camera to the vicinity of the player's army.

 

 

 

AIObjectivePlanner

Note: these are created by the alliance by calling: create_ai_unit_planner()

An AI Objective planner is a simple class where you can collect AI units or ships into a structure (think of it like a controller); and then tell them to do certain high-level actions. This is useful if you want the AI to worry about the specifics of what it’s doing, but you can give it ‘hints’ about what you want it to do.

Example of an AIObjectivePlanner script:-

 

-- declare the AI planner

AI_Planner = Alliance_01:create_ai_unit_planner();

 

--load it with units

AI_Planner:add_units(

      Unit_01,

      Unit_02,

      Unit_03

  );

 

--give it an order

AI_Planner:defend_position(Pos_Defence_Position, 60);

 

add_units

nil add_units(<list>)

This adds one or more units to the controller as an independent group. See the notes in the Unitcontroller for more detailed information.

 

remove_units

nil remove_units(<list>)

Remove the passed in units from the objective and allow the AI to do what it wants with it.

 

defend_position

nil defend_position(Vector position, Number radius)

Tell the units to try defend the position specified, while staying in the area specified by the radius.

 

attack_unit

nil attack_unit(Unit target)

Tell the units to try attack the specified unit.

 

capture_settlement

nil capture_settlement(Vector start_position, Vector end_position)

Tell the units under control to attempt to take a settlement. The attack line with be along the specified Vector positions.

 

clear_objective

nil clear_objective()

Clear the current objective that the controlled AI have.