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
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Cinematic Mode

CampaignUI.EnableCinematicMode(boolean enable)

Enables or disables cinematic mode, if it is not already enabled/disabled respectively. When enabled, cinematic mode shows cinematic borders, hides the UI, and steals/prevents most user input.

Parameters:

1

boolean

enable

Returns:

  1. nil

CampaignUI.IsCinematicModeEnabled()
Returns whether cinematic mode is currently enabled.

Returns:

  1. boolean cinematic mode is enabled

CampaignUI.ToggleScreenCover(boolean enable cover)

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

Parameters:

1

boolean

enable cover

Returns:

  1. nil
Back to top

Current Selection

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

Returns:

  1. nil

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

CampaignUI.SelectSettlement(number settlement cqi, boolean show ERS panel)

Selects a settlement within the UI. The settlement is specified by cqi.

Parameters:

1

number

settlement cqi

2

boolean

show ERS panel

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
13WINDS_OF_MAGIC
14CLIMATE_SUITABILITY
15GEOMATIC_WEB
16TUTORIAL_REGION_HIGHLIGHT
17REGION_INFLUENCE
18REGION_CITIZENS
19REGION_SARPEDON_RARE_RESOURCE
20GODS_APHRODITE
21GODS_APOLLO
22GODS_ARES
23GODS_ATHENA
24GODS_HERA
25GODS_POSEIDON
26GODS_ZEUS
27SACRED_EGYPTIAN_LANDS 28SACRED_HATTI_LANDS 29REALMS

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.TriggerCampaignScriptEvent([number faction cqi], [string event id])

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

number

optional, default value=nil

faction cqi

2

string

optional, default value=nil

event id

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

Triggering Campaign Voiceover

CampaignUI.TriggerCampaignFactionVO(string sound event id key, string faction key)

Trigger some campaign voiceover related to a faction leader.

Parameters:

1

string

sound event id key

2

string

faction key

Returns:

  1. nil

CampaignUI.TriggerCampaignCharacterVO(string sound event id key, number target character cqi)

Trigger some campaign voiceover related to a particular character.

Parameters:

1

string

sound event id key

2

number

target character cqi

Returns:

  1. nil

CampaignUI.TriggerCampaignCourtVO(
  string sound event id key,
  string faction key,
  string court type,
  number target character cqi
)

Trigger some campaign voiceover related to the Court feature.

Parameters:

1

string

sound event id key

2

string

faction key

3

string

court type

4

number

target character cqi

Returns:

  1. nil
Back to top

Miscellaneous

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.FillAgentCard(number character CQI, string panel name, string component name)

Fills an agent card in a panel by component_id.

Parameters:

1

number

Character CQI.

2

string

Name of the parent panel of the component that holds the agent card.

3

string

name of the component that holds the agent card.

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.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.QuitToWindows()
Exits the game. This is used for autotesting.

Returns:

  1. nil

CampaignUI.OpenDetailsForCharacter(
  number character cqi,
  string mode,
  boolean from family tree,
  boolean select skill tab,
  boolean show titles panel
)

Opens the character details panel for a character. The character is specified by cqi.

Parameters:

1

number

CQI of character.

2

string

Mode in which to open the character details panel. Supported string values are currently either "character" or "army".

3

boolean

Open the panel as if we're switching from a family tree.

4

boolean

Select the skill tab on the Character Details panel.

5

boolean

Show titles on the Character Details panel.

Returns:

  1. nil

CampaignUI.TriggerPanelEvent(string panel id, boolean is_opening)

Sends a message to the UI to tell it that a panel has been opened or closed by script. Note that this doesn't actually open or close the panel, but is instead for use if the script manually creates a panel with core:get_or_create_component, or if the script manually closes a panel using a command on the uicomponent interface

Parameters:

1

string

panel id

2

boolean

is_opening

Returns:

  1. nil

CampaignUI.OpenDiplomacyFactionList()
Opens the diplomacy faction list panel.

Returns:

  1. nil

CampaignUI.SetDiplomacyFactionListFilter()
Sets the filtering mode of the diplomacy faction list panel.

Returns:

  1. nil
Last updated 8/23/2024 4:55:15 PM