From Imperator Wiki
Jump to navigation Jump to search

Variables are values that can be stored through script. They come in several types:

  • Value (number)
  • Boolean (true/false)
  • Flags
  • Scopes (province, character, country, etc)

These values can then be accessed later on in an event, script value, gui, or scripted effect.

Creating a Variable[edit]

Creating a variable through script is fairly simple. Variables have several properties you need to consider when creating one:

  1. Location. A variable is stored inside of another scope. This scope is how you will access it later
  2. Name. Every variable has a name so that they can be differentiated from other variables in the same scope.
  3. Value (optional). What this variable is storing. You may want to name the variable something specific so that you later know what it means

In the script itself, there are two ways of creating a variable, but both use the set_variable effect.


scope:character = { # 'character' can be replaced with any named scope or effect ie. every_character, etc
          set_variable = has_best_friend_flag

This sets a variable within the scope 'character' named 'has_best_friend'. This is an example of a flag, where the existence of the variable shows that the query (in this case, "does this character have a best friend?" is true.


scope:character = { # 'character' can be replaced with any named scope or effect ie. every_character, etc
          set_variable = {
                 name = best_friend
                 value = scope:other_character

In this case, it is are creating a variable named "best friend" and saving another character inside it. This way, should finding a character's best friend be needed later in script, this variable can point to it. value = <something> can be used to refer to any scope, number, or boolean variable

Accessing a Variable[edit]

There are several ways of accessing a variable, and the one to use depends on the context.

Flags in Script[edit]

For a flag, the simplest way to access it is by using has_variable, which is a trigger and will return true if the current scope has the specified variable.

if = {
       limit = {
              scope:character = {
                       has_variable = has_best_friend_flag
       debug_log = "Character has best friend!"

would print "Character has best friend!" to the debug log if the scope 'character' has the flag 'has_best_friend_flag'.

Values in Script[edit]

For a value, using the .var:<variable name> function is the way to check the variable's value or scope

if = {
       limit = {
              scope:character.var:best_friend = scope:character_to_check
       debug_log = "This is the character's best friend!"

would print "This is the character's best friend!" if the scopes character_to_check and character's variable "best_friend" are equal; ie. if the character being checked is the original character's best friend. For numerical values =, >=, and <= are also allowed, and for scopes != (not equal to) can be used.

Values in GUIs[edit]

In a gui, there are different functions entirely (gui functions). has_variable or set_variable will not work in gui files. To show a value in a gui, the .Var('variable name') gui function would be used.

text = "[ProvinceWindow.GetProvince.MakeScope.Var('tax_income').GetValue|0]"

This is slightly more complex, and is easier to understand broken up into parts.

  • text = 
    This is a property of a gui item (button, textbox, etc.)
  • "[<functions>]"
    This tells the Gui what to find or get. In this case, we want to find the province that is the focus of the province window. For a full list of GUI Functions, see Data Types. Functions that are specifically attached to one window or file cannot be used in another one. This must always be within "[]"
  • MakeScope
    This makes whatever you have found with GUI functions like ProvinceWindow.GetProvince into the current scope. This is used for variables, Scripted GUIs and Script Values. Without it, the GUI will not know where to look for your variable.
  • .Var('variable name')
    This tells the GUI what variable to look for by name.
  • .GetValue|0
    This section tells the GUI what to do with the variable once it has found it. In this case, the GUI is to get the value of it (GetValue is used for numerical values). In other cases, it could be used to find a province (GetProvince) or a character (GetCharacter). These can be chained ie. .GetProvince.GetName would get the name of a province stored in a variable. The |0 is used to specify, for numerical values, how many digits past the decimal point should be displayed. Typically vanilla GUIs use 2.

Flags in GUIs[edit]

This is a bit more tricky, but the easiest way is probably to save a numerical value inside a flag, and use a data function like GreaterThanInt32 to determine if the variable's value is greater than a specified number:

visible = "[GreaterThanInt32(ProvinceWindow.GetProvince.MakeScope.Var('has_ships_in_port').GetValue, 1)]"
text = "This province has ships in its port."

Note that this solution only works if the value of has_ships_in_port is greater than 1.


To display a variable in a tooltip uses the same syntax as in a GUI, but most likely the tooltip in question will be in a localisation file, not a GUI file. It is recommended to handle tooltips in localisation, not GUI files, as it allows for use of line break characters (\n).

Changing a Variable[edit]

Changing a variable is typically done using the change_variable effect, like so:

change_variable = {
      name = num_friends
      add = 1 # you can use add, subtract, multiply, or divide for numerical variables

For non-numeric values, however, simply using set_variable to override the previous value of the variable is the best way to go. Note that change_variable does not require the var: function in front of the name field, including it will not work.

Documentation EffectsTriggersModifiersScopesVariablesData TypesLocalisationCustomizable localization
Scripting AIBuildingsCasus belliCharacterCharacter InteractionsCombat TacticsCountriesCultureDecisionsDefinesEconomic PoliciesEventsEthnicitiesGovernmentGovernor PoliciesIdeasModifiersMilitary TraditionsOfficesOn ActionsPartiesPricesPopsProvince setupReligionScript ValuesScript ModifiersSubject TypesTechnologyTrade goodsTraitsUnits
Map MapTerrainMap locators
Graphics 3D ModelsInterfaceCoat of armsGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumMod structureTroubleshooting