Common

The common interface (formerly the effect interface) is created automatically by code whenever a script environment is set up. It provides functionality that can be useful in all environments i.e. campaign, battle and frontend. It does not need to be created by script, and the functions it provides may be called directly on the object in the following form.

Example:

common.<function_name>(<args>)
Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Campaign

The following function calls are available in a campaign script environment. They will not work in other environments.

common.ancillary(string ancillary key, number chance, userdata context)

Potentially adds the supplied ancillary to the character in the supplied context. When called, the function generates a random number between 0-100, and if this number is less than or equal to the supplied chance value, then the ancillary is added. The character to add the ancillary to is specified in the supplied context object, which must be a context object created by a character event (e.g. CharacterCompletedBattle, CharacterCreated).
This function is somewhat archaic and should only be used in exported ancillary scripts. For general script usage force_add_ancillary is greatly preferred.

Parameters:

1

string

Ancillary key, from the ancillaries table.

2

number

Percentage chance that the ancillary will actually be added.

3

userdata

Context object, provided by a character event.

Returns:

  1. nil

common.trait(string trait key, string applicable to, number points, number chance, userdata context)

Potentially adds the supplied trait points to the trait-recipient in the supplied context. When called, the function generates a random number between 0-100, and if this number is less than or equal to the supplied chance value then the trait points are added. The trait recipient is specified in the supplied context object, and the type of recipient must also be specified by a supplied string.
This function is somewhat archaic and should only be used in exported trait scripts. For adding traits to characters in general scripts force_add_trait is greatly preferred.

Parameters:

1

string

Trait key, from the traits table.

2

string

Specifies the type of object to apply the trait to. Valid strings here are agent (for all characters), region and unit. Not all recipient types may currently be supported.

3

number

Number of trait points to add, if successful.

4

number

Percentage chance that the trait will actually be added.

5

userdata

Context object, provided by an event.

Returns:

  1. nil

common.OpenBrowser(string encyclopedia url, userdata context)

Opens the in-game web browser with the supplied encyclopedia url.

Parameters:

1

string

encyclopedia url

2

userdata

Context object, provided by an event.

Returns:

  1. nil

Example:

common.OpenBrowser("how_to_play/045b_enc_manual_ui_character.html", context)
Back to top

Advice and Audio

common.suspend_contextual_advice(boolean should suspend)

Prevents advice from being triggered with common.advance_contextual_advice_thread. This can be useful for tutorials, but is not used by modern advice systems.

Parameters:

1

boolean

should suspend

Returns:

  1. nil

common.advice(string text)

Directs the advisor to display the supplied advice string. This should only be used for debugging since localisation is bypassed.

Parameters:

1

string

text

Returns:

  1. nil

common.advance_scripted_advice_thread(string advice key, number score increase)

Directs the advisor to advance the specified thread by the supplied score increase. If any advice on that thread subsequently becomes eligible to be issued, then that advice is issued.

Parameters:

1

string

Advice key, from the advice_threads table.

2

number

Score to increase the advice thread by.

Returns:

  1. nil

common.advance_scripted_advice_thread_located(string advice key, number score increase, number x, number y)

Parameters:

1

string

Advice key, from the advice_threads table.

2

number

Score to increase the advice thread by.

3

number

X display co-ordinate to associate the advice with.

4

number

Y display co-ordinate to associate the advice with.

Returns:

  1. nil

common.get_advice_thread_score(string thread key)

Returns the advice thread score. This can indicate whether advice on this thread has already been played.

Parameters:

1

string

Advice thread key, from the advice_threads table.

Returns:

  1. number score

common.increment_advice_thread_score(string thread key, number score)

Increments the advice thread score by the supplied amount, without playing any advice.

Parameters:

1

string

Advice thread key, from the advice_threads table.

2

number

score

Returns:

  1. nil

common.set_advice_history_string_seen(string key)

Stores a key in the advice history, which can subsequently be tested with common.get_advice_history_string_seen. This allows scripts to test whether the player has ever encountered certain conditions in their playing history (e.g. "has ever started game"). The flag will be reset if the player resets their advice history.

Parameters:

1

string

key

