编辑“模组创作教程”（章节）

=== Events ===
==== fire_only_once ====
: ''See also: [[Event modding]], [https://github.com/OldEnt/stellaris-triggers-modifiers-effects-list List of Stellaris triggers, modifiers and effects]''

[[Events|Event]] is a script which changes state of the game by using [[effects]], provided [[triggers]] are met and event was called.

Create a new <code>\events\tutmod_events.txt</code> file.
Every events file has to have at least one namespace declared at the beginning. We use:
 namespace = tutmod

It is a good practice for any mod which affects gameplay (changes [[checksum]]) to notify its presence to other mods. The commonly accepted way is to set up a <kbd>global_flag</kbd> other mods can check if it exists via effect:
<pre>set_global_flag - Sets an arbitrarily-named global flag
set_global_flag = <key>
Supported Scopes: all</pre>
Example file would look like the following:
<pre>
namespace = tutmod
country_event = {
	id = tutmod.1
	hide_window = yes
	fire_only_once = yes
	trigger = {
		NOT = {
			has_global_flag = tutmod_installed
		}
	}
	immediate = {
		set_global_flag = tutmod_installed
	}
}</pre>
* '''<code>namespace = tutmod</code>''' – declares namespace
* '''<code>country_event = {}</code>''' – declares event of country [[scopes|scope]], it is also name of an effect used to call an event.
* '''<code>id = tutmod.1</code>''' – declares unique id of the event. Consists of namespace and number, separated by a stop.
* '''<code>hide_window = yes</code>''' – a popup window for player will not be created. This is how most events in the game work.
* '''<code>fire_only_once = yes</code>''' – successfully fired event (called and met trigger [[conditions]]) will be added to blocklist and will never be used again in current game.
* '''<code>trigger = {}</code>''' – contains list of conditions ([[triggers]]) which have to be met in order for called event to fire. Default this/root scope is defined by name of event scope (country_event here).
* '''<code>immediate = {}</code>''' – contains list of [[effects]] which change the state of the game when event fires.

This event does not contain the <code>is_triggered_only = yes</code> declaration. This means event will be checked DAILY for EVERY country. If the event was of different scope, ie. pop_event, it would check for EVERY pop in the game DAILY. With a galaxy of 5000 pops it would mean 5000 checks every day. It is a very resource intensive way of scripting and therefore you should always add <code>is_triggered_only = yes</code>, unless there is a good reason not to. <code>is_triggered_only = yes</code> blocks event from checking itself and will require it to be called from elsewhere (more on that below).

We can limit checking of the event by using the aforementioned <code>fire_only_once = yes</code>. Event still checks daily for every country, but as soon as the first country fires the event it will be blocklisted and no longer checked. Since the conditions of the event are simple (<code>NOT = { has_global_flag = tutmod_installed }</code>) event will fire as soon as game starts.

Specific trigger used in trigger section is:
<pre>has_global_flag - Checks if a Global Flag has been set
has_global_flag = <flag>
Supported Scopes: all</pre>
Immediate section is self-explanatory. It contains a single effect:
<pre>set_global_flag - Sets an arbitrarily-named global flag
set_global_flag = <key>
Supported Scopes: all</pre>

This country event is read as the following by the game:
'''Every country must check daily conditions of tutmod.1 event which are "global_flag tutmod_installed has NOT been set". If true set_global_flag = tutmod_installed, then add event to blocklist.
'''

==== is_triggered_only ====
As a general rule every event should have <code>is_triggered_only = yes</code> declared. This makes game not checking the event until it is specifically called by an effect or on_action. Below is a code for the second tutmod event (should be written in <code>\events\tutmod_events.txt</code>):
<syntaxhighlight lang="py">
# Removes military fleets, grants science ship and scientist.
# Scopes:
# Scope: root: country this: country
country_event = {
	id = tutmod.2
	hide_window = yes
	is_triggered_only = yes	# Fire only when called from elsewhere.
	trigger = {
		has_civic = tutmod_civic		# Must have tutmod_civic civic.
	}
	immediate = {
		every_owned_fleet = {
			# Iterate through every owned fleet of THIS country.
			limit = {
				is_ship_class = shipclass_military # only fleets meeting shipclass_military criteria
			}
			delete_fleet = {
				target = this				# Delete THIS fleet.
				kill_leader = no			# Do not delete leader of THIS fleet (unassigns).
			}
		}
		create_leader = {
			# Create leader for THIS country.
			class = scientist # Specified scientist class.
			species = this # Where THIS is the scope of where effect was written in (country, therefore species will be main country species).
		}
		create_fleet = {
			# Create fleet for THIS country.
			effect = {
				# Execute list of effects for THIS fleet.
				set_owner = prev # Set owner of THIS fleet to PREV (PREV/previous scope being country we in previous brackets refered to as THIS).
				create_ship = {
					# Create ship for THIS fleet.
					random_existing_design = science # of random design which is science ship.
					graphical_culture = owner # Visual style of the ship is the same as OWNER of the fleet (can use PREV here).
				}
				set_location = {
					target = owner.capital_scope.solar_system.starbase # Set location of the fleet to owner's capital_scope's solar_system's starbase.
					# distance = 0
					# angle = random
					# direction = out_system
				}
				assign_leader = last_created_leader # Assigns last created leader to the fleet.
			}
		}
	}
}
</syntaxhighlight>

Code is more readable in VSCode.

This event has only one trigger which checks if the country <code>has_civic = tutmod_civic</code>.

There are several effects in the immediate section. Most of them are self-explanatory. All of them are listed on [https://github.com/OldEnt/stellaris-triggers-modifiers-effects-list the effects list] and it is worth reviewing them.