编辑“Scopes”

{{version|3.0}}

== Introduction ==
Most objects in the game provide a scope to access them through script.  A planet will provide a <code>planet</code> scope and a pop will provide a <code>pop</code> scope.  The relationship between objects also relates to their scopes.  To access the planet which a pop is on is called a scope switch, as your code is switching from referring to the pop to referring to the planet.  Most objects and their scopes form a tree-like relationship, with the global scope representing the entire game.

In code, scopes are written as the <code>[scope_type] = {  }</code>, with all the script in the brackets referring to the specific object of the scope.  For example:<br>
<code>pop = { unemploy_pop = yes }</code> would cause the current pop to become unemployed.  Scopes can be used in both <i>trigger</i> and <i>effect</i> blocks.  Some triggers and effects will take a scope as an argument, and some apply to a specific scope despite what scope they are run.  For example, <code>years_passed < 50</code> always refers to global scope, no matter what the current scope is.

A list of all known scopes is available below.

== System scopes ==
There are special system scopes that refer to relationships between scopes.  These are <code>THIS</code>, <code>PREV</code>, <code>ROOT</code>, and <code>FROM</code>.

* THIS – Refers to the current scope. It is useless as context switch, but sometimes is used as input for certain effects.  If you are in a <code>pop</code> scope, <code>this</code> would refer to that pop.
* PREV – Refers to the previous scope. If you are in a <code>pop</code> scope, and change to the <code>planet</code> scope, <code>prev</code> would refer back to the pop.  <code>pop = { planet = { habitability = { who = prev value > 0.6 } } }</code> would check that the habitability of the current pop has over 60% habitability on its current planet.  Sometimes you will want to refer back more than one scope step, in which case you can repeat prev up to four times, i.e. <code>prevprev</code> up to <code>prevprevprevprev</code>
* FROM – Refers to the scope from which the current script was called. For example, if an event executed a planet event, the planet event could refer back to the objects in the first event using the <code>from</code>scope. Just like PREV, up to four FROMs can be repeated to refer back multiple times.
* ROOT – Refers to the main scope of the script. For events, this will be the object the event is called in.  For example, in a <code>planet_event</code>, <code>root</code> will be the specific planet the event was called on.  ROOT is usually the default scope for script blocks in the event, but is shorter and more clear than PREV to refer to when you have switched to other scopes.  For example, in a pop event's <code>immediate</code> block, the pop is the default scope.  But if you switch to the planet scope of the pop, and possibly to even more chained scopes, <code>root</code> will always refer back to the pop the event was called on.  Note that in some scripts, such as scripted_effects and scripted_triggers, the default scope, <code>this</code>, is not necessarily the same as <code>root</code>.

In some contexts, these relationships aren't intuitive.  For instance, <code>on_action</code>s will often override some of these system scopes to hold the objects the action refers to.  For example, in events called from <code>on_ship_disabled</code>, <code>this</code> will refer to the disabled ship, and <code>from</code> will refer to the ship that disabled it.  The vanilla <i>on_actions.txt</i> file has comments describing most of these, while others you will have to look at code to determine to which objects they refer.

== Chaining scopes ==
To simplify code and increase readability, a <code>.</code> can be used to chain scopes together.  For example, <code>owner = { capital_scope = { solar_system = { … } } }</code> is equivalent to <code>owner.capital_scope.solar_system = { … }</code>, and will take you to the solar system of the capital of the country that owns the current scope.  Note that this does not work with the scope-changing triggers and effects referred to below.  For the PREV and FROM system scopes, if you need more than four, you can chain them together as well: <code>prevprevprevprev.prevprev</code>.

== Scope existence ==
Oftentimes scripts expect certain scopes to exist, or to run in certain scopes.  Sometimes, some scopes and relationships don't always exist.  For example, if you scope to the owner of a planet (<code>planet = { … owner = { … } }</code>), and the planet isn't owned, the script will fail and produce an error in the error.log.  As such, it is good practice to always check that a scope exists if there is any chance it might not.  This is done using <code>exists</code>.  Before changing the scope, use <code>exists = [scope]</code>. If it doesn't exist, the following code won't run.<br>
<code>planet = { exists = owner owner = { … } }</code>

== Triggers and scopes ==
Most triggers can only be called within certain scopes.  For instance, <code>is_moon</code> will only work in a planet scope.  If you attempt to call a trigger in the wrong scope, it will produce an error in the error.log and often cause the rest of the code to fail or produce unintended results.  The code will also error if you attempt to execute a trigger on a scope that doesn't exist.

Some triggers will also perform a scope change.  These triggers usually begin with <code>any_</code>, and script in them will run in the implied scope.  They will return yes if any object of that scope matches the criteria.  For example, <code>any_planet_within_border = { is_planet_class = pc_gaia }</code> will return yes if the country it is called on has a Gaia planet in its borders.  It will iterate through all <code>planet</code> scopes of the country and execute the trigger criteria in the scope.  So all script within the trigger's braces will execute in planet scope, even though it was called from country scope.

A list of these scope-like triggers can be found on the [[Triggers]] page, or actually by using the console command <code>trigger_docs</code> to get the defined triggers for your version of the game.