Returns:

  1. nil

common.get_advice_history_string_seen(string key)

Returns whether a key has ever been set in the advice history with common.set_advice_history_string_seen.

Parameters:

1

string

key

Returns:

  1. boolean has been set

common.get_advice_level()
Returns the current advice level setting. The following table indicates potential returned values:

Returned ValueAdvice Level
0Minimal
1Low
2High

Returns:

  1. number advice level

common.clear_advice_session_history()
Clears out the advice session history. This is the list of advice shown in this particular game session, accessed by the next/previous buttons on the advisor panel.

Returns:

  1. nil

common.advance_contextual_advice_thread(string advice thread, number points, userdata context)

Directs the advisor to consider issuing advice on the supplied advice thread. The supplied number of points are added to the thread - if a record from the advice_levels table subsequently becomes eligible to be issued, then that advice is issued.

Parameters:

1

string

Advice thread key.

2

number

Points to add to thread.

3

userdata

context object supplied by game event.

Returns:

  1. nil

common.is_advice_audio_playing()
Returns whether audio for any advice is currently playing.

Returns:

  1. boolean advice is playing

common.set_volume(number volume type, number volume level)

Sets the volume level of a specific volume type. Valid volume types are given in the Volume Types section of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).

Parameters:

1

number

volume type

2

number

volume level

Returns:

  1. nil

common.get_volume(number volume type)

Gets the volume level of a specific volume type. Valid volume types are given in the Volume Types section of this documentation. The volume level will be returned as a number between 0 (inaudible) and 100 (full volume).

Parameters:

1

number

volume type

Returns:

  1. number volume level

common.fade_volume(number volume type, number target level, number fade time)

Gradually fades the volume level of a specified volume type to a specified value over a specified interval. Valid volume types are given in the Volume Types section of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).

Parameters:

1

number

Volume type.

2

number

Target volume level.

3

number

Fade time in seconds.

Returns:

  1. nil

common.trigger_soundevent(string sound event name)

Oneshot triggers a sound event with the sound engine with no position information. This is not suitable for long running events or looping events.

Parameters:

1

string

sound event name

Returns:

  1. nil
Back to top

UI Events

common.trigger_shortcut(string shortcut name)

Triggers a keyboard shortcut event. Valid shortcut events are defined in data\text\default_keys.xml.

Parameters:

1

string

shortcut name

Returns:

  1. nil

common.key_press(string event)

Simulates a key down followed by a key up key event. Valid key events are listed here: Simulating Keyboard Events

Parameters:

1

string

event

Returns:

  1. nil

common.key_down(string event)

Triggers a key down key event. Note that the game will think the key is held down until a key up event is received. Valid key events are listed here: Simulating Keyboard Events

Parameters:

1

string

event

Returns:

  1. nil

common.key_up(string event)

Triggers a key up event. Valid key events are listed here: Simulating Keyboard Events.

Parameters:

1

string

event

Returns:

  1. nil

common.mouse_event(string event, number screen pos x, number screen pos y)

Triggers a mouse event at a specified position. Valid mouse events are listed in the cursor_mouse_events table.

Parameters:

1

string

event

2

number

screen pos x

3

number

screen pos y

Returns:

  1. nil

common.force_report_of_all_ui_script_events(boolean force reporting)

Compels all uicomponents to fires UI script events such as ComponentMouseOn and ComponentAnimationFinished, regardless of whether they have a ScriptEventReporter callback set on them. This should only be used by modders since they can't modify ui layouts easily in order to add ScriptEventReporter callbacks. The game will throw an error if this is called in a configuration other than final release.

Parameters:

1

boolean

Force reporting of script events on or off. Reporting is off by default, except when running an autotest.

Returns:

  1. nil
Back to top

Preferences and Tweakers

common.pref_as_bool(string preference key)

Returns whether the specified boolean user preference setting is true or not.

Parameters:

1

string

preference key

Returns:

  1. boolean preference value

common.pref_as_float(string preference key)

Returns the numeric value of the specified floating point user preference. Floating point number values will be marked with <float> in the preferences file.

Parameters:

1

string

preference key

Returns:

  1. number preference value

