Effects reference

Effects are the mechanical building blocks of every option. When a player clicks a choice, effects are what actually happen — resources change, modifiers apply, research advances, follow-up events fire. This chapter is both a tutorial and a reference for the effects system.

How effects work

Most options have one or two effects. Each effect is a single, concrete gameplay change described as structured data — no raw Clausewitz code. The renderer converts your YAML effects into the scripting commands that Stellaris understands.

effects:
  - category: resource_gain
    resource: energy
    amount: 150
  - category: modifier_add
    modifier_name: curious_scientists
    modifier_description: Our scientists are energized by the discovery.
    duration_days: 360

Every effect has a category that determines what it does, plus that category's fields. The renderer picks the right game scope for each effect, so you never set one. The YAML contract lists every category and field.

Effect categories

Resource effects

resource_gain — add or subtract a flat amount of any resource.

- category: resource_gain
  resource: energy
  amount: -500

Use negative amounts for costs. The tooltip will display "Lose 500 Energy" (not "Gain -500 Energy").

Available resources: energy, minerals, food, alloys, consumer_goods, unity, influence, physics_research, society_research, engineering_research, volatile_motes, exotic_gases, rare_crystals, minor_artifacts, sr_living_metal, sr_zro, sr_dark_matter.

resource_gain_scaled — scale the amount based on the empire's current stockpile. This is the preferred approach for standard resources because flat amounts become trivial mid-game.

- category: resource_gain_scaled
  resource: energy
  percent_of_stockpile: -0.10

A 10% stockpile hit feels meaningful whether the player has 500 energy or 50,000. The mod reads the stockpile when the option is picked and takes exactly that share. Add min_amount or max_amount to clamp it; for a loss, min_amount is the larger loss (min_amount: -800, max_amount: -100).

Typical percentages:

Use flat resource_gain only for strategic resources (minor artifacts, exotic gases, volatile motes, rare crystals) where stockpiles are small and fixed amounts matter.

Research effects

research_progress — grant percentage progress toward the current tech in a research area.

- category: research_progress
  tech_area: physics
  progress: 0.05

The progress value is a fraction (0.05 = 5% of the current tech's cost). Tech areas are physics, society, and engineering.

Modifier effects

modifier_add — apply a temporary empire-wide modifier.

- category: modifier_add
  modifier_name: archive_debt
  modifier_description: Our systems strain under the archive's energy demands.
  duration_days: 720

Modifiers are the most expressive effect type. Key rules:

• Use short names like archive_debt or curious_scientists. The renderer automatically prefixes them with the release code.
• Names must match polarity. A modifier called "debt" or "burden" must have negative effects. "Inspiration" or "wisdom" must be positive. The renderer auto-detects polarity from name patterns.
• Always include a description. One or two sentences explaining the narrative reason for the modifier, not just the mechanical effect.
• Keep durations short. 360–720 days (1–2 years) is preferred. This is a flavor mod, not a gameplay overhaul.

planet_modifier_add — a timed modifier on the empire's capital planet. It needs an explicit planet stat:

- category: planet_modifier_add
  modifier_name: calm_capital
  modifier_description: The capital settles after the discovery.
  modifier_stat: planet_stability_add
  modifier_value: 5
  duration_days: 720

Diplomatic and political effects

opinion_change — every empire you have met changes its opinion of you. The change fades over about ten years.

- category: opinion_change
  opinion_name: museum_thieves
  opinion_label: Stole from the museum
  opinion: -25

ethic_shift — push the empire toward a particular ethic.

- category: ethic_shift
  ethic_key: ethic_spiritualist

ethic_key is one of the eight ethics (ethic_authoritarian, ethic_egalitarian, ethic_xenophobe, ethic_xenophile, ethic_militarist, ethic_pacifist, ethic_spiritualist, ethic_materialist) or its ethic_fanatic_ form.

Leader effects

trait_leader_add — grant a trait to a leader.

- category: trait_leader_add
  trait_key: leader_trait_spark_of_genius
  leader: ruler        # or scientist

trait_key is a Stellaris leader trait id (leader_trait_...). leader: ruler is the default and works in any event. leader: scientist gives the trait to the scientist commanding the science ship, so it only works in anomaly and dig site events. Pick a trait that suits that leader's class; Stellaris ignores traits a leader can't hold.

Event chain effects

trigger_event — fire a follow-up event, optionally with a delay.

- category: trigger_event
  event_key: mysterious_signal_followup/primary
  days_delay: 720

Follow-up events are referenced by {slug}/{role} format. The renderer converts this to the allocated Stellaris event ID at render time. Follow-up events should always carry risk — they're gambles, not free content.

create_project — a research project at the capital. When it completes, it fires an interaction from your bundle, so it works as a slower, costlier follow-up the player chooses to fund.

- category: create_project
  project_name: decode_the_placard
  project_title: Decode the Placard
  project_description: Our linguists think the placard's dates are a cipher.
  tech_area: society
  cost: 1500
  on_complete: placard_decoded/main

Other effects

spawn_anomaly — place one of your bundle's anomalies on a planet in a system the empire owns, ready for a science ship to investigate.

- category: spawn_anomaly
  anomaly: humming_rock   # slug of an anomaly event in the same bundle

add_artifacts — grant minor artifacts.

- category: add_artifacts
  amount: 2

spawn_fleet — new ships of one class join the empire at its capital, built from one of the empire's own designs. Use it sparingly: free warships are a big reward.

- category: spawn_fleet
  ship_class: corvette   # corvette, destroyer, cruiser, battleship, science, constructor
  count: 2               # 1 to 5

Magnitude by reward scope

Every event has a reward_scope that determines how large effects should be. This keeps rewards proportionate to the event's narrative weight.

Modest — small, safe nudges

Normal — standard Stellaris-scale outcomes

Extravagant — big swings with notable tradeoffs

Wild — strange, high-variance outcomes

Weirdness scaling

The event's weirdness level adjusts how far values can deviate from the ranges above:

Best practices

• One effect = one gameplay change. Don't try to cram multiple concepts into a single effect record.
• Max two effects per option. More than two overwhelms the tooltip and makes balance harder.
• Match resources to narrative. If the story says "costs energy," the effect must use energy, not research.
• Keep it parametric. No raw Clausewitz code — only structured fields. The renderer handles the translation.
• Prefer scaled resources. For standard resources (energy, minerals, alloys, unity, influence), use resource_gain_scaled so the effect feels proportionate at any game stage.

Next steps

The next chapter covers balance principles — how to calibrate effect magnitudes, compare against vanilla Stellaris values, and ensure your events feel fair without being forgettable.