ADAMJR: Created page with "{{DISPLAYTITLE:Event authoring}} ''New Stars'' game events — the discoveries and disasters that fire as the galaxy lives — are written as plain '''YAML files'''. The same format powers the game's own built-in events and any events you ship in a content pack, so anything the base game does, your pack can do too. This page is the full reference: where event files go, the anatomy of an event, and every condition, selector and effect you can use. For the p..."

2026-06-08T05:54:10Z

Created page with "{{DISPLAYTITLE:Event authoring}} ''New Stars'' game events — the discoveries and disasters that fire as the galaxy lives — are written as plain '''YAML files'''. The same format powers the game's own built-in events and any events you ship in a content pack, so anything the base game does, your pack can do too. This page is the full reference: where event files go, the anatomy of an event, and every condition, selector and effect you can use. For the p..."

New page

{{DISPLAYTITLE:Event authoring}}

''New Stars'' game events — the discoveries and disasters that fire as the galaxy lives — are written as plain '''YAML files'''. The same format powers the game's own built-in events and any events you ship in a [[Modding|content pack]], so anything the base game does, your pack can do too.

This page is the full reference: where event files go, the anatomy of an event, and every condition, selector and effect you can use.

For the panels that publish and toggle packs, see [[Modding]].

== Where event files go ==

Put one event per {{code|.yaml}} (or {{code|.yml}}) file in your pack's {{code|Events/}} folder:

My Pack/
Events/
meteor_shower.yaml
rogue_ai_uprising.yaml

* '''One event per file.''' The file name is up to you; the event's identity is the {{code|id}} field inside.
* Files in {{code|Events/}} '''and''' {{code|Events/Game/}} are both scanned (use the subfolder only if you like to keep things tidy).
* Enabling or disabling the pack in the '''Mod Manager''' adds or removes its events '''immediately''' — no restart.
* Unknown fields are ignored, so a pack authored against a newer version of the game still loads on an older one.