== Effects and scopes ==
Much like triggers, most effects only work in specific scopes.  If you attempt to call a trigger in the wrong scope, it will produce an error in the error.log.  However, executing an effect on a scope that doesn't exist will just cause nothing to happen with no error.

Some effects will also perform a scope change.  These effects usually being with <code>every_</code> or <code>random_</code>.  <code>every_</code> will apply the effect(s) within to every object of that scope, while <code>random_</code> will apply the effect(s) within to a single random object of that scope.  A <code>limit = { … }</code> statement can be used within these effects to narrow down the results.  For example, <code>every_owned_planet = { limit = { is_planet_type = pc_continental } … }</code> is called from country scope, but would apply the enclosed effect(s) to every Continental planet the country owned.  The effects within would all run in the planet scope of the continental planet, even though they were called from country scope.

A list of these scope-like effects can be found on the [[Effects]] page, or actually by using the console command <code>effect_docs</code> to get the defined effects for your version of the game.

== Event target ==
Sometimes it's a good idea to save certain scopes as event targets to use in later events or projects in the same namespace, or to use globally.

* Use the <code>save_event_target_as = [name]</code> to save the scope for later use in the namespace, or <code>save_global_event_target_as = [name]</code> to save the scope for later use anywhere.
* They can be scoped to using <code>event_target:[name] = { … }</code>, or used as a target for trigger or effect parameter.
For example, if an event at the start of a war saved the war leader as <code>save_event_target_as:war_leader</code>, after the war you could refer to them again:
: <code>planet.owner = { set_subject_of = { who = event_target:war_leader subject_type = vassal } }</code>
Event targets are used in [[Localisation_modding|localization]] by referencing directly the variable name:
: <code>"I have decided to release my vassal [target_leader.GetFullName]"</code>
Or can be used in tooltips of the event in which they are saved (which is normally not possible, as tooltips are built before effects are executed).

When you know you will no longer need a saved global event target, it is good practice to clear it: <code>clear_global_event_target = [name]</code>

== Scope Types ==
Every scope is of a particular type of object.  The type determines when it can be used.  They can be checked with <code>is_scope_type =</code> (''see [[Conditions]]''). The following are types that apply in game:

{| class="wikitable sortable"
|-
! Scope Type !! Scopes of this type !! Description
|-
| country || owner, controller, space_owner, overlord, subject, last_created_country, branch_office_owner || An empire.  Some of these are unique.  For instance, the Shroud is a country, all Tiyanki's are a members of the Tiyanki country, etc.
|-
| sector || sector || A sector in an empire
|-
| galactic_object || solar_system || An object (solar system) on the galactic map.
|-
| megastructure || megastructure || A system object built by constructor ships.  Note that habitats and ringworlds are converted to type <i>planet</i> after they are completed.
|-
| ambient_object || ambient_object, last_created_ambient_object || A point-of-interest in a galactic_object.
|-
| planet || planet, capital_scope, orbit, star || An entity within a galactic_object.  Stars, asteroids, habitats, ringworlds and planets are all considered planet-type scopes.  If a pop can live on it, it is a planet-type.
|-
| deposit || deposit || A planetary feature, including blockers.  Some are exploitable by orbiting stations, others are exploitable by colonizing the planet.
|-
| tile || ? || Mostly deprecated, but still officially supported.  Never used in Vanilla
|-
| archeaological_site || archeaological_site || A site of an archaeological dig, persists after it's completed.
|-
| army || last_created_army || An army.
|-
| pop || pop, last_created_pop || A pop.
|-
| species || species, owner_species, last_created_species || The specific pop (sub)species.
|-
| leader || leader, ruler, last_created_leader || A leader in a country.  This includes the current ruler, as well as leaders in the hiring pool.
|-
| pop_faction || pop_faction || A political faction within a country.
|-
| ship || starbase, last_created_ship || An empire controlled entity in space.  This includes starbases and defense platforms.
|-
| fleet || fleet, last_created_fleet || Every ship belongs to a fleet, even a lone ship.  A starbase fleet includes its defense platforms.
|-
| design || design, last_created_design || A ship design
|-
| federation/alliance || federation/alliance || A federation. Other than localisation of triggers, <code>federation</code> and <code>alliance</code> alliance are interchangeable. Vanilla uses <code>federation</code>.
|-
| war || - || A two-sided diplomatic war between two or more empires
|}

