script_error(string message)

Throws a script error with the supplied message, printing the lua callstack to the Lua console output spool. Useful for debugging.

Parameters:

1

string

message

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/all_scripted.lua, line 33

out(string output)

out is a table that provides multiple methods for outputting text to the various available debug console spools. It may be called as a function to output a string to the main Lua console spool, but the following table elements within it may also be called to output to different output spools:

grudges

ui

chaos

traits

help_pages

interventions

invasions

design

out supplies four additional functions that can be used to show tab characters at the start of lines of output:

Function	Description
out.inc_tab	Increments the number of tab characters shown at the start of the line by one.
out.dec_tab	Decrements the number of tab characters shown at the start of the line by one. Decrementing below zero has no effect.
out.cache_tab	Caches the number of tab characters currently set to be shown at the start of the line.
out.restore_tab	Restores the number of tab characters shown at the start of the line to that previously cached.

Tab levels are managed per output spool. To each of these functions a string argument can be supplied which sets the name of the output spool to apply the modification to. Supply no argument or a blank string to modify the tab level of the main output spool.

Parameters:

1

string

output

Returns:

1. nil

Example - Standard output:

out("Hello World")
out.inc_tab()
out("indented")
out.dec_tab()
out("no longer indented")


Hello World
    indented
no longer indented


Example - UI tab:

Output to the ui tab, with caching and restoring of tab levels

out.ui("Hello UI tab")
out.cache_tab("ui")
out.inc_tab("ui")
out.inc_tab("ui")
out.inc_tab("ui")
out.ui("very indented")
out.restore_tab("ui")
out.ui("not indented any more")


Hello UI tab
            very indented
not indented any more


Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/all_scripted.lua, line 118

force_require(string filename)

Forceably unloads and requires a file by name.

Parameters:

1

string

filename

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/all_scripted.lua, line 396

load_script_libraries()

One-shot function to load the script libraries.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/all_scripted.lua, line 405

get_bm()

Global function to get a battle manager from anywhere (battle only, obviously).

Returns:

1. battle_manager

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_manager.lua, line 234

v(number x position, number y position, number z position)

A shorthand method for creating a battle_vector. Battle only.

Parameters:

1	number	x position
2	number	y position
3	number	z position

Returns:

1. vector

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 11

v_to_s(vector subject vector)

Converts a vector to a string, for debug output

Parameters:

1

vector

subject vector

Returns:

1. string

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 17

v_offset(vector source vector, [number x offset], [number y offset], [number z offset])

Takes a source vector and some x/y/z offset values. Returns a target vector which is offset from the source by the supplied values.

Parameters:

1	vector	source vector
2	number	optional, default value=0 x offset
3	number	optional, default value=0 y offset
4	number	optional, default value=0 z offset

Returns:

1. target vector

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 30

v_offset_by_bearing(battle_vector source vector, number bearing, number dist, [number v bearing])

Takes a source vector, a bearing, a distance, and an optional vertical bearing, and returns a vector at the computed position from the source vector. The horizontal bearing rotates in a horizontal plane (i.e. looking top-down), the vertical bearing rotates in a vertical plane (i.e. looking from side).

Parameters:

1	battle_vector	source vector
2	number	horizontal bearing in radians.
3	number	distance in metres.
4	number	optional, default value=0 Vertical bearing in radians.

Returns:

1. battle_vector target vector

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 53

v_add(vector vector a, vector vector b)

Takes two vectors, and returns a third which is the sum of both.

Parameters:

1	vector	vector a
2	vector	vector b

Returns:

1. target vector

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 80

v_subtract(vector vector a, vector vector b)

Takes two vectors, and returns a third which is the second subtracted from the first.

Parameters:

1	vector	vector a
2	vector	vector b

Returns:

1. target vector

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 101

centre_point_table(table position collection)

Takes a table of vectors, buildings, units or scriptunits, and returns a vector which is the mean centre of the positions described by those objects.

Parameters:

1

table

Table of vectors/buildings/units/scriptunits.

Returns:

1. vector centre position

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 122

get_position_near_target(
  vector source position,
  [number min distance],
  [number max distance],
  [number min bearing],
  [number max bearing]
)

Returns a vector at a random position near to a supplied vector. Additional parameters allow a min/max distance and a min/max angle in degrees from the source vector to be specified.

Parameters:

1	vector	source position
2	number	optional, default value=20 Minimum distance of target position in m.
3	number	optional, default value=50 Maximum distance of target position in m.
4	number	optional, default value=0 Minimum bearing of target position in degrees.
5	number	optional, default value=360 Maximum bearing of target position in degrees.

Returns:

1. vector target position

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 170

get_furthest(vector source position, table position collection)

