Core

The core object provides a varied suite of functionality that is sensible to provide in all the various game modes (campaign/battle/frontend). When the script libraries are loaded, a core_object is automatically created. It is called 'core' and the functions it provides can be called with a double colon e.g. core:get_ui_root()

Examples of the kind of functionality provided by the core object are event listening and triggering, ui access, and saving and loading values to the scripted value registry.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

A core object is automatically created when the script libraries are loaded so there should be no need for client scripts to call core:new themselves.

core:new()
Creates a core object. There is no need for client scripts to call this, as a core object is created automatically by the script libraries when they are loaded.

Returns:

  1. core_object

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 155

Back to top

Usage

Once created (which happens automatically within the declaration of the script libraries), functions on the core object may be called in the form showed below.

Example - Specification:

core:<function_name>(<args>)

Example - Creation and Usage:

core = core_object:new()        -- object called 'core' is automatically set up

-- later, after UI creation
local x, y = core:get_screen_resolution()
out("Screen resolution is [" .. x .. ", " .. y .. "]")
Screen resolution is [1600, 900]
Back to top

UI Root

Functions concerning the UI root.

core:get_ui_root()
Gets a handle to the ui root object. A script_error is thrown if this is called before the ui has been created.

Returns:

  1. uicomponent ui root

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 323

core:set_ui_root(uicomponent ui root)
sets the ui root object that the core stores. Not to be called outside of the script libraries.

Parameters:

1

uicomponent

ui root

Returns:

  1. nil

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

core:is_ui_created()
Returns whether the ui has been created or not. Useful if clients scripts are running so early in the load sequence that the ui may not have been set up yet.
Once this function returns true, client scripts should be okay to start asking questions of the game and model.

Returns:

  1. boolean is ui created

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 350

Back to top

UI Creation and Destruction

The core object listens for the UI being created and destroyed. Client scripts can register callbacks with the core object to get notified when the UI is set up or destroyed.

It is strongly advised that client scripts use this functionality rather than listen for the UICreated and UIDestroyed events directly, because the core object sets up the UI root before sending out notifications about the ui being created.

core:add_ui_created_callback(function callback)

Adds a callback to be called when the UI is created.

Parameters:

1

function

callback

Returns:

  1. nil

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

core:add_ui_destroyed_callback(function callback)
Adds a callback to be called when the UI is destroyed.

Parameters:

1

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 408

Back to top

Game Configuration

Functions that return information about the game.

core:is_debug_config()
Returns true if the game is not running in final release or intel configurations, false if the game is running in debug or profile configuration

Returns:

  1. boolean is debug config

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 453

core:is_tweaker_set(string tweaker name)
Returns whether a tweaker with the supplied name is set

Parameters:

1

string

tweaker name

Returns:

  1. boolean tweaker is set

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 461

core:get_screen_resolution()
Returns the current screen resolution

Returns:

  1. integer screen x dimension
  2. integer screen y dimension

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 471

Back to top

Current Game Mode

Functions that return the mode the game is currently running in.

core:is_campaign()
Returns whether the game is currently in campaign mode.

Returns:

  1. boolean is campaign

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 488

core:is_battle()
Returns whether the game is currently in battle mode.

Returns:

  1. boolean is battle

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 496

core:is_frontend()
Returns whether the game is currently in the frontend.

Returns:

  1. boolean is battle

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 504

core:is_autotest()
Returns whether this is actually an autotest script environment.

Returns:

  1. boolean is autotest

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 512

core:get_current_game_mode()
Returns a string indicating the current game mode - currently either campaign, battle, frontend or autotest.

Returns:

  1. string current game mode

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 520

Back to top

Previous Game Mode

Functions that return what mode the previous game environment was. For example, if a campaign was quit back to frontend the previous game environment would be campaign, or f a custom battle is loaded from the frontend the previous game environment would be frontend.

core:previous_game_mode_was_campaign()
Returns whether the game environment before the current game environment was campaign.

Returns:

  1. boolean previous game mode was campaign

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 539

core:previous_game_mode_was_battle()
Returns whether the game environment before the current game environment was battle.

Returns:

  1. boolean previous game mode was battle

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

core:previous_game_mode_was_frontend()
Returns whether the game environment before the current game environment was frontend.

Returns:

  1. boolean previous game mode was frontend

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 555

