Event modding

From Stellaris Wiki
Jump to: navigation, search


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

Event types[edit]

There are six types of events:

  • event - event for an entire game
  • country_event - event for an entire empire
  • planet_event - event for a planet
  • fleet_event - event for a fleet
  • ship_event - event for a ship
  • pop_faction_event - event for a faction
  • pop_event - event for a population unit
  • crisis event there are only 3 and can be detailed in crisis page has an effect on an entire galaxy

Basic Behavior[edit]


By default every event has all its triggers checked against every game object at least once per game day, possibly once per game tick. For the objects where the triggers are all met, the code of the event is executed with the scope of said object.

The setting is_triggered_only = yes will excempt the event from this persistent polling.

Similarily works fire_only_once = yes. However unlike is_triggered_only the code will still be polled, only to be removed after it was executed at least once.


By default every Event will display a window and thus needs at least one option and a number of textfields to display. In order to supress that window (and the need to set all the nessesary text fields) hide_window = yes can be used.

Code execution[edit]

The primary place for code is the "immediate" section. Most events have all their code contained inside this block.

However visible events need at least one option (the OK Button of a message box). Every option can carry its own code. See Options for details.

Scope is a very important consideration for any code executed in any event and it is heavily based on how the event was called.


A additional conditon very often used on event that triggered by regular polling, is the mean_time_to_happen (MTTH). This will delay the execution of the event by a random amount of ingame days. On average the activation will be delayed as given, but the exact number can varry considerably. Counting starts the moment all other trigger conditions are met and it is not clear how exact the internal implementation of this delay works, however it seems likely the MTTH is regularily polled just like all other triggers.

  • mean_time_to_happen = { months = 5 } or mean_time_to_happen = { days = 15 }

The MTTH can be modified with any number of conditional modifiers and it seems such things can take effect after the MTTH counting has begun.

Calling events from other Events[edit]

It is possible to manually call a Event onto any game object from a running event. Doing so will put the event into the game objects scope. There might be a slight delay of at least one or more game ticks until the event is actually called. For example:

random_planet = {
    planet_event = { id = my_planet_event.1 }

While doing this the triggering can be delayed by any fixed or semi-fixed timeframe. For example country_event = { id = crisis.2000 days = 200 random = 100 } delays it by 100-300 days.


  • If the conditions are not met on the target will the event just fail (with a possible entry into the games logs for debugging) or will it keep running daily in hopes the conditions become true eventually?
  • With delay are the triggers checked on the day it is "queued up" or when "it is due time"?

Triggered Events[edit]

Aside from the default polling another very common way to get a event triggered is on_action. The vanilla game itself has a number of events registerd this way in Stellaris\common\on_actions\00_on_actions.txt

Mods can provide own on_action file whose events are called in addition the vanilla events. The file should be put into Stellaris\common\on_actions\, but the Modding Guidelines should be observed

The situations of triggering range from polling less agressive (monthly or yearly) to numerous developments of the galaxy like ending of a planetary invasion, survey, entering of a system and so forth. This is later part is comparable to registering a Event in a GUI Environment of many higher programming langauges.

Registered events should be marked with "triggered only" modifier. As easily dozens of events can be registered to any one devleopment (often belonging to the same chain) the triggers decide wich events are actually called.

A special case are random events wich have a specific chance to trigger anytime that development happens. However the triggers can make this a lot rarer then even chance might indicates.


All visible events need at least one Option (comparable to the "Ok" Button of a Message Box). Options themself have numerous variables that can be set.

The always block has to be written before the first option and as a peer of the options. It is executed after a option is choosen, regardless wich option was choosen. That makes it comparable to a finally block in many error handling systems of higher programming langauges.

name defines the display name of the option. It is the only value somewhat mandatory. Often a localiseable string is used here. There are numerous default strings that can be used here wich are already localised.

By default the game tries to build a tooltip for each option out of the code written into the option. However a (localiseable) custom_tooltip can be given. However hidden_effect should be used for the code in this case.

trigger defines if the option is shown to a player at all.

default_hide_option default_hide_option = yes will hide the option, unless it is the only option avalible.

allow defines if the option is chooseable by the player. It does not seem to affect AI players. A option can be both shown and not chooseable, often to show wich options will become avalible with specific play. This subblock is comparable to the "Enabeled" value or property in many GUI environmnets. The check is done only when the Event window is first shown and not updated with game progress.

code can be put into the body of the option. No special block must be put around it.

hidden_effect is code in a subblock that is executed normally when the option is choosen. However unlike normal code it is not used to generate the tooltip.

ai_chance generally events with choices are not given to the AI. However this subblock allows a AI to do a (semi-random) decision between avalible options. The weights can be modified by conditional modifiers (inlcuding to 0 to never picking that option). See War in Heaven events for examples.

Best Practices[edit]


Hide Window and Triggered Only are the two most common settings for events, with the bulk of vanilla events having either or even both of them. The MTTH is also a very common setting on any event that is using polling to add some randomness to the game where it seems usefull.

Due to a possible massive CPU load load regular polling should be avoided unless absolutely nessesary. The prefered way to get a series of events started initially is either via a gatekeeper event that does use regular polling with early failing triggers, or by having it triggered by a on_action development.

Chaining Events, Scope, Execution Order[edit]

The vanilla code often has long chains of events calling one another indicating that this chaining might be nessesary for proper execution and scope setting.

In particular a pattern where there is a hidden Event is calling a visible event is extremely common. The hidden event often doing actually (setup) work. This indicates that even "Immediate" code needs a least until the next event is called to take effect past any internal caching.

Example Events[edit]

Visible Events (Robot Rebellion, 1.6.2 version): # Servant AI Perfected country_event = { id = crisis.2192 title = crisis.2192.name desc = crisis.2192.desc picture = GFX_evt_robot_assembly_plant show_sound = event_laboratory_sound location = root is_triggered_only = yes immediate = { set_country_flag = robots_pacified } option = { name = crisis.2192.a custom_tooltip = crisis.2192.a.tooltip hidden_effect = { set_country_flag = ai_perfect_servants } } option = { name = crisis.2192.b hidden_effect = { country_event = { id = crisis.2000 days = 400 random = 400 } } } }

Invisible Events (Prethoryn Crissi 1.6.2 version): # WARNING: May cause galactic mass extinction and/or loss of appetite country_event = { id = crisis.199 hide_window = yes trigger = { always = no } immediate = { set_global_flag = prethoryn_invasion_happened set_global_flag = prethoryn_transmission begin_event_chain = { event_chain = "coming_storm_chain" target = ROOT } random_rim_system = { set_star_flag = swarm_invasion_target_1 save_event_target_as = prethoryn_invasion_system } create_point_of_interest = { id = coming_storm_poi.1 name = "coming_storm_poi_1_poi" desc = "coming_storm_poi_1_poi_desc" event_chain = "coming_storm_chain" location = event_target:prethoryn_invasion_system } country_event = { id = crisis.17 days = 10 } } }


Game concepts
Governance EmpireGovernment typesPoliciesEdictsLeaderFactionsPopulation
Exploration ExplorationMapSpeciesAnomalyEventsFTLFallen empirePre-FTL speciesSpaceborne aliens
Colonization ColonizationCelestial bodyEconomyBuildingsTechnologyConstructionSpaceportFleet
Diplomacy DiplomacyTradeSubject empireAlliances and federationsAI personalities
Warfare WarfareSpace warfareLand warfareOrbital bombardmentMilitary stationShip designer
Others EthosTraitsTerraformingGenetic modificationSlaveryCrisisPreset empiresEaster eggs