Takes a subject vector and a table of vectors/units/sunits/buildings (or a scriptunits collection). Returns the index of the vector in the table/collection which is furthest from the subject vector.

Parameters:

1	vector	source position
2	table	Table of vector/unit/sunit/building objects, or a scriptunits collection

Returns:

1. integer index of furthest object in list

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 301

get_nearest(vector source position, table position collection)

Takes a subject vector and a table of vectors/units/sunits/buildings (or a scriptunits collection). Returns the index of the vector in the table/collection which is closest to the subject vector.

Parameters:

1	vector	source position
2	table	Table of vector/unit/sunit/building objects, or a scriptunits collection

Returns:

1. integer index of closest object in list

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 311

position_along_line(vector first position, vector second position, number distance)

Takes two vector positions as parameters and a distance in metres, and returns a position which is that distance from the first vector in the direction of the second vector.

Parameters:

1	vector	first position
2	vector	second position
3	number	distance

Returns:

1. vector target position

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 321

dot(vector first position, vector second position)

Returns the dot product of two supplied vectors.

Parameters:

1	vector	first position
2	vector	second position

Returns:

1. number dot product

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 345

dot3d(vector first position, vector second position)

Returns the dot product of two supplied vectors in three dimensions.

Parameters:

1	vector	first position
2	vector	second position

Returns:

1. number dot product

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 355

normal(vector first position, vector second position)

Returns the normal vector of two supplied vectors.

Parameters:

1	vector	first position
2	vector	second position

Returns:

1. vector normal

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 365

distance_to_line(vector line position a, vector line position b, vector target position)

Takes two vector positions that describe a 2D line of infinite length, and a target vector position. Returns the distance from the line to the target vector.

Parameters:

1	vector	line position a
2	vector	line position b
3	vector	target position

Returns:

1. number distance

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 375

has_crossed_line(
  object position collection,
  vector line position a,
  vector line position b,
  boolean standing only
)

Takes a vector, unit, scriptunit or collection of objects and returns true if any element within it has crossed a line demarked by two supplied vector positions.
An optional fourth parameter instructs has_crossed_line to only consider the positions of non-routing units, if set to true.
An object is deemed to have 'crossed' the line if it's on the right-hand side of the line.

Parameters:

1	object	Collection of position objects to test. Supported collection object types are scriptunits, units, army, armies, alliance or a numerically-indexed table of any supported objects.
2	vector	line position a
3	vector	line position b
4	boolean	Do not count positions of any routing or dead units

Returns:

1. boolean has crossed line

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 403

get_bearing(battle_vector source vector, battle_vector target vector, [number vertical bearing])

Returns the bearing in radians from one vector to another. If the vertical bearing flag is supplied then the vertical bearing is returned (i.e. looking from the side), otherwise the horizontal bearing (i.e. looking from above) is returned.

Parameters:

1	battle_vector	source vector
2	battle_vector	target vector
3	number	optional, default value=false vertical bearing

Returns:

1. number bearing in radians

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 497

distance_along_line(vector line position a, vector line position b, number distance)

Takes two vectors that describe a 3D line of infinite length, and a numeric distance in metres. Returns a position along the line that is the supplied distance from the first supplied position.

Parameters:

1	vector	line position a
2	vector	line position b
3	number	distance

Returns:

1. vector position along line

Loaded in Battle
Loaded in Campaign

defined in ../working_data/script/_lib/lib_convex_area.lua, line 511

new_sfx(string sound event)

A shorthand method for creating a sound effect object.

Parameters:

1

string

Name of sound event

Returns:

1. battle_sound_effect

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 43

play_sound(vector position, battle_sound_effect sound effect)

Plays a sound effect at a position.

Parameters:

1	vector	position
2	battle_sound_effect	sound effect

Returns:

1. nil

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 60

play_sound_2D(battle_sound_effect sound effect)

Plays a sound effect. Sound will play at normal volume and will not appear to come from a position in 3D space.

Parameters:

1

battle_sound_effect

sound effect

Returns:

1. nil

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 80

stop_sound(battle_sound_effect sound effect)

Stops a sound, if it's playing.

Parameters:

1

battle_sound_effect

sound effect

Returns:

1. nil

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 93

create_unitcontroller(army host army, ... list of units)

Shorthand method for creating a unitcontroller. Supply a host army, along with zero or more units belonging to the same army that will be placed within the unitcontroller

Parameters:

1	army	host army
2	...	list of units

Returns:

1. unitcontroller

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 111

unitcontroller_from_army(army host army)

Creates a unitcontroller from a supplied army, containing all the units within that army.

Parameters:

1

army

host army

Returns:

1. unitcontroller

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 140

