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

CampaignUI.ToggleCinematicBorders(boolean enable borders)

Creates or destroys top and bottom cinematic borders.

Parameters:

1

boolean

enable borders

Returns:

  1. nil

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

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

Returns:

  1. nil

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

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

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

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

Returns:

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

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
13REGION_CORRUPTION_VAMPIRIC
14REGION_CORRUPTION_CHAOS
15REGION_CORRUPTION_SKAVEN
16REGION_CORRUPTION_UNTAINTED
17WINDS_OF_MAGIC
18CLIMATE_SUITABILITY
19GEOMATIC_WEB
20TUTORIAL_REGION_HIGHLIGHT

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

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

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

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

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

Allows the script running on one machine in a multiplayer game to cause a scripted event, UITrigger, 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

number

optional, default value=nil

faction cqi

2

string

optional, default value=nil

event id

Returns:

  1. nil

Example:

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

// later, perhaps on a different machine:
CampaignUI.TriggerCampaignScriptEvent(123, "test_event")
* UITrigger received, id: test_event, faction cqi: 123    
Last updated 07/02/21 06:39:14