core:get_previous_game_mode()
Returns a string indicating the current game mode - currently either campaign, battle, frontend, autotest, or a blank string if the current environment is the first game environment in the session (e.g. we're in the frontend after launching the game).

Returns:

  1. string previous game mode

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 563

Back to top

Script Environment

core:get_env()
Returns the current global lua function environment. This can be used to force other functions to have global scope.

Returns:

  1. table environment

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 580

Back to top

Timer Manager

core:get_tm()
Returns a handle to the timer manager created for the current environment.

Returns:

  1. timer_manager timer manager

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 600

Back to top

Mod Loading

Functions for loading and, in campaign, executing mod scripts. Note that ModLog can be used by mods for output.

core:load_mods(... paths)
Loads all mod scripts found on each of the supplied paths, setting the environment of every loaded mod to the global environment.

Parameters:

1

...

List of string paths from which to load mods from. The terminating / character must be included.

Returns:

  1. boolean All mods loaded correctly

Example:

core:load_mods("/script/_lib/mod/", "/script/battle/mod/");

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 621

core:execute_mods(... arguments)
Attempts to execute a function of the same name as the filename of each mod that has previously been loaded by core:load_mods. For example, if mods have been loaded from mod_a.lua, mod_b.lua and mod_c.lua, the functions mod_a(), mod_b() and mod_c() will be called, if they exist. This can be used to start the execution of mod scripts at an appropriate time, particularly during campaign script startup.
One or more arguments can be passed to execute_mods, which are in-turn passed to the mod functions being executed.

Parameters:

1

...

Arguments to be passed to mod function(s).

Returns:

  1. boolean No errors reported

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 750

core:is_mod_loaded(string mod name)

Returns whether a mod with the supplied name is loaded. The path may be omitted.

Parameters:

1

string

mod name

Returns:

  1. boolean mod is loaded

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 795

Back to top

Advice Level

Functions concerning the advice level setting, which defaults to 'high' but can be changed by the player.

core:get_advice_level()
Returns the current advice level value. A returned value of 0 corresponds to 'minimal', 1 corresponds to 'low', and 2 corresponds to 'high'.

Returns:

  1. integer advice level

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 826

core:is_advice_level_minimal()
Returns whether the advice level is currently set to minimal.

Returns:

  1. boolean is advice level minimal

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 834

core:is_advice_level_low()
Returns whether the advice level is currently set to low.

Returns:

  1. boolean is advice level low

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 842

core:is_advice_level_high()
Returns whether the advice level is currently set to high.

Returns:

  1. boolean is advice level high

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 850

Back to top

Scripted Value Registry

The scripted value registry is an object supplied by the game to script which can be used to set values that persist over lua sessions. As lua sessions are destroyed/recreated when the game loads from one mode to another (campaign to battle, frontend to campaign etc) the svr makes it possible for scripts to store information for scripts in future sessions to retrieve.

This information is cleared when the game as a whole is closed and re-opened, but the scripted value registry also allows boolean values to be saved in the registry. Such values will persist, even between reloads of the game client.

The core object automatically creates a handle to the scripted value registry and an interface to it. The following functions can be called to interact with the scripted value registry.

core:get_svr()
Returns a handle to the scripted value registry object. It shouldn't be necessary to call this, as the core object provides access to all its functionality through its wrapper functions.

Returns:

  1. scripted_value_registry svr

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 870

core:svr_save_bool(string value name, boolean value)
Saves a boolean value to the svr. This will persist as the game loads between modes (campaign/battle/frontend) but will be destroyed if the game is restarted.

Parameters:

1

string

value name

2

boolean

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 878

core:svr_load_bool(string value name)
Retrieves a boolean value from the svr.

Parameters:

1

string

value name

Returns:

  1. boolean value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 897

core:svr_save_string(string value name, string value)
Saves a string value to the svr. This will persist as the game loads between modes (campaign/battle/frontend) but will be destroyed if the game is restarted.

Parameters:

1

string

value name

2

string

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 906

core:svr_load_string(string value name)
Retrieves a string value from the svr.

Parameters:

1

string

value name

Returns:

  1. string value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 925

core:svr_save_registry_bool(string value name, boolean value)
Saves a boolean value to the registry. This will persist, even if the game is reloaded.

Parameters:

1

string

value name

2

boolean

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 934

core:svr_load_registry_bool(string value name)
Loads a boolean value from the registry.

Parameters:

1

string

value name

Returns:

  1. boolean value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 953

core:svr_save_registry_string(string value name, string value)

Saves a string value to the registry. This will persist, even if the game is reloaded.

Parameters:

1

string

value name

2

string

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 962

core:svr_load_registry_string(string value name)

Loads a string value from the registry.

Parameters:

1

string

value name

Returns:

  1. string value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 981

core:svr_save_timestamp(string timestamp name)

Records a timestamp with the supplied name. This can be compared to a later timestamp with core:svr_time_since_timestamp to see how much time has elapsed between two game events. This value is saved into the registry so will survive between game sessions.
This can be used to trigger advice if the player has not performed a certain action in game for a given period (e.g. not loaded a campaign in three months), for example.

Parameters:

1

string

timestamp name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 990

core:svr_time_since_timestamp(string timestamp name)

Returns the number of seconds since a timestamp with the supplied name was last recorded with core:svr_save_timestamp. If the timestamp has never been recorded then nil is returned.

Parameters:

1

string

timestamp name

Returns:

  1. number seconds since timestamp last recorded

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1003

Back to top

Preferences

User preferences are stored and listed in %appdata%\The Creative Assembly\<game>\scripts\preferences.script.txt. They may be read and written with the functions below. Different functions must be used for different value types. Preference names and the type of each preference value are shown in the preferences.script.txt file.

core:get_boolean_preference(string preference name)

Returns a boolean preference value. The value is looked up by a string preference name.

Parameters:

1

string

preference name

Returns:

  1. boolean preference value

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

core:set_boolean_preference(string preference name, boolean preference value)

Sets a boolean preference value, by string preference name.

Parameters:

1

string

preference name

2

boolean

preference value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1041

core:cache_boolean_preference(string preference name)

Looks up a boolean preference value by name, stores it in an internal cache, and returns the value. The cached value may be later restored with core:restore_boolean_preference.

Parameters:

1

string

preference name

Returns:

  1. boolean preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1054

core:cache_and_set_boolean_preference(string preference name, boolean new value)

Caches and then sets a boolean preference value. Equivalent to calling core:cache_boolean_preference and then core:set_boolean_preference. The value cached by core:cache_boolean_preference is returned.

Parameters:

1

string

preference name

2

boolean

new value

Returns:

  1. boolean existing preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1068

core:restore_boolean_preference(string preference name)

Looks up a boolean preference value by name from the internal cache and sets the preference to the looked-up value. The value retrieved from the cache is also returned by the function. The preference value must have been written to the cache with core:cache_boolean_preference beforehand - if no cached value could be found then the preference is not set and nil is returned.

Parameters:

1

string

preference name

Returns:

  1. boolean restored preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1085

core:get_integer_preference(string preference name)

Returns an integer preference value. The value is looked up by a string preference name.

Parameters:

1

string

preference name

Returns:

  1. number integer preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1099

core:set_integer_preference(string preference name, number preference value)

Sets an integer preference value, by string preference name.

Parameters:

1

string

preference name

2

number

preference value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1112

core:cache_integer_preference(string preference name)

Looks up an integer preference value by name, stores it in an internal cache, and returns the value. The cached value may be later restored with core:restore_integer_preference.

Parameters:

1

string

preference name

Returns:

  1. number preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1125

core:cache_and_set_integer_preference(string preference name, number new value)

Caches and then sets an integer preference value. Equivalent to calling core:cache_integer_preference and then core:set_integer_preference. The value cached by core:cache_integer_preference is returned.

Parameters:

1

string

preference name

2

number

new value

Returns:

  1. number existing preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1139

core:restore_integer_preference(string preference name)

Looks up an integer preference value by name from the internal cache and sets the preference to the looked-up value. The value retrieved from the cache is also returned by the function. The preference value must have been written to the cache with core:cache_integer_preference beforehand - if no cached value could be found then the preference is not set and nil is returned.

Parameters:

1

string

preference name

Returns:

  1. number restored preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1156

core:get_float_preference(string preference name)

Returns an float preference value. The value is looked up by a string preference name.

Parameters:

1

string

preference name

Returns:

  1. number float preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1170

core:set_float_preference(string preference name, number preference value)

Sets an float preference value, by string preference name.

Parameters:

1

string

preference name

2

number

preference value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1183

core:cache_float_preference(string preference name)

Looks up an float preference value by name, stores it in an internal cache, and returns the value. The cached value may be later restored with core:restore_float_preference.

Parameters:

1

string

preference name

Returns:

  1. number preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1196

core:cache_and_set_float_preference(string preference name, [number new value])

Caches and then sets a float preference value. Equivalent to calling core:cache_float_preference and then core:set_float_preference. The value cached by core:cache_float_preference is returned.

Parameters:

1

string

preference name

2

number

optional, default value=nil

new value

Returns:

  1. number existing preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1210

core:restore_float_preference(string preference name)

Looks up an float preference value by name from the internal cache and sets the preference to the looked-up value. The value retrieved from the cache is also returned by the function. The preference value must have been written to the cache with core:cache_float_preference beforehand - if no cached value could be found then the preference is not set and nil is returned.

Parameters:

1

string

preference name

Returns:

  1. number restored preference value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1227

Back to top

Lookup Listeners

For script events which are triggered often and in which many client scripts might be interested in listening for, such as FactionTurnStart in campaign or ComponentLClickUp across the game, it's common for client scripts to test the context of that event against a known value (e.g. does the faction have this string key or does the component have this string name) and to only proceed if there's a match. With many listeners all listening for the same common event, these tests can become more and more expensive.

The lookup listener system is designed to alleviate this. It allows for downstream systems such as the campaign_manager to declare lookup listeners for events like FactionTurnStart, which listen for that event, query the faction name or any other static value and then look up and trigger listeners that have subscribed to that event and lookup key combination. This is much more computationally efficient than having many listeners all running their own individual tests each time the event is triggered.

Such a listener system may be set up by calling core:declare_lookup_listener. Client scripts can then register a callback with core:add_lookup_listener_callback, although it may be beneficial to set up wrappers for this functionality (see campaign_manager:add_faction_turn_start_listener_by_name for an example). core:remove_lookup_listener_callback can be called to remove listeners by name.

Example - Declares a lookup listener that triggers listeners by faction name:

core:declare_lookup_listener(
    "faction_turn_start_faction_name",
    "FactionTurnStart",
    function(context) return context:faction():name() end
);

-- adds a listener entry to the declared lookup listener
-- to trigger when wh_main_emp_empire starts a turn
core:add_lookup_listener_callback(
    "faction_turn_start_faction_name",
    "test",
    "wh_main_emp_empire",
    function() out("Empire are starting a turn") end,
    true
);

core:declare_lookup_listener(string list name, string event name, function test)

Declares a new lookup listener, which listens for the supplied event and then calls listener records based on the key generated by the supplied test function. The test function will be called when the event is received and will be passed the event context. It should return a value which can be used to look up listeners added with core:add_lookup_listener_callback.
See the section documentation Lookup Listeners for an example of usage.

Parameters:

1

string

Unique list name.

2

string

Script event to listen for.

3

function

Conditional test to perform on the function context. This must return a value.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1334

core:add_lookup_listener_callback(
  string list name,
  string listener name,
  value lookup value,
  function callback,
  boolean persistent
)

Adds a listener entry to a lookup listener previously declared with core:declare_lookup_listener. This specifies a lookup value which, should it match the value produced by the test specified when the lookup listener was declared, will cause the supplied callback to be called.
See the section documentation Lookup Listeners for an example of usage.

Parameters:

1

string

Lookup listener to add this listener entry to. This should match the name passed to core:declare_lookup_listener.

2

string

Listener name, by which this listener entry may later be removed with core:remove_lookup_listener_callback if desired. It is valid to have multiple listeners with the same name.

3

value

Lookup value. If, when the test function supplied to core:declare_lookup_listener is called it returns this value, then the callback for this listener will be called. The value given here can be any type.

4

function

Callback to call if the lookup value is matched.

5

boolean

Is this a persistent listener. If false is specified here the listener will stop the first time the callback is triggered. If true, the listener will continue until cancelled with core:remove_lookup_listener_callback.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1382

core:remove_lookup_listener_callback(string list name, string listener name)

Removes any listener entries from the specified lookup listener that match the supplied name.

Parameters:

1

string

Lookup listener to remove listener entries from.

2

string

Name of listener to remove. This corresponds with the listener name specified when core:add_lookup_listener_callback is called.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1456

Back to top

Fullscreen Highlighting

A fullscreen highlight is an effect where the screen is masked out with a semi-opaque layer on top, apart from a window in the middle through which the game interface can be seen. This can be used by tutorial scripts to draw the player's attention to a particular part of the screen. The fullscreen highlight prevents the player from clicking on those portions of the screen that are masked off.

A fullscreen highlight effect may be established around a supplied set of components with core:show_fullscreen_highlight_around_components. Once established, a fullscreen highlight effect must later be removed with core:hide_fullscreen_highlight.

This fullscreen highlight functionality wraps the uicomponent:FullScreenHighlight function. It's recommended to use this wrapper rather than calling the uicomponent function directly.

core:show_fullscreen_highlight_around_components(
  number padding,
  [string highlight text key],
  [boolean allow interaction],
  ... uicomponent list
)
Shows a fullscreen highlight around multiple components at the same time. An invisible dummy uicomponent is created, and positioned/sized so that it extends from the top-left corner to the bottom-right corner of the supplied uicomponents. Therefore, the window in the fullscreen highlight will reveal all of the supplied components.
Once established, this highlight must later be removed with core:hide_fullscreen_highlight.
An integer padding value must also be supplied, which specifies how much additional visual padding to give the components shown in the window. The higher the supplied value, the bigger the visual window around the supplied components.
The function also supports showing text from the random_localisation_strings database table on the fullscreen highlight while it's being displayed.

Parameters:

1

number

Padding value, must be 0 or greater

2

string

optional, default value=nil

Key of text to show on the fullscreen highlight, if text is desired. If set, this should be the key of an entry from the random_localisation_strings database table. nil or an empty string can be supplied to specify that no text should be shown.

3

boolean

optional, default value=false

Allow the components shown in the central fullscreen highlight window to be interacted with while the highlight is active.

4

...

Vararg (variable number of arguments) of uicomponent objects. The components may also be specified here as either string names, in which case they will be looked up from the ui root, or as table paths of string names, in which case the paths will be passed to find_uicomponent_from_table in order to look up the intended uicomponent. See the examples given below.

The uicomponents can be specified in any order - which one is top-left and which one is bottom-right will be computed automatically.

Returns:

  1. nil

Example - usage of show_fullscreen_highlight_around_components with uicomponent specifiers:

local uic_example_top_left = find_uicomponent("parent_panel", "example_top_left")
local uic_example_bottom_right = find_uicomponent("parent_panel", "example_bottom_right")
local uic_example_additional_component_1 = find_uicomponent("parent_panel", "example_additional_1")
local uic_example_additional_component_2 = find_uicomponent("parent_panel", "example_additional_2")

core:show_fullscreen_highlight_around_components(
    25,                            -- 25 px padding
    nil,                        -- no text
    true,                        -- allow interaction
    -- list of uicomponents
    uic_example_top_left,
    uic_example_bottom_right,
    uic_example_additional_component_1,
    uic_example_additional_component_2,
)

Example - usage of show_fullscreen_highlight_around_components with string specifiers:

core:show_fullscreen_highlight_around_components(
    0,                            -- no padding
    "example_rls_text_key",        -- text key from "random_localisation_strings" database table
    false,                        -- prevent interaction
    -- list of uicomponent names: they will be looked up from the ui root, so will need to be unique
    "unique_component_name_1",
    "unique_component_name_2",
    "unique_component_name_3"
)

Example - usage of show_fullscreen_highlight_around_components with table path specifiers:

core:show_fullscreen_highlight_around_components(
    100,        -- 100px padding
    nil,        -- no text
    true,        -- allow interaction
    -- list of uicomponent paths: they will be looked up from the ui root
    {"grandparent", "parent", "unique_component_name_1"},
    {"grandparent", "parent", "unique_component_name_2"},
    {"grandparent", "parent", "unique_component_name_3"}
)

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1550

core:hide_fullscreen_highlight([boolean immediate])

Hides/destroys the active fullscreen highlight.

Parameters:

1

boolean

optional, default value=false

Hide the fullscreen highlight effect immediately instead of over a short period.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1744

core:set_fullscreen_highlight_interactive([boolean value])
Sets the active fullscreen highlight to be interactive. An interactive fullscreen highlight will respond to clicks. By default fullscreen highlights are non-interactive, but the functionality to make them interactive is provided here in case it's needed.

Parameters:

1

boolean

optional, default value=true

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1768

core:set_fullscreen_highlight_window_interactive([boolean value])
Sets the active fullscreen highlight to be interactive. An interactive fullscreen highlight will respond to clicks. By default fullscreen highlights are non-interactive, but the functionality to make them interactive is provided here in case it's needed.

Parameters:

1

boolean

optional, default value=true

value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1788

Back to top

Advisor Priority Cache

Functionality to set and reset the advisor UI priority, which determines at what level the advisor is displayed (i.e. on top of/underneath other components). This is useful during tutorial scripting when the ui priority of other elements on the screen (particularly fullscreen highlighting) has been modified, or is otherwise interfering with the visibility of the advisor.

core:cache_and_set_advisor_priority()
Sets the advisor priority to the supplied value, and caches the value previously set. The advisor priority can later be restored with restore_advisor_priority.
The register_topmost flag can also be set to force the advisor to topmost.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1825

core:restore_advisor_priority()
Restores the advisor priority to a value previously cached with cache_and_set_advisor_priority.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1851

Back to top

UIComponent Creation

core:get_or_create_component(string name, string file path, [uicomponent parent])
Creates a UI component with the supplied name, or retrieves it if it's already been created.

Parameters:

1

string

Name to give uicomponent.

2

string

File path to uicomponent layout, from the working data folder.

3

uicomponent

optional, default value=ui_root

Parent uicomponent.

Returns:

  1. uicomponent created or retrieved uicomponent
  2. boolean uicomponent was created

Example:

uic_skip_button = core:get_or_create_component("scripted_tour_skip_button", "UI/Common UI/scripted_tour_skip_button")

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1882

Back to top

Event Handling

The core object provides a wrapper interface for client scripts to listen for events triggered by the game code, which is the main mechanism by which the game sends messages to script.

core:add_listener(
  string listener name,
  string event name,
  function conditional test,
  function target callback,
  boolean persistent,
  [boolean prevent duplicates]
)

Adds a listener for an event. When the code triggers this event, and should the optional supplied conditional test pass, the core object will call the supplied target callback with the event context as a single argument.
A name must be specified for the listener which may be used to cancel it at any time. Names do not have to be unique between listeners.
The conditional test should be a function that returns a boolean value. This conditional test callback is called when the event is triggered, and the listener only goes on to trigger the supplied target callback if the conditional test returns true. Alternatively, a boolean true value may be given in place of a conditional callback, in which case the listener will always go on to call the target callback if the event is triggered.
Once a listener has called its callback it then shuts down unless the persistent flag is set to true, in which case it may only be stopped by being cancelled by name.

Parameters:

1

string

String name for this listener, by which it may be later removed if necessary with core:remove_listener.

2

string

Event name to listen for.

3

function

Conditional test, or true to always pass.

4

function

Target callback to call when the conditional test passes.

5

boolean

Listener persists after target callback called.

6

boolean

optional, default value=false

Prevents adding listeners with a duplicate name. If this argument is true, and there is already a listener with the same name listening for the same event, this new listener will not be added.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 1916

core:remove_listener(string listener name)
Removes and stops any event listeners with the specified name.

Parameters:

1

string

listener name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2135

core:trigger_event(string event name, ... context data items)
Triggers an event from script, to which event listeners will respond. An event name must be specified, as well as zero or more items of data to package up in a custom event context. See custom_context documentation for information about what types of data may be supplied with a custom context. A limitation of the implementation means that only one data item of each supported type may be specified.
By convention, the names of events triggered from script are prepended with "ScriptEvent" e.g. "ScriptEventPlayerFactionTurnStart".

Parameters:

1

string

event name

2

...

context data items

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2176

core:trigger_custom_event(string event name, [table data items])

Triggers an event from script with a context object constructed from custom data. An event name must be specified, as well as a table containing context data at key/value pairs. For keys that are strings, the value corresponding to the key will be added to the custom_context generated, and will be available to listening scripts through a function with the same name as the key value. An example might be a hypothetical event ScriptEventCharacterInfected, with a key disease and a value which is the name of the disease. This would be accessible to listeners of this event that call context:disease().
Should the key not be a string then the data is added to the context as normal, as if supplied to custom_context:add_data.
By convention, the names of events triggered from script are prepended with "ScriptEvent" e.g. "ScriptEventPlayerFactionTurnStart".

Parameters:

1

string

event name

2

table

optional, default value=nil

data items

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2214

Back to top

Custom Event Generator

A custom event generator is a simple listener that listens for event, tests a condition, and if the condition passes triggers a target event with some optional context data. Performance and code re-use can be improved by setting up a custom event generator rather than having lots of instances of client scripts all listening for the same event and performing the same conditional test as one another.

core:start_custom_event_generator(
  string source event,
  function condition,
  string target event,
  [function context generator]
)
Adds a custom event generator.

Parameters:

1

string

Source event to listen for.

2

function

Conditional test to perform. This test will be passed the context of the source event just triggered as a single argument, and should return a boolean value. If the condition returns true, or a value that evaluates to true, the target event will be triggered.

3

string

Target event to fire if the source event is received and the condition passes. By convention, events triggered from script begin with "ScriptEvent"

4

function

optional, default value=nil

Function that returns an object to be placed on the context of the target event

Returns:

  1. nil

Example - ScriptEventPlayerBesieged:

This script fires a "ScriptEventPlayerBesieged" event, with the besieged region attached to the context, when a player settlement is besieged in campaign.
core:start_custom_event_generator(
    "CharacterBesiegesSettlement",
    function(context) return context:region():owning_faction():name() == cm:get_local_faction_name() end,
    "ScriptEventPlayerBesieged",
    function(context) return context:region() end
)

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2278

core:stop_custom_event_generator()
Stops a custom event generator, by the name of the target event. If multiple custom generators produce the same target event they will all be stopped.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2331

Back to top

Performance Monitoring

core:monitor_performance(function function to call, number time limit in s, string name)
Immediately calls a supplied function, and monitors how long it takes to complete. If this duration is longer than a supplied time limit a script error is thrown. A string name must also be specified for the function, for output purposes.

Parameters:

1

function

function to call

2

number

time limit in s

3

string

name

Returns:

  1. boolean passed perfomance check

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2348

Back to top

Limited Callbacks

The utility functions described in this section can be useful for script that goes round a loop of an indeterminate number of cycles (e.g. some script monitoring player interaction where they can click back and forth as many times as they like) which wishes to call an external function only on the first time, or the first x number of times, around the loop. Using these utility functions means those scripts do not have to maintain a counter of how many times the function has been called themselves.

core:call_limited(string name, function callback, [number quantity])

Calls the supplied function if the number of previously function calls with the supplied name is less than the supplied limit. Only function calls handled by call_limited (or core:call_once) are counted. If the function is called then the internal counter associated with the name given is incremented.

Parameters:

1

string

Name of the callback record to check.

2

function

Callback to call.

3

number

optional, default value=1

Maximum number of times a callback with this name can be called. If the internal counter of the number of callbacks related to the supplied name is less than this supplied quantity then the callback will be called.

Returns:

  1. boolean callback was called

Example:

-- This will be called, as no callback with the name test_callback has been previously called
core:call_limited("test_callback", function() out("This is a test") end, 1)
-- This will not be called, as the number of callbacks with the supplied
-- name is not less than the supplied quantity (1)
core:call_limited("test_callback", function() out("This is a test") end, 1)
-- This will be called, as the quantity has been increased.
-- The callback being different doesn't matter as the name is the same.
core:call_limited("test_callback", function() out("A different callback") end, 2)
This is a test
A different callback

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2391

core:call_once(string name, function callback)

Calls the supplied function if no function with the supplied name has previously been called by call_once or core:call_limited.

Parameters:

1

string

Name of the callback record to check.

2

function

Callback to call.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2444

Back to top

Text and Active Pointers

Functionality to help prevent text pointers with duplicate names.

core:is_text_pointer_name_registered(string text pointer name)
Returns true if a text pointer with the supplied name has already been registered, false otherwise.

Parameters:

1

string

text pointer name

Returns:

  1. boolean has been registered

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2465

core:register_text_pointer_name(string text pointer name)
Registers a text pointer with the supplied name.

Parameters:

1

string

text pointer name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2478

core:register_active_pointer(active_pointer active pointer)

Registers an active pointer. This is called automatically when an active pointer is set to save a record of itself into the advice history. It should not be called externally.

Parameters:

1

active_pointer

active pointer

Returns:

  1. boolean registration successful

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2499

core:get_active_pointer(string name)

Gets a previously-registered active pointer by name.

Parameters:

1

string

name

Returns:

  1. active_pointer active pointer

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2520

core:register_active_pointer_showing(active_pointer active pointer)

Registers that a particular active pointer is currently showing or not. Not to be called externally.

Parameters:

1

active_pointer

active pointer

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2529

core:is_any_active_pointer_showing()
Returns whether any active pointers are currently being displayed.

Returns:

  1. boolean active pointer is showing

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2545

core:get_showing_active_pointer_names()
Returns a sorted indexed table of the names of active pointers that are currently showing. There will usually be only zero or one active pointers being displayed at any given time, but in certain circumstances there could be more. The table will be sorted so that the active pointer names are in alphabetical order.

Returns:

  1. table names of active pointers currently showing

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2553

core:hide_all_text_pointers([boolean hide immediately])

Hide any text_pointer's current visible.

Parameters:

1

boolean

optional, default value=false

hide immediately

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2569

Back to top

Topic Leaders

core:hide_all_topic_leaders()
Immediately hide any topic_leader objects currently visible.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2592

Back to top

Info Overlays

core:close_info_overlays()
Immediately close any open info overlay.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2611

Back to top

Scripted Tours

core:get_active_scripted_tour()
Returns the scripted tour or navigable tour object that's currently playing. If no tour is currently playing then false is returned.

Returns:

  1. scripted_tour active tour

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2628

Back to top

Autonumbers

core:get_unique_counter()
Retrieves a unique integer number. Each number is 1 higher than the previous unique number. Useful for scripts that need to generate unique identifiers.

Returns:

  1. integer unique number

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2649

Back to top

Loading Screens/UI Event Progression

core:get_loading_screen()
Returns the name and uicomponent of any detected loading screen, or false if one is not currently resident in the ui hierarchy (which would indicate that loading has finished).

Returns:

  1. string loading screen name
  2. uicomponent loading screen uicomponent

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2666

core:is_loading_screen_visible()
Returns the name and uicomponent of any visible loading screen, or false otherwise.

Returns:

  1. string loading screen name
  2. uicomponent loading screen uicomponent

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2701

core:progress_on_loading_screen_dismissed(function callback, [boolean suppress wait])
Calls the supplied callback once the loading screen has been dismissed. If no loading screen is currently visible the function throws a script error and calls the callback immediately.

Parameters:

1

function

Callback to call.

2

boolean

optional, default value=false

Suppress wait for loading screen to animate offscreen.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2724

core:is_loading_screen_being_dismissed_this_tick()
Returns whether the game is in the process of progressing after a loading screen has been dismissed. This will true if a core:progress_on_loading_screen_dismissed callback is currently in the callstack, false otherwise. This test is provided because at the point where the progress callback is called, testing the loading screen visibility is not a reliable indicator of whether the loading screen has been dismissed (it is visible, but has been dismissed and is about to disappear).

Returns:

  1. boolean loading screen is currently being dismissed

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2819

core:progress_on_uicomponent_animation_finished(uicomponent uicomponent, function callback)
Calls the supplied callback once the supplied component has finished animating. This function polls the animation state every 1/10th of a second, so there may be a slight unavoidable delay between the animation finishing and the supplied callback being called.

Parameters:

1

uicomponent

uicomponent

2

function

callback

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2827

core:progress_on_uicomponent_animation(
  string unique name,
  uicomponent uicomponent,
  function callback,
  [number callback delay],
  [string animation name]
)
Calls the supplied callback when the active animation on the supplied uicomponent returns a certain string. By default this string is empty, which means this function would progress when the target uicomponent is not animating. However, an alternative animation name can be supplied, which makes this function progress when that animation plays instead.
Note that this script has to repeatedly poll the supplied uicomponent, so because of model tick resolution it's not possible to guarantee that the callback will be called the instant the animation changes to the desired state.

Parameters:

1

string

Unique name for this monitor (multiple such monitors may be active at once).

2

uicomponent

Target uicomponent.

3

function

Callback to call.

4

number

optional, default value=0

Time in seconds to wait after the animation finishes before calling the supplied callback.

5

string

optional, default value=""

Animation name which, when seen to be playing on the supplied uicomponent, causes the monitor to fire. The default animation name "" implies no animation playing.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2849

core:cancel_progress_on_uicomponent_animation(string unique name)

Cancels a monitor started with core:progress_on_uicomponent_animation by name.

Parameters:

1

string

Unique name for the monitor to cancel (multiple such monitors may be active at once).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2915

Back to top

Caching/Restoring UIComponent Tooltips

core:cache_and_set_tooltip_for_component_state(
  uicomponent subject uicomponent,
  string state name,
  string text key
)
Caches and sets the tooltip for a particular state of a component. Once cached, the tooltip may be restored with restore_tooltip_for_component_state. This is used by tutorial scripts that overwrite the tooltip state of certain UIComponents.
The tooltip text key should be supplied in the common localised text format [table]_[field_of_text]_[key_from_table].

Parameters:

1

uicomponent

subject uicomponent

2

string

state name

3

string

text key

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2940

core:restore_tooltip_for_component_state(uicomponent subject uicomponent, string state name)
Restores a tooltip for a uicomponent state that's been previously modified with cache_and_set_tooltip_for_component_state.

Parameters:

1

uicomponent

subject uicomponent

2

string

state name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 2985

Back to top

Localised Text Tags

core:strip_tags_from_localised_text(string text)
Strips any tags out of a localised text string. Tags stripped are "[[ .. ]]" and "{{ .. }}".

Parameters:

1

string

text

Returns:

  1. string stripped text

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3052

Back to top

Bit Checking

core:check_bit(number subject value, integer bit position)
Takes a number value and a numeric bit position. Returns true if the bit at the numeric bit position would be a '1' were the number value converted to binary, false otherwise.

Parameters:

1

number

subject value

2

integer

bit position

Returns:

  1. boolean bit value

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3102

Back to top

Static Object Registry

core:add_static_object(
  string object name,
  object object to register,
  [string classification],
  [boolean overwrite],
  [boolean silent]
)

Registers a static object by a string name, which can be retrieved later with core:get_static_object. This is intended for use as a registry of global static objects (objects of which there should only be one copy) such as battle_manager, campaign_manager, timer_manager, script_messager, generated_battle and so-on. Scripts that intended to create one of these objects can query the static object registry to see if they've been created before and, if not, can register it.
An optional classification string may be supplied to specify a grouping for the object. Static objects in different classifications may share the same name. This functionality can be used to register static objects of a particular type, e.g. a particular mission manager, and to ensure that names are unique amongst those objects.
If a static object with the supplied name and classification already exists then this function produces a script error unless the overwrite flag is set.
The static object registry is not saved into the campaign savegame or saved between game sessions.

Parameters:

1

string

Object name.

2

object

Object to register.

3

string

optional, default value=nil

Object classification.

4

boolean

optional, default value=false

Should overwrite if an object already exists with this name.

5

boolean

optional, default value=false

Do not generate a script error if the object couldn't be added.

Returns:

  1. boolean object added successfully

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3170

core:get_static_object(string object name, [string classification])

Returns the static object previously registered with the supplied string name and optional classification using core:add_static_object, if any such object has been registered, or nil if no object was found.

Parameters:

1

string

object name

2

string

optional, default value=nil

classification

Returns:

  1. object object

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3219

Back to top

Windowed Movie Players

core:stop_all_windowed_movie_players()
Stops any windowed movie players currently playing.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3258

core:register_windowed_movie_player(windowed_movie_player player)

Registers a windowed_movie_player with the core object so that it may be stopped if core:stop_all_windowed_movie_players is called. This is only intended to be called internally by windowed movie players.

Parameters:

1

windowed_movie_player

player

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3269

core:unregister_windowed_movie_player(windowed_movie_player player)

Unregisters a windowed_movie_player with the core object so that won't be stopped if core:stop_all_windowed_movie_players is called. This is only intended to be called internally by windowed movie players.

Parameters:

1

windowed_movie_player

player

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/_lib/lib_core.lua, line 3281

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