is_routing_or_dead(object collection to test, [boolean shattered only], [boolean permit rampaging])

Returns true if all units in the supplied object/collection are routing or dead.

Parameters:

1	object	Object or collection to test. Supported objects/collections are unit, scriptunit, scriptunits, units, army, armies, alliance or a table containing any of the above.
2	boolean	optional, default value=false Only count shattered units
3	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. boolean all units routing or dead

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 180

is_shattered_or_dead(object collection to test, [boolean permit rampaging])

Alias for is_routing_or_dead(obj, true, permit_rampaging). Returns true if all units in the supplied object/collection are shattered or dead.

Parameters:

1	object	Object or collection to test. Supported objects/collections are unit, scriptunit, scriptunits, units, army, armies, alliance or a table containing any of the above.
2	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually shattered too.

Returns:

1. boolean all units shattered or dead

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 273

num_units_routing(object collection to test, [boolean shattered only], [boolean permit rampaging])

Returns the number of units in the supplied collection that are routing or dead.
The second parameter, if true, instructs num_units_routing to only count those units that are shattered or dead. The third parameter, if true, instructs the function to not automatically count rampaging units - they have to be actually routing as well.

Parameters:

1	object	Object or collection to test. Supported objects/collections are units, scriptunits, army, armies, alliance or a table containing any of the above, or units/scriptunits.
2	boolean	optional, default value=false Only count shattered units
3	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. integer number of routing or dead units

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 283

num_units_shattered(object collection to test, [boolean permit rampaging])

Alias of num_units_routing(obj, true, permit_rampaging). Returns the number of units in the supplied collection that are shattered or dead. Supported collections are units, scriptunits, army, armies, alliance or a table containing any of the above, or units/scriptunits.
The second parameter, if true, instructs num_units_shattered to not automatically count those units that are rampaging.

Parameters:

1	object	Object or collection to test. Supported objects/collections are units, scriptunits, army, armies, alliance or a table containing any of the above, or units/scriptunits.
2	boolean	optional, default value=false Don't automatically count rampaging units, check if they are actually routing too.

Returns:

1. integer number of shattered or dead units

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 363

num_units_engaged(object collection to test)

Returns the number of units in the supplied collection which are currently engaged in melee.

Parameters:

1

object

Collection to test. Supported collection types are units, scriptunits, army, armies, alliance and table.

Returns:

1. number of units engaged in melee

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 374

num_units_under_fire(object collection to test)

Returns the number of units in the supplied collection which are currently under missile fire.

Parameters:

1

object

Collection to test. Supported collection types are units, scriptunits, army, armies, alliance and table.

Returns:

1. number of units under fire

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 423

rout_all_units(object collection of units)

Instantly rout all units in the supplied collection.

Parameters:

1

object

Collection of units to rout. Supported collection types are scriptunits, army, armies, alliance and table.

Returns:

1. nil

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 472

number_close_to_position(
  object collection of units,
  vector position,
  number range in m,
  boolean 2D only,
  boolean non-routing only
)

Returns the number of units or sunits in a supplied collection within a given range of a given position.

Parameters:

1	object	Collection of units. Supported collection types are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	number	range in m
4	boolean	Consider 2 dimensional distance only. If true, then number_close_to_position disregards height differences in its distance calculation.
5	boolean	Disregard routing or dead units from inclusion in the result.

Returns:

1. integer number within range of position

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 537

standing_number_close_to_position(
  object collection of units,
  vector position,
  number range in m,
  boolean 2D only
)

Alias of number_close_to_position(obj, pos, range, two_d, true). Returns the number of non-routing units or sunits in a supplied collection within a given range of a given position.

Parameters:

1	object	Collection of units. Supported collection types are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	number	range in m
4	boolean	Consider 2 dimensional distance only. If true, then standing_number_close_to_position disregards height differences in its distance calculation.

Returns:

1. integer number within range of position

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 704

is_close_to_position(
  object collection of units,
  vector position,
  number range in m,
  boolean 2D only,
  boolean non-routing only
)

Returns true if any units or sunits in a supplied collection are within a given range of a given position, false otherwise.

Parameters:

1	object	Collection of units. Supported container types are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	number	range in m
4	boolean	Consider 2 dimensional distance only. If true, then is_close_to_position disregards height differences in its distance calculation.
5	boolean	Disregard routing or dead units from inclusion in the result.

Returns:

1. integer number within range of position

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 716

standing_is_close_to_position(object collection of units, vector position, number range in m, boolean 2D only)

Alias of is_close_to_position(obj, pos, range, two_d, true). Returns true if any non-routing units or sunits in a supplied collection are within a given range of a given position, false otherwise. The 2D only flag instructs the function to disregard height differences in its distance calculation.