common.pref_as_integer(string preference key)

Returns the numeric value of the specified integer user preference. Integer values will be marked with <int> in the preferences file.

Parameters:

1

string

preference key

Returns:

  1. number preference value

common.tweaker_value(string tweaker name)

Returns the value of the specified tweaker as a string. Tweakers are game settings that may be easily set and changed during development, through methods such as startup scripts or the game console.

Parameters:

1

string

tweaker name

Returns:

  1. string tweaker value
Back to top

Game Version

common.game_version()
Returns the game version string.

Returns:

  1. string game version
Back to top

Autotest

common.is_autotest()
Returns whether the game is currently running in autotest mode.

Returns:

  1. boolean is autotest
Back to top

Filesystem

common.vfs_exists(string path)

Performs a VFS lookup of the supplied file and path, and returns whether the file exists in the virtual file system. The path should be specified from the working data folder.

Parameters:

1

string

Path from data/ in which to look.

Returns:

  1. boolean file exists

Example:

common.vfs_exists("script/all_scripted.lua")

common.vfs_working_directory()
Returns the absolute file path of the game's working data directory.

Returns:

  1. string file path

Example:

local absolute_path = common.vfs_working_directory()

common.filesystem_lookup(string path, string pattern)

Performs a VFS lookup in the specified relative path (root is data/) for files matching the supplied pattern. Returns a comma-delimited list of files found.

Parameters:

1

string

Path from data/ in which to look.

2

string

Search pattern.

Returns:

  1. string file list

Example:

common.filesystem_lookup("/script/_lib/", "*.lua")
Back to top

Screenshots

common.take_screenshot(string screenshot filename)

Takes a screenshot and writes a tga file with the supplied filename. If no path is specified with the filename then the screenshot file is written into the binaries folder. The file path to the screenshots folder in appdata may be retrieved with common.get_appdata_screenshots_path.

Parameters:

1

string

screenshot filename

Returns:

  1. nil

Example:

common.take_screenshot(common.get_appdata_screenshots_path() .. "my_screenshot.tga")

common.get_appdata_screenshots_path()
Returns the full path to the screenshots directory in appdata.

Returns:

  1. string screenshots path
Back to top

VTune Profiling

common.VTune_pause_resume(boolean pause)

Pauses or resumes VTune profiler. Supply true to pause or false to resume.

Parameters:

1

boolean

pause

Returns:

  1. nil
Back to top

Battle Ping Icons

common.PingIconPath(number ping type)

Returns the icon path for the supplied ping icon type, specified by a numeric index. This allows script to create its own pings that don't go through the ping system (like ping icons attached to units - see script_unit:add_ping_icon). This function works in battle only.

Parameters:

1

number

ping type

Returns:

  1. string icon path
Back to top

Localised Strings

common.get_localised_string(string localisation key)

Retrieves a localised string from the database by its full localisation key. This is in the form [table]_[field]_[record_key]. If the lookup fails, an empty string is returned.

Parameters:

1

string

localisation key

Returns:

  1. string localised string

Example:

out(effect.get_localised_string("random_localisation_strings_string_shakespeare_quote"))
Alas, Poor Yoric..
Back to top

Subtitles

common.subtitles_enabled()
Returns whether subtitles are enabled or not in the player's preferences.

Returns:

  1. boolean subtitles enabled
Back to top

Movies

common.num_movies_that_can_play_in_parallel()
Returns the number of movies that can be played in parallel.

Returns:

  1. number number of movies that can be played

common.is_movie_playing_on_track()
Returns whether a movie is currently playing on a specified track.

Returns:

  1. boolean is movie playing

common.is_any_movie_playing()
Returns whether any movie is currently playing.

Returns:

  1. boolean is movie playing

common.stop_all_movies()
Stops any currently playing movies.

Returns:

  1. nil

common.get_movie_current_frame_num()
Returns the current frame number for the movie playing on the specified movie track. 0 is returned if no movie is playing.

Returns:

  1. number current frame number

common.get_movie_total_frames()
Returns the total number of frames in the movie playing on the specified movie track. 0 is returned if no movie is playing.

