Mission framework

Every “Find this object” / “Deliver these wares” / “Defend this station” mission the player encounters in X4 is generated by a layered mission framework. The framework separates mission TEMPLATES (what to do) from mission COMPOSITION (which template to pick) from BEHAVIOR REUSE (shared phases). This overview maps the layers.

Vanilla scope:

• 37 gm_*.xml files — base mission templates
• 6 gmc_*.xml files — mission catalogues / compositions
• 67 rml_*.xml files — reusable mission library
• 7 story_*.xml files — narrative content

Three layers

┌───────────────────────────────────────────────┐
│  Layer 3: Story missions (story_*)            │
│  - Hand-authored narrative content            │
│  - Tied to specific characters, sectors       │
└────────────────┬──────────────────────────────┘
                 ↓ uses
┌───────────────────────────────────────────────┐
│  Layer 2: Generic Mission Catalogues (gmc_*)  │
│  - Compose templates into themed flows        │
│  - Examples: assisted_task, dynamic, mad_     │
│    scientist                                   │
└────────────────┬──────────────────────────────┘
                 ↓ instantiates
┌───────────────────────────────────────────────┐
│  Layer 1: Generic Missions (gm_*)             │
│  - Mission TEMPLATES                          │
│  - Examples: gm_bringitems, gm_board_ship,    │
│    gm_buildstation, gm_patrol                 │
└────────────────┬──────────────────────────────┘
                 ↓ uses
┌───────────────────────────────────────────────┐
│  Layer 0: Reusable Mission Library (rml_*)    │
│  - Shared phases / sub-objectives             │
│  - Examples: rml_find_object, rml_buildstation│
└───────────────────────────────────────────────┘

Layer 1: Generic Missions (gm_*)

The 37 gm_* files are mission templates. Each defines one “kind” of mission:

File	Mission type
gm_bringitems.xml	Deliver wares to a station
gm_board_ship.xml	Capture a ship via boarding
gm_buildstation.xml	Build a station
gm_destroy_objects.xml	Destroy components / objects
gm_find_object.xml	Find a specific object
gm_patrol.xml	Patrol a region
gm_assassinate.xml	Kill a specific NPC
gm_barterwares.xml	Trade wares between two stations
gm_ambush.xml	Ambush a passing convoy
(and 28 more)	Various mission types

Each gm_* script implements the full lifecycle: offer creation → player accept → objective setup → progress tracking → completion / failure → reward distribution.

A typical gm_* script is 1000-3000 lines. Larger ones (gm_buildstation ~5000+) handle complex multi-phase missions.

Layer 2: Generic Mission Catalogues (gmc_*)

The 6 gmc_* files are mission composers — they pick which gm_* to instantiate based on context.

File	Composition theme
gmc_assisted_task.xml	Player-assisted task missions
gmc_dynamic.xml	Dynamic encounter missions (deploy in space)
gmc_improve_station_defences.xml	Faction-requested defence upgrades
gmc_madscientist.xml	Mad scientist story content (interior dynamic interior)
gmc_retrieve_dead_drop.xml	Black-market dead drops
gmc_supervised_mining.xml	Mining supervision tasks

Catalogues are the “Where do missions come from?” layer. When the player approaches a station, the engine asks a catalogue “what mission do you have for me right now?”, and the catalogue picks a gm_* template and instantiates it with appropriate parameters.

Layer 0: Reusable Mission Library (rml_*)

The 67 rml_* files are shared phases / sub-objectives. Multiple gm_* missions reference the same rml_* for common functionality:

File	Reusable functionality
rml_find_object.xml	Find-an-object sub-objective (used by 5+ missions)
rml_buildstation.xml	Build-a-station sub-objective
rml_collect_crates.xml	Collect floating crates
rml_deploy_in_sectors.xml	Deploy satellites/probes
rml_trade_wares.xml	Trade ware exchanges
rml_destroy_components.xml	Destroy sub-components
rml_largesupply.xml	Large-scale supply runs
rml_rescue_ship.xml	Rescue stranded ships
(and 59 more)	…

The naming is parallel: gm_bringitems (top-level mission) uses rml_bringitems (the actual delivery phase). The split lets one mission compose multiple rml_* phases — e.g. find-then-deliver-then-defend uses 3 different rml_*.

Layer 3: Story content (story_*)

The 7 story_* files are hand-authored narrative content — main plot missions, DLC arcs. They use the same framework primitives but are not templated. Each story script is bespoke.

File	Story arc
story_buccaneers.xml	Pirate DLC arc
story_diplomacy_intro.xml	Diplomacy system introduction
story_paranid.xml	Paranid story
story_research_welfare_1.xml	Research welfare story
story_ventures.xml	Ventures DLC arc
(and 2 more)	DLC-specific

Mission lifecycle (gm_* pattern)

Every gm_* mission follows a similar lifecycle:

   Offer creation
   - Catalogue picks gm_*, sets parameters
   - Creates a mission offer at the offering object
            ↓
   Player accept (event_mission_accepted)
   - Mission becomes "active"
   - .hasmission = true on the cue
            ↓
   Objective setup
   - Spawn target objects / NPCs
   - Create map markers / guidance
            ↓
   Progress tracking
   - Listen for completion events
   - Update objective state
   - Voice line / UI feedback
            ↓
   Completion / failure
   - Reward distribution (LIB_Reward_Balancing)
   - Cleanup spawned content
   - Faction relation hit (if applicable)

Mission offer location

Each catalogue picks an OFFER LOCATION — typically:

• A specific NPC (faction representative, ship trader)
• A control panel (signal leak with mission type)
• A signal leak (random encounter)

The location’s .offerlocations list tracks active offers. See Cue → Properties for .offerlocations accessor.

Why this matters for modders

Adding a new mission type

If your mod needs a new mission KIND not in vanilla:

1. Write a new gm_X.xml (consider patterns from existing gm_* files)
2. Reuse rml_* for common sub-objectives
3. Either: (a) hand-add offers via your own cue, or (b) register with an existing gmc_* catalogue
4. Implement reward via LIB_Reward_Balancing for vanilla-style economy

Reusing rml_*

Most “primitive” mission objectives (find, deliver, destroy, collect) are already in rml_*. Your custom mission should call into them via <run_actions ref=> rather than reimplementing.

Mission group categorisation

Mission group lets you bucket missions by theme. Custom missions should register a mission group for analytics + UI.

Signal leaks and offer-source distinction

Many vanilla missions (gm_bringitems uses 5+ sites) check whether the offer object is a Signal leak vs a station, and apply different content per case. Custom missions should follow the same pattern.

Cross-references

• Cue (lang) — .hasmission / .missiontype / .objective accessors
• Mission group — categorisation
• Signal leak — common offer source
• Crate — find_crate_slot used in rml_collect_crates

Related architectural overviews

• Reward calculation — LIB_Reward_Balancing math
• NPC orders — missions create orders for cooperating ships
• Mission framework reward — separate concern

---

Pattern — three-tier mission architecture

Mission framework is X4’s most layered MD system — composers above templates above shared libraries above story. The layering pays off when modders extend the system: new missions reuse rml_*, new catalogues compose existing gm_*. Don’t write monolithic mission scripts when this architecture exists.