Parameters:

1	object	Collection of units. Supported container types are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	number	range in m
4	boolean	Consider 2 dimensional distance only. If true, then standing_is_close_to_position disregards height differences in its distance calculation.

Returns:

1. integer number within range of position

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 729

distance_between_forces(
  object first collection,
  object second collection,
  [boolean non-routing only],
  return number closest distance in m between forces
)

Returns the closest distance between two collections of units. Supported collections are scriptunits, units, army, armies, alliance and table of unit, scriptunit or any of the above object types.

Parameters:

1	object	first collection
2	object	second collection
3	boolean	optional, default value=false Disregard routing or dead units from inclusion in the result.
4	return	number closest distance in m between forces

Returns:

1. nil

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 741

get_closest_unit(
  object unit collection,
  vector position,
  [boolean non-routing only],
  [function additional test]
)

Returns the closest unit in the supplied container to a supplied position, as well as its distance to that position. If the supplied collection is a scriptunits object, the closest scriptunit is also returned as the third return parameter (the scriptunit that contains the closest unit).

Parameters:

1	object	Unit collection. Supported types are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	boolean	optional, default value=false Disregard routing or dead units from inclusion in the result.
4	function	optional, default value=nil Additional test to perform on each candidate unit, which must be passed in order to count the subject unit towards the result. This must be supplied in the form of a function block which takes a unit as a parameter and returns a boolean result. If this function returns true when called, or a result that evaluates to true, then the subject unit can be considered for inclusion in the result.

Returns:

1. unit closest unit
2. number distance of closest unit
3. scriptunit closest scriptunit if applicable, nil if not

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 846

get_closest_standing_unit(object unit collection, vector position, [function additional test])

Alias of get_closest_unit(obj, pos, true, test). Returns the closest unit in the supplied container to a supplied position, and its distance to that position.
The third parameter allows the calling script to specify an additional test which must be passed in order to count the subject unit towards the result. This must be in the form of a function block which takes a unit as a parameter and returns a boolean result.

Parameters:

1	object	Unit collection. Supported containers are scriptunits, units, army, armies, alliance and table.
2	vector	position
3	function	optional, default value=nil Additional test to perform on each candidate unit, which must be passed in order to count the subject unit towards the result. This must be supplied in the form of a function block which takes a unit as a parameter and returns a boolean result. If this function returns true when called, or a result that evaluates to true, then the subject unit can be considered for inclusion in the result.

Returns:

1. unit closest unit
2. number distance of closest unit
3. scriptunit closest scriptunit if applicable, nil if not

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 974

get_average_altitude(object unit collection)

Returns the average altitude in m and the total number of units in the supplied collection.

Parameters:

1

object

unit collection

Returns:

1. number average altitude in m
2. integer number of units in collection

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1003

num_units_in_collection(object collection to test)

Returns the number of units in the supplied collection.

Parameters:

1

object

Collection to test. Supported collection types are units, scriptunits, army, armies, alliance and table.

Returns:

1. number of units in collection

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1086

contains_unit(object collection to test, unit subject unit)

Returns true is the supplied container contains the supplied unit, otherwise returns false.

Parameters:

1	object	Collection to test. Supported containers are scriptunits, units, army, armies, alliance and table.
2	unit	subject unit

Returns:

1. boolean collection contains unit

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1122

num_units_passing_test(object collection to test, function test function)

Returns the number of units in the supplied collection that pass a supplied test, as well as the total number of units. The test must be supplied in the form of a function that takes a unit parameter and returns a boolean result.

Parameters:

1	object	Collection to test. Supported collection object types are units, scriptunits, army, armies, alliance and table.
2	function	test function

Returns:

1. integer number of passing units
2. integer total number of units

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1200

get_all_matching_units(object collection to test, function test function)

Returns a table containing all units in the supplied collection that pass a supplied test.

Parameters:

1	object	Collection to test. Supported collection object types are units, scriptunits, army, armies, alliance and table.
2	function	Test function. The test must be supplied in the form of a function that takes a unit parameter and returns a boolean result. If the boolean result is true, or evaluates to true, the unit is added to the result.

Returns:

1. table table containing passing units

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1272

number_alive(object collection to test)

Returns the number of soldiers in a collection that are alive, as well as the initial number of soldiers that collection started with.

Parameters:

1

object

Collection to test. Supported collections are alliance, armies, army, units, unit, scriptunit, scriptunits and table.

Returns:

1. integer number of soldiers currently alive
2. integer initial number of soldiers

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1333

is_visible(object collection to test, alliance alliance)

Returns true if any part of the supplied collection object is visible to the supplied alliance by the rules of the visibility system.

