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 1290

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 1308

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 1327

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 1349

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 1392

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 1422

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 1445

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 1464

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 1484

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 1504

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 3012

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 3042

Back to top

UI Events

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

defined in ../../common/EmpireUtility/Source/KeyboardShortcuts/KeyboardShortcutHandler.cpp, line 2008

Back to top

UI Event Simulation

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

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

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

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

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 3114

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 3136

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 3171

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 3192

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 3213

effect.set_pref_integer(string preference key, number value)

Sets the specified integer user preference with the given value

Parameters:

1

string

preference key

2

number

value

Returns:

  1. nil

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

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 3255

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 3305

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 3325

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

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 281

effect.get_shortcut_key_string(string shortcut_key)

Retrieves localised description string for given shortcut key

Parameters:

1

string

shortcut_key

Returns:

  1. string localised string

Example:

out(effect.get_shortcut_key_string("select_all"))

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

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 337

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.png")

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

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 388

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 408

effect.stop_all_movies()
Stops any currently playing movies.

Returns:

  1. nil

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

effect.are_info_overlays_enabled()
Checks if the info overlays are enabled.

Returns:

  1. boolean are_enabled

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

effect.enable_info_overlays()
Enables or disables info overlays in current ui

Returns:

  1. nil

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

effect.disable_all_shortcuts(boolean should_disable)

Disable or enable all shortcuts

Parameters:

1

boolean

should_disable

Returns:

  1. nil

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

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 327

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