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 Battle loaded in battle
Loaded in Campaign loaded in campaign
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 ../working_data/script/_lib/lib_core.lua, line 95

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 ../working_data/script/_lib/lib_core.lua, line 218

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 ../working_data/script/_lib/lib_core.lua, line 231

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 ../working_data/script/_lib/lib_core.lua, line 245

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 ../working_data/script/_lib/lib_core.lua, line 266

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 ../working_data/script/_lib/lib_core.lua, line 303

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 ../working_data/script/_lib/lib_core.lua, line 348

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 ../working_data/script/_lib/lib_core.lua, line 356

core:get_screen_resolution()
Returns the current screen resolution

Returns:

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

defined in ../working_data/script/_lib/lib_core.lua, line 366

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 ../working_data/script/_lib/lib_core.lua, line 383

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

Returns:

  1. boolean is battle

defined in ../working_data/script/_lib/lib_core.lua, line 391

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

Returns:

  1. boolean is battle

defined in ../working_data/script/_lib/lib_core.lua, line 399

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 ../working_data/script/_lib/lib_core.lua, line 417

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 ../working_data/script/_lib/lib_core.lua, line 438

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 ../working_data/script/_lib/lib_core.lua, line 567

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 ../working_data/script/_lib/lib_core.lua, line 612

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 ../working_data/script/_lib/lib_core.lua, line 643

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

Returns:

  1. boolean is advice level minimal

defined in ../working_data/script/_lib/lib_core.lua, line 651

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

Returns:

  1. boolean is advice level low

defined in ../working_data/script/_lib/lib_core.lua, line 659

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

Returns:

  1. boolean is advice level high

defined in ../working_data/script/_lib/lib_core.lua, line 667

Back to top

Scripted Value Registry

The scriptedvalueregistry is an interface provided by the game to script which can be used to set values that persist over lua sessions. While client scripts are free to create their own scripted value registry handle and call its methods directly, core provides the following pass-through functions.

See the scriptedvalueregistry documentation for more information.

core:get_svr()
Returns a handle to the scripted value registry object.

Returns:

  1. scriptedvalueregistry svr

defined in ../working_data/script/_lib/lib_core.lua, line 689

core:svr_save_bool(string value name, boolean value)

Calls ScriptedValueRegistry:SaveBool to save a game session boolean value to the svr. Game session values are not reset until another campaign or the frontend is loaded.

Parameters:

1

string

value name

2

boolean

value

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 697

core:svr_load_bool(string value name)

Calls ScriptedValueRegistry:LoadBool to retrieve a game session boolean value from the svr. Game session values are not reset until another campaign or the frontend is loaded.

Parameters:

1

string

value name

Returns:

  1. boolean value

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

core:svr_save_string(string value name, string value)

Calls ScriptedValueRegistry:SaveString to save a game session string value to the svr. Game session values are not reset until another campaign or the frontend is loaded.

Parameters:

1

string

value name

2

string

value

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 725

core:svr_load_string(string value name)
Calls ScriptedValueRegistry:LoadString to retrieve a game session string value from the svr. Game session values are not reset until another campaign or the frontend is loaded.

Parameters:

1

string

value name

Returns:

  1. string value

defined in ../working_data/script/_lib/lib_core.lua, line 744

core:svr_save_persistent_bool(string value name, string value)

Calls ScriptedValueRegistry:SavePersistentBool to save a persistent boolean value to the svr. Persistent values are not reset until the game is shut down and restarted.

Parameters:

1

string

value name

2

string

value

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 758

core:svr_load_persistent_bool(string value name)

Calls ScriptedValueRegistry:LoadPersistentBool to load a persistent boolean value from the svr. Persistent values are not reset until the game is shut down and restarted.

Parameters:

1

string

value name

Returns:

  1. boolean value

defined in ../working_data/script/_lib/lib_core.lua, line 777

core:svr_save_persistent_string(string value name, string value)

Calls ScriptedValueRegistry:SavePersistentBool to save a persistent boolean value to the svr. Persistent values are not reset until the game is shut down and restarted.

Parameters:

1

string

value name

2

string

value

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 791

core:svr_load_persistent_string(string value name)

Calls ScriptedValueRegistry:LoadPersistentString to load a persistent string value from the svr. Persistent values are not reset until the game is shut down and restarted.

Parameters:

1

string

value name

Returns:

  1. string value

defined in ../working_data/script/_lib/lib_core.lua, line 810

core:svr_save_registry_bool(string value name, boolean value)
Calls ScriptedValueRegistry:SaveRegistryBool to save a boolean value to the operating system registry.

Parameters:

1

string

value name

2

boolean

value

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 824

core:svr_load_registry_bool(string value name)
Calls ScriptedValueRegistry:LoadRegistryBool to load a boolean value from the operating system registry. Values saved to the operating system registry will persist even if the game is shut down and reloaded.

Parameters:

1

string

value name

Returns:

  1. boolean value

