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 Events within On Actions (both Vanilla & Custom)
  • 3.4. Execution Order of Vanilla On Actions while the Game is initializing for First Time
  • 3.5. Various Useful Vanilla On Actions
  • 3.6. Useful Template for Creation of new On Action Files (Delete unneeded things while using)

---

---

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)'
        <event-id>
    }
    random_events = {	#	Based on weights and in-event 'weight_multiplier = {}' code blocks, only runs 1 event.
        <event-id>
    }
}

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

TODO (Also include how execution order of a fire_on_action fired in a event and the effects in both parent event & on action events works)

3.4. 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.

3.5. Various Useful Vanilla On Actions

These doesn't have an Execution Order. They only get called when an action happens or a Pulse triggers them.

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
3	Various Pulse On Actions (NOSCOPE): on_monthly_pulse on_yearly_pulse on_bi_yearly_pulse on_five_year_pulse on_decade_pulse	scope: NOSCOPE (!NOT GLOBAL)	Gets Executed repeatedly. The time between each execution is based on their Pulse type.	1. Scope isn't GLOBAL. It's NOSCOPE just like on_game_start, which means it has similar limitations and benefits. 2. Pulse On Actions aren't executed based on MTTH. They get executed again and again on exactly their Pulse Duration. 3. Most performance efficient type of Pulse On Actions. If you need to target only 1 Country, mark it with a GLOBALTARGET, and use these instead of Country scope Pulses.
4	Various Pulse On Actions (Country): on_monthly_pulse_country on_yearly_pulse_country on_bi_yearly_pulse_country on_five_year_pulse_country on_decade_pulse_country	scope: country (every)	Gets Executed repeatedly. The time between each execution is based on their Pulse type. Note: to prevent Game Freezes, Country Pulses trigger 1 Country each day instead of doing everything in one Game Day	1. Only country_types with has_pulse_events = yes will get these events. Notably, Fallen/Awakened Empires will not get these events. 2. Very Performance Costly because it runs in every Country in the game.
5	Various Pulse On Actions (Colony): on_colony_monthly_pulse on_colony_yearly_pulse on_colony_5_year_pulse on_colony_10_year_pulse	scope: colony (every)	Gets Executed for each Colony every PULSE duration (counting up from colonisation date, includes home colony)	Most Performance Costly Pulse Actions belong to this category. Use Pre-triggers extensively to reduce performance impact.
6	Various Random On Actions e.g. on_cyberization_situation_random_events_list on_colony_10_year_pulse_random_pop_events_list on_five_year_random_pulse_country_fe_list	scope: Scope of their Parent On Action	Usually gets executed by their Parent On Actions to provide additional random_events = {} blocks to Vanilla On Actions and fire multiple random events instead of just one.	1. These are fired by Vanilla Events via fire_on_action = {} to provide additional random_events = {} blocks to Vanilla On Actions and fire multiple random events instead of just one. They usually have parent On Actions. 2. They vary in Execution scopes, look for their Parent On Actions 3. You can create your own easily via fire_on_action
7	on_mid_game_pulse and on_late_game_pulse	scope: NOSCOPE (!NOT GLOBAL)	Unlike their name, these aren't pulse events. They're executed only once in entire game (when reached mid game & late game).	1. Scope isn't GLOBAL. It's NOSCOPE just like on_game_start, which means it has similar limitations and benefits. 2. Very Performance Efficient.
8	on_mid_game_pulse_country and on_late_game_pulse_country	scope: country (every)	Unlike their name, these aren't pulse events. They're executed only once in entire game (when reached mid game & late game).	Slightly less performance efficient compared to on_mid_game_pulse

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

TODO