Scopes

From Stellaris Wiki
Jump to navigation Jump to search

Version

Outliner top.png
This article may contain outdated information that is inaccurate for the current version of the game. It was last updated for 2.0.

This article is for the PC version of Stellaris only.

Scopes allow to select entities in order to check for conditions or apply commands.

Scopes always have a bracketed block on the right side:

<scope_name> = {
	#Stuff to execute in the scope.
}

But not all bracketed blocks are scopes: some are function blocks (option, trigger, mean_time_to_happen,...), operators (AND), flow control statements (if, limit), or clause for complex conditions or commands (create_country, ...).

These are the basic scope types: country, sector, system (aka star,galactic_object), species, planet, ambient_object, fleet, ship, pop, pop_faction, leader, war, army, tile.

How scopes work[edit]

Scopes define objects to which code inside their brackets apply. Most effects and triggers need to apply to a specific scope, although some relate to state of the entire galaxy (global) and work identically in any scope. For example, years_passed will work for anyone. Sometimes scopes are used as arguments in certain effects and triggers instead.

Most scope switches are relations between objects, such as owner would take you to a country that owns the current scope. Some, however, are indenpendent - for example every_country will take you to every country, regardless of where you currently are.

Roughly scopes can be split in 5 categories:

  • "Random" scopes - those scopes start with random_ and effects within them will apply to a randomly chosen objects that fits definitions and fulfils conditions specified within limit = { }
    For example: random_planet = { limit = { is_planet_class = pc_gaia } } will scope to randomly chosen Gaia world anywhere in the galaxy. This is also the scope to be used to scope to a specific object that doesn't have a specific scope to it (For example a previously marked planet that is not country's capital) - limit that only one object fulfils (for example a specific previously set flag) is used to scope to this specific object.
  • "Every" scopes - those scopes start with every_ and effects within them will apply to every object that fits definitions and fulfils conditions specified
    For example: every_planet = { limit = { is_planet_class = pc_gaia } } will scope to every Gaia world anywhere in the galaxy.
  • "Any" scopes - those scopes start with any_. Unlike the previous two they are not fit to have effects in them and instead check for existence of an object that fits criteria.
    For example any_system_planet = { is_planet_class = pc_gaia } would allow you to check if there's a gaia in the system in question. Unlike random_ and every_ scope those should not include limit = { }.
    Note: Never use any_[scope] = { limit = { } - the 'limit' is superfluous and will create strange error messages on the error log (it will claim that a random nearby line is a faulty scripted trigger or some such).
  • System scopes - those are FROM, PREV, ROOT and THIS. Those scope to a specific object but those are dependent on the bigger context.
    • FROM (As well as several froms changed together, up to FROMFROMFROMFROM) is the scope of the piece of script that called current script. For example, if a country event called an event on planet, FROM in the latter will be the country that experienced the former. FROM is also used to keep relevant objects in scripts caused by certain mechanics. For example "on_actions" will use them to store effects relevant to current actions, or when "opinions" are scripted "from" will refer to the receiver of the opinion. Those parts are not always documented, but deducible from the code.
      Note: If you need more than four froms, you can use e.g. FROMFROMFROMFROM.FROMFROM = {
    • PREV (Can also be chained together into up to PREVPREVPREVPREV) is a step back within the same code. For example if in country scope you scope to a planet, scoping to prev from within the planet will take you back to the country.
    • ROOT - this is the main scope of the entire script. For events it will be the object event is called in
    • THIS - the current scope. Is useless as context switch, but sometimes used as input for certain effects
  • All the rest - those scopes will track certain definitive relations - like scoping from country to its capital, or from ship to its owner - and can be used for both effects and triggers.

Trying to apply effect to a non-existent scope (Such as owner of a barren planet) would do nothing but trying to apply trigger to a scope that doesn't exist (Such as trying to check properties of owner of a barren planet) would produce an error. You can prevent it by using exists = scope_in_question right before scoping to pre-emptively stop checking if scope does not exist.

In code, any scope that isn't random_ every_ or _any can be chained in a single string using periods. for example owner.capital_scope.solar_system will take you to the solar system, where the capital of the country that owns current scope is.

Event target[edit]

Sometimes it's a good idea to save certain scopes as event targets. Maybe you'll need them as input or just can't handle the long chain of scope switches.

Use save_event_target_as = [name] save_global_event_target_as = [name] effect and it will save the scope for later use. They can be scoped to using event_target:[name] = { }. Regular event target will persist through all scripts (Not just other events, but special projects, for example) that are explicitly called from the script where it exists and global will persist everywhere.

List of Scopes[edit]

Scope Used in vanilla Description Trigger Effect From scope
any_attacker Scopes to the attacker and all co-belligerents in this war. X War
any_bordering_country Scopes to all countries whose borders are near this system. X System
any_controlled_planet Scopes to all planets owned or occupied by this country. X Country
any_country Scopes to all countries in the galaxy. X Any
any_defender Scopes to the defender and all co-belligerents in this war. X War
any_moon Scopes to all of this planet's moons, or all of this star's planets. X Planet
any_neighbor_country Scopes to all countries bordering this one. X Country
any_neighbor_system Scopes to all systems near this one. X System
any_neighboring_tile Scopes to all tiles adjacent to this one. X Tile
any_owned_fleet Scopes to all fleets belonging to this country. X Country
any_owned_leader Scopes to all of this country's leaders. X Country
any_owned_planet Scopes to all planets owned by this country. X Country
any_owned_pop Scopes to all pops belonging to this country. X Country
any_owned_ship Scopes to all ships and stations belonging to this country. X Country
any_system_planet Scopes to all planets in this system. X System
any_planet_within_border Scopes to all planets within this country's borders. X Country
any_pop Scopes to all pops on this planet. X Planet
any_sector Scopes to of this country's sectors. X Country
any_ship Scopes to all ships in this fleet. X Fleet
any_ship_in_system Scopes to ships in this system. X System
any_system Scopes to all systems in the galaxy. X Any
any_system_within_border Scopes to any system within the current country's borders. X Country
any_tile Scopes to all tiles on this planet. X Planet
any_war Scopes to all wars involving this country. X Country
best_tile_for_pop Scopes to the best tile for a pop on this planet. X Planet
capital_scope Scopes to the capital planet of this country. Country
closest_system Scopes to the closest system to this planet/system/fleet Planet/System/Fleet
every_country Scopes to all countries in the galaxy. X Any
every_playable_country Scopes to all (major empire) countries in the galaxy. X Any
every_fleet_in_system Scopes to every fleet in this system. X System
every_neighboring_tile Scopes to all tiles adjacent to this one. X Tile
every_owned_fleet Scopes to all fleets owned by this country. X Country
every_owned_planet Scopes to all planets owned by this country. X Country
every_owned_leader Scopes to all leaders owned by this country. X Country
every_owned_pop Scopes to all pops belonging to this country. X Country
every_pop Executes enclosed effects for every pop in the game that meet the limit criteria. X Any
every_owned_ship Scopes to all ships owned by this country. X Country
every_planet Scopes to all planets in the galaxy. X Any
every_planet_within_border Scopes to all planets within country borders. X Country
every_planet_army Scopes to all armies on this planet. Doesn't work if you do remove_army = yes, that stops the loop. Use while={limit={has_army=yes}}random_army={remove_army=yes}} instead for deleting all armies on a planet. X Planet
every_pop_faction Scopes to all factions in this country. X Country
every_system_ambient_object Scopes to all ambient objects in this system. X System
every_system_planet Scopes to all planets in this system. X System
every_tile Scopes to all tiles on this planet. X Planet
every_system_within_border Iterate through all systems within the country's borders. X Country
fleet Scopes to the fleet this ship belongs to. Ship
last_created_ambient_object Scopes to the last created ambient_object. X Any
last_created_country Scopes to the last created country. X Any
last_created_fleet Scopes to the last created fleet. X Any
last_created_leader Scopes to the last created leader. X Any
last_created_pop Scopes to the last created pop. X Any
last_created_species Scopes to the last created species. X Any
leader Scopes to the leader of this ship/planet/country. X Ship/Planet/Country
orbit Scopes to the planet this fleet is orbiting. (does not work for ship!) Fleet
orbital_deposit_tile Scopes to the orbital tile of this planet. Planet
owner Scopes to the owner country of this ship, Pop, or planet. Ship, Pop, Planet
owner_species Scopes to the owner species of this country. X Country
overlord Scopes to the country's overlord, if it has one. Country
random_army Scopes to a random army. X Any
random_country Scopes to a random country. X Any
random_moon Scopes to a random moon orbiting this planet. X Planet
random_neighbor_country Scopes to a random country bordering this one. X Country
random_neighboring_tile Scopes to a random tile adjacent to this one. X Tile
random_owned_fleet Scopes to a random fleet belonging to this country. X Country
random_owned_leader Scopes to a random leader belonging to this country. X Country
random_owned_planet Scopes to a random planet owned by this country. X Country
random_owned_pop Scopes to a random pop belonging to this country. X Country
random_owned_ship Scopes to a random ship or station belonging to this country. X Country
random_fleet_in_system Scopes to a random fleet or station belonging to this system. X Country
random_planet Scopes to a random planet anywhere in the galaxy. X Any
random_pop Scopes to a random pop on this planet. X Planet
random_pop_faction Scopes to a random faction in this country. X Country
random_rim_system Scopes to a random system on the outer rim of the galaxy. X Any
random_sector Scopes to a random country sector. X Country
random_system Scopes to a random system anywhere in the galaxy. X Any
random_system_within_border Scopes to a random system within the countries borders. X Country
random_system_ambient_object Scopes to a random ambient object in this system. X System
random_system_planet Scopes to a random planet in this system. X System
random_tile Scopes to a random tile on this planet. X Planet
solar_system Scopes to system this country/ship/planet is in. Country/Ship/Planet
space_owner Scopes to owning country of this planet or system. System, Planet
pop_faction Scopes to the faction of this pop pop
planet Scopes to the planet of a pop pop
home_planet Scopes to the home planet of species (Will use primary species if used on planet) country, species
observation_outpost_owner Scopes to the owner of the observation outpost of a planet planet
observation_outpost Scopes to the observation outpost of a planet planet
sector Scopes to the planet's sector planet
starbase Scopes to the systems's starbase System

Additional scopes:

type Scope =

       |Country
       |Leader
       |GalacticObject
       |Planet
       |Ship
       |Fleet
       |Pop
       |AmbientObject
       |Army
       |Tile
       |Species
       |PopFaction
       |Sector
       |Alliance
       |War
       |Megastructure
       |Any //Not an ingame scope
       |Design
       |Starbase
       |Star
       |Solar_System
       |InvalidScope // Not an ingame scope

References[edit]