Parameters:

1	object	Collection to test.
2	alliance	alliance

Returns:

1. boolean visibility result

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1401

has_deployed(object collection to test)

Returns true if all units in the supplied collection object are valid targets and are not routing or dead, and are therefore considered to be deployed. Supported objects are unit, scriptunit, units, scriptunits, army, armies and table.

Parameters:

1

object

Collection to test. Supported collection objects are unit, units, army, armies, scriptunit, scriptunits and table.

Returns:

1. boolean are all deployed

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_misc.lua, line 1449

scriptunits_from_army(string name, army, Subject army.)

Method of automatically deriving a script_units collection from an army. Each script_unit object is created automatically.

Parameters:

1	string	Name for this scriptunits collection.
2	army,	Subject army.

Returns:

1. script_units

Loaded in Battle

defined in ../working_data/script/_lib/lib_battle_script_unit.lua, line 1640

Variables in this section:

VOLUME_TYPE_MUSIC	@number	Volume type representing music, that can be used with sound-related functions. Value is 0.
VOLUME_TYPE_SFX	@number	Volume type representing sfx, that can be used with sound-related functions. Value is 1.
VOLUME_TYPE_ADVISOR	@number	Volume type representing advisor sounds, that can be used with sound-related functions. Value is 2.
VOLUME_TYPE_VO	@number	Volume type representing voiceover sounds, that can be used with sound-related functions. Value is 3.
VOLUME_TYPE_INTERFACE	@number	Volume type representing user interface sounds, that can be used with sound-related functions. Value is 4.
VOLUME_TYPE_MOVIE	@number	Volume type representing movie sounds, that can be used with sound-related functions. Value is 5.
VOLUME_TYPE_VOICE_CHAT	@number	Volume type representing voice chat audio, that can be used with sound-related functions. Value is 6.
VOLUME_TYPE_MASTER	@number	Volume type representing the master volume level, that can be used with sound-related functions. Value is 7.

These variables are also listed in the global variables list for this class or module.

r_to_d(number angle)

Converts a supplied angle in radians to degrees.

Parameters:

1

number

Angle in radians

Returns:

1. number angle in degrees

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 35

d_to_r(number angle)

Converts a supplied angle in degrees to radians.

Parameters:

1

number

Angle in degrees

Returns:

1. number angle in radians

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 48

get_file_and_folder_path_as_table([integer stack offset])

Returns the file and path of the calling script as a table of strings.

Parameters:

1

integer

optional, default value=0 Supply a positive integer here to return a result for a different file on the callstack e.g. supply '1' to return the file and folder path of the script file calling the the script file calling this function, for example.

Returns:

1. table table of strings

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 73

get_folder_name_and_shortform([integer stack offset])

Returns the folder name of the calling file and the shortform of its filename as separate return parameters. The shortform of the filename is the portion of the filename before the first "_", if one is found. If no shortform is found the function returns only the folder name.
A shortform used to be prepended on battle script files to allow them to be easily differentiated from one another in text editors e.g. "TF_battle_main.lua" vs "PY_battle_main.lua" rather than two "battle_main.lua"'s.

Parameters:

1

integer

optional, default value=0 Supply a positive integer here to return a result for a different file on the callstack e.g. supply '1' to return the folder name/shortform of the script file calling the the script file calling this function, for example.

Returns:

1. string name of folder containing calling file
2. string shortform of calling filename, if any

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 136

get_full_file_path([integer stack offset])

Gets the full filepath and name of the calling file.

Parameters:

1

integer

optional, default value=0 Supply a positive integer here to return a result for a different file on the callstack e.g. supply '1' to return the file path of the script file calling the the script file calling this function, for example.

Returns:

1. string file path

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 174

get_file_name_and_path([integer stack offset])

Returns the filename and the filepath of the calling file as separate return parameters.

Parameters:

1

integer

optional, default value=0 Supply a positive integer here to return a result for a different file on the callstack e.g. supply '1' to return the file name and path of the script file calling the the script file calling this function, for example.

Returns:

1. string file name
2. string file path

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 190

is_nil(object object)

Returns true if the supplied object is nil, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 264

is_number(object object)

Returns true if the supplied object is a number, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is number

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 277

is_function(object object)

Returns true if the supplied object is a function, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is function

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 290

is_string(object object)

Returns true if the supplied object is a string, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is string

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 303

is_boolean(object object)

Returns true if the supplied object is a boolean, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is boolean

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 316

is_table(object object)

Returns true if the supplied object is a table, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is table

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 329

is_eventcontext(object object)

Returns true if the supplied object is an event context, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is event context

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 342

is_battlesoundeffect(object object)

