Common
The common interface object is created automatically by code whenever a script environment is set up. It is mostly used to provide functionality that can be useful in all environments (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 Battle |
|
| Loaded in Frontend |
|
The following function calls are available in a campaign script environment. They will not work in other environments.
-
common.ancillary(ancillary keystring,chancenumber,contextuserdata) -
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 usageforce_add_ancillaryis greatly preferred.Parameters:
1
Ancillary key, from the
ancillariestable.2
Percentage chance that the ancillary will actually be added.
3
Context object, provided by a character event.
Returns:
nil
-
common.trait(trait keystring,applicable tostring,pointsnumber,chancenumber,contextuserdata) -
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 scriptsforce_add_traitis greatly preferred.Parameters:
1
Trait key, from the
traitstable.2
Specifies the type of object to apply the trait to. Valid strings here are
agent(for all characters),regionandunit. Not all recipient types may currently be supported.3
Number of trait points to add, if successful.
4
Percentage chance that the trait will actually be added.
5
Context object, provided by an event.
Returns:
nil
-
common.OpenBrowser(encyclopedia urlstring,contextuserdata) -
Opens the in-game web browser with the supplied encyclopedia url.
Parameters:
1
encyclopedia url
2
Context object, provided by an event.
Returns:
nil
Example:
common.OpenBrowser("how_to_play/045b_enc_manual_ui_character.html", context)
-
common.suspend_contextual_advice(should suspendboolean) -
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
should suspend
Returns:
nil
-
common.advice(textstring) -
Directs the advisor to display the supplied advice string. This should only be used for debugging since localisation is bypassed.
Parameters:
1
text
Returns:
nil
-
common.advance_scripted_advice_thread(advice keystring,score increasenumber) -
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
Advice key, from the
advice_threadstable.2
Score to increase the advice thread by.
Returns:
nil
-
common.advance_scripted_advice_thread_located(advice keystring,score increasenumber,xnumber,ynumber) -
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 with the specified location. Located advice shows a button on the advisor panel which, when clicked, pans the camera to the specified location.
Parameters:
1
Advice key, from the
advice_threadstable.2
Score to increase the advice thread by.
3
X display co-ordinate to associate the advice with.
4
Y display co-ordinate to associate the advice with.
Returns:
nil
-
common.get_advice_thread_score(thread keystring) -
Returns the advice thread score. This can indicate whether advice on this thread has already been played.
Parameters:
1
Advice thread key, from the
advice_threadstable.Returns:
number
-
common.increment_advice_thread_score(thread keystring,scorenumber) -
Increments the advice thread score by the supplied amount, without playing any advice.
Parameters:
1
Advice thread key, from the
advice_threadstable.2
score
Returns:
nil
-
common.set_advice_history_string_seen(keystring) -
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
key
Returns:
nil
-
common.get_advice_history_string_seen(keystring) -
Returns whether a key has ever been set in the advice history with
common.set_advice_history_string_seen.Parameters:
1
key
Returns:
boolean
-
common.get_advice_level() -
Returns the current advice level setting. The following table indicates potential returned values:
Returned Value Advice Level
0Minimal 1Low 2High Returns:
number
-
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:
nil
-
common.advance_contextual_advice_thread(advice threadstring,pointsnumber,contextuserdata) -
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_levelstable subsequently becomes eligible to be issued, then that advice is issued.Parameters:
1
Advice thread key.
2
Points to add to thread.
3
context object supplied by game event.
Returns:
nil
-
common.is_advice_audio_playing() -
Returns whether audio for any advice is currently playing.
Returns:
boolean
-
common.set_volume(volume typenumber,volume levelnumber) -
Sets the volume level of a specific volume type. Valid volume types are given in the
Volume Typessection of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).Parameters:
1
volume type
2
volume level
Returns:
nil
-
common.get_volume(volume typenumber) -
Gets the volume level of a specific volume type. Valid volume types are given in the
Volume Typessection of this documentation. The volume level will be returned as a number between 0 (inaudible) and 100 (full volume).Parameters:
1
volume type
Returns:
number
-
common.fade_volume(volume typenumber,target levelnumber,fade timenumber) -
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 Typessection of this documentation. The volume level should be set as a number between 0 (inaudible) and 100 (full volume).Parameters:
1
Volume type.
2
Target volume level.
3
Fade time in seconds.
Returns:
nil
-
common.trigger_soundevent(sound event namestring) -
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
sound event name
Returns:
nil
-
common.trigger_shortcut(shortcut namestring) -
Triggers a keyboard shortcut event. Valid shortcut events are defined in
data\text\default_keys.xml.Parameters:
1
shortcut name
Returns:
nil
-
common.enable_shortcut(shortcut keystring,enable shortcutboolean) -
Enables or disables a keyboard shortcut. Pass a shortcut key (see data/text/default_keys.xml) and a bool for enabling/disabling the shortcut.
Parameters:
1
shortcut key
2
enable shortcut
Returns:
nil
-
common.disable_all_shortcuts(should disableboolean) -
Disables or enables all keyboard shortcuts.
Parameters:
1
should disable
Returns:
nil
-
common.get_shortcut_key_string(shortcut_keystring) -
Retrieves localised description string for given shortcut key
Parameters:
1
shortcut_key
Returns:
string
Example:
out(common.get_shortcut_key_string("select_all"))
-
common.key_press(eventstring) -
Simulates a key down followed by a key up key event. Valid key events are listed here:
Simulating Keyboard EventsParameters:
1
event
Returns:
nil
-
common.key_down(eventstring) -
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 EventsParameters:
1
event
Returns:
nil
-
common.key_up(eventstring) -
Triggers a key up event. Valid key events are listed here:
Simulating Keyboard Events.Parameters:
1
event
Returns:
nil
-
common.pref_as_bool(preference keystring) -
Returns whether the specified boolean user preference setting is true or not.
Parameters:
1
preference key
Returns:
boolean
-
common.pref_as_float(preference keystring) -
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
preference key
Returns:
number
-
common.pref_as_integer(preference keystring) -
Returns the numeric value of the specified integer user preference. Integer values will be marked with <int> in the preferences file.
Parameters:
1
preference key
Returns:
number
-
common.set_pref_integer(preference keystring,valuenumber) -
Sets the specified integer user preference with the given value
Parameters:
1
preference key
2
value
Returns:
nil
-
common.tweaker_value(tweaker namestring) -
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
tweaker name
Returns:
string
-
common.game_version() -
Returns the game version string.
Returns:
string
-
common.is_autotest() -
Returns whether the game is currently running in autotest mode.
Returns:
boolean
-
common.vfs_exists(pathstring) -
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
Path from data/ in which to look.
Returns:
boolean
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:
string
Example:
local absolute_path = common.vfs_working_directory()
-
common.filesystem_lookup(pathstring,patternstring) -
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
Path from data/ in which to look.
2
Search pattern.
Returns:
string
Example:
common.filesystem_lookup("/script/_lib/", "*.lua")
-
common.get_build_type() -
Returns type of the build. Returned values intentionally are not self explanatory.
Returns:
string
-
common.PingIconPath(ping typenumber) -
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
ping type
Returns:
string
-
common.get_localised_string(localisation keystring) -
Retrieves a localised string from the database by its full localisation key. This is in the form [table]_[field]_[record_key].
Parameters:
1
localisation key
Returns:
string
Example:
out(common.get_localised_string("random_localisation_strings_string_shakespeare_quote"))
Alas, Poor Yoric..
-
common.string_safe_format(textstring, ...formatting arguments) -
A unicode-safe string format function. Arguments can be substituted in to the input string if it contains formatting markers in the form %x%, where x is the number of the argument to substitute in.
Parameters:
1
Text to format.
2
...Variable number of formatting arguments.
Returns:
string
Example:
out(common.string_safe_format("Alas, Poor %1%, I knew him %2%", "Eeyore", "well"))
Alas, Poor Eeyore, I knew him well
-
common.subtitles_enabled() -
Returns whether subtitles are enabled or not in the player's preferences.
Returns:
boolean
-
common.take_screenshot(screenshot filenamestring) -
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
screenshot filename
Returns:
nil
Example:
common.take_screenshot(common.get_appdata_screenshots_path() .. "my_screenshot.png")
-
common.get_appdata_screenshots_path() -
Returns the full path to the screenshots directory in appdata.
Returns:
string
-
common.num_movies_that_can_play_in_parallel() -
Returns the number of movies that can be played in parallel.
Returns:
number
-
common.is_movie_playing_on_track() -
Returns whether a movie is currently playing on a specified track.
Returns:
boolean
-
common.is_any_movie_playing() -
Returns whether any movie is currently playing.
Returns:
boolean
-
common.stop_all_movies() -
Stops any currently playing movies.
Returns:
nil
-
common.get_movie_current_frame_num() -
Returns the current frame number for the movie playing on the specified movie track.
0is returned if no movie is playing.Returns:
number
-
common.get_movie_total_frames() -
Returns the total number of frames in the movie playing on the specified movie track.
0is returned if no movie is playing.Returns:
number
-
common.get_movie_duration() -
Returns the duration in seconds of the movie playing on the specified movie track.
0is returned if no movie is playing.Returns:
number
-
common.is_achievement_awarded() -
Returns whether achievement is awarded.
Returns:
boolean
-
common.toggle_fm_panel(panel_namestring) -
Toggle a specific FM panel using its name.
Parameters:
1
panel_name
Returns:
nil
Example:
common.toggle_fm_panel("technology_panel")
The panel was either opened or closed, depending on whether it was closed or opened previously
-
common.update_settlement_nameplates() -
Updates all settlement nameplates
Returns:
nil
Example:
common.update_settlement_nameplates()
-
common.update_ers_nameplates() -
Updates all ERS/outpost nameplates
Returns:
nil
Example:
common.update_ers_nameplates()
-
common.is_secondary_faction() -
Returns whether a faction is a secondary faction. Used mainly for UI purposes.
Returns:
nil
Example:
common.is_secondary_faction(String faction_key)
-
common.get_selected_character_cqi() -
Returns the selected character's cqi if any is selected, 0 otherwise.
Returns:
number
Example:
local selected_character_cqi = common.get_selected_character_cqi()
if selected_character_cqi ~= 0 then
-- local character = cm:get_character_by_cqi(selected_character_cqi)
-- ...
end
-
common.are_info_overlays_enabled() -
Checks if the info overlays are enabled.
Returns:
booleanare_enabled
-
common.enable_info_overlays(enableboolean) -
Enables or disables info overlays in current ui.
Parameters:
1
enable
Returns:
nil
-
common.set_custom_loading_screen_key(keystring) -
Sets a record from the
custom_loading_screenstable to use for the next loading screen. The record is specified by string key.Parameters:
1
key
Returns:
nil
-
common.OverrideLoadingScreenText(keystring) -
Sets a custom text entry for display on the next loading screen into battle.
Parameters:
1
key
Returns:
nil
-
common.set_context_value(unique_idstring,orstringnumber) -
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
the unique id for the value so can set and get the value
2
Can pass either a string or numeric value
Returns:
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([object idstring],function idstring) -
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
optional, default value="CcoScriptObject"
Context object id on which to call the function. If omitted, the function is called on the CcoScriptObject object.
2
Function id on the context object to call. This can also be an expression, but the result must return a context id.
Returns:
variablereturn 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.filter_profanity(textstring) -
Given some text, returns a filtered version of text replacing any profanity with *
Parameters:
1
text
Returns:
nil
-
common.call_context_command([object idstring],function idstring) -
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
optional, default value="CcoScriptObject"
Context object id on which to call the function. If omitted, the function is called on the CcoScriptObject object.
2
Function id on the context object to call. This can be expression.
Returns:
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")
-
common.send_ui_update_message(message idstring) -
Sends an update message to the UI context system.
Parameters:
1
message id
Returns:
nil
-
common.show_error_with_callstack(error_msgstring) -
Triggers an error dialog which contains callstack of calling lua, useful for debugging.
Parameters:
1
error_msg
Returns:
nil
Example:
common.show_error_with_callstack("this is an error")
-
common.show_error(error_msgstring) -
Triggers an error dialog without any callstack.
Parameters:
1
error_msg
Returns:
nil
Example:
common.show_error("this is an error")