On Actions

Table of Contents

• 1. Wiki Section
• 2. From Stellaris Game Files
  • 2.1. common/on_actions/99_README_ON_ACTIONS.txt
    • 2.1.1. GOOD PRACTICES FOR EVENTS FIRED BY ON ACTIONS
    • 2.1.2. EXAMPLE:
• 3. From by Github Contributors to the Project
  • 3.1. How to use fire_on_actions and configure it's scope configurations
  • 3.2. Basic Usage and Documentation of On Actions
  • 3.3. Execution Order of Vanilla On Actions while the Game is initializing for First Time

---

---

This Wiki page was last updated for $$\textcolor{aqua}{Stellaris}$$ version v4.4.*

---

---

1. Wiki Section

See https://stellaris.paradoxwikis.com/On_actions

2. From Stellaris Game Files

2.1. common/on_actions/99_README_ON_ACTIONS.txt

On Actions are lists of events that get triggered automatically whenever a certain action occurs.

For example, we have On Actions for when you survey a planet (on_survey), when a starship gets destroyed (on_starbase_destroyed), or you win a space battle (on_space_battle_won). We also have "pulse" On Actions which occur at regular periods of time (on_colony_X_year_pulse, on_monthly_pulse_country, etc).

Every time an On Action gets fired, it will:

