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

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

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)
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

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

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

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

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

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

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

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

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

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

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

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

Returns:

  1. boolean advice is playing
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
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

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

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

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

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

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

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
Back to top

Game Version

effect.game_version()
Returns the game version string.

Returns:

  1. string game version
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")
Back to top

Screenshots

effect.take_screenshot(string filename)

Triggers a screenshot

Parameters:

1

string

filename

Returns:

  1. nil

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

Returns:

  1. string screenshots path
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
Back to top

UI Skins

effect.get_skinned_image_path(string image name)

Retrieves a full image path from the working data folder for a supplied image name that obeys the currently loaded skins. For each loaded skin, the existence of the image is queried and, should it exist, the path to that image is returned. If the image is not found then a path to the image in the default skin folder is returned, although in this case the existence of the image is not checked for. The returned image path can subsequently be supplied to uicomponent:SetImagePath.

Parameters:

1

string

Image name, excluding path but including file extension.

Returns:

  1. string image path
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..
Back to top

Subtitles

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

Returns:

  1. boolean subtitles enabled
Back to top

Movies

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

Returns:

  1. boolean is movie playing

effect.stop_all_movies()
Stops any currently playing movies.

Returns:

  1. nil
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
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

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

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

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

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

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

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")
Last updated 07/02/21 06:39:15