Returns true if the supplied object is a battle sound effect, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is battle sound effect

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 355

is_battle(object object)

Returns true if the supplied object is an empire battle object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is battle

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 368

is_alliances(object object)

Returns true if the supplied object is an alliances object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is alliances

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 381

is_alliance(object object)

Returns true if the supplied object is an alliance, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is alliance

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 394

is_armies(object object)

Returns true if the supplied object is an armies object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is armies

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 407

is_army(object object)

Returns true if the supplied object is an army object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is army

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 420

is_units(object object)

Returns true if the supplied object is a units object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is units

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 433

is_unit(object object)

Returns true if the supplied object is a unit object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is unit

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 445

is_unitcontroller(object object)

Returns true if the supplied object is a unitcontroller, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is unitcontroller

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 458

is_core(object object)

Returns true if the supplied object is a core object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is core

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 471

is_battlemanager(object object)

Returns true if the supplied object is a battle_manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is battle manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 484

is_campaignmanager(object object)

Returns true if the supplied object is a campaign manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is campaign manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 497

is_factionstart(object object)

Returns true if the supplied object is a faction start object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is faction start

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 510

is_campaigncutscene(object object)

Returns true if the supplied object is a campaign cutscene, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is campaign cutscene

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 523

is_cutscene(object object)

Returns true if the supplied object is a battle cutscene, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is cutscene

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 536

is_vector(object object)

Returns true if the supplied object is a vector object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is vector

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 549

is_building(object object)

Returns true if the supplied object is a building object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is building

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 563

is_buildings(object object)

Returns true if the supplied object is a buildings object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is buildings

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 577

is_buildinglist(object object)

Returns true if the supplied object is a building list object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is building list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 591

is_convexarea(object object)

Returns true if the supplied object is a convex_area, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is convex area

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 604

is_scriptunit(object object)

Returns true if the supplied object is a script_unit, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is scriptunit

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 617

is_scriptunits(object object)

Returns true if the supplied object is a script_units object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is scriptunits

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 630

is_subtitles(object object)

Returns true if the supplied object is a battle subtitles object, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is subtitles

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 643

is_patrolmanager(object object)

Returns true if the supplied object is a patrol manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is patrol manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 656

is_waypoint(object object)

Returns true if the supplied object is a patrol manager waypoint, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is waypoint

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 669

is_eventhandler(object object)

Returns true if the supplied object is an event handler, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is event handler

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 682

is_scriptaiplanner(object object)

Returns true if the supplied object is a script ai planner, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is script ai planner

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 695

is_timermanager(object object)

Returns true if the supplied object is a timer manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is timer manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 708

is_uioverride(object object)

Returns true if the supplied object is a ui override, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is ui override

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 721

is_uicomponent(object object)

Returns true if the supplied object is a uicomponent, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is uicomponent

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 734

is_component(object object)

Returns true if the supplied object is a component, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is component

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 747

is_scriptmessager(object object)

Returns true if the supplied object is a script messager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is script messager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 760

is_generatedbattle(object object)

Returns true if the supplied object is a generated battle, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is generated battle

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 773

is_generatedarmy(object object)

Returns true if the supplied object is a generated army, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is generated army

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 786

is_generatedcutscene(object object)

Returns true if the supplied object is a generated cutscene, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is generated cutscene

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 799

is_null(object object)

Returns true if the supplied object is a campaign null script interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is null

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 812

is_model(object object)

Returns true if the supplied object is a campaign model interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is model

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 825

is_world(object object)

Returns true if the supplied object is a campaign world interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is world

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 838

is_faction(object object)

Returns true if the supplied object is a campaign faction interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is faction

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 851

is_factionlist(object object)

Returns true if the supplied object is a campaign faction list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is faction list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 864

is_character(object object)

Returns true if the supplied object is a campaign character interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is character

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 877

is_characterlist(object object)

Returns true if the supplied object is a campaign character list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is character list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 890

is_regionmanager(object object)

Returns true if the supplied object is a campaign region manager interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is region manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 903

is_region(object object)

Returns true if the supplied object is a campaign region interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is region

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 916

is_regionlist(object object)

Returns true if the supplied object is a campaign region list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is region list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 929

is_garrisonresidence(object object)

Returns true if the supplied object is a campaign garrison residence interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is garrison residence

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 942

is_settlement(object object)

Returns true if the supplied object is a campaign settlement interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is settlement

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 955

is_slot(object object)

Returns true if the supplied object is a campaign slot interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is slot

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 968

is_slotlist(object object)

Returns true if the supplied object is a campaign slot list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is slot list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 981

is_militaryforce(object object)

Returns true if the supplied object is a campaign military force interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is military force

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 994