== List of scopes ==
{{SVersion|2.8}}
Current scopes can be found in an '''''scopes.log''''' file in your local data folder's script_documentation (defaults to "%USERPROFILE%\Documents\Paradox Interactive\Stellaris\'''logs\script_documentation\'''")
{| class="wikitable sortable"
|-
! Scope name !! Scope type !! Can be scoped from<br><code>xxx = { owner = {…} }</code><ref>Each scope should match the respective object in the other column (from/to). Scopes in brackets are only indirect (per extra command).</ref> !! Can scope to<br><code>owner = { xxx = {…} }</code> !! Description
|-
| owner || country || fleet, ship, planet, pop, leader, army, megastructure, sector, starbase || capital_scope, ruler, species, owner_species || Scopes to the country that owns the object
|-
| controller || country || fleet, ship, planet, pop, leader, army, megastructure, sector, starbase || capital_scope, ruler, species, owner_species || Scopes to the country that currently occupies the object
|-
| space_owner || country || galactic_object || capital_scope, ruler, species, owner_species || Scopes to the country that currently owns the galactic_object
|-
| last_created_country || country || any || capital_scope, ruler, species, owner_species || Scopes to the last created country. Usually used after a <code>create_country</code> effect.
|-
| sector || sector || planet || leader, owner, leader || A sector in a country
|-
| solar_system || galactic_object || planet, star, ship, leader || star, starbase, owner, space_owner || A solar system
|-
| last_created_system || galactic_object || any || star, starbase, owner, space_owner || The last created solar system. Usually used after a <code>spawn_system</code> effect.
|-
| megastructure || megastructure || – || planet, owner || A megastructure
|-
| ambient_object || ambient_object || – || solar_system || A non-planet entity in a solar_system. Often a point-of-interest for a special project.
|-
| last_created_ambient_object || ambient_object || any || solar_system || The last created ambient object. Usually used after a <code>create_ambient_object</code> effect.
|-
| star || planet || galactic_object || solar_system, starbase, owner, space_owner || The star of the solar system. May consist of multiple planet-scope stars, though one is always considered the main star.
|-
| planet || planet || pop, deposit, leader, army, archeaological_site, planet (moon) || solar_system, owner, planet_owner, space_owner, controller || A planet, star, or habitable structure.
|-
| capital_scope || planet || country || solar_system, owner, space_owner, controller || The capital planet of the country.
|-
| home_planet || planet || leader, pop, species, country || solar_system, owner, space_owner, controller || The home planet of a species/country.
|-
| orbit || planet || fleet, ship, planet || solar_system, owner, space_owner, controller || The planet-type object a fleet, ship, or moon is orbiting.
|-
| deposit || deposit || – || planet || A planetary feature, including blockers and space deposits.
|-
| archeaological_site || archeaological_site || planet || planet, leader, (excavator_fleet) || An archeaological_site on a planet.
|-
| army || army || – <s>ship</s> (country, planet) || <s>ship,</s> fleet, leader, owner, planet, pop, species || A defensive or offensive army.
|-
| last_created_army || army || any || fleet, leader, owner, planet, pop, species || The last created army, usually used with the <code>create_army</code> effect.
|-
| pop || pop || leader, army (planet, country, pop_faction, sector, species) || owner, planet, home_planet, species || A pop
|-
| last_created_pop || pop || any || country, planet, species || The last created pop, usually used with the <code>create_pop</code> effect.
|-
| species || species || pop, leader, army, country, (planet) || home_planet – (pop) || A specific pop species or subspecies
|-
| owner_species || species || country || home_planet – (pop) || The main species of a country. Usually the founder species, unless changed with <code>change_dominant_species</code> effect.
|-
| last_created_species || species || any || home_planet – (pop) || The last created species, usually used with the <code>create_species</code> effect, or the secondary species created by a player during empire creation.
|-
| leader || leader || fleet, ship, sector, army, archeaological_site || fleet, species, owner, ruler, sector, solar_system, home_planet || A leader in a country, including potential leaders in the pool.
|-
| ruler || leader || country || species, owner, ruler, sector, solar_system, home_planet || The leader that is the current ruler of a country,
|-
| last_created_leader || leader || any || fleet, species, owner, ruler, sector, solar_system, home_planet || The last created leader, usually used with the <code>create_leader</code> effect.
|-
| pop_faction || pop_faction || – || country || A political faction in an empire.
|-
| ship || ship || – (fleet) || fleet, orbit, leader, owner, space_owner ||
|-
| last_created_ship || ship || any || fleet, orbit, leader, owner, space_owner || The last created ship, usually used with the <code>create_ship</code> effect.
|-
| starbase || ship || planet (star), galactic_object || fleet, orbit, <s>leader,</s> owner, space_owner || An outpost or larger starbase that claims a system.
|-
| fleet || fleet || ship, army (country, galactic_object) || orbit, leader, owner, space_owner || A fleet containing at least one ship-type object.
|-
| last_created_fleet || fleet || any || orbit, leader, owner || The last created fleet, usually used with the <code>create_fleet</code> effect.
|-
| excavator_fleet || fleet || – (archaeological_site?) || orbit, leader, owner || A excavator fleet of an archaeological site.
|-
| design || design || – || (owner) || A ship design.
|-
| last_created_design || design || any || (owner) || The last created design, usually used with the <code>create_design</code> effect.
|-
| federation/alliance || federation/alliance || country || – || A federation. Note that <code>federation</code> and <code>alliance</code> are seemingly interchangeable but vanilla uses federation.
|-
| war || war || – (country) || – (attacker, defender) || A declared war.
|}
You can get the latest version in-game by using the ''<code>trigger_docs</code>'' [[Console commands#Testing Commands|console command]].

{{:Scopes/Flat list of scopes}}

== References ==
<references />

{{ModdingNavbox}}
[[Category:模组制作]]