编辑“Variables”

{{version|3.1}}
We can use script-defined variables to perform calculations in scripts and events. Once created, variables are stored in their [[scopes|scope]] and can be retrieved for later use. As of [[3.1|version 3.1]], you can do a lot more (fancy things) with variables in script. Variables can be copied between scopes (''[[#Copying variables between scopes 版本|see below]]''), and can be used as part of bracket commands in [[Localisation modding]].

== Available scopes ==

As of version 3.1 we can use variables nearly within every scope. When a variable is set in a scope, it binds to the scope and persists in it.
: Scopes: <code>megastructure planet country ship pop fleet galactic_object leader army ambient_object species pop_faction war federation starbase deposit sector archaeological_site first_contact spy_network espionage_operation espionage_asset</code>

== Commands ==

=== Setting variables ===

You can make a variable out of various numbers. The easiest is <code>set_variable</code> and <code>change_variable</code>:
* <code>set_variable = { which = star_temperature value = @G2V_star_temperature }</code> – Sets a specific star's temperature to the scripted variable value
But you can also do it with:
* <code>get_galaxy_setup_value</code>: galaxy setup options
* <code>export_trigger_value_to_variable</code>: the value of a trigger (e.g. number of pops in the empire). Should work for all triggers that are comparing a single numerical value or (since 3.3) the value of count_x triggers. Otherwise for triggers with { }, you can specify parameters = { }
* <code>export_modifier_to_variable</code>: the sum of the specific modifier applying to this scope, e.g. the amount of pop_citizen_happiness that a pop is gaining from all sources (including any country and planet modifiers).
* <code>export_resource_income_to_variable</code>, <code>export_resource_stockpile_to_variable</code>: country's monthly income or current stockpile of a resource
''For more [[#Limitations and other notes|see below]].''

=== Manipulating variables ===

Once the variable is set, you can then alter it with standard mathematical operations:
* <code>change_variable = { which = <string> value = <float>/<variable>/<scope.variable>/trigger:<trigger> }</code> – Increments a previously-set variable by a specific amount
* <code>subtract_variable = { which = <string> value = <float>/<variable>/<scope.variable>/trigger:<trigger> }</code> – Decrements a previously-set variable by a specific amount
* <code>multiply_variable = { which = <string> value = <float>/<variable>/<scope.variable>/trigger:<trigger> }</code> – Multiplies a previously-set variable by a specific amount
* <code>divide_variable = { which = <string> value = <float>/<variable>/<scope.variable>/trigger:<trigger> }</code> – Divides a previously-set variable by a specific amount
* <code>modulo_variable = { which = <string> value = <float>/<variable>/<scope.variable>/trigger:<trigger> }</code> – Modulos a previously-set variable by a specific amount i.e. X % Y

In all of these effects (except round/floor/ceiling variables), you can add/multiply/whatever the variable by another one, with dot scoping and referring to triggers allowed.<sup>''with 3.1''</sup> E.g.:
 multiply_variable = {
 	which = my_var <i class=effect-green># must be directly referring to a variable</i>
 	value = fromfromfrom.owner.trigger:num_pops
 }

Once you are done with a variable, you can clear it using: <code>clear_variable = <string></code><sup>(''since 3.0'')</sup>

Also worth noting: if you need to manipulate a variable in a trigger, you can use the <code>check_variable_arithmetic</code> trigger (which now supports an unlimited number of <code>add/subtract/divide/multiply/modulo operations</code>).<sup>''with 3.1''</sup>

=== Checking variable values ===

* <code>check_variable = { which = <variable> value = <float>/<variable>/<scope.variable>/trigger:<trigger>/modifier:<modifier> }</code>
This checks a variable for the chosen scope – accepts <code>=</code>, <code>>=</code>, <code>></code>, <code><=</code>, and <code><</code> as operators.
: When you are using the value of a variable, you can now (''with 3.1'') use dot scoping: <code>value = owner.capital_scope.my_var</code>
: You can also directly refer to the value of a trigger: <code>value = trigger:num_pops</code>
: A combination of the two is also possible: <code>value = owner.capital_scope.trigger:num_pops</code>
: You can also (with 3.3) directly refer to the value of a modifier: <code>value = modifier:pop_growth_speed_reduction</code>
: This works almost everywhere where you are using variables. The exception is in the basic variable effects and triggers where you are specifying which variable to check or change.

 check_variable_arithmetic = {
 	which = <variable>
 	add/subtract/multiply/divide/modulo = <float>/<variable>/<scope.variable>/trigger:<trigger> <i class=effect-green># (note: this line can be repeated as many times as desired)</i>
 	value <=> <float>/<variable>/<scope.variable>/trigger:<trigger> <i class=effect-green># (the value to compare against)</i>
 }
This checks a variable for the scope if a certain amount of arithmetic is done to it (Note: the variable's value is not changed by this trigger).<sup>''with 3.0''</sup>

=== Copying variables between scopes ===

Just like with checking variables, you must (now ''with 3.1'') use dot scoping:
:<code>set_variable = { which = var1 value = owner.capital_scope.my_var }</code>


{{Spoiler|Header=<small>Pre 3.1 outdated syntax</small>|Text=* A '''scope''' (in the form of root/from/prev) ''which'' contains a variable with the ''same name'': <code><nowiki>(set|change|subtract|multiply|divide|modulo)_variable = { which = <variable_name> value = <scope> }</nowiki></code><br>* A '''scope reference''' to point to ''another'' variable in ''another'' scope <code>value = { scope = <scope> variable >=< <variable> }</code> <sup>(''with 3.0'')</sup>
We can copy variables direct between scopes. To do this, you can either name a scope to copy a variable of the same name, or specify both the scope and variable name. This command looks for a variable in the "owner" scope called "var1", and if it finds it, copies its value to "var1" in the current scope: <code>set_variable = { which = var1 value = owner }</code>
And this looks for a variable in the owner ''scope'' called "var2", to set the value of "var1": <sup>(''with 3.0'')</sup> <code>set_variable = { which = var1 value = { scope = owner variable = var2 } }</code>}}

== Limitations and other notes ==

It is not required to "initialize" a variable before use. When a variable is first used, it is assumed by the game to be zero. However, the game will throw an error if you use an unset variable. To avoid unset variables errors, use a check if the specified variable is set on the current scope.
: <code>is_variable_set = <string></code>

We can assign more than only simple trigger/modifier values to a variable:<sup>(''with 3.0'')</sup>
* <code>export_modifier_to_variable = { modifier = pop_growth_speed_reduction variable = <string> }</code> – Exports the value of a specified modifier in the current scope to a specified variable.
* Resource stockpiles and incomes can also be exported using one of one of the following:
:<code>export_resource_stockpile_to_variable = { resource = <resource> variable = <string> }</code> – Exports the value of the current country's stockpile of the specified resource to a variable.
:<code>export_resource_income_to_variable = { resource = <resource> variable = <string> }</code> – Exports the value of the current country's monthly income of the specified resource to a variable.
* <code>get_galaxy_setup_value = { which = <string> setting = <string> [ scale_by = <float> ] }</code> – Copies a value from the galaxy setup into a variable, optionally scaling it by an int value.
:: possible values: <small><code>num_empires, num_advanced_empires, num_fallen_empires, num_marauder_empires, mid_game_year, end_game_year, victory_year, num_guaranteed_colonies, num_gateways, num_wormhole_pairs, num_hyperlanes, habitable_worlds_scale, primitive_worlds_scale, crisis_strength_scale, tech_costs_scale</code></small>


{{Spoiler|Header=<small>Pre 3.1 outdated syntax</small>|Text=(''with 3.0'') the only trigger value that can be exported is <code>fleet_power</code>: <code>export_trigger_value_to_variable = { trigger = fleet_power variable = <string> rounded = yes (default: no) }</code> – Exports the value of a specified simple value trigger (i.e. no { }, returns a number on the right hand side) to a specified variable.</small>}}

=== Using variables – the wheres ===

We can (now ''with 3.1'') use variables in a lot of different places:
* Any trigger that is comparing a single number, including ones with <code>{ }</code>. E.g. "<code>num_pops > my_var</code>", "<code>intel = { who = from value < trigger:num_pops }"</code>.
* Any effect using a single number, including ones with <code>{ }</code>. E.g. "<code>add_experience = my_var</code>".
* The count parameter of while loops!
* Certain effects let you input variables for various reasons. E.g. <code>multiplier</code> on <code>add_modifier</code> (the modifier's bonuses will be multiplied by the variable), <code>mult</code> on <code>add_resource</code> (multiplies all resources granted by that effect).
* Resource tables and triggered resource tables can take a "<code>multiplier = <variable></code>", the variable must be in the planet scope  and may not be dot scoped:
<pre>	resources = {
		category = planet_buildings
		cost = {
			trigger = { <triggers> }
			minerals = 100
			multiplier = my_var/trigger:num_pops
		}
	}</pre>
* [[MTTH]]/AI Chance modifiers:
<pre>	ai_chance = {
		factor = 1
		modifier = {
			add/factor = my_var/trigger:num_pops
			is_variable_set = my_var
		}
	}</pre>
* Ordered script lists: scope to the country with the highest (or 3rd highest, or lowest) value for a variable or trigger.
* In [[Localisation modding|locs]]: if you refer to <code>[This.my_var]</code>, it will print the value of the variable, so long as the variable is set.

=== Number precision and rounding ===

We have several native options for rounding variables:<sup>(''with 3.0'')</sup>
: <code>round_variable = <string></code> – Rounds a previously-set variable to the closest integer.
: <code>floor_variable = <string></code> – Rounds a previously-set variable down to the previous integer.
: <code>ceiling_variable = <string></code> – Rounds a previously-set variable up to the next integer.
: <code>round_variable_to_closest</code> – Rounds a previously-set variable to the closest X (multiple of the specified value).


{{Spoiler|Header=<small>Pre 3.0 rounding syntax</small>|Text=You had to use an operation workaround here, by simply dividing and multiplying.<pre>
 <code>set_variable</code> = { which = myvar value = 360.3451 }
 divide_variable = { which = myvar value = 100000 }
 multiply_variable = { which = myvar value = 100000 }
 ...
 # gives 360 </pre>
: Note: This rounds the number only down, if you want round to the nearest above 0, add <code>0.5</code>. If you want round up above 0, add <code>0.99999</code>. The floating point precision of (almost) every float number is 5 digits.</small>}}
----
{{ModdingNavbox}}
[[Category:模组制作]]