Effect

The effect 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:

effect.<function_name>(<args>)
Loaded in Battle loaded in battle
Loaded in Campaign loaded in campaign
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.

effect.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

defined in ../working_data/script/docgen/docgen_campaign_effect.lua, line 23

effect.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

defined in ../working_data/script/docgen/docgen_campaign_effect.lua, line 32

effect.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:

effect.OpenBrowser("how_to_play/045b_enc_manual_ui_character.html", context)

defined in ../working_data/script/docgen/docgen_campaign_effect.lua, line 42

Back to top

Advice

effect.suspend_contextual_advice(boolean should suspend)

Prevents advice from being triggered with effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1292

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1310

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1329

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1351

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1394

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1424

effect.set_advice_history_string_seen(string key)

Stores a key in the advice history, which can subsequently be tested with effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1447

effect.get_advice_history_string_seen(string key)

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

Parameters:

1

string

key

Returns:

  1. boolean has been set

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1466

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1486

effect.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

defined in ../../common/EmpireUtility/Source/Advice.cpp, line 1506

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3060

effect.is_advice_audio_playing()

Returns whether audio for any advice is currently playing.

Returns:

  1. boolean advice is playing

defined in ../../common/Empire/Source/Empire.cpp, line 3090

Back to top

UI Event Simulation

effect.key_down(string event)

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

Parameters:

1

string

event

Returns:

  1. nil

defined in ../../common/Empire/Source/Empire.cpp, line 3117

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3139

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3161

Back to top

Preferences and Tweakers

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3196

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3217

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3238

effect.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

defined in ../../common/Empire/Source/Empire.cpp, line 3259

Back to top

Game Version

effect.game_version()

Returns the game version string.

Returns:

  1. string game version

defined in ../../common/Empire/Source/Empire.cpp, line 3293

Back to top

Filesystem

effect.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:

effect.filesystem_lookup("/script/_lib/", "*.lua")

defined in ../../common/Empire/Source/Empire.cpp, line 3313

Back to top

Battle Ping Icons

effect.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

defined in ../../common/UIDll/Source/Battle/ComponentCallbacks/OffscreenIndicator.cpp, line 98

Back to top

Localised Strings

effect.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..

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 260

Back to top

Subtitles

effect.subtitles_enabled()

Returns whether subtitles are enabled or not in the player's preferences.

Returns:

  1. boolean subtitles enabled

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 296

Back to top

Screenshots

effect.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 effect.get_appdata_screenshots_path.

Parameters:

1

string

screenshot filename

Returns:

  1. nil

Example:

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

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 318

effect.get_appdata_screenshots_path()

Returns the full path to the screenshots directory in appdata.

Returns:

  1. string screenshots path

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 343

Back to top

Movies

effect.is_any_movie_playing()

Returns whether any movie is currently playing.

Returns:

  1. boolean is movie playing

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 363

effect.stop_all_movies()

Stops any currently playing movies.

Returns:

  1. nil

defined in ../../common/UIDll/Source/Common/EmpireCommonUI.cpp, line 383

Back to top

Custom Loading Screen

effect.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

defined in ../../common/UIDll/Source/Common/LoadingScreenUI.cpp, line 319

Back to top

UI Context System

effect.set_context_value(string id, number/string value)

Creates or updates a CcoScriptObject data record within the UI context system with a specified value. UI components and layouts can be separately set up to query these values by name. This allows script to set up and modify values which are then reflected in the UI, giving script great power to set up custom gameplay structures which are visible to the player on the UI. Examples might include health bars, counters, progress meters etc which are tied to arbitrary scripted values.

Parameters:

1

string

Context value id.

2

number/string

Value to set - this can be a number or a string.

Returns:

  1. nil

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 41

effect.get_context_bool_value(string object id, string function id)

Calls a specified function on a specified context object. The value returned by the function is passed back to script as a boolean. This allows script to query values on objects within the UI context system.

Parameters:

1

string

Context object id on which to call the function.

2

string

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

Returns:

  1. boolean returned value

Example - Query CcoBattleRoot to see if battle is in deployment phase:

local is_deployment_phase = effect.get_context_bool_value("CcoBattleRoot", "IsDeploymentPhase")

Example - Query whether campaign character with cqi 51 is on the campaign map:

local char_is_on_map = effect.get_context_bool_value("CcoCampaignCharacter51", "IsOnMap")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 104

effect.get_context_numeric_value(string object id, string function id)

Calls a specified function on a specified context object. The value returned by the function is passed back to script as a number. This allows script to query number values on objects within the UI context system.

Parameters:

1

string

Context object id on which to call the function.

2

string

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

Returns:

  1. number returned value

Example - Query CcoBattleRoot to see which alliance wins on timeout:

local winning_alliance_index = effect.get_context_bool_value("CcoBattleRoot", "TimeoutWinningAllianceIndex")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 151

effect.get_context_string_value(string object id, string function id)

Calls a specified function on a specified context object. The value returned by the function is passed back to script as a string. This allows script to query string values on objects within the UI context system.

Parameters:

1

string

Context object id on which to call the function.

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. string context object id

Example - Query battle unit 1004 for their morale state as a string:

local morale_state = effect.get_context_string_value("CcoBattleUnit1004", "MoraleName")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 195

effect.get_context_vector4_value(string object id, string function id)

Calls a specified function on a specified context object. The value returned by the function is passed back to script as a vector4, which is expressed in lua as 4 number values. This allows script to query position values on objects within the UI context system.

Parameters:

1

string

Context object id on which to call the function.

2

string

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

Returns:

  1. number x position value
  2. number y position value
  3. number z position value
  4. number w position value (meaning varies per function)

Example - Get the position of the Victory Point in battle:

local x, y, z, w = effect.get_context_vector4_value("CcoBattleRoot", "VictoryCapturePointContext.Position")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 239

effect.get_context_object_id(string object id, string function id)

Calls a specified function on a specified context object that returns a string name of another context object. This allows script to get a handle to a context object related to the subject context object, such as an army related to a unit.

Parameters:

1

string

Context object id on which to call the function.

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. string context object id

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

local cco_military_force = effect.get_context_string_value("CcoCharacter123", "MilitaryForceContext")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 287

effect.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

Context object id on which to call the function.

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("CcoBattleRoot", "ToggleCinematicMode")

defined in ../../common/UIDll/Source/Common/ComponentContexts/CcoScriptObject.cpp, line 339

Last updated 12/10/19 15:46:48