Arrays

From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

Arrays in general are containers that store elements (data). In Hearts of Iron IV, it is possible to store numerical data and scope data within arrays.

Arrays are used via effects and can be checked with triggers. There are special effects that allow you to iterate through an array to then apply other effects to or with the data within. Arrays are assigned to scopes, and thus each country/state/unit leader has a different pool of arrays.

Temp arrays work similarly to regular arrays, but they will be cleared after the effect is finished (Say, if one is defined in a completion reward of a focus, it will be cleared after the completion reward is executed), and they are not assigned to scopes, each one working globally. Temp arrays can also be set and modified in triggers as well as effects.

Effects

add_to_array

add_to_array = {
    array = <name>
    value = <value>
    index = <index>
}

An array is created once an element has been added to it.
The name of the array is what you use to refer to the array in other effects and triggers.
The value is the data you are adding to the array. It can be a number (i.e. 1 or var:my_num) or a scope (i.e. GER or var:my_scope). This is optional, if not included the current scope is added as the value.
The index refers the where the value should be inserted into the array. By default data is added to the end of the array, otherwise, the data is shifted to accommodate the new value.
A short form can be used: add_to_array = { <name> = <value> }
A temp array version exists as add_to_temp_array.

remove_from_array

remove_from_array = {
	array = <name>
	value = <value>
	index = <index>
}

The name of the array is the array you want to remove the data from.
The value is the value you want to remove from the array (if present).
The index is the index of the value you want to remove from the array (if present).
If neither the value nor index attributes are defined, the last element will be deleted.
A short form can be used: remove_from_array = { <name> = <value> }
A temp array version exists as remove_from_temp_array.

clear_array

clear_array = <name>

Clears all data from the specified array.
A temp array version exists as clear_temp_array.

resize_array

resize_array = {
	array = <name>
	value = <value>
	size = <int>
}

Resizes the specified array.
The value attribute sets any empty elements to the specified value if expanding the array. Defaults to 0 if not specified.
The size attribute specifies the new size of the array, removing elements if shrinking the array, or adding new elements with the specified value if expanding it.
A short form can be used: resize_array = { <name> = <size> }
A temp array version exists as resize_temp_array.

find_highest_in_array

find_highest_in_array = { 
	array = array_name 
	value = value_name 
	index = index_name
}

Finds the highest value in the array and assigns its value and index to the specified temp variables.
The value attribute specifies the name of the temp variable the value of the highest element will be assigned to. Paradox Documentation says that it's 'v' by default, but testing has shown that to be false.
The index attribute specifies the name of the temp variable the index of the highest element will be assigned to. Paradox Documentation says that it's 'i' by default, but testing has shown that to be false.
This effect works for temp arrays without the need for any changes and can be used in triggers. If the values inside the Array are all the same, it will return the first entry of the array.

find_lowest_in_array

find_lowest_in_array = { 
	array = array_name 
	value = value_name 
	index = index_name
}

Finds the lowest value in the array and assigns its value and index to the specified temp variables.
The value attribute specifies the name of the temp variable the value of the lowest element will be assigned to. Paradox Documentation says that it's 'v' by default, but testing has shown that to be false.
The index attribute specifies the name of the temp variable the index of the lowest element will be assigned to. Paradox Documentation says that it's 'i' by default, but testing has shown that to be false.
This effect works for temp arrays without the need for any changes and can be used in triggers.

while_loop_effect

while_loop_effect = {
	break = <string>
	limit = { <triggers> }
	
	<effects>
}

Runs the effect as long as a trigger is true.
The break attribute specifies a temp variable that can be set to non-0 to break the loop, ending iteration. By default this is break.
Effects can be used within the loop to perform operations with the data within an array.

for_each_loop

for_each_loop = {
	array = <name>
	value = <string>
	index = <string>
	break = <string>
	
	<effects>
}

