CampaignUI

The CampaignUI script object is created automatically when the campaign UI loads, and offers a suite a functions that allow scripts to query and customise bits of the UI. 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:

CampaignUI.<function_name>(<args>)
Loaded in Campaign loaded in campaign
Back to top

Miscellaneous

CampaignUI.ToggleScreenCover(boolean enable cover)

Creates or destroys a black screen cover (when not eyefinity).

Parameters:

1

boolean

enable cover

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 371

CampaignUI.ToggleCinematicBorders(boolean enable borders)

Creates or destroys top and bottom cinematic borders.

Parameters:

1

boolean

enable borders

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 410

CampaignUI.ShowVictoryScreen([boolean is victory], [boolean can continue], [string mission key])

Shows the campaign victory screen, optionally corresponding to a specified mission. All three arguments must be specified, or none can be specified.

Parameters:

1

boolean

optional, default value=nil

is victory

2

boolean

optional, default value=nil

can continue

3

string

optional, default value=nil

mission key

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 425

CampaignUI.ClearSelection()
Clears the current ui selection, ensuring that no settlements or characters are selected by the player.

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 457

CampaignUI.SelectObject(
  number - the CQI of the object,
  string - the TYPE of the object ("character",
  boolean - zoom or not to object location
)

Selects an object by CQI and TYPE, and optionally zooms to his location

Parameters:

1

number

- the CQI of the object

2

string

"region", "settlement")

3

boolean

- zoom or not to object location

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 465

CampaignUI.UpdateTechButton()
Updates the available technologies counter inset into the technology button the campaign interface. This should be called after the script does anything that might modify the value shown on this counter (including turning the technology button on and off).

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 515

CampaignUI.UpdateSettlementEffectIcons()
Updates any settlement effect icons on the campaign interface. This should be called after the script does anything that might modify settlement effects.

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 529

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

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 541

CampaignUI.QuitToWindows()
Exits the game. This is used for autotesting.

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 562

Back to top

Campaign Map Overlay

CampaignUI.SetOverlayVisible(boolean activate overlay)

Sets the campaign overlay to be visible or not. The campaign overlay colourises regions on the campaign map display for various purposes (it is used by the tactical map, for example). The overlay mode to display, and what regions to display it on, should be set with CampaignUI.SetOverlayMode before activating the overlay with this function.

Parameters:

1

boolean

activate overlay

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 579

CampaignUI.SetOverlayMode(number overlay mode, ... region(s))

Sets the overlay mode to display by numeric id, and one or more regions to display it across by region key. Multiple region keys may be specified with separate arguments. Calling this function has no effect until the overlay is subsequently enabled with CampaignUI.SetOverlayVisible.
Valid overlay mode ids:

overlay mode iddescription
0DIPLOMACY_STATUS
1DIPLOMACY_ATTITUDE_FACTION
2DIPLOMACY_ATTITUDE_OWNER
3RADAR
4HISTORICAL_OWNERSHIP
5REGION_WEALTH
6REGION_GROWTH
7REGION_HAPPINESS
8REGION_SLAVES
9REGION_FERTILITY
10REGION_SANITATION
11REGION_FOOD
12REGION_GOVERNORSHIP
13WINDS_OF_MAGIC
14CLIMATE_SUITABILITY
15GEOMATIC_WEB
16TUTORIAL_REGION_HIGHLIGHT
16REGION_INFLUENCE
16REGION_CITIZENS
16REGION_SARPEDON_RARE_RESOURCE
16GODS_APHRODITE
16GODS_APOLLO
16GODS_ARES
16GODS_ATHENA
16GODS_HERA
16GODS_POSEIDON
16GODS_ZEUS

Parameters:

1

number

Overlay mode (see lookup table above).

2

...

One or more string region keys

Returns:

  1. nil

Example:

CampaignUI.SetOverlayMode(20, lothern_region_str, glittering_tower_region_str, tower_of_lysean_region_str)
CampaignUI.SetOverlayVisible(true)

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 594

Back to top

Events and Suppression

CampaignUI.SuppressAllEventTypesInUI(boolean enable suppression)

Enables or disables a suppression lock that prevents any event messages being shown on the UI. Once the lock is enabled, individual event types may be whitelisted for display with CampaignUI.WhiteListEventTypeInUI, at which point they will bypass the suppression.

Parameters:

1

boolean

enable suppression

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 676

CampaignUI.WhiteListEventTypeInUI(string event type)

Whitelists an event type to bypass suppression activated by CampaignUI.SuppressAllEventTypesInUI. Event types to be whitelisted are specified by a compound key from the event_feed_targeted_events table - the key must be specified by concatenating the event and target> field values for a given record from that table. Currently valid examples might include "faction_event_mission_issuedevent_feed_target_mission_faction" or "scripted_persistent_located_eventevent_feed_target_faction". Whitelisting an event type has no effect if suppression has not been enabled.

Parameters:

1

string

event type

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 692

CampaignUI.DoesEventTypeExist(string event type)

Returns whether or not an event of the specified type exists in the display queue (i.e. is being displayed or is pending to be displayed). Event types are specified by a compound key from the event_feed_targeted_events table - the key must be specified by concatenating the event and target> field values for a given record from that table.

Parameters:

1

string

event type

Returns:

  1. boolean event type exists

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 709

CampaignUI.DoesEventTypeRequireResponse(string event type)

Returns whether or not an event of the specified type exists in the display queue (i.e. is being displayed or is pending to be displayed) and requires a response. Event types are specified by a compound key from the event_feed_targeted_events table - the key must be specified by concatenating the event and target> field values for a given record from that table.
This is of most use for testing if a dilemma is currently active.

Parameters:

1

string

event type

Returns:

  1. boolean event type requires response

Example:

if CampaignUI.DoesEventTypeRequireResponse("faction_event_dilemmaevent_feed_target_dilemma_faction") then
    out("dilemma is open")
end

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 728

Back to top

Multiplayer UI Events

CampaignUI.TriggerIncident(string incident key)

Triggers an incident for the local player, specified by incident key. If called on one machine in a multiplayer game this will trigger the incident on all machines - as such, it can be called in script that is triggered from a UI event in a multiplayer game.

Parameters:

1

string

incident key

Returns:

  1. nil

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 754

CampaignUI.TriggerCampaignScriptEvent([string event id], [number faction cqi])

Allows the script running on one machine in a multiplayer game to cause a scripted event, UITriggerScriptEvent, to be triggered on all machines in that game. By listening for this event, scripts on all machines in a multiplayer game can therefore respond to a UI event occuring on just one of those machines.
An optional string event id and number faction cqi may be specified. If specified, these values are passed from the triggering script through to all listening scripts, using the context objects supplied with the events. The event id may be accessed by listening scripts by calling <context>:trigger() on the supplied context object, and can be used to identify the script event being triggered. The faction cqi may be accessed by calling <context>:faction_cqi() on the context object, and can be used to identify a faction associated with the event. Both must be specified, or neither.

Parameters:

1

string

optional, default value=nil

event id

2

number

optional, default value=nil

faction cqi

Returns:

  1. nil

Example:

core:add_listener(
    "test",
    "UITriggerScriptEvent",
    true,
    function(context)
        out("* UITriggerScriptEvent received, id: " .. tostring(context:trigger()) .. ", faction cqi: " .. tostring(context:faction_cqi()))
    end,
    true
)

// later, perhaps on a different machine:
CampaignUI.TriggerCampaignScriptEvent(123, "test_event")
* UITriggerScriptEvent received, id: test_event, faction cqi: 123    

defined in ../../common/UIDll/Source/Campaign/CampaignUIScriptInterface.cpp, line 775

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