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

defined in ../../Warhammer/working_data/script/all_scripted.lua, line 56

Back to top

Output

out(string output)
out is a table that provides multiple methods for outputting text to the game console. It may be called as a function to output a string to the main Lua tab, but the following table elements within it may also be called to output to different output tabs:
  • autotest

  • chaos

  • design

  • help_pages

  • interventions

  • invasions

  • narrative

  • savegame

  • scripted_tours

  • status

  • traits

  • ui


    • 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 tab. To each of these functions a string argument can be supplied which sets the name of the console tab to apply the modification to. Supply no argument or a blank string to modify the tab level of the main console output.

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

    defined in ../../Warhammer/working_data/script/all_scripted.lua, line 165

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

    defined in ../../Warhammer/working_data/script/all_scripted.lua, line 447

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

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/all_scripted.lua, line 456

    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_to_s(vector subject vector)
    Converts a vector to a string, for debug output

    Parameters:

    1

    vector

    subject vector

    Returns:

    1. string
    Loaded in Campaign Loaded in .. Campaign

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

    v_offset(vector source vector, [number x offset], [number y offset], [number z offset])
    Takes a source vector and some x/y/z offset values. Returns a target vector which is offset from the source by the supplied values.

    Parameters:

    1

    vector

    source vector

    2

    number

    optional, default value=0

    x offset

    3

    number

    optional, default value=0

    y offset

    4

    number

    optional, default value=0

    z offset

    Returns:

    1. target vector
    Loaded in Campaign Loaded in .. Campaign

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

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

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

    v_add(vector vector a, vector vector b)
    Takes two vectors, and returns a third which is the sum of both.

    Parameters:

    1

    vector

    vector a

    2

    vector

    vector b

    Returns:

    1. target vector
    Loaded in Campaign Loaded in .. Campaign

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

    v_subtract(vector vector a, vector vector b)
    Takes two vectors, and returns a third which is the second subtracted from the first.

    Parameters:

    1

    vector

    vector a

    2

    vector

    vector b

    Returns:

    1. target vector
    Loaded in Campaign Loaded in .. Campaign

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

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

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

    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],
      [callback     to use when generating random numbers]
    )
    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.

    6

    callback

    optional, default value=nil

    this is a must when using the function in the model, otherwise the game will desync

    Returns:

    1. vector target position
    Loaded in Campaign Loaded in .. Campaign

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

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 376

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

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 386

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

    Parameters:

    1

    vector

    first position

    2

    vector

    second position

    3

    number

    distance

    Returns:

    1. vector target position
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 396

    dot(vector first position, vector second position)
    Returns the dot product of two supplied vectors.

    Parameters:

    1

    vector

    first position

    2

    vector

    second position

    Returns:

    1. number dot product
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 420

    dot3d(vector first position, vector second position)
    Returns the dot product of two supplied vectors in three dimensions.

    Parameters:

    1

    vector

    first position

    2

    vector

    second position

    Returns:

    1. number dot product
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 430

    normal(vector first position, vector second position)
    Returns the normal vector of two supplied vectors.

    Parameters:

    1

    vector

    first position

    2

    vector

    second position

    Returns:

    1. vector normal
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 440

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

    Parameters:

    1

    vector

    line position a

    2

    vector

    line position b

    3

    vector

    target position

    Returns:

    1. number distance
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 450

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

    Parameters:

    1

    object

    Collection of position objects to test. Supported collection object types are scriptunits, units, army, armies, alliance or a numerically-indexed table of any supported objects.

    2

    vector

    line position a

    3

    vector

    line position b

    4

    boolean

    Do not count positions of any routing or dead units

    Returns:

    1. boolean has crossed line
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 478

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

    Parameters:

    1

    vector

    line position a

    2

    vector

    line position b

    3

    number

    distance

    Returns:

    1. vector position along line
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 572

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

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 590

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

    defined in ../../Warhammer/working_data/script/_lib/lib_convex_area.lua, line 604

    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.

    Back to top

    Game Object Iterators

    See also the section on Table 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 Campaign Loaded in .. Campaign

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

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 124

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 137

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 162

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 225

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 263

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 279

    Back to top

    Tables

    table_find(table subject table, object or function find, [boolean If set to true and an object is found])
    Returns the first occurance of the provided object, if find is not a function, or the first object for which find returns a true value if find is a function. Returns nil otherwise.

    Parameters:

    1

    table

    subject table

    2

    object

    or function find

    3

    boolean

    optional, default value=false

    return its index instead of the object

    Returns:

    1. object or nil the first occurance or satisfying ojbect in the table
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 336

    table_find_extremum(table subject table , function compare, [boolean If set to true and an object is found])
    Returns the extremum among the elements of a table (such as minimum or maximum).

    Parameters:

    1

    table

    subject table

    2

    function

    compare

    3

    boolean

    optional, default value=false

    return its index instead of the object

    Returns:

    1. The extremum in the table, such as minimum or maximum.
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 352

    table_get_random_element(table subject table)
    Returns a randomly chosen element regardless of whether the table uses keys or not (or mixed). MP safe as long as keys/indexes have deterministic 'tostring'. Inefficient, not suitable for large tables and frequent use

    Parameters:

    1

    table

    subject table

    Returns:

    1. a randomly chosen element of the table and the key of that element
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 371

    table_contains(table subject table, object object)
    Returns true if the supplied indexed table contains the supplied object.

    Parameters:

    1

    table

    subject table

    2

    object

    object

    Returns:

    1. boolean table contains object
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 387

    table_append(destination destination table, source source table)
    Append the contents of the indexed table destination with the contents of the index table source.

    Parameters:

    1

    destination

    destination table

    2

    source

    source table

    Returns:

    1. destination table
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 402

    table_erase(table subject table, object object)
    Erase from the indexed table the supplied element. Returns true if the table contains the object and it was erased.

    Parameters:

    1

    table

    subject table

    2

    object

    object

    Returns:

    1. boolean table contained object
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 415

    table_erase_if(table subject table, filter filter function)
    Erase from the indexed table all elements that fullfil the supplied predicate. Returns true if any elements were removed.

    Parameters:

    1

    table

    subject table

    2

    filter

    filter function

    Returns:

    1. boolean table contained elements that fullfilled the filter
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 431

    table_erase_if_first_only(table subject table, filter filter function)
    Erase from the indexed table only the first element that fullfils the supplied predicate. Returns true if the table contains the object and it was erased.

    Parameters:

    1

    table

    subject table

    2

    filter

    filter function

    Returns:

    1. boolean table contained elements that fullfilled the filter
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 449

    table_add_unique(table subject table, object object)
    Add to the end of the indexed table the supplied element, but only if it did not already exist inside it. Returns true if the table did not contain the object and it was added.

    Parameters:

    1

    table

    subject table

    2

    object

    object

    Returns:

    1. boolean table did not contain object
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 465

    table_stable_sort(
      table     subject table,
      comp     comparison function,
      [in_place     A flag whether the operation should be done in-place. Slower than to simply assign to the result]
    )
    Stable sort the contents of the indexed table using the provided comp function. A very simple and inefficient not-in-place way to do this, but probably OK for small tables.

    Parameters:

    1

    table

    subject table

    2

    comp

    comparison function

    3

    in_place

    optional, default value=false

    but could be useful if working with a passed as a parameter table.

    Returns:

    1. sorted table
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 481

    table_accumulate(table subject table, obj initial value, [op operator function])
    Accumulate the contents of the indexed table using the provided op function or + if no function is provided.

    Parameters:

    1

    table

    subject table

    2

    obj

    initial value

    3

    op

    optional, default value=+

    taking as first argument the so far accumulated value and as second argument the next element of the table. If not provided, + is used

    Returns:

    1. accumulated value of the table
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 527

    table_read_only(table subject table)
    Prevents to edit a table

    Parameters:

    1

    table

    subject table

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 547

    table_deep_copy(object_to_copy - the object we want a copy of)
    Makes a deep copy (recursive copy by value, not reference) of all objects, including tables

    Parameters:

    1

    object_to_copy

    - the object we want a copy of

    Returns:

    1. - the copy of obj
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 562

    table_print(node - the table we want to print)
    Iterates through the table and prints it in the console

    Parameters:

    1

    node

    - the table we want to print

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 589

    table_size(
      t:     the supplied table,
      [table_dimension:     if positive integer N then consider t as an N-dimensional table and recurse accordingly (N-1 times) to find its length],
      seen:     the function should NOT be called with a value for this parameter; it is nil by default and it is used as a safeguard against infinite recursion and cyclical tables
    )
    Returns the amount of elements in the table

    Parameters:

    1

    t:

    the supplied table

    2

    table_dimension:

    optional, default value=1

    if true then recurse infinitely-deep

    3

    seen:

    the function should NOT be called with a value for this parameter; it is nil by default and it is used as a safeguard against infinite recursion and cyclical tables

    Returns:

    1. integer size of the table, or nil if error
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 598

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 649

    find_child_uicomponent_by_property(
      uicomponent     parent ui component,
      string     property key,
      string     property value,
      [    table exception ids]
    )

    Takes a uicomponent, and a string property key and value. Searches the direct children (and no further - not grandchildren etc) of the supplied uicomponent for a uicomponent where the property key/value matches what has been supplied. If a uicomponent where the value of the specified property matches the supplied value then it is returned, otherwise false is returned.

    Parameters:

    1

    uicomponent

    parent ui component

    2

    string

    property key

    3

    string

    property value

    4

    table

    optional, default value=nil

    An optional table of component ids/names that are excluded from the search criteria.

    Returns:

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 666

    find_children_uicomponents(
      uicomponent     parent : the ui component to start the search from,
      function     func : a predicate function
    )
    Takes a uicomponent and an arbitrary predicate function. Searches the direct children (and no further grandchildren) of the supplied uicomponent for other uicomponents for which the supplied predicate function returns true. All such found uicomponents are returned into an array; the array could be empty.

    Parameters:

    1

    uicomponent

    parent : the ui component to start the search from

    2

    function

    func : a predicate function

    Returns:

    1. table of uicomponent(s) or empty table
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 689

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

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

    find_uicomponent_from_table(uicomponent parent ui component, table table of string names)
    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.

    Returns:

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 742

    uicomponent_descended_from(
      uicomponent     subject uic,
      string     parent name,
      boolean     [opt=nil] include_parent : if true it takes into account the possibility for uic's id to be the parent_name requested (effectively turning the function into "uicomponent_descended_from_or_is")
    )
    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

    3

    boolean

    [opt=nil] include_parent : if true it takes into account the possibility for uic's id to be the parent_name requested (effectively turning the function into "uicomponent_descended_from_or_is")

    Returns:

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 762

    uicomponent_find_up(uicomponent subject uic, string parent specifier)

    Searches within the ui hierarchy above a supplied uicomponent, and finds and returns a uicomponent that matches a specifier argument. The specifier argument can be a string or a function, and the parent of the supplied uicomponent, then the parent of that parent, and so on back to the ui root are queried until a match is found.
    If a string specifier is given, that is tested against the name of each parent uicomponent in turn. If a function specifier is given instead, then that function is called for each parent in sequence, with the parent candidate being supplied to the function as a single argument. If the function returns a value other than nil or false then that is considered a match.
    If a match is found, then that particular parent uicomponent is returned. Otherwise, nil is returned.

    Parameters:

    1

    uicomponent

    subject uic

    2

    string

    Parent specifier. This can either be a string name, or a function that, when called with the candidate uicomponent, returns true.

    Returns:

    1. uicomponent parent uicomponent, or nil if no matching parent was found
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 823

    uicomponent_find_down(uicomponent subject uic, string child specifier)

    Searches within the ui hierarchy below a supplied uicomponent, and finds and returns a uicomponent that matches a specifier argument. The specifier argument can be a string or a function, and the supplied uicomponent itself, then its children recursively are queried until a match is found. The search is depth-first, so the children of the first child are queried before the second child is.
    If a string specifier is given, that is tested against the name of each child uicomponent. If a function specifier is given instead, then that function is called for each child uicomponent, with the candidate child being supplied to the function as a single argument. If the function returns a value other than nil or false then that is considered a match.
    If a match is found, then that particular child uicomponent is returned. Otherwise, nil is returned.
    Use this function with caution with a uicomponent that has many children, as the search could be expensive.

    Parameters:

    1

    uicomponent

    subject uic

    2

    string

    Child specifier. This can either be a string name, or a function that, when called with the candidate uicomponent, returns true.

    Returns:

    1. uicomponent child uicomponent, or nil if no matching child was found
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 866

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 899

    output_uicomponent(uicomponent subject uic, [boolean omit children])
    Outputs extensive debug information about a supplied uicomponent to the console.

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 923

    output_uicomponent_on_click()
    Starts a listener which outputs information to the console about every uicomponent that's clicked on.

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1013

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1028

    pulse_uicomponent(
      uicomponent     ui component,
      boolean     should pulse,
      [number     brightness],
      [boolean     progagate],
      [string     state name]
    )
    Activates or deactivates a pulsing highlight effect on the supplied uicomponent. This is primarily used for scripts which activate when the player moves the mouse cursor over certain words in the help pages, to indicate to the player what UI feature is being talked about on the page.

    Parameters:

    1

    uicomponent

    Subject ui component.

    2

    boolean

    Set to true to activate the pulsing effect, false to deactivate it.

    3

    number

    optional, default value=0

    Pulse brightness. Set a higher number for a more pronounced pulsing effect.

    4

    boolean

    optional, default value=false

    Propagate the effect through the component's children. Use this with care, as the visual effect can stack and often it's better to activate the effect on specific uicomponents instead of activating this.

    5

    string

    optional, default value=nil

    Optional state name to affect. If a string name is supplied, the pulsing effect is only applied to the specified state instead of to all states on the component.

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1049

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1088

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

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

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1122

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1143

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

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

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1184

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1219

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1229

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1255

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

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1282

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1289

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

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1379

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1390

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1406

    create_confirmation_box(
      string     id of the uicomponent that is going to be created,
      string     localisation_key,
      [function     on_accept_callback],
      [function     on_cancel_callback],
      [uicomponent     uic_parent]
    )
    Creates confirmation box component with the specified id, text and accept / cancel callbacks

    Parameters:

    1

    string

    id of the uicomponent that is going to be created

    2

    string

    localisation_key

    3

    function

    optional, default value=nil

    on_accept_callback

    4

    function

    optional, default value=nil

    on_cancel_callback

    5

    uicomponent

    optional, default value=nil

    Parent uicomponent

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1429

    create_confirmation_box_with_text_from_script(
      string     id of the uicomponent that is going to be created,
      string     text Localised text constructed in lua,
      string     text_source Source of the localised text,
      [function     on_accept_callback],
      [function     on_cancel_callback],
      [uicomponent     uic_parent],
      [string     title_text Localised title text constructed in lua],
      [string     title_text_source Source of the localised title text constructed in lua]
    )
    Creates confirmation box component with the specified id, localised_text constructed in the scripts and accept / cancel callbacks

    Parameters:

    1

    string

    id of the uicomponent that is going to be created

    2

    string

    text Localised text constructed in lua

    3

    string

    text_source Source of the localised text

    4

    function

    optional, default value=nil

    on_accept_callback

    5

    function

    optional, default value=nil

    on_cancel_callback

    6

    uicomponent

    optional, default value=nil

    Parent uicomponent

    7

    string

    optional, default value=nil

    title_text Localised title text constructed in lua

    8

    string

    optional, default value=nil

    title_text_source Source of the localised title text constructed in lua

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1443

    Back to top

    Advisor Components

    get_advisor_progress_buttons()
    Returns a table containing advisor progress/close button uicomponents, in order of precedence.

    Returns:

    1. table of uicomponent objects
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1591

    get_advisor_non_progress_controls()
    Returns a table containing advisor back/forward and settings buttons.

    Returns:

    1. table of uicomponent objects
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1610

    get_all_advisor_controls()
    Returns a table containing advisor back/forward and settings buttons, as well as advisor close/progress buttons.

    Returns:

    1. table of uicomponent objects
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1631

    show_advisor_progress_buttons([boolean show button])
    Makes the advisor progress/close buttons active or inactive.

    Parameters:

    1

    boolean

    optional, default value=true

    show button

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

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

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

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1683

    Back to top

    Localised Text

    get_localised_text_replacement_source(string record key)

    Returns a full localised text key for the ui_text_replacements database table, corresponding to the supplied key. If the supplied key is already a full localised text key in the [table]_[field]_[key] format then it is returned without modification, otherwise it is assumed to be a key of a record in the ui_text_replacements database table. In this case, the supplied string is returned with "ui_text_replacements_localised_text_" prepended to it, to convert the string to a full localised text key.

    Parameters:

    1

    string

    record key

    Returns:

    1. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1743

    get_localised_text_replacement(string record key)

    Returns the localised text corresponding to the supplied record from the ui_text_replacements database table. The key is passed through get_localised_text_replacement_source, so it may be supplied as the key for a record from the ui_text_replacements table, or as a full localised text key in the [table]_[field]_[key] format.

    Parameters:

    1

    string

    record key

    Returns:

    1. string localised text
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1755

    get_localised_text_replacement_safe_formatted(string record key, ... formatting arguments)

    Gets the localised text corresponding to the supplied record from the ui_text_replacements database table, and performs a unicode-safe format operation using common.string_safe_format and the supplied formatting arguments, before returning it. One or more formatting arguments can be provided.

    Parameters:

    1

    string

    UI text replacements record key.

    2

    ...

    Formatting arguments to pass to common.string_safe_format.

    Returns:

    1. string formatted string

    Example:

    -- Consider a record in the ui_text_replacements db table with key "example_shakespeare_quote" and value "Alas, poor %1%"
    print( get_localised_text_replacement_safe_formatted("example_shakespeare_quote", "Yoric") )
    Alas, poor Yoric
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1764

    get_localised_text_replacement_and_source(string record key)

    Returns the localised text (by calling get_localised_text_replacement) and text key (by calling get_localised_text_replacement_source) for a specified record from the ui_text_replacements database table. As with get_localised_text_replacement and get_localised_text_replacement_source, the specified key may be a record key from the ui_text_replacements database table, or as a full localised text key in the [table]_[field]_[key] format.

    Parameters:

    1

    string

    record key

    Returns:

    1. string localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1777

    get_localised_text_replacement_and_source_formatted(string record key, ... formatting arguments)

    Returns localised text (from get_localised_text_replacement) passed through string.format with the supplied format arguments, and also the text key (by calling get_localised_text_replacement_source), for a specified record from the ui_text_replacements database table. As with get_localised_text_replacement and get_localised_text_replacement_source, the specified key may be a record key from the ui_text_replacements database table, or as a full localised text key in the [table]_[field]_[key] format.
    The format arguments are supplied to this function as a variable number of arguments, in exactly the same way that they may be supplied to string.format. The localised text string is formatted before it is returned.

    Parameters:

    1

    string

    UI text replacements record key.

    2

    ...

    One or more string formatting arguments.

    Returns:

    1. string formatted localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1787

    get_localised_text_replacement_and_source_safe_formatted(string record key, ... formatting arguments)

    Returns localised text (from get_localised_text_replacement) passed through common.string_safe_format with the supplied format arguments, and also the text key (by calling get_localised_text_replacement_source), for a specified record from the ui_text_replacements database table. common.string_safe_format provides certain unicode-safe formatting functions - see the documentation of that function for more details.
    As with get_localised_text_replacement and get_localised_text_replacement_source, the specified key may be a record key from the ui_text_replacements database table, or as a full localised text key in the [table]_[field]_[key] format.
    The format arguments are supplied to this function as a variable number of arguments, in exactly the same way that they may be supplied to common.string_safe_format. The localised text string is formatted before it is returned.

    Parameters:

    1

    string

    UI text replacements record key.

    2

    ...

    One or more string formatting arguments.

    Returns:

    1. string formatted localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1799

    get_localised_random_string_source(string record key)

    Returns a full localised text key for the random_localisation_strings database table, corresponding to the supplied key. If the supplied key is already a full localised text key in the [table]_[field]_[key] format then it is returned without modification, otherwise it is assumed to be a key of a record in the random_localisation_strings database table. In this case, the supplied string is returned with "random_localisation_strings_string_" prepended to it, to convert the string to a full localised text key.

    Parameters:

    1

    string

    record key

    Returns:

    1. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1812

    get_localised_random_string(string record key)

    Returns the localised text corresponding to the supplied record from the random_localisation_strings database table. The key is passed through get_localised_random_string_source, so it may be supplied as the key for a record from the random_localisation_strings table, or as a full localised text key in the [table]_[field]_[key] format.

    Parameters:

    1

    string

    record key

    Returns:

    1. string localised text
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1824

    get_localised_random_string_safe_formatted(string record key, ... formatting arguments)

    Gets the localised text corresponding to the supplied record from the random_localisation_strings database table, and performs a unicode-safe format operation using common.string_safe_format and the supplied formatting arguments, before returning it. One or more formatting arguments can be provided.

    Parameters:

    1

    string

    Random localised strings record key.

    2

    ...

    Formatting arguments to pass to common.string_safe_format.

    Returns:

    1. string formatted string

    Example:

    -- Consider a record in the random_localisation_strings db table with key "example_shakespeare_quote" and value "Alas, poor %1%"
    print( get_localised_random_string_safe_formatted("example_shakespeare_quote", "Yoric") )
    Alas, poor Yoric
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1833

    get_localised_random_string_and_source(string record key)

    Returns the localised text (by calling get_localised_random_string) and text key (by calling get_localised_random_string_source) for a specified record from the random_localisation_strings database table. As with get_localised_random_string and get_localised_random_string_source, the specified key may be a record key from the ui_text_replacements database table, or as a full localised text key in the [table]_[field]_[key] format.

    Parameters:

    1

    string

    record key

    Returns:

    1. string localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1846

    get_localised_random_string_and_source_formatted(string record key, ... formatting arguments)

    Returns localised text (from get_localised_random_string) passed through string.format with the supplied format arguments, and also the text key (by calling get_localised_random_string_source), for a specified record from the random_localisation_strings database table. As with get_localised_random_string and get_localised_random_string_source, the specified key may be a record key from the ui_text_replacements database table, or as a full localised text key in the [table]_[field]_[key] format.
    The format arguments are supplied to this function as a variable number of arguments, in exactly the same way that they may be supplied to string.format. The localised text string is formatted before it is returned.

    Parameters:

    1

    string

    Random localised strings record key.

    2

    ...

    One or more string formatting arguments.

    Returns:

    1. string formatted localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1856

    get_localised_random_string_and_source_safe_formatted(string record key, ... formatting arguments)

    Returns localised text (from get_localised_random_string) passed through common.string_safe_format with the supplied format arguments, and also the text key (by calling get_localised_random_string_source), for a specified record from the random_localisation_strings database table. common.string_safe_format provides certain unicode-safe formatting functions - see the documentation of that function for more details.
    As with get_localised_random_string and get_localised_random_string_source, the specified key may be a record key from the random_localisation_strings database table, or as a full localised text key in the [table]_[field]_[key] format.
    The format arguments are supplied to this function as a variable number of arguments, in exactly the same way that they may be supplied to common.string_safe_format. The localised text string is formatted before it is returned.

    Parameters:

    1

    string

    Random localised strings record key.

    2

    ...

    One or more string formatting arguments.

    Returns:

    1. string formatted localised text
    2. string full localised text key
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1868

    append_with_newline(
          string message the main string we want to add to,
      string     addition the string we want to add to the main one
    )

    Small util method to add a string to another string, on a new line
    Intended to make sure a list has all items on separate lines without a leading new line

    Parameters:

    1

    string

    message the main string we want to add to

    2

    string

    addition the string we want to add to the main one

    Returns:

    1. string the two strings combined
    Loaded in Campaign Loaded in .. Campaign

    defined in ../../Warhammer/working_data/script/_lib/lib_common.lua, line 1880

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

    defined in ../../Warhammer/working_data/script/_lib/lib_infotext.lua, line 130

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

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

    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 development console.

    Parameters:

    1

    string

    output text

    Returns:

    1. nil
    Loaded in Campaign Loaded in .. Campaign

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

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

    Last updated 8/23/2024 4:55:15 PM