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 102

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 233

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 246

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 260

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 281

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 318

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 363

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 371

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 381

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 398

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 406

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 414

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 432

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 453

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 582

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 627

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 658

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 666

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 674

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 682

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

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

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

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

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

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

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

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

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

Returns:

  1. nil

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

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 964

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

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 1021

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 1055

Back to top

UIComponent Creation

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

Parameters:

1

string

Name to give uicomponent.

2

string

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

3

uicomponent

optional, default value=ui_root

Parent uicomponent.

Returns:

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

Example:

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

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

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

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 1314

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 1355

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() end,
    "ScriptEventPlayerBesieged",
    function(context) return context:region() end
)

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

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 1461

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 1478

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 1521

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 1574

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

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 1608

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

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

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

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

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

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

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

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

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 1846

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 1868

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 1934

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 1959

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 2004

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 2071

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 2121

Back to top

Static Object Registry

core:add_static_object(string object name, object object to register, [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.

Parameters:

1

string

object name

2

object

object to register

3

boolean

optional, default value=false

overwrite

Returns:

  1. nil

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

core:get_static_object(string object name)
Returns the static object registered with the supplied string name using core:add_static_object, if any such object has been registered, otherwise it returns nil.

Parameters:

1

string

object name

Returns:

  1. object

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

Context

A custom context is created when the core object is compelled to trigger an event with trigger_event. Data items supplied to trigger_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:new()
Creates a custom context object.

Returns:

  1. custom_context

defined in ../working_data/script/_lib/lib_custom_context.lua, line 20

Custom: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

    • string: will be accessible to the receiving script as context.string

      • number: will be accessible to the receiving script as context.number

      • region: will be accessible to the receiving script using context:region()

      • character: will be accessible to the receiving script using context:character()

      • faction: will be accessible to the receiving script using context:faction()

      • component: will be accessible to the receiving script using context:component()

      • military_force: will be accessible to the receiving script using context:military_force()

      • pending_battle: will be accessible to the receiving script using context:pending_battle()

      • garrison_residence: will be accessible to the receiving script using context:garrison_residence()

      • building: will be accessible to the receiving script using context:building()

      A limitation of the implementation is that only one object of each type may be placed on the custom context.

      Parameters:

      1

      object

      Data object to add

      Returns:

      1. nil

      defined in ../working_data/script/_lib/lib_custom_context.lua, line 32

Custom: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_custom_context.lua, line 83

Custom: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_custom_context.lua, line 91

Custom: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_custom_context.lua, line 99

Custom: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_custom_context.lua, line 107

Custom: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_custom_context.lua, line 115

Custom: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_custom_context.lua, line 123

Custom: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_custom_context.lua, line 131

Custom: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_custom_context.lua, line 139

Custom: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_custom_context.lua, line 147

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

Returns:

  1. table the custom passed table if any

defined in ../working_data/script/_lib/lib_custom_context.lua, line 155

Last updated 25/08/2021 12:07:51