is_militaryforcelist(object object)

Returns true if the supplied object is a campaign military force list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is military force list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1007

is_unitlist(object object)

Returns true if the supplied object is a campaign unit list interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is unit list

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1020

is_pendingbattle(object object)

Returns true if the supplied object is a campaign pending battle interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is pending battle

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1033

is_campaignmission(object object)

Returns true if the supplied object is a campaign mission interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is campaign mission

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1046

is_campaignai(object object)

Returns true if the supplied object is a campaign ai interface, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is campaign ai

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1059

is_campaignuimanager(object object)

Returns true if the supplied object is a campaign ui manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is campaign ui manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1072

is_objectivesmanager(object object)

Returns true if the supplied object is an objectives_manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is objectives manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1085

is_infotextmanager(object object)

Returns true if the supplied object is an infotext_manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is infotext manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1098

is_missionmanager(object object)

Returns true if the supplied object is a mission manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is text pointer

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1111

is_intervention(object object)

Returns true if the supplied object is an intervention, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is intervention

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1124

is_interventionmanager(object object)

Returns true if the supplied object is an intervention manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is intervention manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1137

is_linkparser(object object)

Returns true if the supplied object is a link parser, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is link parser

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1150

is_advicemanager(object object)

Returns true if the supplied object is an advice manager, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is advice manager

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1163

is_advicemonitor(object object)

Returns true if the supplied object is an advice monitor, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is advice monitor

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1176

is_textpointer(object object)

Returns true if the supplied object is a text pointer, false otherwise.

Parameters:

1

object

object

Returns:

1. boolean is text pointer

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common_ui.lua, line 29

table_contains(table subject table, object object)

Returns true if the supplied indexed table contains the supplied object.

Parameters:

1	table	subject table
2	object	object

Returns:

1. boolean table contains object

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1201

find_child_uicomponent(uicomponent parent ui component, string name)

Takes a uicomponent and a string name. Searches the direct children (and no further - not grandchildren etc) of the supplied uicomponent for another uicomponent with the supplied name. If a uicomponent with the matching name is found then it is returned, otherwise false is returned.

Parameters:

1	uicomponent	parent ui component
2	string	name

Returns:

1. uicomponent child, or false if not found

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1228

find_uicomponent([uicomponent parent ui component], ... list of string names)

Finds and returns a uicomponent based on a set of strings that define its path in the ui hierarchy. This parent uicomponent can be supplied as the first argument - if omitted, the root uicomponent is used. Starting from the parent or root, the function searches through all descendants for a uicomponent with the next supplied uicomponent name in the sequence. If a uicomponent is found, its descendants are then searched for a uicomponent with the next name in the list, and so on until the list is finished or no uicomponent with the supplied name is found. A fragmentary path may be supplied if it still unambiguously specifies the intended uicomponent.

Parameters:

1	uicomponent	optional, default value=nil parent ui component
2	...	list of string names

Returns:

1. uicomponent child, or false if not found.

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1267

find_uicomponent_from_table(
  uicomponent parent ui component,
  table table of string names,
  [assert on failure]
)

Takes a start uicomponent and a numerically-indexed table of string uicomponent names. Starting from the supplied start uicomponent, the function searches through all descendants for a uicomponent with the next supplied uicomponent name in the table. If a uicomponent is found, its descendants are then searched for a uicomponent with the next name in the list, and so on until the list is finished or no uicomponent with the supplied name is found. This allows a uicomponent to be searched for by matching its name and part of or all of its path.

Parameters:

1	uicomponent	Parent uicomponent.
2	table	Table of string names, indexed by number.
3	assert	optional, default value=false Fire a script error if the search fails.

Returns:

1. uicomponent child, or false if not found.

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1297

uicomponent_descended_from(uicomponent subject uic, string parent name)

Takes a uicomponent and a string name. Returns true if any parent ancestor component all the way up to the ui root has the supplied name (i.e. the supplied component is descended from it), false otherwise.

Parameters:

1	uicomponent	subject uic
2	string	parent name

Returns:

1. boolean uic is descended from a component with the supplied name.

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1335

uicomponent_to_str(uicomponent subject uic)

Converts a uicomponent to a string showing its path, for output purposes.

Parameters:

1

uicomponent

subject uic

Returns:

1. string output

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1367

output_uicomponent(uicomponent subject uic, [boolean omit children])

Outputs extensive debug information about a supplied uicomponent to the Lua - UI console spool.

Parameters:

1	uicomponent	Subject uicomponent.
2	boolean	optional, default value=false Do not show information about the uicomponent's children.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1391

output_uicomponent_on_click()

