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 114

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 238

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 251

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 265

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 286

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 322

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 366

core:is_tweaker_set(string tweaker name)

Returns whether a boolean tweaker with the supplied name is set. If the tweaker is set to true or false then that value is returned, otherwise nil is returned.

Parameters:

1

string

tweaker name

Returns:

  1. boolean tweaker value (or nil if not set)

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 374

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 388

Back to top

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 405

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 413

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 421

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 439

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 459

Back to top

File Loading

Functions for file loading.

core:get_scripts_in_directory(string directory, [boolean include_file_extension])

Get a list of all lua files in the specified folder (relative from the working_data folder)

Parameters:

1

string

Directory to search under, relative to working_data. e.g. /script/campaign/

2

boolean

optional, default value=false

Whether or not to include the script file extension in the returned strings.

Returns:

  1. table List of the names of lua files found in this folder (including file expensions). Returns empty table if none were found.

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 479

Back to top

Filesystem

core:get_filepaths_from_folder(string folder path, [string filter])

Returns a list of all files in a specified folder, conforming to an optional filter. The list is returned as an indexed table of string file paths.
The folder path should be given from the working data folder. If no filter is supplied, then all files are searched for.

Parameters:

1

string

Folder path, from the working data folder.

2

string

optional, default value="*"

File filter.

Returns:

  1. table indexed table of file paths

Example:

local file_paths = core:get_filepaths_from_folder("/script/", "*scripted.lua")
for i = 1, #file_paths do
    out(file_paths[i])
end
script\all_scripted.lua
script\battle_scripted.lua
script\campaign_scripted.lua
script\frontend_scripted.lua

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

core:load_global_script(string script name)
This function attempts to load a lua script from all folders currently on the path, and, when loaded, sets the environment of the loaded file to match the global environment. This is used when loading scripts within a block (within if statement that is testing for the file's existence, for example) - loading the file with require would not give it access to the global environment.
If the script file fails to load cleanly, a script error will be thrown.

Parameters:

1

string

script name

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 553

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 613

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 746

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 791

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 822

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 830

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 838

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 846

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 866

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 874

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 893

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 902

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 921

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 930

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 949

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 958

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 977

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 986

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 999

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 1022

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 1035

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 1048

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 1062

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 1079

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 1093

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 1106

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 1119

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 1133

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 1150

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 1164

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 1177

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 1190

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 1204

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 1221

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 1327

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 1375

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 1449

Back to top

Fullscreen Highlighting

A fullscreen highlight is an effect where the screen is masked out with a semi-opaque layer on top, save for a window cut out 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 show_fullscreen_highlight_around_components(). Once established, a fullscreen highlight effect must be destroyed with hide_fullscreen_highlight().

This fullscreen highlight functionality wraps the FullscreenHighlight functionality provided by the underlying UI code. It's recommended to use this wrapper rather than calling the code functions directly.

core:show_fullscreen_highlight_around_components(
  number padding,
  [string highlight text],
  [boolean allow interaction],
  ... uicomponent list
)
Shows a fullscreen highlight around a supplied component list. Once established, this highlight must later be destroyed with hide_fullscreen_highlight().
An integer padding value must be supplied, which specifies how much visual padding to give the components. The higher the supplied value, the more space is given around the supplied components visually.
The underlying FullscreenHighlight functionality supports showing text on the fullscreen highlight itself. If you wish to specify some text to be shown, it may be supplied using the second parameter in the common localised text format [table]_[field_of_text]_[key_from_table].

Parameters:

1

number

Padding value, must be 0 or greater

2

string

optional, default value=nil

Highlight text key, may be nil.

3

boolean

optional, default value=false

Allows the components in the central window to be interacted with.

4

...

uicomponent list

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 1528

core:hide_fullscreen_highlight()
Hides/destroys the active fullscreen highlight.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 1658

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 1685

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 1705

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 1742

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 1778

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.twui.xml")

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 1817

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 listener persists after target callback called
)
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

listener name

2

string

event name

3

function

Conditional test, or true to always pass

4

function

target callback

5

boolean

listener persists after target callback called

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 1866

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 2071

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 2112

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

data items

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 2150

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 2212

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 2265

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 2282

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 2325

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 2378

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 2399

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 2412

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 2433

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 2454

core:is_any_active_pointer_showing()
Returns whether any active pointer is currently being displayed, as well as the active pointer being displayed if one is found.

Returns:

  1. boolean active pointer is showing
  2. active_pointer active pointer being shown

defined in ../../warhammer/working_data/script/_lib/lib_core.lua, line 2463

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 2480

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 2497

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 2514

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 2552

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 2572

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 2676

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 2698

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 2764

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 2789

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 2837

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 2900

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 2950

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 3018

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 3067

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 3106

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 3117

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 3129

Custom Context

A custom context is created when the core object is compelled to trigger an event with core:trigger_event or core:trigger_custom_event. Data items supplied to core:trigger_event or core:trigger_custom_event are added to the custom context, which is then sent to any script listening for the event being triggered.

The receiving script should then be able to interrogate the custom context it receives as if it were a context issued from the game code.

No script outside of trigger_event should need to create a custom context, but it's documented here in order to list the data types it supports.

Back to top

Functionality

custom_context:new()
Creates a custom context object.

Returns:

  1. custom_context

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 25

custom_context:add_data(object context data)
Adds data to the custom context object. Supported data types:
  • boolean: will be accessible to the receiving script as context.bool

custom_context:add_data_with_key(value value, string function name)

Adds data to the custom context which will be made accessible at the supplied function name. The function name is supplied by string key.

Parameters:

1

value

Value to add to custom context. Any value may be supplied.

2

string

Name of function at which the value may be retrieved, if called on the custom context.

Returns:

  1. nil

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 96

custom_context:table_data()
Called by the receiving script to retrieve the table placed on the custom context, were one specified by the script that created it.

Returns:

  1. table of user defined values

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 113

custom_context:region()
Called by the receiving script to retrieve the region object placed on the custom context, were one specified by the script that created it.

Returns:

  1. region region object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 121

custom_context:character()
Called by the receiving script to retrieve the character object placed on the custom context, were one specified by the script that created it.

Returns:

  1. character character object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 129

custom_context:target_character()
Called by the receiving script to retrieve the target character object placed on the custom context, were one specified by the script that created it. The target character is the second character added to the context.

Returns:

  1. character target character object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 137

custom_context:faction()
Called by the receiving script to retrieve the faction object placed on the custom context, were one specified by the script that created it.

Returns:

  1. faction faction object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 145

custom_context:component()
Called by the receiving script to retrieve the component object placed on the custom context, were one specified by the script that created it.

Returns:

  1. component component object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 153

custom_context:military_force()
Called by the receiving script to retrieve the military force object placed on the custom context, were one specified by the script that created it.

Returns:

  1. military_force military force object

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

custom_context:pending_battle()
Called by the receiving script to retrieve the pending battle object placed on the custom context, were one specified by the script that created it.

Returns:

  1. pending_battle pending battle object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 169

custom_context:garrison_residence()
Called by the receiving script to retrieve the garrison residence object placed on the custom context, were one specified by the script that created it.

Returns:

  1. garrison_residence garrison residence object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 177

custom_context:building()
Called by the receiving script to retrieve the building object placed on the custom context, were one specified by the script that created it.

Returns:

  1. building building object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 185

custom_context:vector()
Called by the receiving script to retrieve the vector object placed on the custom context, were one specified by the script that created it.

Returns:

  1. vector vector object

defined in ../../warhammer/working_data/script/_lib/lib_custom_context.lua, line 193

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