Returns:

  1. number the frame number movie currently on

common.get_movie_duration()
Returns the duration in seconds of the movie playing on the specified movie track. 0 is returned if no movie is playing.

Returns:

  1. number movie duration
Back to top

Shortcuts

common.enable_shortcut(
  string shortcut key (see (see working_data/text/default_keys.xml),
  boolean true to enable
)

Pass a shortcut key (see working_data/text/default_keys.xml) and a bool for enabling/disabling the shortcut

Parameters:

1

string

shortcut key (see (see working_data/text/default_keys.xml)

2

boolean

false to disable

Returns:

  1. nil

common.enable_all_shortcuts(boolean true to enable)

Pass a bool for enabling/disabling all shortcuts

Parameters:

1

boolean

false to disable

Returns:

  1. nil
Back to top

Custom Loading Screen

common.set_custom_loading_screen_text(string key)

Sets a custom text entry for display on the next loading screen. The text must be specified by a key corresponding to a record in the scripted_objectives table.

Parameters:

1

string

key

Returns:

  1. nil

common.set_custom_loading_screen_key(string key)

Sets a record from the custom_loading_screens table to use for the next loading screen. The record is specified by string key.

Parameters:

1

string

key

Returns:

  1. nil

common.setup_dynamic_loading_screen(string json filename, string layout name)

Specifies a layout from the working data/ui/loading_ui/ folder and a json data-file from the working data/ui/loading_ui/dynamic_loading_screen_data folder which drive a sequence of context-driven events throughout the next loading sequence.

Parameters:

1

string

JSON filename, from the data/ui/loading_ui/dynamic_loading_screen_data folder.

2

string

Layout name, from the data/ui/loading_ui/ folder.

Returns:

  1. nil
Back to top

Context System

common.set_context_value(string unique_id, string or number)

Will create a CcoScriptObject to context cache with specified value (or update existing objects value), and send notification of change so ContextInitScriptObject can refresh display of self and children

Parameters:

1

string

the unique id for the value so can set and get the value

2

string

Can pass either a string or numeric value

Returns:

  1. nil

Example - Setting a string value:

effect.set_context_value("example_id", "example_string_value"))

Example - Setting a numeric value:

effect.set_context_value("example_id", 1.5))

common.get_context_value([string object id], string function id)

Will look up the context object from the context cache or construct one with the type "context_object_typename" and the data (usually a CQI) from "construction_data", call the context function specified by context_function_id and return the value.

Parameters:

1

string

optional, default value="CcoScriptObject"

Context object id on which to call the function. If omitted, the function is called on the CcoScriptObject object.

2

string

Function id on the context object to call. This can also be an expression, but the result must return a context id.

Returns:

  1. variable return value of the function, type will be based on function called

Example - Query campaign character with cqi 123 for the context id of the associated military force:

local cco_military_force = common.get_context_value("CcoCharacter", "1", "MilitaryForceContext")

Example - Query without needing context object id (calling global functions):

local root_object_id = effect.get_context_value("CampaignRoot")

common.call_context_command([string object id], string function id)

Calls a specified function on a specified context object that makes changes to the game. This allows script to use the context system to modify the state of the game.

Parameters:

1

string

optional, default value="CcoScriptObject"

Context object id on which to call the function. If omitted, the function is called on the CcoScriptObject object.

2

string

Function id on the context object to call. This can be expression.

Returns:

  1. nil

Example - Toggles cinematics mode through the context system:

effect.call_context_command("CcoBattleUnit", "1001", "ZoomTo")

Example - Query without needing context object id (calling global functions):

effect.call_context_command("BattleRoot.ToggleCinematicMode")
Back to top

Error Messages

common.show_error_with_callstack(string error_msg)

Triggers an error dialog which contains callstack of calling lua, useful for debugging.

Parameters:

1

string

error_msg

Returns:

  1. nil

Example:

common.show_error_with_callstack("this is an error")

common.show_error(string error_msg)

Triggers an error dialog without any callstack.

Parameters:

1

string

error_msg

Returns:

  1. nil

Example:

common.show_error("this is an error")
Last updated 7/9/2024 11:45:05 AM