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:
  • 2.2. File Path 2
  • 2.3. File Path 3...
• 3. From Discord (Stellaris Modding Den)
  • 3.1. TOPIC 1:
  • 3.2. TOPIC 2:
  • 3.3. TOPIC 3:
• 4. From by Github Contributors to the Project
  • 4.1. Contributor Name or Topic

---

---

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
	}
}

4. From by Github Contributors to the Project

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.

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

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	Scope	What It Does?
1	empire_init_add_technologies	country	??? TODO ???
2	empire_init_capital_planet
3	Target Scope:	Global script compilation layer
4	Persistence:	Static baseline compile register
5	Details:	Hardcoded float or integer constants evaluated globally during script loading routines to override game engine behaviors dynamically.