• Go through every single event in its events = {}, exclude the ones that trigger false, and fire all the other events
• Go through every single event in its random_events = { # Based on weights and in-event 'weight_multiplier = {}'' code blocks, only runs 1 event.} block, exclude the ones that trigger false, roll weights and fire one random valid event

2.1.1. GOOD PRACTICES FOR EVENTS FIRED BY ON ACTIONS

For planet, system, starbase, leader and pop events, it's recommended to use pre_triggers (fast triggers that are checked before normal ones) to improve performance. See events/000_added_pre_triggers_to_planet_events.txt for information and examples.

Unlike random_list = {}, random_events = {} don't support weight modifiers, don't support weight modifiers, but you can add a weight_multiplier = {} block to the event itself:

weight_multiplier = {
	factor = 1				# Default multiplier value
	modifier = {
		factor = X			# Multiply by X if the triggers below are true
		trigger_name = value 
	}
}

Custom on actions can be defined in script and triggered by the fire_on_action = { on_action = your_on_action_here } effect.

2.1.2. EXAMPLE:

on_action_name = {
	events = {
		# Events within this block may fire every time the on_action occurs
	}
	random_events = {	#	Based on weights and in-event 'weight_multiplier = {}'' code blocks, only runs 1 event.
		# One valid event is chosen every time the on_action occurs
		200 = 0					# Chance of no events firing
		10 = event_name.01
		10 = event_name.02
	}
}

3. From by Github Contributors to the Project

3.1. How to use fire_on_actions and configure it's scope configurations

When you use fire_on_action to run either a Vanilla or a Custom On_Action, the Engine automatically assigns ROOT for on_action to the Scope you run fire_on_action from.

And PREV, PREVPREV etc also work as if you're running an effect from the scope you run 'fire_on_action' from.

This simplifies things a lot. For most on_action's, you don't need to play with scope overrides.

However, if an on_action needs a specific Scope to specifically be something else (most likely to be a Vanilla on_action, as custom on_actions can be properly designed with those use cases you're using them for), you need to use Scope Overrides to manually assign scope(s).

Here is an example of fire_on_action. Pay attention to the scopes = {} field:

fire_on_action = {
    on_action = on_ship_built
    scopes = {
        from = root.from OR prev.from		#	Planet Scope transfer (makes new Event's 'from' scope; this event's root's (the original ship) from)
        }
    }

The left side of (=) is the scope that will be used for the on_action that you run via fire_on_action.

If you override the from scope as you did in here, non-global event_targets will not be available in the fired events. (as the from scope relation breaks, thus game can't track non-global event_targets while running the on_action)

The right side of (=) is the scope you're transferring.

Take note that this side assumes fire_on_action effect's scope as prev scope. (THIS if you're not overriding scopes, thus not using scopes = {} code block.)

Take note that in this scope, only while you're overriding scopes, fire_on_action counts as a scope despite not being a scope. So you need to use either root to bypass it, or use an additional prev to access the scope that runs fire_on_action, and other scopes from that.

• (e.g. instead of from = from, use from = prev.from)
• (e.g. instead of from = prev, use from = prev.prev)
• (e.g. instead of from = prevprev, use from = prevprevprev) You can also transfer Global Event Targets.

3.2. Basic Usage and Documentation of On Actions

While Using/Creating Vanilla & Custom On Actions, use them in following syntax below, and also don't forget to add scope info to the file in comments.

DEBCF_ACTION_<SCOPE>_<purpose> = {
    events = {	#	Event triggers gets evaluated and all the ones that can execute gets executed according to rules in [Execution Order of Events within On Actions (both Vanilla & Custom)](TODO)
        <event-id>
    }
    random_events = {	#	Based on weights and in-event 'weight_multiplier = {}' code blocks, only runs 1 event.
        <event-id>
    }
}

Execution Order of Events within On Actions (both Vanilla & Custom)

TODO

3.3. Execution Order of Vanilla On Actions while the Game is initializing for First Time

After you selected your Empire, Set-up Galaxy Generation Settings, and Clicked NEXT button, the Game starts to Generate the Game while following this sequence of Vanilla On Actions:

Step	On Action	Scopes	What It Does?	Special Notes
1	empire_init_add_technologies	scope: country (every)	Runs events that add Technologies to every empire in the Game based on Origins, Civics etc	Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet.
2	empire_init_capital_colony (was previously empire_init_capital_planet in past Stellaris Versions)	scope: colony (every, capital only) from: founder species fromfrom: secondary species (if exists)	Runs events that sets up the Capital Colonies (depending on the Country, it could be Planets, Special Megastructures, Habitats, Arkships etc) such as Creating Buildings, Districts, Pops etc	1. Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet. 2. At this point the species might have changed (because we added traits), so FROMFROM might not be the secondary species anymore. 3. Always fires on the planet with home_planet = yes, even if the country's actual capital has been moved elsewhere by an empire_init_add_technologies event.
3	empire_init_create_ships	scope: country (every)	Runs events that create Ships/Fleets to every empire in the Game	Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet.
4	on_become_advanced_empire	scope: country (every)	Setups the Advanced Empires (Including instant colonizing 2~3 colonies)	Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet.
5	on_initialize_advanced_colony	scope: colony (every) from: country (every Advanced Empire)	Setups advanced colonies, similar to empire_init_capital_colony behaviour	Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet.
6	on_game_start	scope: NOSCOPE (!NOT GLOBAL)	This is the Main On Action that does the heavy lifting of generation of Galaxy	1. Be Careful with doing stuff, many of Triggers etc doesn't work because the things to trigger from aren't created yet. 2. Scope isn't GLOBAL. It's NOSCOPE, which means while it can effect the whole game, it doesn't have any direct scope relation to any object or other scopes in the Game. This means you can only safely execute global-tier effects (e.g. set_global_flag) or need to scope other scopes (e.g. every_country) in the events. This has one specific benefit; Unlike the on_game_start_country which loops through all Countries, this On Action is only gets executed once. Which is great for Performance. Note: Events assigned to this On Action can't be scope events, create them in event = {} block.
7	on_game_start_country	scope: country (every)	This is the one that does the Heavy Lifting for Country generation	1. You no longer need to be afraid, most stuff is generated by now. 2. Because it runs for every Empire in existence, it's performance heavy. If you don't have problems with it, on_game_start or on_press_begin might be a better choice. Or optimize your Event Triggers to improve performance
8	on_press_begin	scope: country (to press begin button)	Triggers when pressing begin in the intro window	Only runs for the Country that Presses the Begin Button. Thus it only executes once. Very Performance Efficient.

Other Useful Vanilla On Actions

Step	On Action	Scopes	What It Does?	Special Notes
1	on_single_player_save_game_load	scope: NOSCOPE (!NOT GLOBAL)	Gets executed when you load a savegame as long as you aren't in Multiplayer	1. Scope isn't GLOBAL. It's NOSCOPE just like on_game_start, which means it has similar limitations and benefits. 2. Does not run when loading MP saves due to OOS concerns 3. Border related triggers/effects do not work. 4. Performance efficient, but take note that this On Action runs every time you load a savegame. Be careful with events put there to not allow Player's to repeat Powerful Events infinitely.
2	on_new_country_selected	This: Newly selected Country	Gets executed when a player selects a new country during the game	NOTE: from scope can't scope to your previous Country. You need to use other methods instead

Useful Template for Creation of new On Action Files (Delete unneeded things while using)

TODO