defined in ../working_data/script/_lib/lib_core.lua, line 843

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 ../working_data/script/_lib/lib_core.lua, line 950

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 ../working_data/script/_lib/lib_core.lua, line 998

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 ../working_data/script/_lib/lib_core.lua, line 1072

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 key Highlight text key],
  ... 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

may be nil

3

...

uicomponent list

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 1151

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 1273

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 ../working_data/script/_lib/lib_core.lua, line 1301

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 ../working_data/script/_lib/lib_core.lua, line 1337

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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 1371

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

Example:

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

defined in ../working_data/script/_lib/lib_core.lua, line 1408

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

Example - FactionTurnEnd listener:

Listen for a FactionTurnEnd event for a specific faction on or after a specific turn.
core:add_listener(
    "faction_turn_start_listener",
    "FactionTurnStart",
    function(context)
        return context:faction():name() == "wh_main_emp_empire" and cm:turn_number() == 7
    end,
    function()
        empire_ending_turn_seven()
    end,
    false
);

Example - Diplomacy panel listener:

Call a function whenever the diplomacy panel is opened.
core:add_listener(
    "diplomacy_panel_listener",
    "PanelOpenedCampaign",
    function(context)
        return context.string == "diplomacy_dropdown";
    end,
    function()
        diplomacy_panel_opened()
    end,
    true            -- keeps listening
);

defined in ../working_data/script/_lib/lib_core.lua, line 1441

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 ../working_data/script/_lib/lib_core.lua, line 1662

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 ../working_data/script/_lib/lib_core.lua, line 1703

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 ../working_data/script/_lib/lib_core.lua, line 1741

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 ../working_data/script/_lib/lib_core.lua, line 1803

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 ../working_data/script/_lib/lib_core.lua, line 1856

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 ../working_data/script/_lib/lib_core.lua, line 1873

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 ../working_data/script/_lib/lib_core.lua, line 1908

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 ../working_data/script/_lib/lib_core.lua, line 1961

Back to top

Text 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 ../working_data/script/_lib/lib_core.lua, line 1982

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 ../working_data/script/_lib/lib_core.lua, line 1995

core:hide_all_text_pointers()
Hide any text_pointer's current visible.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 2016

Back to top

Progress on UI event

core:progress_on_loading_screen_dismissed(function callback)
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

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 2035

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 ../working_data/script/_lib/lib_core.lua, line 2112

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 ../working_data/script/_lib/lib_core.lua, line 2129

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 ../working_data/script/_lib/lib_core.lua, line 2195

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 ../working_data/script/_lib/lib_core.lua, line 2220

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 ../working_data/script/_lib/lib_core.lua, line 2268

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 ../working_data/script/_lib/lib_core.lua, line 2331

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 ../working_data/script/_lib/lib_core.lua, line 2381

Back to top

Autonumbers

core:get_unique_counter([string classification])

Retrieves a unique integer number. Each number is 1 higher than the previous unique number, with the sequence starting at 1. This functionality is useful for scripts that need to generate unique identifiers. The ascending sequence is not saved into a campaign savegame.
An optional string classification may be provided. For each classification a new ascending integer is created and maintained.

Parameters:

1

string

optional, default value=nil

classification

Returns:

  1. number unique number

Example:

out(core:get_unique_counter())
out(core:get_unique_counter())
out(core:get_unique_counter("test"))        -- start new counter
out(core:get_unique_counter())                -- default counter is still maintained
out(core:get_unique_counter("test"))
1
2
1
3
2

defined in ../working_data/script/_lib/lib_core.lua, line 2449

Back to top

Static Object Registry

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

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

classification

4

boolean

optional, default value=false

overwrite

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_core.lua, line 2501

core:get_static_object(string object name)
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

Returns:

  1. object

defined in ../working_data/script/_lib/lib_core.lua, line 2543

Custom Context

A custom context is created when the core object is compelled to trigger an event with trigger_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 the core:trigger_event function should need to create a custom context, but it's documented here in order to list the data types it supports.

The core:trigger_custom_event function allows triggering script to customise the function names on the custom context by which the receiving script may query the context data.

Back to top

Functionality

custom_context:new()
Creates a custom context object.

Returns:

  1. custom_context

defined in ../working_data/script/_lib/lib_core.lua, line 2599

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 ../working_data/script/_lib/lib_core.lua, line 2666

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 ../working_data/script/_lib/lib_core.lua, line 2683

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 ../working_data/script/_lib/lib_core.lua, line 2691

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 ../working_data/script/_lib/lib_core.lua, line 2699

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 ../working_data/script/_lib/lib_core.lua, line 2707

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 ../working_data/script/_lib/lib_core.lua, line 2715

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 ../working_data/script/_lib/lib_core.lua, line 2723

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 ../working_data/script/_lib/lib_core.lua, line 2731

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 ../working_data/script/_lib/lib_core.lua, line 2739

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 ../working_data/script/_lib/lib_core.lua, line 2747

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 ../working_data/script/_lib/lib_core.lua, line 2755

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 ../working_data/script/_lib/lib_core.lua, line 2763

Last updated 07/02/21 06:39:14