Imported from loficore/Neo-Stellaris (AGENTS.md). Install upstream with npx skills add loficore/Neo-Stellaris. Copyright stays with the author.

AGENTS.md — Stellaris Reverse Engineering

Project Context

Reverse engineering stellaris.exe (Clausewitz engine, codename "augustus") to map the mod system's registration pipeline and identify extension points for new effects/triggers.

Binary: /mnt/drive_d/SteamLibrary/steamapps/common/Stellaris/stellaris.exe IDA session: Use ida-pro_idb_open with mode=force_headless. The .i64 database exists alongside the exe. Game data: /mnt/drive_d/SteamLibrary/steamapps/common/Stellaris/common/ — scripted_effects, scripted_triggers, on_actions, events, defines, etc.

Evidence Collection

All analysis artifacts go to evidence/ at project root:

• evidence/disasm/ — disassembly snippets, decompiled pseudocode
• evidence/strings/ — relevant string references with addresses
• evidence/xrefs/ — cross-reference maps for key functions
• evidence/external/ — findings from external sources (stellarstellaris-win, forums, docs)
• evidence/errors/ — error logs from failed operations
• evidence/analysis/ — synthesis reports, extension point analysis

Naming convention: <component>_<finding>.md (e.g., effect_dispatch_switch_cases.md)

IDA Pro MCP Workflow

# Open binary (use force_headless, never prefer_gui in this project)
ida-pro_idb_open(input_path="...stellaris.exe", mode="force_headless")

# Session ID is required for ALL subsequent calls — pass database="<session_id>"

# Survey first
ida-pro_survey_binary(database=session_id, detail_level="standard")

# Find strings
ida-pro_find_regex(database=session_id, pattern="...", limit=50)

# Trace xrefs
ida-pro_xrefs_to(addrs=["0x..."], database=session_id, limit=30)

# Decompile
ida-pro_decompile(addr="0x...", database=session_id)

# Analyze function (includes callees, strings, xrefs)
ida-pro_analyze_function(addr="0x...", database=session_id)

Gotcha: If ida-pro_idb_open fails, check if another IDA GUI instance has the file locked. Close it first.

Key Addresses (Confirmed)

Effect System

Key Global Data

Source File String References

Engine Architecture (from external research)

C++ class names (from Linux symbols, confirmed by stellarstellaris-win):

• CEffect::ExecuteActual(CEventScope*) — virtual, every effect enters here
• CTrigger::Evaluate(const CEventScope&) — virtual trigger evaluation
• CEvent::PerformImmediate — event execution pipeline
• COnActionDatabase::PerformEvent — on_action dispatch
• CToken::Init / CTextLexer::GetTok — script tokenizer/parser
• CEventScope — scope object: escopetype at +8, objectid at +12

Jomini layer: Shared library between game and engine. Implements scope types, event targets, variables, scripted effects/triggers. Registration categories: Types, Promotes, Functions, Callbacks.

Critical constraint: No public project has added a new hardcoded effect keyword. DLL hook (see stellarstellaris-win) can intercept/modify existing effects but not register new ones without deep binary patches.

External References

• stellarstellaris-win: https://github.com/MattMills/stellarstellaris-win — DLL injection + hook framework, versioned VA tables for 3.4.5–3.7.4
• rakaly/jomini: https://github.com/rakaly/jomini — Rust parser for Clausewitz text+binary saves
• CWTools: https://github.com/cwtools/cwtools — F# validator with per-game effect/trigger databases
• class101 Ghidra guide: Steam community "Enabling Achievements in Stellaris With Mods [SRE]"

Game Data Structure

The engine auto-registers script definitions by scanning common/ subdirectories:

• common/scripted_effects/ — 42 files, macro effects with $PARAM$ substitution
• common/scripted_triggers/ — 37 files, conditional logic
• common/on_actions/ — 4 files, event hooks (on_game_start, on_monthly_pulse, etc.)
• common/scripted_actions/ — 6 files, fleet/megastructure commands
• events/ — 170 event files

Script DSL features: scope chains (This/Root/Prev/From), parameterized macros, inline math @[expr], optimize_memory tag, conditional blocks [[PARAM] ... ].