Introduction to Stellaris event modding

Stellaris events are the building blocks of narrative content in the game. They're how the game presents choices to the player, delivers story beats, and creates the memorable moments that define a playthrough.

This guide teaches you how to build balanced, well-structured events — from the basic anatomy of an event file to advanced techniques like chained event sequences and balanced option design.

What you'll learn

• Chapter 1 (this chapter): The basics — what events are, how they're structured, and how Stellaris loads them
• Chapter 2: Interaction design — writing options that create meaningful choices
• Chapter 3: Effects and balance — resource costs, modifiers, and making tradeoffs feel fair
• Chapter 4: Event chains — triggers, follow-ups, and multi-part narratives

More chapters covering anomalies, dig sites, situations, testing, and advanced patterns are planned for a future release.

What is a Stellaris event?

At its core, a Stellaris event is a popup window with a title, description, a portrait or background image, and one or more options the player can click. Each option can trigger effects — resource changes, modifier applications, follow-up events, or any of the hundreds of commands in the Clausewitz scripting language.

Events are defined in plain text files using Paradox's Clausewitz syntax. They live in the events/ folder of a mod and are referenced by a namespace and numeric ID.

The YAML layer

Forge World uses YAML as an authoring format, sitting above Clausewitz. You write your events in YAML — a cleaner, more structured format — and Forge World validates and renders them into the Clausewitz .txt files that Stellaris actually loads.

This separation gives you:

• Validation before rendering — catch errors in your YAML before they become cryptic Clausewitz bugs
• Structured data — YAML's explicit fields prevent the common mistake of forgetting a closing brace three hundred lines later
• Portability — the same YAML can target different Stellaris versions as the renderer adapts

Event anatomy

Every event in Forge World's YAML format has these required fields:

slug: mysterious_signal        # unique identifier
kind: standalone               # standalone, anomaly, site, or situation
name: A mysterious signal      # human-readable name
interaction_events:            # the actual content
  - role: main
    title: The signal
    description: Your science ship has detected an unusual signal...
    options:
      - opt_key: investigate
        text: Investigate the source
      - opt_key: ignore
        text: Ignore it and move on

The kind field determines how Stellaris triggers the event:

Next steps

In the next chapter, we'll dive into interaction design — how to write options that create meaningful, balanced choices for the player.