Starts a listener which outputs debug information to the Lua - UI console spool about every uicomponent that's clicked on.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1446

print_all_uicomponent_children(uicomponent subject uic)

Prints the name and path of the supplied uicomponent and all its descendents. Very verbose, and can take a number of seconds to complete.

Parameters:

1

uicomponent

Subject uicomponent.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1461

pulse_uicomponent(
  uicomponent ui component,
  [boolean should pulse],
  [number brightness],
  [boolean progagate],
  [string state name]
)

Activates or deactivates a pulsing highlight effect on the supplied uicomponent. This is primarily used for scripts which activate when the player moves the mouse cursor over certain words in the help pages, to indicate to the player what UI feature is being talked about on the page.

Parameters:

1	uicomponent	Subject ui component.
2	boolean	optional, default value=true Set to true to activate the pulsing effect, false to deactivate it.
3	number	optional, default value=0 Pulse brightness. Set a higher number for a more pronounced pulsing effect.
4	boolean	optional, default value=false Propagate the effect through the component's children. Use this with care, as the visual effect can stack and often it's better to activate the effect on specific uicomponents instead of activating this.
5	string	optional, default value=nil Optional state name to affect. If a string name is supplied, the pulsing effect is only applied to the specified state instead of to all states on the component.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1473

is_fully_onscreen(uicomponent uicomponent)

Returns true if the uicomponent is fully on-screen, false otherwise.

Parameters:

1

uicomponent

uicomponent

Returns:

1. boolean is onscreen

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1522

is_partially_onscreen(uicomponent uicomponent)

Returns true if the uicomponent is partially on-screen, false otherwise.

Parameters:

1

uicomponent

uicomponent

Returns:

1. boolean is onscreen

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1538

set_component_visible(boolean set visible, ... list of string names)

Sets a uicomponent visible or invisible by its path. The path should be one or more strings which when sequentially searched for from the ui root lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	set visible
2	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1556

set_component_visible_with_parent(
  boolean set visible,
  uicomponent parent uicomponent,
  ... list of string names
)

Sets a uicomponent visible or invisible by its path. The path should be one or more strings which when sequentially searched for from a supplied uicomponent parent lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	set visible
2	uicomponent	parent uicomponent
3	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1577

set_component_active(boolean set active, ... list of string names)

Sets a uicomponent to be active or inactive by its path. The path should be one or more strings which when sequentially searched for from the ui root lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	set active
2	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1597

set_component_active_with_parent(
  boolean set active,
  uicomponent parent uicomponent,
  ... list of string names
)

Sets a uicomponent to be active or inactive by its path. The path should be one or more strings which when sequentially searched for from a supplied uicomponent parent lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	set active
2	uicomponent	parent uicomponent
3	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1618

highlight_component(boolean activate highlight, boolean is square, ... list of string names)

Highlights or unhighlights a uicomponent by its path. The path should be one or more strings which when sequentially searched for from the ui root lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	Set true to activate the highlight, false to deactivate.
2	boolean	Set to true if the target uicomponent is square, false if it's circular.
3	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1652

highlight_visible_component(boolean activate highlight, boolean is square, ... list of string names)

Highlights or unhighlights a uicomponent by its path, but only if it's visible. The path should be one or more strings which when sequentially searched for from the ui root lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	boolean	Set true to activate the highlight, false to deactivate.
2	boolean	Set to true if the target uicomponent is square, false if it's circular.
3	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1662

highlight_all_visible_children(uicomponent parent, [number visual padding])

Draws a box highlight around all visible children of the supplied uicomponent. A padding value in pixels may also be supplied to increase the visual space between the highlight and the components being highlighted.

Parameters:

1	uicomponent	parent
2	number	optional, default value=0 visual padding

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1686

unhighlight_all_visible_children()

Cancels any and all highlights created with highlight_all_visible_children.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1713

highlight_component_table(number visual padding, ... uicomponents)

Draws a box highlight stretching around the supplied list of components. A padding value in pixels may also be supplied to increase the visual space between the highlight and the components being highlighted.

Parameters:

1	number	Visual padding in pixels.
2	...	Variable number of uicomponents to draw highlight over.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1720

unhighlight_component_table()

Cancels any and all highlights created with highlight_component_table.

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1810

play_component_animation(string animation name, ... list of string names)

Plays a specified component animation on a uicomponent by its path. The path should be one or more strings which when sequentially searched for from the ui root lead to the target uicomponent (see documentation for find_uicomponent_from_table, which performs the search).

Parameters:

1	string	animation name
2	...	list of string names

Returns:

1. nil

Loaded in Battle
Loaded in Campaign
Loaded in Frontend

defined in ../working_data/script/_lib/lib_common.lua, line 1817