Runs a loop for each element of the specified array.
The value attribute specifies a temp variable that stores the current value whilst iterating over the loop. By default this is v.
The index attribute specifies a temp variable that stores the current index whilst iterating over the loop. By default this is i.
The break attribute specifies a temp variable that can be set to non-0 to break the loop, ending iteration. By default this is break.
Effects can be used within the loop to perform operations with the data within an array.

for_each_scope_loop

for_each_scope_loop = {
	array = <name>
	break = <string>
	
	<effects>
}

Runs a loop for each element of the specified array and changes the current scope to the current element in each iteration.
The break attribute specifies a temp variable that can be set to non-0 to break the loop, ending iteration. By default this is break.
Effects can be used within the loop to perform operations with the data within an array.

random_scope_in_array

random_scope_in_array = {
	array = <name>
	break = <string>
	limit = { <triggers> }
	
	<effects>
}

Runs a loop for each element of the specified array and changes the current scope to a random scope (out of the scopes within the array) that meet the triggers specified.
The break attribute specifies a temp variable that can be set to non-0 to break the loop, ending iteration. By default this is break.
Effects can be used within the loop to perform operations with the data within an array.

Triggers

is_in_array

is_in_array = {
	array = <name>
	value = <value>
}

Checks if the specified value is in the specified array.

any_of

any_of = {
	array = <name>
	value = <string>
	index = <string>
	
	<triggers>
}

Runs a loop on the specified array and checks the triggers against the current element. If any return true, the whole check returns true, otherwise returns false.

all_of

all_of = {
	array = <name>
	value = <string>
	index = <string>
	
	<triggers>
}

Runs a loop on the specified array and checks the triggers against the current element. If any return false, the whole check returns false, otherwise returns true.

any_of_scopes

any_of_scopes = {
	array = <name>
	
	<triggers>
}

Runs a loop on the specified array and checks the triggers against the current element scope. If any return true, the whole check returns true, otherwise returns false.

all_of_scopes

all_of_scopes = {
	array = <name>
	
	<triggers>
}

Runs a loop on the specified array and checks the triggers against the current element scope. If any return false, the whole check returns false, otherwise returns true.

Additional information

You can set a variable equal to the number of elements in an array by using the following code: set_variable = { var_name = array_name^num } This example will set var_name to be equal to the number of elements in array_name.
To modify a single element in an array, you need to use set_variable as such: set_variable = { array_name^index = new_value } This example will set array_name's element with the index equal to index to be new_value. index can be a variable. In order to modify a single element in a temporary array, set_temp_variable = { array_name^index = new_value } must be used instead.

Examples

#This example shows you how to add variables to an array and trigger an effect depending on which variable has the highest value
#Initializing variables
set_variable = {
  var = PHF_weight_behind_proposal_bc_british
  value = 1
}
set_variable = {
  var = PHF_weight_behind_proposal_bc_american
  value = 2
}
set_variable = {
  var = PHF_weight_behind_proposal_bc_german
  value = 3
}
#adding variables into an array
add_to_array = {
    array = PHF_london_naval_conference_result_BC
    value = var:ENG.PHF_weight_behind_proposal_bc_british
}
add_to_array = {
    array = PHF_london_naval_conference_result_BC
    value = var:ENG.PHF_weight_behind_proposal_bc_american
}
add_to_array = {
    array = PHF_london_naval_conference_result_BC
    value = var:ENG.PHF_weight_behind_proposal_bc_german
}
#Triggering an effect depending on which variable has the highest value
find_highest_in_array = {
     array = PHF_london_naval_conference_result_BC
}
# i is the index of the highest value. Because of the order in which the variables have been added to the array check_variable = { i = 0 } means that the first variable added to the array contains the highest value of the array
if = {
   limit = {
     check_variable = { i = 0 }
   }
   add_political_power = 10
}
else_if = {
  limit = {
    check_variable = { i = 1 }
  }
   add_political_power = 20
 }
 else_if = {
     limit = {
         check_variable = { i = 2}
     }
   add_political_power = 30         
}