Global

Global functions that are not part of a class or object are listed here. Be sure to check what game modes they are loaded in before use, as not all of them will be loaded in campaign, battle or the frontend.

Back to top

Script Errors

script_error(string message, [number stack level modifier], [boolean suppress assert])

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 to print.

2

number

optional, default value=0

By default this function will print the callstack of the calling function. A modifier may be supplied here to alter which function in the callstack should be at the top of the callstack. A positive integer moves the callstack pointer down the callstack, so a supplied value of 1 here would mean the callstack of the function calling the function calling script_error would be printed.

If the stack level modifier is set to a negative number then no traceback is printed as part of the script error. This can be useful if the error message itself contains a traceback.

3

boolean

optional, default value=false

If set to true then no assert is generated with this script error.

Returns:

  1. nil
Loaded in Battle Loaded in .. Battle

defined in ../../warhammer/working_data/script/all_scripted.lua, line 31

Back to top

Output

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:
    FunctionDescription
    out.inc_tabIncrements the number of tab characters shown at the start of the line by one.
    out.dec_tabDecrements the number of tab characters shown at the start of the line by one. Decrementing below zero has no effect.
    out.cache_tabCaches the number of tab characters currently set to be shown at the start of the line.
    out.restore_tabRestores 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 .. Battle

    defined in ../../warhammer/working_data/script/all_scripted.lua, line 144

    Back to top

    Loading Script Libraries

    force_require(string filename)
    Forceably unloads and requires a file by name.

    Parameters:

    1

    string

    filename

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/all_scripted.lua, line 422

    load_script_libraries()
    One-shot function to load the script libraries.

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/all_scripted.lua, line 431

    Back to top

    Vector Manipulation

    A suite of functions related to vectors. In battle scripting terminology, vectors are 2D/3D positions in the game world.

    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 Loaded in .. Battle

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

    v_from_context_str([string object id], [string constructed string], string function id)

    Assembles and returns a vector from a supplied ui context string. The string should specify a function that returns co-ordinates, which can then be assembled into a vector.

    Parameters:

    1

    string

    optional, default value=nil

    object id

    2

    string

    optional, default value=nil

    constructed string

    3

    string

    function id

    Returns:

    1. battle_vector vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 38

    v_to_s(battle_vector vector)

    Converts a vector to a string, for debug output

    Parameters:

    1

    battle_vector

    vector

    Returns:

    1. string output string
    Loaded in Battle Loaded in .. Battle

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

    v_offset(battle_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

    battle_vector

    source vector

    2

    number

    optional, default value=0

    X offset in metres (east-west).

    3

    number

    optional, default value=0

    Y offset in metres (height).

    4

    number

    optional, default value=0

    Z offset in metres (north-south).

    Returns:

    1. vector target vector
    Loaded in Battle Loaded in .. Battle

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

    v_copy()
    Returns a copy of a vector.

    Returns:

    1. vector vector copy
    Loaded in Battle Loaded in .. Battle

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

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 66

    v_add(battle_vector vector a, battle_vector vector b)

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

    Parameters:

    1

    battle_vector

    vector a

    2

    battle_vector

    vector b

    Returns:

    1. battle_vector target vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 93

    v_subtract(battle_vector vector a, battle_vector vector b)

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

    Parameters:

    1

    battle_vector

    vector a

    2

    battle_vector

    vector b

    Returns:

    1. battle_vector target vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 114

    v_to_ground(battle_vector source position, [number height offset])

    Returns a battle_vector at a supplied 2D position at a specified height above or below the ground, making use of battle:get_terrain_height.

    Parameters:

    1

    battle_vector

    Source position. A vertical line will be drawn at this position. Where this line intersects the terrain will be considered height 0.

    2

    number

    optional, default value=0

    Height offset from ground in metres. This can be negative.

    Returns:

    1. battle_vector target vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 135

    v_min_height(battle_vector input position, [number minimum altitude])

    Returns a battle_vector at the supplied position at an altitude of at-least the supplied minimum height. If the supplied position is above the minimum height over the terrain then it is returned unaltered.

    Parameters:

    1

    battle_vector

    input position

    2

    number

    optional, default value=2

    minimum altitude

    Returns:

    1. battle_vector output position
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 161

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 189

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 237

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 368

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 378

    position_along_line(
          battle_vector first position,
      battle_vector     second position,
      number     distance,
      [boolean     2D only]
    )

    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

    battle_vector

    First position.

    2

    battle_vector

    Second position.

    3

    number

    Distance in metres.

    4

    boolean

    optional, default value=false

    Disregard height.

    Returns:

    1. battle_vector target position
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 388

    position_along_line_unary(
          battle_vector first position,
      battle_vector     second position,
      number     unary distance,
      [boolean     2D only]
    )

    Takes two vector positions as parameters and a unary (0-1) proportion, and returns a position which is that proportional distance from the first vector in the direction of the second vector. Unary values outside the range of 0-1 are supported.

    Parameters:

    1

    battle_vector

    First position.

    2

    battle_vector

    Second position.

    3

    number

    Unary distance.

    4

    boolean

    optional, default value=false

    Disregard height.

    Returns:

    1. battle_vector target position
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 421

    dot(battle_vector first position, battle_vector second position)

    Returns the dot product of two supplied vectors.

    Parameters:

    1

    battle_vector

    first position

    2

    battle_vector

    second position

    Returns:

    1. number dot product
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 446

    dot3d(battle_vector first position, battle_vector second position)

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

    Parameters:

    1

    battle_vector

    first position

    2

    battle_vector

    second position

    Returns:

    1. number dot product
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 456

    normal(battle_vector first position, battle_vector second position)

    Returns the normal vector of two supplied vectors.

    Parameters:

    1

    battle_vector

    first position

    2

    battle_vector

    second position

    Returns:

    1. battle_vector normal
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 466

    distance_to_line(
          battle_vector line position a,
      battle_vector     line position b,
      battle_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. This distance will be negative if the target is on the left side of the line, and positive if on the right side of the line.

    Parameters:

    1

    battle_vector

    line position a

    2

    battle_vector

    line position b

    3

    battle_vector

    target position

    Returns:

    1. number distance
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 476

    has_crossed_line(
      object     position collection,
          battle_vector line position a,
      battle_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

    battle_vector

    line position a

    3

    battle_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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 504

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 598

    get_vector_offset_by_bearing(
          battle_vector source,
      [number     distance],
      [number     h bearing],
      [number     v bearing]
    )

    Returns a vector that is offset from a supplied source vector, in a particular horizontal 2d bearing (top-down), at a particular distance and vertical bearing. The function is primarily intended to compute camera position offsets from a supplied target but can be used for any purpose.

    Parameters:

    1

    battle_vector

    source

    2

    number

    optional, default value=50

    Distance in m.

    3

    number

    optional, default value=0

    Horizontal (top-down) bearing in radians.

    4

    number

    optional, default value=0

    Vertical (from-side) bearing in radians.

    Returns:

    1. battle_vector offset vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_convex_area.lua, line 612

    Back to top

    Sound

    new_sfx(string sound event, [boolean is the sound cinematic], [boolean is the sound vo])

    A shorthand method for creating a sound effect object.

    Parameters:

    1

    string

    Name of sound event

    2

    boolean

    optional, default value=true

    if true it can only trigger during cinematics

    3

    boolean

    optional, default value=true

    if true we will make sure it doesn't overlap other vo

    Returns:

    1. battle_sound_effect
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 92

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 132

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 152

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 165

    Back to top

    Unitcontroller Creation

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 183

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 223

    Back to top

    Unit Routing and Engagement Tests

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 263

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 356

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 366

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 446

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 457

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 506

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 555

    Back to top

    Unit Position Tests

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 620

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 787

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 799

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 812

    distance_between_forces(
      object     first collection,
      object     second collection,
      [boolean     non-routing only],
      return     number Closest distance in m between forces,
      return     obj Closest object from first supplied force,
      return     obj Closest object from second supplied force
    )
    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.
    The function will also return the objects in both collections that are closest to one another. These will be script_unit objects, if available, otherwise they will be battle_unit objects.

    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

    5

    return

    a script_unit or a battle_unit

    6

    return

    a script_unit or a battle_unit

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 824

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 944

    get_closest_standing_unit(object unit collection, vector position, [function additional test])
    Returns the closest unit in the supplied container to a supplied position, and its distance to that position. This function is an alias of get_closest_unit(obj, pos, true, test).
    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1074

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1103

    Back to top

    Miscellaneous Unit Collection Tests

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1189

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1223

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1301

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1373

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1434

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1502

    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 Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1556

    Back to top

    Ground Types

    ground_type_proportion_along_line(
          battle_vector start position,
      battle_vector     end position,
      string     ground type,
      [number     samples]
    )

    Returns the percentage of points sampled along a supplied line that match the supplied ground type. The line is specified by start and end vectors.

    Parameters:

    1

    battle_vector

    Starting position of line.

    2

    battle_vector

    End position of line.

    3

    string

    Ground type key, from the ground_types database table.

    4

    number

    optional, default value=10

    Number of samples to take. A higher number of samples will give a more accurate result but will be slower.

    Returns:

    1. number percentage of ground type
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1612

    ground_type_proportion_in_bounding_box(
          battle_vector centre position,
      number     bearing,
      number     width,
      number     depth,
      [number     width samples],
      [number     depth samples]
    )

    Returns the percentage of points sampled in a bounding box that match the supplied ground type. The oriented-bounding box is specified by a centre position, a bearing in radians, a width and a depth. The number of width and depth samples may optionally be specified, the total number of samples being these numbers multiplied together.
    Be aware of the performance implications of using this function.

    Parameters:

    1

    battle_vector

    Centre position of the oriented bounding box.

    2

    number

    Bearing of bounding box in radians.

    3

    number

    Width of bounding box in metres.

    4

    number

    Depth of bounding box in metres.

    5

    number

    optional, default value=10

    Number of sample lines to take across width of bounding box.

    6

    number

    optional, default value=10

    Number of samples to take for each front-to-back sample line taken.

    Returns:

    1. number percentage of ground type
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_battle_misc.lua, line 1644

    Back to top

    Object-Orientation, Inheritance, and Types

    is_custom_type(table object, value custom type)

    Returns true if the supplied value is of the supplied custom type. This is not intended to be directly called by client scripts, who should instead call one of the is_ functions listed elsewhere.

    Parameters:

    1

    table

    object

    2

    value

    custom type

    Returns:

    1. boolean is custom type
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 97

    get_custom_type(table object)

    Returns the custom type value of the supplied value. If it has no custom type then nil is returned.

    Parameters:

    1

    table

    object

    Returns:

    1. value custom type, or nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 107

    set_class_custom_type(table class table, string custom type)

    Sets a supplied class table to the supplied type string by setting its __custom_type value. Once this is set, other object tables that are later set to derive from this class with set_object_class will report this custom type when passed to get_custom_type or is_custom_type.

    Parameters:

    1

    table

    class table

    2

    string

    custom type

    Returns:

    1. nil

    Example:

    TYPE_RABBIT = "rabbit"

    -- class definition
    rabbit = {}
    set_class_custom_type(rabbit, TYPE_RABBIT)

    -- object definition
    thumper = {}
    set_object_class(thumper, rabbit)

    out("thumper custom type is " .. get_custom_type(thumper)
    thumper custom type is rabbit
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 118

    set_class_tostring(table class table, string custom type)

    Sets the tostring value of a supplied class table to the specified value by setting its __tostring value. Once this is set, other object tables that are later set to derive from this class with set_object_class will return this value when passed to tostring().
    The tostring specifier may be supplied as a string or a function. If supplied as a function, that function will be called when the tostring() function is called with an object derived from the supplied class. The object will be supplied as a single argument to the tostring specifier function, which allows the tostring() value to be assembled at runtime and include elements such as the objects name, co-ordinates or other realtime information. The specifier function should return a string.
    The default behaviour is for the generated string to be cached in the object table, at the __cached_tostring field. Further calls to tostring() will then return the cached string rather than regenerating it each time. If this is undesirable - for example if the generated string might change as the object changes state - then the do_not_cache flag may be set on this function.
    The flag to not append the memory address may be set if the memory address of the table is not wanted on the end of the returned tostring value. The default behaviour is to append the memory address.

    Parameters:

    1

    table

    class table

    2

    string

    custom type

    Returns:

    1. nil

    Example - Setting a function tostring specifier:

    TYPE_CAT = "cat"

    -- class definition
    cat = {}
    set_class_tostring(cat, function(cat_obj) return TYPE_CAT .. "_" .. cat_obj.name end)

    -- object definition
    cat_freddy = {name = "freddy"}
    set_object_class(cat_freddy, cat)
    out(tostring(cat_freddy))
    cat_freddy: 000001C2B9D4E730
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 150

    set_class_custom_type_and_tostring(table class table, string custom type value)

    Sets the custom type and tostring value on the supplied class table to the supplied string value. This function calls set_class_custom_type and set_class_tostring to do this.

    Parameters:

    1

    table

    class table

    2

    string

    custom type value

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 226

    set_object_class(table object table, table class table, ... additional interfaces)

    Sets the supplied object to index from the supplied class in a manner that emulates object-orientation. This will set the class to be the metatable of the object and will set the __index field of the metatable also to the supplied class. This means that if functions or values are looked up on the object and are not present they are then looked up on the class. It is through this kind of mechanism that object-orientation may be emulated in lua. Because the class is also the metatable, it means the metatable is shared between objects of the same type. Use set_object_class_unique if this is not desired.
    set_object_class will also associate the object with any custom type or tostring values that have been previously set up on the class with calls to set_class_custom_type and set_class_tostring.
    Any number of additional classes and objects may be specified, from which the main supplied object will also derive. If a value (such as a function to be called) is looked up on the object and is not provided on the object or the main class table it derives from, it will be looked up in turn on each additional classes or objects supplied. These additional objects/classes may be table or userdata values.

    Parameters:

    1

    table

    Object table.

    2

    table

    Class table.

    3

    ...

    Additional classes or objects to index.

    Returns:

    1. object
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 360

    set_object_class_unique(table object table, table class table, ... additional interfaces)

    Sets the supplied object to index from the supplied class in a manner that emulates object-orientation. This will set up a metatable unique to this object and will set the __index field of this metatable to the supplied class. This means that if functions or values are looked up on the object and are not present they are then looked up on the class. It is through this kind of mechanism that object-orientation may be emulated in lua. In contrast to object-to-class relationships set up with set_object_class the metatable is not shared between objects of the same type, which is less memory-efficient but may be desirable in certain circumstances.
    set_object_class_unique will also associate the object with any custom type or tostring values that have been previously set up on the class with calls to set_class_custom_type and set_class_tostring.
    Any number of additional classes and objects may be specified, from which the main supplied object will also derive. If a value (such as a function to be called) is looked up on the object and is not provided on the object or the main class table it derives from, it will be looked up in turn on each additional classes or objects supplied. These additional objects/classes may be table or userdata values.

    Parameters:

    1

    table

    Object table.

    2

    table

    Class table.

    3

    ...

    Additional classes or objects to index.

    Returns:

    1. object
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 373

    set_class_metatable(table class table, table metatable, [boolean allow overwrite])

    Sets the metatable of the specified class table to the supplied table. This also sets the __is_class_definition field in the metatable which set_object_class uses internally to know the difference between a class definition (which has no concept of self) and an object definition (which does) in certain circumstances. This function is for use in specific situations where a class definition requires a metatable and objects derive from it.

    Parameters:

    1

    table

    Class table.

    2

    table

    Metatable.

    3

    boolean

    optional, default value=false

    Allow the overwriting of the metatable if one already exists.

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 386

    Back to top

    Lua Type Checking

    The functions in this section can be used to check whether variables are a built-in type.

    is_nil(value value)
    Returns true if the supplied value is nil, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 437

    is_number(value value)
    Returns true if the supplied value is a number, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is number
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 446

    is_function(value value)
    Returns true if the supplied value is a function, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is function
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 455

    is_string(value value)
    Returns true if the supplied value is a string, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is string
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 464

    is_boolean(value value)
    Returns true if the supplied value is a boolean, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is boolean
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 473

    is_table(value value)
    Returns true if the supplied value is a table, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is table
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 482

    is_userdata(value value)
    Returns true if the supplied value is userdata, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is userdata
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 491

    Back to top

    Complex Lua Type Checking

    The functions in this section can be used to check whether variables are specific arrangements of built-in types.

    is_integer(value value)
    Returns true if the supplied value is a whole number with no decimal component, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is integer
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 512

    is_positive_number(value value)
    Returns true if the supplied value is a number greater than 0, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is positive number
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 521

    is_non_negative_number(value value)
    Returns true if the supplied value is a number greater than or equal to 0, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is non-negative number
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 530

    is_empty_table(value value)
    Returns true if the supplied value is an empty table, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is an empty table
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 539

    is_non_empty_table(value value)
    Returns true if the supplied value is a table containing one or more values at any keys, or false otherwise. See also is_non_empty_table_indexed which checks if the values are stored at numerical keys.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is non-empty table
    2. string error message
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 548

    is_non_empty_table_indexed(value value)
    Returns true if the supplied value is a numerically-indexed table containing one or more values, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is indexed table containing values
    2. string error message
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 565

    is_table_of_strings(value value)
    Returns true if the supplied value is a numerically-indexed table containing one or more string values, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is indexed table of strings
    2. string error message
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 582

    is_string_or_table_of_strings(value value)
    Returns true if the supplied value is a string, or a numerically-indexed table containing one or more string values. If the supplied value is neither of these types then false is returned.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is string/indexed table of strings
    2. string error message
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 602

    is_table_of_strings_allow_empty(value value)
    Returns true if the supplied value is an empty table or a numerically-indexed table containing one or more string values, or false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is indexed table of strings
    2. string error message
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 626

    is_condition(value value)
    Returns true if the supplied value is a function or the boolean value true. Event conditions in the scripting library commonly adhere to this format, where an event is received and the condition must either be a function that returns a result, or be the boolean value true. If the supplied value is not true or a function, then false is returned.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean value is a condition
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 645

    Back to top

    Common Type Checking

    The functions in this section can be used to check whether variables are of a code type that is not built-in to Lua but common across all our game environments.

    is_eventcontext(value value)
    Returns true if the supplied value is an event context, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is event context
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 669

    is_uicomponent(value value)
    Returns true if the supplied value is a uicomponent, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is uicomponent
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 678

    is_component(value value)
    Returns true if the supplied value is a component memory address, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is component memory address
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 687

    Back to top

    Campaign Code Type Checking

    The functions in this section can be used to check whether variables are of a userdata code type that is provided in the campaign environment. In certain cases the function also works in battle.

    is_null(value value)
    Returns true if the supplied value is a campaign null script interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is null
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 709

    is_model(value value)
    Returns true if the supplied value is a campaign model interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is model
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 718

    is_world(value value)
    Returns true if the supplied value is a campaign world interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is world
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 727

    is_faction(value value)
    Returns true if the supplied value is a campaign faction interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is faction
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 736

    is_factionlist(value value)
    Returns true if the supplied value is a campaign faction list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is faction list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 745

    is_character(value value)
    Returns true if the supplied value is a campaign character interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is character
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 754

    is_family_member(value value)
    Returns true if the supplied value is a campaign family member interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is family member
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 763

    is_characterlist(value value)
    Returns true if the supplied value is a campaign character list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is character list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 772

    is_regionmanager(value value)
    Returns true if the supplied value is a campaign region manager interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is region manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 781

    is_region(value value)
    Returns true if the supplied value is a campaign region interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is region
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 790

    is_regiondata(value value)
    Returns true if the supplied value is a campaign region data interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is region data
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 799

    is_province(value value)
    Returns true if the supplied value is a campaign province interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is province
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 808

    is_factionprovince(value value)
    Returns true if the supplied value is a campaign faction province interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is faction province
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 817

    is_regionlist(value value)
    Returns true if the supplied value is a campaign region list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is region list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 826

    is_garrisonresidence(value value)
    Returns true if the supplied value is a campaign garrison residence interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is garrison residence
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 835

    is_settlement(value value)
    Returns true if the supplied value is a campaign settlement interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is settlement
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 844

    is_slot(value value)
    Returns true if the supplied value is a campaign slot interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is slot
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 853

    is_slotlist(value value)
    Returns true if the supplied value is a campaign slot list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is slot list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 862

    is_militaryforce(value value)
    Returns true if the supplied value is a campaign military force interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is military force
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 871

    is_militaryforcelist(value value)
    Returns true if the supplied value is a campaign military force list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is military force list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 880

    is_unit(value value)
    Returns true if the supplied value is a unit object, false otherwise. This works in both campaign and battle on their respective unit object types.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is unit
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 889

    is_unitlist(value value)
    Returns true if the supplied value is a campaign unit list interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is unit list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 898

    is_pendingbattle(value value)
    Returns true if the supplied value is a campaign pending battle interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is pending battle
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 907

    is_campaignmission(value value)
    Returns true if the supplied value is a campaign mission interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is campaign mission
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 916

    is_campaignai(value value)
    Returns true if the supplied value is a campaign ai interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is campaign ai
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 925

    is_buildinglist(value value)
    Returns true if the supplied value is a building list object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is building list
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 934

    is_building(value value)
    Returns true if the supplied value is a building object in campaign or battle, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is building
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 943

    is_foreignslotmanager(value value)
    Returns true if the supplied value is a foreign slot manager interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is foreign slot manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 953

    is_foreignslot(value value)
    Returns true if the supplied value is a foreign slot interface, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is foreign slot
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 962

    Back to top

    Battle Code Type Checking

    The functions in this section can be used to check whether variables are of a userdata code type that is provided in the battle environment. In certain cases functions are shared with campaign, in which case they are listed with the campaign type-checking functions.

    is_battlesoundeffect(value value)
    Returns true if the supplied value is a battle sound effect, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is battle sound effect
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 987

    is_battle(value value)
    Returns true if the supplied value is an empire battle object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is battle
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 996

    is_alliances(value value)
    Returns true if the supplied value is an alliances object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is alliances
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1005

    is_alliance(value value)
    Returns true if the supplied value is an alliance, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is alliance
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1014

    is_armies(value value)
    Returns true if the supplied value is an armies object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is armies
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1023

    is_army(value value)
    Returns true if the supplied value is an army object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is army
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1032

    is_units(value value)
    Returns true if the supplied value is a units object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is units
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1041

    is_unitcontroller(value value)
    Returns true if the supplied value is a unitcontroller, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is unitcontroller
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1050

    is_vector(value value)
    Returns true if the supplied value is a vector object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is vector
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1059

    is_buildings(value value)
    Returns true if the supplied value is a buildings object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is buildings
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1068

    is_subtitles(value value)
    Returns true if the supplied value is a battle subtitles object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is subtitles
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1077

    Back to top

    Common Script Type Checking

    The functions in this section can be used to check whether variables are of a script data type that is provided in multiple game environments.

    is_core(value value)
    Returns true if the supplied value is a core object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is core
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1102

    is_timermanager(value value)
    Returns true if the supplied value is a timer manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is timer manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1111

    is_scriptmessager(value value)
    Returns true if the supplied value is a script messager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is script messager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1120

    is_customcontext(value value)
    Returns true if the supplied value is a custom event context, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is custom context
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1129

    is_objectivesmanager(value value)
    Returns true if the supplied value is an objectives_manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is objectives manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1138

    is_infotextmanager(value value)
    Returns true if the supplied value is an infotext_manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is infotext manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1147

    is_linkparser(value value)
    Returns true if the supplied value is a link parser, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is link parser
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1156

    is_tooltiplistener(value value)
    Returns true if the supplied value is a tooltip listener, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is tooltip listener
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1165

    is_contextvisibilitymonitor(value value)
    Returns true if the supplied value is a context visibility monitor, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is context visibility monitor
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1174

    is_tooltippatcher(value value)
    Returns true if the supplied value is a tooltip patcher, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is tooltip patcher
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1183

    is_helppagemanager(value value)
    Returns true if the supplied value is a help page manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is help page manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1192

    is_helppage(value value)
    Returns true if the supplied value is a help page, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is help page
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1201

    is_textpointer(value value)
    Returns true if the supplied value is a text pointer, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is text pointer
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1210

    is_activepointer(value value)
    Returns true if the supplied value is an active pointer, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is active pointer
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1219

    is_scriptedtour(value value)
    Returns true if the supplied value is a scripted tour, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is scripted tour
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1228

    is_navigabletour(value value)
    Returns true if the supplied value is a navigable tour, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is navigable tour
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1237

    is_navigabletoursection(value value)
    Returns true if the supplied value is a navigable tour section, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is navigable tour section
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1246

    is_movieoverlay(value value)
    Returns true if the supplied value is a movie_overlay, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is movie overlay
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1255

    is_windowedmovieplayer(value value)
    Returns true if the supplied value is a windowed_movie_player, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is windowed movie player
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1264

    is_topicleader(value value)
    Returns true if the supplied value is a topic_leader, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is topic leader
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1273

    Back to top

    Campaign Script Type Checking

    The functions in this section can be used to check whether variables are of a script data type that is provided in campaign.

    is_campaignmanager(value value)
    Returns true if the supplied value is a campaign manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is campaign manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1296

    is_factionstart(value value)
    Returns true if the supplied value is a faction start object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is faction start
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1305

    is_factionintrodata(value, value)
    Returns true if the supplied value is a faction intro data object, false otherwise.

    Parameters:

    1

    value,

    value

    Returns:

    1. boolean is intro data
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1314

    is_campaigncutscene(value value)
    Returns true if the supplied value is a campaign cutscene, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is campaign cutscene
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1323

    is_uioverride(value value)
    Returns true if the supplied value is a ui override, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is ui override
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1332

    is_campaignuimanager(value value)
    Returns true if the supplied value is a campaign ui manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is campaign ui manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1341

    is_missionmanager(value value)
    Returns true if the supplied value is a mission manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is mission manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1350

    is_chaptermission(value value)
    Returns true if the supplied value is a chapter mission, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is chapter mission
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1359

    is_intervention(value value)
    Returns true if the supplied value is an intervention, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is intervention
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1368

    is_interventionmanager(value value)
    Returns true if the supplied value is an intervention manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is intervention manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1377

    is_invasionmanager(value value)
    Returns true if the supplied value is an invasion manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is invasion manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1386

    is_randomarmy(value value)
    Returns true if the supplied value is a random army manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is random army manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1395

    is_narrativeevent(value value)
    Returns true if the supplied value is a narrative_event, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is narrative event
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1404

    is_narrativequery(value value)
    Returns true if the supplied value is a narrative_query, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is narrative query
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1413

    is_narrativetrigger(value value)
    Returns true if the supplied value is a narrative_trigger, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is narrative trigger
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1422

    Back to top

    Battle Script Type Checking

    The functions in this section can be used to check whether variables are of a script data type that is provided in battle.

    is_battlemanager(value value)
    Returns true if the supplied value is a battle_manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is battle manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1509

    is_cutscene(value value)
    Returns true if the supplied value is a battle cutscene, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is cutscene
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1518

    is_convexarea(value value)
    Returns true if the supplied value is a convex_area, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is convex area
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1527

    is_scriptunit(value value)
    Returns true if the supplied value is a script_unit, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is scriptunit
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1536

    is_scriptunits(value value)
    Returns true if the supplied value is a script_units object, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is scriptunits
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1545

    is_patrolmanager(value value)
    Returns true if the supplied value is a patrol manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is patrol manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1554

    is_waypoint(value value)
    Returns true if the supplied value is a patrol manager waypoint, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is waypoint
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1563

    is_scriptaiplanner(value value)
    Returns true if the supplied value is a script ai planner, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is script ai planner
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1572

    is_generatedbattle(value value)
    Returns true if the supplied value is a generated battle, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is generated battle
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1581

    is_generatedarmy(value value)
    Returns true if the supplied value is a generated army, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is generated army
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1590

    is_generatedcutscene(value value)
    Returns true if the supplied value is a generated cutscene, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is generated cutscene
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1599

    is_advicemanager(value value)
    Returns true if the supplied value is an advice manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is advice manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1608

    is_advicemonitor(value value)
    Returns true if the supplied value is an advice monitor, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is advice monitor
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1617

    is_attacklanemanager(value value)
    Returns true if the supplied value is an attack lane manager, false otherwise.

    Parameters:

    1

    value

    value

    Returns:

    1. boolean is attack lane manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_types.lua, line 1626

    Back to top

    Volume Types

    A handful of sound-related functions in battle require a volume type to be specified when they are called. The values described below represent those volume types. They can be passed into functions such as battle:set_volume and battle:get_volume to specify a volume type.

    Variables in this section:

    These variables may be accessed via <interface>.<variable_name>:

    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.
    Back to top

    Iterators

    model_pairs(object parent list object)
    An iterator for use with model objects in campaign and battle. When used in a for loop with a model list object, the iterator function returns the index and next item provided by the list object each loop pass.
    In campaign, this iterator supports all model list objects such as region_list, character_list, military_force_list etc. In battle, this iterator supports model list objects such as battle_alliances, battle_armies and battle_units, as well as script_units script collection objects.

    Parameters:

    1

    object

    parent list object

    Returns:

    1. object child list item

    Example - model_pairs usage in campaign:

    local region_list = cm:model():world():region_manager():region_list();
    for i, region in model_pairs(region_list) do
        out(i .. " " .. region:name());
    end;
    list of all regions

    Example - model_pairs usage in battle:

    for i, unit in model_pairs(bm:get_player_army():units()) do
        bm:out(i .. ": unit with id " .. unit:unique_ui_id() .. " is at position " .. v_to_s(unit:position()));
    end;
    list of player units
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 41

    uic_pairs(uicomponent parent uicomponent object)

    An iterator for use with uicomponent objects, which returns each child in succession. When used in a for loop with a uicomponent object, the iterator function returns the index number and the child corresponding to that index each loop pass.

    Parameters:

    1

    uicomponent

    parent uicomponent object

    Returns:

    1. object child uicomponent iterator

    Example:

    local uic_parent = find_uicomponent(core:get_ui_root(), "some_parent")
    out("Listing children of some_parent:");
    for i, uic_child in uic_pairs(uic_parent) do
        out("\tChild " .. i .. " is " .. uic_child:Id());
    end;
    Listing children of some_parent:
        Child 0 is first_child
        Child 1 is some_other_child
        Child 2 is yet_another_child
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 87

    Back to top

    Angle Conversions

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 122

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 135

    Back to top

    File and Folder Paths

    Functions to help get the filename and path of the calling script.

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 160

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 223

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 261

    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 .. Battle

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

    Back to top

    UIComponents

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 338

    find_child_uicomponent_by_index(uicomponent parent ui component, number index)
    Takes a uicomponent and an index. Searches the direct children (and no further - not grandchildren etc) of the supplied uicomponent. If a uicomponent with the correct index is found then it is returned, otherwise false is returned.

    Parameters:

    1

    uicomponent

    parent ui component

    2

    number

    starting at 0

    Returns:

    1. uicomponent child, or false if not found
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 354

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 406

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 436

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 474

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 515

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 554

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 619

    print_all_uicomponent_children([uicomponent subject uic], [boolean full output])

    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

    optional, default value=uiroot

    subject uic

    2

    boolean

    optional, default value=false

    full output

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 634

    pulse_uicomponent(
      uicomponent     ui component,
      boolean     should pulse,
      [number     brightness],
      [boolean     progagate],
      [string     state name]
    )
    Activates or deactivates a pulsing highlight effect on a particular state of 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

    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 no string state name is supplied here then the current state is used.

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 655

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 699

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 715

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 733

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 754

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 774

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 795

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 829

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 839

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 863

    unhighlight_all_visible_children()
    Cancels any and all highlights created with highlight_all_visible_children.

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

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

    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 .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 897

    unhighlight_component_table()
    Cancels any and all highlights created with highlight_component_table.

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 987

    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 .. Battle

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

    uicomponent_has_parent_filter(uicomponent uicomponent, function filter)

    Returns true if the supplied uicomponent has a parent or ancestor that matches the supplied filter, or false otherwise. The filter should be a function that accepts a uicomponent as a single argument and returns true or false depending on whether the uicomponent passes the filter. The first matching ancestor is also returned.

    Parameters:

    1

    uicomponent

    uicomponent

    2

    function

    filter

    Returns:

    1. boolean uic parent passes filter
    2. uicomponent first matching ancestor
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 1008

    Back to top

    Advisor Progress Button

    get_advisor_progress_button()
    Returns the advisor progress/close button uicomponent.

    Returns:

    1. uicomponent
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 1050

    show_advisor_progress_button([boolean show button])
    Shows or hides the advisor progress/close button.

    Parameters:

    1

    boolean

    optional, default value=true

    show button

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 1074

    highlight_advisor_progress_button([boolean show button])
    Activates or deactivates a highlight on the advisor progress/close button.

    Parameters:

    1

    boolean

    optional, default value=true

    show button

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_common.lua, line 1104

    Back to top

    Infotext Manager

    get_infotext_manager()
    Gets an infotext manager, or creates one if one doesn't already exist.

    Returns:

    1. infotext_manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_infotext.lua, line 114

    Back to top

    Objectives Manager

    get_objectives_manager()
    Gets an objectives manager, or creates one if one doesn't already exist.

    Returns:

    1. objectives_manager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_objectives.lua, line 67

    Back to top

    Script Messager

    get_messager()
    Gets or creates a script_messager object.

    Returns:

    1. script_messager
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_script_messager.lua, line 10

    Back to top

    Mod Output

    ModLog(string output text)

    Writes output to the lua_mod_log.txt text file, and also to the game console.

    Parameters:

    1

    string

    output text

    Returns:

    1. nil
    Loaded in Battle Loaded in .. Battle

    defined in ../../warhammer/working_data/script/_lib/lib_mod_loader.lua, line 34

    Back to top

    Other Functionality

    Variables in this section:

    These variables may be accessed via <interface>.<variable_name>:

    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.

    Functions in this section:

    UIComponent(address component address)
    Casts a component memory address, returned by several functions such as uicomponent:Find, into a valid uicomponent script object so that functions in the uicomponent script interface may be called on it.
    This function is provided by the UI code.

    Parameters:

    1

    address

    component address

    Returns:

    1. uicomponent
    Loaded in Battle Loaded in .. Battle

    defined in ../../common/UiComponentLib/Source/LuaComponentInterface.cpp, line 449

    Last updated 7/9/2024 11:45:05 AM