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

Camera Movement

CampaignUI.ZoomToSmooth(
  number x,
  number y,
  [number horizontal distance],
  [number bearing],
  [number vertical distance]
)

Zooms the game camera to the specified display co-ordinates using smooth movement. x and y must be provided. If no bearing and distance values are provided then the current camera bearing and distance values are used.

Parameters:

1

number

x display position.

2

number

y display position.

3

number

optional, default value=nil

Horizontal distance from camera to camera target.

4

number

optional, default value=nil

Bearing in radians from camera to camera target.

5

number

optional, default value=nil

Vertical distance from camera to camera target.

Returns:

  1. nil

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

Back to top

Miscellaneous

CampaignUI.ClosePanel(string panel name)

Closes an open UI panel by name.

Parameters:

1

string

panel name

Returns:

  1. nil

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

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 400

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 439

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 454

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 486

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 495

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

Returns:

  1. nil

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

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 530

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

Sets the overlay mode to display by numeric id with a mode mask, 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_GROWTH
6REGION_HAPPINESS
7REGION_SLAVES
8REGION_FOOD
9REGION_CORRUPTION
10WINDS_OF_MAGIC
11CLIMATE_SUITABILITY
12GEOMATIC_WEB
13TUTORIAL_REGION_HIGHLIGHT
14ATTRITION_FOR_SELECTED_CHARACTER

Parameters:

1

number

Overlay mode (see lookup table above).

2

number

The mode mask, which can specify additional information about the overlay mode in certain circumstances. Where no special mode mask is required (i.e. most circumstances) the value 0 should be supplied here.

When showing the corruption overlay, this value specifies a corruption type (in order within the corruption_types table). When showing the happiness overlay, supplying a value other than 0 shows happiness trending rather than current happiness.

3

...

One or more string region keys

Returns:

  1. nil

Example:

CampaignUI.SetOverlayMode(5, 0, lothern_region_str, glittering_tower_region_str, tower_of_lysean_region_str)
CampaignUI.SetOverlayVisible(true)

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

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 626

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 645

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 666

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 688

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 717

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    

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

CampaignUI.AddBuildingChainToWhitelist(string building chain key)

Adds building chains to whitelist.

Parameters:

1

string

building chain key

Returns:

  1. nil

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

CampaignUI.ClearBuildingChainWhitelist()
Clears the building chain whitelist.

Returns:

  1. nil

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

CampaignUI.AddUnitToBlacklist(string main unit record key)

Adds a unit to the blacklist

Parameters:

1

string

main unit record key

Returns:

  1. nil

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

CampaignUI.ClearUnitBlacklist()
Clears the unit blacklist.

Returns:

  1. nil

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

Back to top

Minimal View

CampaignUI.IsMinimalViewModeEnabled()
Returns true if campaign_minimal_view_mode enabled (set in userscript to speed up campaign loading)

Returns:

  1. boolean is_campaign_minimal_view_mode_enabled

defined in ../../common/UIDll/Source/Campaign/EmpireCampaignUI.cpp, line 802

Last updated 12/08/2022 11:56:58