The game's built-in events live the same way, shipped inside the game and seeded into your save folder on launch; a pack can '''override''' a built-in by declaring the same {{code|id}}.

== Anatomy of an event ==

```yaml
id: mypack:meteor_shower # required — unique, namespace it to your pack
type: natural # natural | colony
roll:
scope: per_system # per_system | per_colony
once_in_years: 8 # average cadence; OR a flat `probability: 0.05`
can_instigate: "is_colonized and is_disaster_prone"
meta: system.world # the subject shown in text/UI
sfx: Game_Event_Fail # optional SFX clip name
text:
title: "Meteor Shower"
description: "A meteor shower batters {meta}."
on_instigate: # effects applied when the event fires
- op: damage_buildings
options: # the player's choices (optional)
- title: "Unfortunate."
```

{| class="wikitable"
! Field !! Required !! Meaning
|-
| {{code|id}} || '''yes''' || Unique identity, namespaced to your pack — e.g. {{code|mypack:meteor_shower}}. Built-in events use the {{code|core:}} namespace; reuse a {{code|core:}} id to override a built-in.
|-
| {{code|type}} || '''yes''' || Event category. {{code|natural}} and {{code|colony}} events are rolled each in-game month. ({{code|global}} and {{code|planet}} are reserved for future use.)
|-
| {{code|roll}} || no || How often the event is considered (see below).
|-
| {{code|can_instigate}} || no || A condition that must hold for the event to fire. Empty means "always".
|-
| {{code|meta}} || no || A selector picking the event's '''subject''' (a planet or star), shown via the {{code|{meta} }} text token.
|-
| {{code|sfx}} || no || Name of the sound clip to play (e.g. {{code|Game_Event_Normal}}, {{code|Game_Event_Fail}}, {{code|Game_Event_Success}}).
|-
| {{code|text}} || no || {{code|title}} and {{code|description}} shown on the event pop-up.
|-
| {{code|on_instigate}} || no || Effects applied on the server the moment the event fires.
|-
| {{code|options}} || no || The player's choices. If omitted, a single "Interesting." acknowledgement is shown.
|}

=== roll ===

{| class="wikitable"
! Key !! Meaning
|-
| {{code|scope}} || {{code|per_system}} or {{code|per_colony}} — documents the intent; the real gate is {{code|can_instigate}}.
|-
| {{code|once_in_years}} || The event averages once every N in-game years. Use this '''or''' {{code|probability}}.
|-
| {{code|probability}} || A flat per-roll chance, {{code|0}}–{{code|1}}. Set {{code|probability: 0}} for an event that only ever fires as a '''chain outcome''' (never on its own).
|}

== Conditions ==

{{code|can_instigate}} is a short expression. Combine atoms with {{code|and}} / {{code|or}}, and negate any atom with {{code|not}}. {{code|and}} binds tighter than {{code|or}}, so {{code|a and b or c}} means {{code|(a and b) or c}}. An empty expression is always true; an unrecognised atom is treated as false.

{| class="wikitable"
! Atom !! True when…
|-
| {{code|is_owned}} || the system has an owner
|-
| {{code|is_colonized}} || the system has a colony
|-
| {{code|world_exists}} || the system has a colonisable world
|-
| {{code|is_disaster_prone}} || the world is disaster-prone
|-
| {{code|has_star(TYPE)}} || a star of {{code|TYPE}} is present (e.g. {{code|has_star(M)}})
|-
| {{code|has_feature(FEATURE)}} || the world has a planet feature (e.g. {{code|has_feature(Dangerous_Wildlife)}})
|-
| {{code|world.climate == X}} || the world's climate '''is''' {{code|X}} (also {{code|!= X}} for "isn't")
|}

A leading {{code|system.}} or {{code|world.}} on the flag atoms is accepted and ignored.

''Example:'' {{code|"is_colonized and is_disaster_prone and world.climate != Ice"}}

== Selectors ==

A selector picks an object for {{code|meta}} or for an effect's {{code|target}}.

{| class="wikitable"
! Selector !! Resolves to
|-
| {{code|system.world}} / {{code|world}} / {{code|planet}} || the system's colonisable world
|-
| {{code|system.colony.world}} / {{code|colony}} || the colony's world
|-
| {{code|system.first_star}} || the first star in the system
|-
| {{code|system.first_star(TYPE)}} / {{code|star(TYPE)}} || the first star of {{code|TYPE}}
|-
| {{code|owner}} / {{code|explorer}} || the system's owner (a player)
|}

== Effects ==

Each entry in {{code|on_instigate}} (and in an option's {{code|effects}}) is an {{code|op}} plus its parameters. Effects run on the server, and their world changes replicate to every player. An unknown {{code|op}}, or an out-of-range value, is skipped safely — it never crashes the game.

{| class="wikitable"
! op !! Parameters !! Effect
|-
| {{code|grant_resources}} || {{code|to:}} {{code|owner}} or {{code|world}}, {{code|resources:}} || Adds resources to the owner's balance, or to a world's trade value
|-
| {{code|add_collection_value}} || {{code|target:}}, {{code|resources:}} || Adds to a planet's trade value
|-
| {{code|damage_buildings}} || — || Damages the colony's buildings
|-
| {{code|set_climate}} || {{code|target:}}, {{code|climate:}} ''or'' {{code|random_of: [ … ]}} || Sets a planet's climate (or picks one at random)
|-
| {{code|set_planet_type}} || {{code|target:}}, {{code|planet_type:}} || Sets a planet's type
|-
| {{code|set_star_type}} || {{code|target:}} (or {{code|all_stars}}), {{code|star_type:}} || Sets a star's type — or every star's, with {{code|target: all_stars}}
|-
| {{code|regenerate_trade_value}} || {{code|target:}} || Re-rolls a planet's or star's trade value
|-
| {{code|start_storm}} || {{code|storm:}}, {{code|radius:}} {{code|self}} or {{code|neighbours}} || Starts a storm in the system (optionally its neighbours too)
|-
| {{code|remove_feature}} || {{code|feature:}} || Removes a planet feature from the world
|}

If {{code|target}} is omitted, world-targeting effects act on {{code|system.world}}.

=== Resource names ===

Resource tables use these names (case-insensitive):

gold energy minerals metals food power science
antimatter pink_plasma crimson_stardust golden_spice

```yaml
resources:
minerals: 200
science: 25
crimson_stardust: 10
```

=== Value names ===

{{code|climate}}, {{code|planet_type}}, {{code|star_type}}, {{code|storm}} and {{code|feature}} take the game's own names (the same words shown in-game, with spaces written as underscores). A few common ones:

{| class="wikitable"
! Kind !! Examples
|-
| Star type || {{code|M}}, {{code|A}}, {{code|O}}, {{code|White_Dwarf}}, {{code|Neutron_Star}}, {{code|Black_Hole}}, {{code|Pulsar}}
|-
| Climate || {{code|Pristine}}, {{code|Arid}}, {{code|Ice}}, {{code|Rocky}}, {{code|Molten}}, {{code|Toxic}}, {{code|Void}}
|-
| Planet type || {{code|World}}, {{code|Barren}}, {{code|Asteroid}}
|-
| Storm || {{code|Solar_Storm}}
|-
| World features || {{code|Exotic_Planet_Life}}, {{code|Unpredictable_Weather_Patterns}}, {{code|Unique_Wildlife}}, {{code|Dangerous_Wildlife}}, {{code|Dense_Forests}}, {{code|Abandoned_Alien_Colony}}, {{code|Geothermal_Hot_Springs}}, {{code|Abundant_Natural_Wonders}}, {{code|Widespread_Volcanic_Regions}}, {{code|Extreme_Polar_Regions}}
|}

An unrecognised value makes that effect a no-op, so a typo fails quietly rather than breaking the game.

== Text tokens ==

In {{code|title}} and {{code|description}}, these tokens are replaced with highlighted in-game names:

{| class="wikitable"
! Token !! Becomes
|-
| {{code|{meta} }} || the event's subject (from the {{code|meta}} selector)
|-
| {{code|{subject} }} || the star system
|-
| {{code|{species} }} || the owner's species
|}

Anything else is shown literally.

== Options and chains ==

Options are the buttons on the event pop-up. They surface to the player exactly like built-in events, in single-player '''and''' multiplayer (events are rolled on the server and shown on every client). An option can do one of two things:

* '''Instant''' — apply {{code|effects}} the moment it's chosen.
* '''Timed branch''' — wait {{code|duration}} months, then roll one of a weighted set of follow-up events ({{code|chain}}), which may be your own events.

{| class="wikitable"
! Option field !! Meaning
|-
| {{code|title}} || Button label.
|-
| {{code|summary}} || Tooltip line. If omitted, one is derived from the option's reward effects ("Get 50 Science.").
|-
| {{code|cost}} || A resource table the player pays when choosing.
|-
| {{code|duration}} || Months to wait before the chain rolls (omit for an instant option).
|-
| {{code|effects}} || Effects applied when chosen (instant options).
|-
| {{code|chain}} || A weighted map of {{code|weight: "event id"}} outcomes.
|}

```yaml
options:
- title: "Ignore it."
duration: 2 # months
chain:
0.65: "mypack:bad_outcome"
0.35: "mypack:good_outcome"
- title: "Pay to fix it."
cost: { energy: 150 }
effects:
- op: grant_resources
to: owner
resources: { science: 50 }
```

A chain '''ends''' when it reaches an event whose options don't branch any further: that outcome's effects apply and the quest closes. Give each chain-outcome event {{code|roll: { probability: 0 } }} so it only ever fires through the chain, never on its own.

== Worked examples ==

=== A colony disaster ===

```yaml
id: mypack:reactor_meltdown
type: colony
roll:
scope: per_colony
once_in_years: 40
can_instigate: "is_colonized"
meta: system.world
sfx: Game_Event_Fail
text:
title: "Reactor Meltdown"
description: "A containment failure devastates {meta}."
on_instigate:
- op: damage_buildings
- op: set_climate
target: world
climate: Toxic
options:
- title: "Rebuild."
```

=== A reward gated on a feature ===

```yaml
id: mypack:crystal_caverns
type: colony
roll:
scope: per_colony
once_in_years: 2
can_instigate: "is_colonized and has_feature(Rare_Crystals)"
meta: system.world
text:
title: "Crystal Caverns"
description: "Surveyors find rich crystal seams under {meta}."
options:
- title: "Mine them."
effects:
- op: grant_resources
to: owner
resources: { minerals: 200 }
- title: "Study them."
effects:
- op: add_collection_value
target: world
resources: { science: 2 }
```

=== A branching disaster ===

```yaml
id: mypack:gamma_burst
type: natural
roll:
scope: per_system
once_in_years: 50
can_instigate: "is_owned and has_star(M)"
meta: system.first_star(M)
sfx: Game_Event_Fail
text:
title: "Gamma Burst Warning"
description: "{meta} is about to flare. {subject} has little time to react."
options:
- title: "Shield the colony. (costs energy)"
duration: 1
cost: { energy: 200 }
chain:
0.80: "mypack:gamma_burst_averted"
0.20: "mypack:gamma_burst_impact"
- title: "Do nothing."
duration: 1
chain:
0.50: "mypack:gamma_burst_impact"
0.50: "mypack:gamma_burst_averted"
---
# (in its own file: gamma_burst_impact.yaml)
id: mypack:gamma_burst_impact
type: natural
roll: { probability: 0 }
meta: system.world
text:
title: "Gamma Burst"
description: "The flare scorches {meta}."
on_instigate:
- op: damage_buildings
options:
- title: "Unfortunate."
```

(Reminder: keep each event in its own file — the {{code|---}} above is only to show the two together.)

== Tips and troubleshooting ==

{| class="wikitable"
! Symptom !! Cause / fix
|-
| The event never fires || Check {{code|can_instigate}} actually passes (e.g. the system is colonized), and that {{code|roll}} isn't {{code|probability: 0}} unless it's a chain outcome. Events only roll during play — give them time.
|-
| A reward or climate change does nothing || A misspelled resource, climate, star type or feature name makes that effect a no-op. Use the in-game names with underscores for spaces.
|-
| The whole event doesn't load || It needs a unique {{code|id}} and a {{code|type}} of {{code|natural}} or {{code|colony}}; otherwise it's skipped. Confirm the pack is enabled in the Mod Manager.
|-
| A chain never ends || Make sure the final outcome's options have no {{code|chain}} — that's what closes the quest.
|-
| My event clashes with a built-in || Reusing a {{code|core:}} id '''overrides''' that built-in; use your own {{code|mypack:}} namespace to add alongside instead.
|}

[[Category:Modding]]

Event authoring - Revision history