Wiki menu

Data overrides: content

Mod files that change game content: buildings, units, resources, doctrines, research, laws, interest groups, goals, specialists and events.

Last updated for v0.5.26
On this page

This page was last updated for v0.5.26. The game is now on v0.5.35, so some details may have changed.

This page covers the mod files that change what is in the game: the building, unit and resource rosters, the Knowledge Network’s doctrines and a mod’s own research, laws, interest groups, national goals, specialists and events. Every file here is optional and lives outside the scenario’s country lists. Files that change rules and numbers are on Data overrides: rules and numbers; text and art are on Data overrides: interface and text.

Content rosters

Content/buildings.json, Content/units.json and Content/resources.json describe the game’s content roster. So do the files a scenario names with buildingsOverrideFile, unitsOverrideFile and resourcesOverrideFile (see Scenario header fields). Entries are matched against the base game by id, without regard to case. The Mod Builder’s Buildings, Units and Resources pages edit these files.

Each entry follows building_type.schema.json, unit_type.schema.json or resource_type.schema.json, and the file as a whole follows mod_content_envelope.schema.json; see JSON schemas. An id is lower-case letters, digits and underscores. A unit id must fit 29 bytes and a building id 61.

Roster modes

Each file picks a mode:

ModeWhat the file means
"merge" (the default, and any bare array)Change or add to the base game. Fields you write overwrite the base entry, fields you omit keep their base values, and a new id is added.
"replace"The file is the roster. Every base id it does not list is switched off.
"replace" with no entriesStart from scratch: every base entry is switched off.

A merge file that re-prices one building:

[
  { "id": "power_plant", "cost": { "money": 850, "build_time_months": 12 } }
]

A replace file for an earlier era:

{
  "mode": "replace",
  "overrides": [
    { "id": "naval_base", "name": "Shipyard", "category": "military",
      "cost": { "money": 400, "build_time_months": 6 } },
    { "id": "castle", "name": "Castle", "category": "defense",
      "cost": { "money": 900, "build_time_months": 18 }, "effects": { "defense_bonus": 25 } }
  ],
  "disabled": []
}
  • "replace": true is accepted as a shorthand for "mode": "replace". Do not combine it with a contradicting mode.
  • The entries may live under overrides (what the Mod Builder writes) or under the base config’s own root key: buildings, units or resources.
  • A building’s category is one of economic, military, infrastructure, research, social, defense, intelligence. A unit’s category is one of ground, air, naval, missile, special.

Load order. Files apply in load order: every active mod in the order described under Load order, dependencies and game version, then the active scenario’s override file. A later merge file wins on any field it sets and can bring back a base id an earlier replace file dropped. A later replace file discards everything composed before it, and the MOD LOADOUT panel warns when that happens.

Save compatibility. Ids you add are appended in roster order. Keep that order between versions of your mod. If you remove or reorder ids you added, saves made with the older version point at the wrong entries.

Disabled and inherit

disabled switches ids off in any mode, for buildings, units and resources alike. It wins over being listed.

inherit decides what an entry for an existing base id means:

  • true: overwrite only the fields you wrote (a sparse merge).
  • false: the entry is the whole definition. Fields you leave out take engine defaults instead of the base game’s values.

Entries in a replace-mode file default to inherit: false, so a medieval roster cannot silently keep modern recipes or effects. Entries in a merge-mode file default to true. New ids are always whole definitions. Nested objects (cost, effects, prerequisites) are replaced as a whole, never merged field by field, so write the full object.

When several layers touch one id, the first layer that introduces the id decides its inherit flag, and the flag sticks. A later mod or scenario layer that edits the same id and leaves inherit out keeps that flag, even when the later file is in the other mode. To change it, write inherit explicitly in the later entry; an explicit value wins.

What switched off means. Base entries are never removed from the game’s data, because saves store buildings and units by position and multiplayer compares unit positions. Instead:

  • A switched-off building is hidden from every build menu, is not placed at game start, is not chosen by the AI, and is rejected by the build command (upgrades included).
  • A switched-off unit is hidden from recruitment, rejected by the recruit commands, and removed from the base game’s starting armies.
  • A switched-off resource is not produced; see Resources.

Buildings the engine finds by id

Some features look their building up by id. Switching one off switches that feature off, so a historical roster usually keeps the id and re-skins it (name, icon, localization) instead. The MOD LOADOUT panel warns when a replace roster leaves one of these out. When you mean to drop the feature, name the id in the roster’s disabled list or the scenario’s disabledBuildingIds, and the warning goes away.

Building idUsed for
naval_baseFleet recruitment and docking
airfieldAir wing bases and starting airfields
barracks, military_baseLand unit recruitment (units name them in cost.required_building)
submarine_pen, trade_portCoastal building rules
intelligence_hq, cyber_ops_center, counterintel_bureauEspionage
satellite_launch_facilityThe base game’s satellite launch site

Units name the building they are recruited at in cost.required_building. A unit whose building is missing or switched off cannot be recruited. The load messages say so, and name the doctrine branch when that is why the building is gone.

Names and descriptions

An entry’s name and description are what the game shows for that id. A building reads display_name first, and a resource uses display_name. At load they become the localization rows the interface reads (building.<id>.name and .description, unit.<id>.name and .description, resource.<Resource>.name and .description) for every language whose Content/localization/<language>.csv does not define that key. An empty value counts as not defined.

A re-skinned base building therefore shows its new name and description, and a row in your CSV wins for its language: put translations there (see Localization). An entry whose name or description is the same as the base game’s registers nothing, so copying a base entry to re-price it keeps the base game’s translations.

Doctrine gates

A building or unit whose prerequisites.tech names a tier of a hidden doctrine branch is never offered. A branch is hidden by the scenario’s disabledDoctrineBranches, or by a replace-mode doctrines.json that leaves it out. The load messages warn for the entries your roster lists; set their prerequisites.tech to "none" or to a tier of a branch the game shows. Base-game entries your roster does not list go quietly with their branch, except the buildings the engine finds by id: for those the warning names the branch, because re-skinning the id alone keeps the base game’s gate. List such a building with its own prerequisites.tech.

prerequisites.tech must be one of:

  • "none";
  • <branch>_t<tier>: a branch id exactly as doctrines.json writes it (military, government, economy, industry, diplomacy, intelligence, cyber, space, energy, society) and a tier from 1 to 5, for example "industry_t2";
  • a key from a mod’s own research: "tech:<node or card id>", a mod branch tier such as "atlantis_t2", or a base branch tier above 5 such as "military_t6". See Mod research.

The game compares the key exactly. "None", "Industry_t2", a branch that does not exist, or a key that is not a doctrine gate can never be met, and the entry stays locked for the whole game. The load messages and Validate Mod warn about such a key on any entry your roster lists.

Flag gates

A unit or building can also wait for an event flag, so a story event can unlock it for one country, player or AI:

{ "id": "sunken_vault", "category": "military",
  "prerequisites": { "tech": "none", "flag": "atlantis_vault_found", "hidden_until_flag": true } }
  • prerequisites.flag is the name a set_flag effect writes (see Flags and variables). A country that does not hold the flag cannot recruit the unit or build the building, and cannot upgrade it. The recruit and build commands refuse it for the player, for the AI and for every multiplayer peer. The name is trimmed and matched exactly, as has_flag does.
  • prerequisites.hidden_until_flag: true hides the entry from the recruit and build lists until the flag is set. Without it the entry is listed but locked, and the player sees an unmet requirement. It does nothing without a flag.
  • The flag gate sits beside prerequisites.tech: both must be met. prerequisites is replaced as a whole, so keep the tech you want when you add a flag.
  • Only a flag that a mod event, a goal’s on_complete_flag or a script sets can open the gate. Validate Mod warns about a flag that no event of the mod sets.

Resources

Resources are a fixed set: the ids of the base game’s resources.json (Oil, Uranium, Semiconductors and the rest, matched without regard to case). A mod can re-price, re-skin or switch them off, but cannot add ones of its own. Unknown resource ids are reported.

A scenario takes modern commodities out of an earlier era with its resourcesOverrideFile, applied after every mod’s Content/resources.json:

{ "disabled": ["Oil", "NaturalGas", "Uranium", "Lithium", "Semiconductors", "Batteries", "SolarPanels"] }

A "mode": "replace" file lists the resources the scenario keeps instead, and switches off every resource it does not list.

A switched-off resource is not produced, by buildings or by province land. It is hidden from the spot market, trade-agreement proposals, the resource overview, the Economy overlay’s resource and market lists, and a building’s output and recipe choices (a recipe that needs or only makes a disabled resource is left out). The simulation enforces it for the player, the AI and multiplayer peers alike: the spot-market command refuses the resource, strategic-reserve auto-buy and auto-sell skip it, and the AI does not name it in the priority resources of a trade agreement it proposes.

Satellite launch capacity

A country may keep as many satellites in orbit (active plus queued) as the sum of the satellite_launch_capacity building effect over its completed buildings. Any building that carries the effect is a launch site. In the base game only satellite_launch_facility carries it, with a value of 3.

Give another building "effects": { "satellite_launch_capacity": N } to make it a launch site. satellite.max_per_facility in game_settings.json is only a fallback: it is read when no building in the roster carries the effect.

Retired tech tree file

Content/tech_tree.json is ignored, and so is a scenario’s techOverrideFile. Research is the Knowledge Network. To keep modern technology out of an earlier era, hide whole branches with the scenario header’s disabledDoctrineBranches. To rebuild the tree for another era, use a replace-mode doctrines.json.

Doctrines

overrides/doctrines.json changes the Knowledge Network’s doctrine tree. Its schema is doctrines.schema.json, and the Mod Builder’s Doctrines page edits it. The file has a root "mode".

"merge" (the default) patches the base tree position by position. You can change a doctrine’s numbers, effects and strings. Adding entries (branches, tiers, doctrines, hidden cards, directives) is rejected: positions are save-stable, and new ones would repoint every existing save. Nested objects merge key by key, so an effects block you write keeps every base effect you did not mention.

"replace" rebuilds whole branches.

  • Each branch the file lists, matched by id (file order does not matter), replaces the base branch outright: its tiers, doctrines, effects, icons, AI weights, milestone, directives and hidden cards are exactly what you wrote. Nothing is inherited.
  • Every base branch the file leaves out is hidden, exactly as if the scenario listed it in disabledDoctrineBranches. Its tier gates never open, so laws, buildings and units gated behind it stay locked.
  • A replacing branch needs the base branch’s 5 tiers, each with 1 to 3 doctrines with unique ids, at most 16 hidden cards and 3 directives. Effect values must be numbers.
  • settings merges sparsely, starting_grants replaces the base grants when present, and the legacy tech map is always the base game’s.
  • Names and descriptions come from your name_key and desc_key rows in the mod’s localization CSVs. Icons come from icons/doctrines/; see Icons and event pictures.
{ "mode": "replace",
  "branches": [
    { "id": "military", "name_key": "doctrine.branch.military",
      "tiers": [
        { "name_key": "mymod.military.t1", "doctrines": [
            { "id": "feudal_levies", "name_key": "mymod.feudal_levies", "desc_key": "mymod.feudal_levies.desc",
              "icon": "military_t1a_professional_armed_forces", "effects": { "recruit_cost_mult": 0.9 },
              "ai": { "military": 0.6 } },
            { "id": "mercenary_companies", "name_key": "mymod.mercenaries", "effects": { "military_attack": 0.05 } } ] }
      ] } ] }

The example shows tier 1 only; a real replacing branch lists all five tiers.

Files apply in load order. A replace file starts again from the base tree, and the MOD LOADOUT panel warns that it discarded the doctrine files loaded before it.

Flag-gated doctrine cards

requires_flag on a doctrine card locks that one card behind an event flag. It is a value, so it works in both modes. In a merge file, earlier positions are {} placeholders:

{ "branches": [ {}, { "tiers": [ {}, { "doctrines": [ {}, { "requires_flag": "my_flag" } ] } ] } ] }

A country without the flag sees the card locked and cannot start it: the research command is refused for every player and peer, and the AI does not pick it. A tier whose cards are all locked is not started by the AI.

Mod research

A mod can add research beside the Knowledge Network without touching the base branches. Two sources feed one engine, and mod research runs in its own slots, so it does not take points from doctrine research.

New branches and extra tiers

The append block of overrides/doctrines.json is read next to "mode"; both modes accept it.

{
  "append": {
    "branches": [
      { "id": "atlantis", "name": "Atlantis", "description": "...", "icon": "space_t1a_centralized_national_space_agency",
        "tiers": [
          { "name": "Foundations", "question": "Which foundation?", "cost": 400, "months": 6,
            "cards": [ { "id": "crystal_a", "name": "Crystal lattice", "effects": { "research_speed": 0.1 },
                         "ai": { "economy": 0.6 }, "requires_flag": "found_atlantis" } ] } ],
        "milestone": { "name": "Deep knowledge", "effects": { "gdp_modifier": 0.05 } } } ],
    "tiers": [ { "branch": "military", "tiers": [ { "cards": [ { "id": "mil_six", "name": "Sixth doctrine" } ] } ] } ]
  }
}
  • append.branches creates branches shown under Mod research in the Knowledge Network. A branch has 1 to 9 tiers and an optional milestone, granted once every tier has a researched card.
  • append.tiers extends a base branch (branch is its id). Tier numbers continue after 5: 6 to 9, at most four. The first extra tier needs the base branch’s tier 5.
  • A tier holds 1 to 3 cards. The country researches exactly one, as in a base tier, and tiers go in order. cost (research points) and months (minimum duration) default to the base values for the same tier number; tiers above 5 use tier 5’s.
  • A card has id and name (required), description, icon, requires_flag, effects and ai. Its effects use the same keys as a base card (see doctrines.schema.json); an unknown key is an error. The loader also reads prerequisites on a card: other cards or base gates that must be researched first.
  • Ids are 1 to 24 characters of a-z, 0-9 and _, unique across every mod card and track node.
  • Hidden pools and directives are not supported on mod branches.
  • AI countries choose among the cards they may research from the five ai axes (military, economy, stability, diplomacy, intel), the effect lanes and a national taste.

Gate keys that content can require in prerequisites.tech: tech:<card or node id>, <branch>_t<N> of a mod branch (N up to 9), and <base branch>_t6 to _t9 for appended tiers.

Research tracks

Content/research_tracks.json holds free-form nodes with prerequisites and costs. Its schema is mod_research_tracks.schema.json, and the Mod Builder’s Research tracks page edits it.

FieldDescription
settings.slotsMod research slots that run at once, 1 to 4. Default 2.
settings.points_shareThe fraction of the country’s monthly research points each mod slot receives, above 0 and at most 1. Default 0.5. Nothing is taken from doctrine research.
tracks[].id, nameRequired. The track’s id (1 to 24 characters of a-z, 0-9, _) and display name. Also description and icon.
tracks[].nodes[]Required, at least one node.
node id, name, costRequired. cost is in research points, above 0.
node monthsMinimum months to research, however many points a country has.
node prerequisitesAll of these must be researched first: node ids, tech:<id> keys or doctrine gate keys such as military_t3.
node any_ofAt least one of these must be researched, on top of prerequisites. The list needs two or more entries; put a single one under prerequisites.
node requires_flagAn event flag the country must hold.
node effectsDoctrine effect lanes, the same keys as a doctrine card.
node ai, ai_weightThe five AI axes, and an extra AI preference added to the node’s score.
node position[column, row] in the track view.
startingNodes a country already knows at the start of a new game, keyed by ISO3.

A file can hold at most 192 nodes, and a mod’s branches at most 64 tiers in all. Validation runs in Validate Mod and at load: duplicate or malformed ids, unknown effects, tier and card counts, unresolved prerequisites and prerequisite cycles. A tree that breaks a rule is dropped with a warning; the mod still loads.

Mod nodes raise the on_tech_researched script hook, and the reactive event trigger of the same name, with tech index 64 + gate index, once per completed node. Events test a mod node with has_tech and "tech:<node id>" (see Conditions). Saves store progress by node id; ids a later version of the mod does not define are dropped with a warning.

From research to a building

A research node unlocks a building through the building’s prerequisites.tech. No flag or event is needed. Content/research_tracks.json adds the node:

{ "tracks": [ { "id": "atlantis_lab", "name": "Atlantis lab", "nodes": [
  { "id": "atl_t01", "name": "Orichalcum smelting", "cost": 400, "months": 6, "ai_weight": 1.5 } ] } ] }

Content/buildings.json (a merge file, so a new id is added) gates the building on it:

[
  { "id": "atl_b01", "name": "Orichalcum foundry", "category": "economic",
    "cost": { "money": 900, "build_time_months": 8 },
    "prerequisites": { "tech": "tech:atl_t01", "infrastructure": 20 },
    "effects": { "gdp_modifier": 0.02 } }
]
  • Before the node is researched, the building is listed in the build picker as locked, with the research it requires. The build command refuses it for the player, for the AI and for every multiplayer peer, and the AI’s build planner skips it.
  • After it, the node finishes on the monthly research tick and the building opens at once for the country that researched it, and only that country. The AI builds it like any other building it may build.
  • A story beat is optional. A monthly event with a has_tech condition fires once the node is done:
{ "id": "atl_t01_done", "type": "scripted", "category": "geopolitical_crisis", "target": "player", "fire_once": true,
  "title": "Orichalcum", "description": "Our smelters can work the Atlantean metal.",
  "conditions": [ { "type": "has_tech", "value": "tech:atl_t01" } ],
  "options": [ { "text": "Build the foundries", "effects": [ { "type": "set_flag", "flag_name": "atl_orichalcum" } ] } ] }

A unit uses the same key in its own prerequisites.tech, and a building or unit can wait for a mod doctrine tier instead, for example "atlantis_t2".

Laws

overrides/laws.json is applied at runtime: it merges onto the shipped laws.json (sparse, position by position) and the laws are rebuilt when the mods load. The Mod Builder’s Laws page edits it, and its schema is laws.schema.json.

  • A mod may retune values on existing categories and options, and append new ones at the end. Appends are save-stable by design.
  • Removing, reordering or replacing existing entries is rejected, because category and option positions live in saves and in multiplayer messages. It disables the offending mod.
  • Caps: 16 categories, 6 options per category, and 4 categories with a diplo_weight above 0.
  • Every appended category needs at least one option without a doctrine gate and a complete defaults block. defaults names the starting option for each of the ten government keys: unknown, democracy, authoritarian, hybrid, monarchy, theocracy, military_junta, one_party, communist_state, transitional.
  • A category has id, name_key, change_cost, cooldown_months, diplo_weight, options and defaults. An option has id, name_key, desc_key, bloc_stance and modifiers. The modifier keys are listed in laws.schema.json.
  • Law names and descriptions come from politics.law.* keys in the mod’s Content/localization/<language>.csv files.

Switching options off

A mod can remove options that do not fit its era without touching the save-stable order:

{ "disabled_options": [ "conscription.cyber_reserve_corps", "press_freedom.platform_regulation" ] }

Each entry is category.option (the ids in laws.json), or a bare option id when only one category has it.

  • A disabled option keeps its position but is hidden in the Laws tab, skipped by the AI, and refused by the law commands for every player and multiplayer peer.
  • A country that has it active falls back to its category default when a game loads, and a pending debate for it is dropped.
  • Lists from several mods are combined.
  • An entry is ignored, with a warning, when it names nothing, is ambiguous, is the default option of a government type (change that default first), or would leave its category with no enabled option.
  • A starting-law override in country_overrides that names a disabled option falls back to the usual seeding.

Options gated by a doctrine branch the game hides can never be unlocked, so the Laws tab does not list them. You do not need to disable them.

Interest groups

overrides/interest_groups.json changes the electorate: age-band leans, interest-group affinities, drivers and demand multipliers, law and doctrine bonuses, religiosity and country overrides. It is applied at runtime and rebuilt when the mods load. It is a sparse patch against interest_groups.schema.json, and the Mod Builder’s Interest groups page edits it.

{ "age_bands": [ { "id": "senior", "lean": { "nationalist_conservative": 0.4 } } ] }
  • age_bands and groups entries are matched by id and merge key by key, so the example changes one number. The band ids are youth, young, middle, senior. The group ids are workers, entrepreneurs, military, religious, environmentalists.
  • The model has exactly these four bands and five groups. An entry with any other id is rejected with a message naming it, and the mod is disabled. Bands and groups cannot be added, removed, reordered or renamed.
  • A band’s lean and a group’s bloc_affinity have four keys, each from -1 to 1: liberal_capitalist, socialist_communist, nationalist_conservative, authoritarian_theocratic.
  • law_bonuses (matched by category + option + group, with a bonus from -0.5 to 0.5) and doctrine_bonuses (matched by branch + group, with a per_tier from -0.1 to 0.1) update the matching entry or append one.
  • country_overrides, religiosity_by_religion and neutrality_reference_shares merge key by key. gdp_factor_thresholds replaces the list. A country override has shares, an optional religiosity and a mode of fixed or delta.

The merged document must pass the same rules as the shipped file:

  • bands and groups in order; turnout above 0 and at most 1; leans and affinities from -1 to 1;
  • law options, doctrine branches, resource categories and resources must exist;
  • fixed country overrides list every group and sum to 1;
  • demand multipliers stay neutral: weighted by the world age mix for bands, or by neutrality_reference_shares for groups, every resource averages 1 within 10%.

A mod that breaks a rule is disabled on its own, and the RELOAD & TEST message names the problem. Validate Mod reports the same findings as errors. The file is part of the lobby’s mod check, so two players with different electorate files do not match. Nothing is written to a save: the config is rebuilt from the loaded mods each session.

National goals

A scenario can bring its own national goals: the Agenda’s goals, and the goals AI countries pursue. The file is named by the scenario header’s nationalGoalsFile, relative to the scenario folder. Its schema is national_goals.schema.json, and the Mod Builder’s Goals page edits it.

By default the file replaces the base game’s goals entirely: countries it does not list have no agenda, and a file without _BASIC has no starter goals. Put "mode": "merge" at the root to keep the base game’s goals and append yours instead, per country and in the shared _BASIC set. A goal id may not repeat one of the base game’s, or the file is rejected.

The file uses the shape of the base game’s national_goals_2026.json:

{
  "_BASIC": { "goals": [
    { "id": "basic_secure_the_realm", "title_key": "mymod.goal.secure_realm",
      "description_key": "mymod.goal.secure_realm.desc", "type": "defense", "priority": "starter",
      "tasks": [ { "id": "war_chest", "title_key": "mymod.task.war_chest",
                   "condition": { "type": "treasury_above", "params": { "min_value": "5000" } } } ] } ] },
  "OTT": { "goals": [
    { "id": "ott_heir_of_rome", "title": "Heir of Rome", "title_key": "mymod.goal.heir_of_rome",
      "description_key": "mymod.goal.heir_of_rome.desc", "type": "territorial", "priority": "primary",
      "ai_weight": 0.9, "target_countries": ["BYZ"],
      "on_complete_effects": { "prestige": 50, "stability": 5 },
      "tasks": [ { "id": "war_on_byzantium", "title_key": "mymod.task.war_on_byzantium",
                   "condition": { "type": "declare_war_on", "params": { "target_iso3": "BYZ" } } } ] } ] }
}

Goal fields

FieldDescription
Root keys_BASIC (starter goals every country sees) or a country’s upper-case code. Other keys that start with _ are ignored as notes. "mode" is "replace" (default) or "merge". A country holds at most 25 goals.
idRequired, unique across the file. The player’s active goal is saved by id. The schema expects basic_ or a three-letter lower-case country prefix, then lower-case letters, digits and underscores. Starter goals appear in the planner’s starter list only when their id starts with basic_.
title_key, description_keyLooked up in the mod’s localization CSVs. title and description are the fallback text. The AI’s copy of the goal uses title, or the key.
typeexpansion, territorial, economic, unification, defense, prestige, diplomatic, ideological (the AI understands these), plus technology and intelligence for the Agenda’s task templates. An unknown value is reported and read as economic.
prioritystarter, primary, secondary, aspirational. An unknown value is reported and read as secondary.
ai_weight0 to 1, default 0.5: how strongly AI countries pursue the goal.
target_countriesISO3 codes the goal is aimed at, for AI countries that pursue it.
agenda_panel_id, agenda_subjectOptional hints for the Agenda’s generated tasks: a panel route such as quickrecruit:air, quickbuild or diplomacy, and the subject text shown in the task copy.
on_complete_effectsPaid once when the goal is completed, to the player and to AI countries alike: prestige (a fading prestige bonus), stability (added, kept within 0 to 100), aggression_modifier and military_modifier (added to the country’s AI personality). economy_boost is read and shown, but no system applies it.
on_complete_flagAn event flag set on the country when the goal completes, player and AI. has_flag conditions, other goals’ has_flag tasks, and the flag gates of units, buildings and doctrine cards can test it.
on_complete_eventAn event id queued for the player’s country at the same moment, the way a script’s fire_event queues it: its conditions and cooldowns are not checked. AI countries do not fire it.
tasksThe player’s steps, 1 to 6 per goal. A goal without tasks gets a template from its type.

For the player, the completion payment is a command that every multiplayer peer runs from its own goals table, and the completion is saved, so reloading neither repays nor forgets it. The Agenda shows the same numbers as the reward.

Task conditions

Each task has an id, a title (title_key or title), an optional description, panel_id and required_count, and a condition with a type and params. Parameter values are written as strings.

condition.typeparams
own_provincesprovince_owner: counts owned provinces whose base-map country is this code.
alliance_withtarget_iso3 (one country) or partners: a comma-separated ISO3 list such as "ISR,SAU,ARE", or "*" for any country. Progress is the number of distinct listed countries that hold a bilateral alliance or a defence pact treaty with the owner. Collective-defence memberships such as NATO do not count.
declare_war_on, espionage_on, embassy_with, trade_agreement_with, defensive_pact_with, guarantee_independencetarget_iso3.
sphere_membertarget_iso3 or partners (one ISO3 or a comma-separated list; absent means any member) and/or region, a world region name such as SoutheastAsia. A member must match both when both are given. Progress is the number of matching members of the owner’s sphere of influence.
improve_relationstarget_iso3 (optional), min_value (default 50).
build_in_provincesprovince_owner (optional).
built_since_startbuilding_id: a building id or a comma-separated list; absent counts any building. Progress is the number of buildings the country has completed during the game.
recruit_units, military_units_aboveunit_type: tanks, aircraft, ships, submarines, helicopters, apcs, artillery, personnel (or active_personnel). The count is the progress. military_units_above also takes min_value, the count to reach, used when required_count is absent.
research_techNone. The number of completed doctrine tiers is the progress.
treasury_above, gdp_abovemin_value, in the base money unit.
country_statstat: growth_pct (annual GDP growth, in percent), unemployment_pct, stability or corruption (0 to 100 points); and min_value and/or max_value. Met while the figure lies inside the bounds. An unknown stat, or no bound at all, is never met.
tutorial_objectiveobjective_id.
has_flag, not_has_flagflag_name: met while the country holds (or does not hold) that saved event flag, written by a mod event’s set_flag effect or another goal’s on_complete_flag.

required_count (default 1) is the progress a counting task needs, for example 10 for “own 10 provinces” or 5000 for “5,000 personnel”. Yes-or-no conditions report 1 when met. Unknown condition types never progress.

The AI ignores tasks, with one exception: it does not complete a goal while one of its has_flag or not_has_flag tasks fails.

A file is rejected, and the base goals stay, when it is not an object, uses a key that is not a country code, has a mode other than merge or replace, or has a goal without an id or with a repeated id (in merge mode, one that repeats a base-game goal). The load messages say why. The goals file is part of the multiplayer lobby check. Validate Mod also warns about a has_flag task whose flag nothing in the mod sets.

Goal prerequisites and the goal graph

A goal may list other goals it depends on:

{ "id": "tur_modern_navy", "prerequisites": ["tur_shipyards"], "mutually_exclusive": ["tur_land_power"], "editor_position": [3, 1] }
  • prerequisites: goal ids of the same country (or the shared _BASIC goals) that must all be completed first. Until they are, the Agenda shows what the goal requires, it cannot be set active, its tasks do not complete it, and the simulation refuses its completion, for a multiplayer peer too. AI countries make no progress on such a goal.
  • mutually_exclusive: goal ids whose completion makes this goal unavailable. The relation is made symmetric when the file loads.
  • editor_position: [column, row] in the Mod Builder’s goal graph. The game ignores it.
  • incompatible_with is informational only.
  • At load, unknown ids, a goal naming itself, ids of another country, entries that would close a cycle, and an id that is both prerequisite and exclusion are dropped and listed in the mod warnings. Validate Mod reports them as errors.

Specialists

Content/specialists.json defines named scientists and engineers a country can employ. The base game has none; every one comes from a mod. Its schema is mod_specialists.schema.json, and the Mod Builder’s Specialists page edits it.

{
  "mode": "merge",
  "settings": { "max_assigned": 2 },
  "specialists": [
    { "id": "dr_vega", "name": "Dr Vega", "description": "...", "role": "scientist",
      "portrait": "portraits/specialists/dr_vega.png", "country": "ATL", "available_from": 1990,
      "hire_cost": 5000000, "upkeep_monthly": 250000, "requires_flag": "found_lab", "ai_weight": 0.4,
      "effects": { "research_speed": 0.05, "construction_speed_mult": 1.1 } } ]
}
FieldDescription
modemerge (default) adds to the roster other mods define; an id an earlier mod already defines keeps that definition. replace discards the roster of the mods loaded before.
settings.max_assignedHow many specialists one country employs at once, 1 to 8. Default 2.
id, nameRequired. The id is 1 to 24 characters of a-z, 0-9 and _.
descriptionText shown for the specialist.
rolescientist, engineer or other. Display only.
portraitA PNG path relative to the mod folder, by convention portraits/specialists/<id>.png. It must stay inside the mod folder. Without one a placeholder is shown.
countryISO3 of the country that employs the specialist at the start of a new game. Empty means anyone can hire.
available_fromThe first year the specialist can be hired, 0 to 3000. 0 means from the start.
hire_costOne-off cost, paid from the treasury.
upkeep_monthlyMonthly cost while the specialist is employed.
requires_flagAn event flag a country must hold before it can hire the specialist.
ai_weightExtra preference the AI gives this specialist when it chooses whom to hire.
effectsOnly research_speed, construction_speed_mult, unit_build_speed_mult and production_output_mult, with the same meaning as the doctrine effects of those names. They apply from the next monthly update after a hire or dismissal.
  • A specialist works for one country at a time. The roster holds at most 128 specialists.
  • AI countries hire the best specialist they can afford once a month.
  • Events reward and test specialists with the effects grant_specialist and remove_specialist and the condition has_specialist; see Effects and Conditions.
{ "type": "grant_specialist", "specialist": "dr_vega" }
{ "type": "has_specialist", "specialist": "dr_vega" }

Events

Every *.json file in Content/events/ can hold any number of events, in any of three shapes:

[ { "id": "my_event_a" }, { "id": "my_event_b" } ]
{ "id": "my_event_a" }
{ "events": [ { "id": "my_event_a" }, { "id": "my_event_b" } ] }

The third form is what the Mod Builder’s Events page writes. Files load in file-name order, mods in load order, and events in the order they appear in a file. Each event follows event.schema.json; see JSON schemas.

Engine events and legacy events

An object with a type field (scripted, procedural or reactive) is an engine event. At game start it is appended to the base game’s event table and runs through the same engine as the built-in events: monthly evaluation, conditions, the popup, AI choices, effects, chains and saves.

An object without type is a legacy event. It only appears when a script fires it, shows a popup whose buttons close it, and does not fire on its own. Its title, description and option text may each be a localization key, shown in the player’s language (see Script popups). Add type when you want the engine to run the event.

The effects decide too. An object that has type but writes any option effect as a string ("effects": ["stability:0.10"]) loads as a legacy event, with a warning. Write effects as objects ({ "type": "modify_stat" } with its fields) to run the event in the engine.

Event ids

  • Use lower-case ids (a-z, 0-9, _), prefixed with your mod, for example atlas_01.
  • An engine event whose id matches a base-game event, or an event that another mod loaded first, is skipped. It does not replace the other event. Use an id of your own to add an event.
  • Saves store events by id, so renaming an event breaks it in existing saves.
  • Event ids are case-sensitive.

Event fields

FieldDefaultDescription
idnoneRequired.
typenonescripted, procedural or reactive. Required for an engine event.
categorynonegeopolitical_crisis, economic_shock, military_incident, diplomatic_opportunity, technology_breakthrough, natural_disaster, internal_politics or social_cultural.
targetnoneWho can get the event: player, any_country, specific_country, all, global or every_country (described below). The schema also lists random_matching.
target_countrynoneISO3. Required for a specific_country event.
title, descriptionnonePlain text, used when no key is given or found.
title_key, description_keynoneLocalization keys, looked up in your Content/localization/<language>.csv.
imagenoneThe popup’s picture, by file name without extension (see below).
priority51 to 10.
mean_time_to_happen_months12Sets the chance per roll, 1 - e^(-1/MTTH).
immediatefalseNo random roll (see below).
fire_oncefalseThe event fires at most once per country.
cooldown_months0A cooldown for this event alone.
pause_gameby categoryWhether the popup pauses the game when it opens.
conditionsnoneSee Conditions.
triggersnoneFor reactive events; see Reactive triggers.
optionsnoneRequired, 1 to 6.
chain_event, chain_delay_monthsnone, 0An event-level chain; see Chains.

Each option has:

FieldDefaultDescription
text, text_keynoneThe button text, and its localization key.
tooltip, tooltip_keynoneThe hover text, and its localization key.
ai_weight1.0Base AI preference for the option, before personality.
ai_personality_factorsnoneMultipliers per AI personality trait: military_investment, economic_priority, diplomacy_focus, tech_investment, alliance_loyalty, isolationism, nuclear_threshold.
conditionsnoneConditions for the option to be available.
hide_when_unavailablefalseHide the option while its conditions fail, instead of showing it greyed out.
effectsnoneRequired. See Effects.

On conditions and effects, flag is the same as flag_name, and target is the same as target_country. ISO3 codes are upper-cased.

immediate: true. The event fires at the first monthly evaluation where all its conditions pass. It ignores the 60-day cooldown left by an earlier event and beats ordinary events in that evaluation. If several immediate events are eligible, the highest priority fires first; on a tie, the one loaded first. It waits while the country has an unanswered event, and it respects its own cooldown_months, fire_once and target. An immediate event that can repeat (no fire_once) and has no cooldown_months waits 60 days after each of its own firings, and while its conditions hold it beats ordinary events every time: give it fire_once, cooldown_months or a condition that stops passing. mean_time_to_happen_months: 0 without immediate works the same way, with a load note.

pause_game. true always pauses and false never does. When it is absent, the game pauses for geopolitical_crisis, military_incident, natural_disaster and internal_politics events and not for the other four categories. The player’s Pause on Event Popup setting turns pausing off for every event.

target.

  • player: only human-controlled countries can get the event. AI countries do not roll it. In multiplayer, every human player can get it.
  • global: a world-scoped event. It is rolled once per check for a single country (the first human player by ISO3, otherwise the first live country by ISO3), so it fires once, not once per country, and its conditions are tested on that country.
  • every_country: every country whose conditions pass gets the event at the first monthly evaluation where they hold, all in the same evaluation. There is no random roll and no 60-day wait, and the mean_time_to_happen_months you write is ignored. A country with an unanswered event gets this one queued behind it, up to max_active_events_per_country (3 in the base game); a country that is full is tried again next month. An AI country answers in the same evaluation; a human sees the popup. The event respects fire_once and cooldown_months. A repeatable one waits at least repeatable_immediate_min_cooldown_days between its own firings. Countries are judged in ISO3 order on every player’s game. Eliminated countries are skipped.
  • all behaves like any_country.

image. The game looks in the active mods’ images/events/ and then Content/images/events/ folders first (.png, .jpg or .jpeg; .png wins when one name has both; when several active mods ship a name, the mod that loads last wins), then in the base game’s pictures, for example event_airstrike. The name is not a path: a name with /, \, : or .. matches nothing. The popup shows the picture as a wide band, scaled to fill its width and cropped around the centre, so a wide picture shows almost whole. With no image, or a name that matches nothing, the popup shows the category’s default picture. See Icons and event pictures.

change_government accepts a government name as its value: democracy, authoritarian, hybrid, monarchy, theocracy, military_junta, one_party, communist_state or transitional.

When events fire

  • Monthly check. Events are evaluated once per in-game month, on day 6 to 8, for every country. A game or scenario that starts after that day gets its first check on the first day it runs.
  • AI countries are staggered. AI countries are split into 5 groups, and one group rolls scripted and procedural events each month. A human country rolls every month at 5 times the MTTH, so over those 5 months its chance per event is the same as the AI’s. target: "player" and specific_country events are the exception: humans roll them every month at the MTTH you wrote. An immediate event for an AI country therefore arrives within about 6 months after its conditions pass, not on the first day.
  • One event at a time. A country with an unanswered event gets no other scripted or procedural event that month. This applies to immediate events too: they fire at the next evaluation after the answer.
  • Cooldown. After a scripted or procedural event fires, that country gets no other scripted or procedural event for 60 days (generated_post_event_cooldown_days). After a reactive event the wait is 3 days (reactive_post_event_cooldown_days). cooldown_months adds a cooldown for one event. A repeatable immediate event with no cooldown_months waits at least repeatable_immediate_min_cooldown_days (60 in the base game) after its own firing. A mod can raise these in the events section of overrides/game_settings.json; see Game settings.
  • Ties. When several events are eligible in the same month, one is picked at random, weighted by priority. An eligible immediate event skips the draw and fires instead.
  • Reactive events fire from their triggers. A reactive event without triggers does not fire on its own; it fires only as a chain target or from a script.
  • Choices. AI countries choose an option automatically, from ai_weight and the personality factors. The player sees a popup. If the player does not answer, the game picks an option after 30 days (player_event_auto_decide_days).
  • Notification setting. Players can hide less important popups. Use one of the four pausing categories (geopolitical_crisis, military_incident, natural_disaster, internal_politics) for story events the player must see.

Reactive triggers

A reactive event lists one or more triggers. The game raises all thirteen types itself, for the player and the AI alike, and a mod script can raise any of them with the fire_trigger call.

TriggerRaised whenThe event goes to (source_country)target_country
on_war_declaredA country declares warThe country that declaredThe defender
on_peace_signedA peace deal is signedThe country that proposed itThe other party
on_alliance_formedTwo countries form an allianceThe country that proposed itThe partner
on_alliance_brokenAn alliance ends: broken, or the ally is attacked, or a call to arms is dishonouredThe country that broke itThe former ally
on_sanction_appliedA country imposes sanctionsThe country that imposed themThe sanctioned country
on_tech_researchedA country completes a doctrine tier, or a mod research nodeThat countryNone
on_country_collapseA country is eliminated (its last province is lost)The fallen countryNone
on_building_completedA building finishes constructionThe country that owns the provinceNone
on_coup, on_revolution, on_leader_deathThe government changes that way, or the leader diesThat countryNone
on_nuke_launchedA country launches a nuclear strikeThe launching countryNone
on_espionage_resolvedAn espionage mission reaches an outcome: success, failure or caughtThe country that ran the missionThe country it was run against
  • Recipient. The event is queued for the source country only. To react from the other side (the defender of a war), write a second reactive event with target_country set the other way round and a condition that only the other side meets.
  • Filters. A trigger’s source_country and target_country (ISO3) narrow it to those countries. Leave them out to match any.
  • Timing. The game collects triggers all month, and the reactive events fire at the next monthly event evaluation, after the usual checks: an unanswered event, a running cooldown_months, a fire_once event the country already had, or the 3-day reactive wait all hold the event back, and the trigger is not kept.
  • Cost. A trigger is raised only while some loaded event lists it.
  • A fallen country (on_country_collapse) exists but owns no land, so keep that event’s effects to things that do not need territory: flags, variables, relations.
  • Mod scripts can listen to the same moments through script hooks. The two do not depend on each other.

Chains

A chain is an event-level chain_event (with chain_delay_months), or a fire_event effect on one option with chain_event and delay_months. The effect form queues the follow-up only when the player or AI picks that option.

  • Delay. 0 or no value uses the default, chain_event_delay_months (1 month in the base game). The maximum is 600 months; a longer delay is cut to 600, with a note. A month is 30 days.
  • Recipient. If the chained event is specific_country, it goes to that country. Otherwise it goes to the country that made the choice.
  • Conditions. The chained event’s own conditions are checked on the recipient when the chain comes due and the recipient can take it, not when it was queued. If they fail, the chain is dropped.
  • Fire once. A chained fire_once event that the recipient has already had is dropped. A chained target: "player" event is dropped if the recipient is an AI country.
  • Busy recipient. If the recipient has an unanswered event, the chain waits. As soon as the queue is free, its conditions are checked and it fires.
  • No cooldown. A chain ignores the 60-day cooldown, but it starts one when it fires.
  • Lookup order. chain_event looks for your mod’s events first, then the base game’s. An id that matches neither is reported and the chain is dropped.

Conditions

Conditions test the country that would get the event, unless a row says otherwise.

ConditionFields and meaning
date_aftervalue: "YYYY-MM" (a day part is ignored). Counts by month and includes the month itself: "2026-06" passes from June 2026.
date_beforevalue: "YYYY-MM". Excludes the month itself.
country_stat_gt, country_stat_ltfield and a numeric value. The fields that work are listed under the table.
at_war, not_at_warOptional target_country: at war with that country.
has_nuclearThe country has nuclear warheads.
has_flag, not_has_flagflag_name. See Flags and variables.
flag_age_months_gt, flag_age_months_ltflag_name and value (whole months, 0 to 1200). True when the flag was set more, or fewer, than that many whole months ago. Not true while the country lacks the flag.
variable_gt, variable_lt, variable_eqvariable and value (a whole number). Optional scope. A variable that was never set reads 0.
espionage_activeThe country has an espionage mission running. Optional mission_type and target_country. See Covert operations.
mission_caught_recentlymonths (1 to 1200): one of the country’s missions was caught within that many months. Optional target_country.
lifetime_gt, lifetime_ltcounter and value (0 to 2,000,000,000). See Lifetime counters.
government_typevalue: the same names as change_government.
continent, not_continentvalue: africa, americas, asia, europe, oceania, antarctica.
region, not_regionvalue: northern_africa, sub_saharan_africa, latin_america_caribbean, northern_america, central_asia, east_asia, south_asia, southeast_asia, western_asia, eastern_europe, northern_europe, southern_europe, western_europe, australia_new_zealand, melanesia, micronesia, polynesia.
country_unrest_gt, country_unrest_ltvalue: average national unrest, 0 to 100.
owns_province, not_owns_provincevalue: a province id. True when the country is the province’s legal owner. Optional target_country. See Province conditions.
controls_province, not_controls_provincevalue: a province id. True when the country controls the province. Optional target_country.
alliance_membertarget_country: the country is allied with that country. Without one it does not pass.
relation_above, relation_gt, relation_below, relation_lttarget_country and value (-100 to 100): the country’s relation toward that country is above, or below, the value.
stakeholdertarget_country (required) and value: the country is that country, is at war with it, is allied with it, or has a relation toward it whose size is at least value. Several stakeholder conditions on one event are OR-ed, then AND-ed with the rest.
has_techvalue: a doctrine tier, "<branch>_t<tier>" with a tier from 1 to 5, for example "cyber_t2"; or a mod research key: "tech:<node id>", a mod branch tier, or a base branch tier above 5. A key no loaded content defines gets a warning at load and does not pass.
has_specialistspecialist: a specialist id. True when the country employs it.
wave_eliminatedwave_id: a wave of the same mod has no stack left. See Invasion waves.
wave_remaining_gt, wave_remaining_ltwave_id, value and optional measure (units, the default, or stacks). A wave that was never spawned fails both.
armies_in_province_gt, armies_in_province_ltprovince_id, value, optional owner_country and measure (stacks, the default, or units): the armies standing in that province.
province_stat_gtfield: province.population, province.infrastructure, province.unrest, province.dev_level or province.radiation; value: a number. True when at least one province the country legally owns has that stat above the value.
in_organization, not_in_organizationid: an organization’s id: a mod’s own organization, a built-in one such as NATO, or an institution.
institution_seatorgan: a council as institution.organ, for example "un.unsc"; optional seat: any (default), permanent or elected.
institution_item_opendecision: institution.organ.decision, for example "un.ga.condemnation". True while such an item is being drafted or voted on. Optional target_country, subject: "self" or sponsor: "self".
institution_measure_in_forceOptional institution (an institution id, or any, the default), plus target_country or subject: "self". True while such a trade measure is in force.
in_trade_arrangementOptional arrangement: a trade arrangement’s key, or any (the default). True when the country is a member.
world_ceasefire_activeNo fields. True while a world ceasefire holds.
defcon_levelvalue: 0 to 5. True when the country’s DEFCON is at the value or more severe (5 is peace, 0 is nuclear exchange).
active_law_isNot available in mod events: it is rejected.

has_tech, has_specialist, province_stat_gt, defcon_level, the flag-age, variable and lifetime conditions, in_organization, not_in_organization, institution_seat and world_ceasefire_active always check the country that gets the event. A target_country on them is rejected.

Stat fields that country_stat_gt and country_stat_lt read: economy.gdp, economy.gdp_per_capita, economy.gdp_growth_rate, economy.inflation_rate, economy.debt_to_gdp, economy.unemployment, economy.hdi, government.stability, government.corruption, government.economic_stance, government.social_stance, military.manpower, military.reserve, military.defense_budget, military.tanks, military.aircraft, military.ships, military.nuclear_warheads, budget.tax_rate, budget.treasury, budget.military_pct, budget.research_pct.

Lifetime counters

Every country keeps nine counters for the whole game, with or without mods. They are saved with the game and readable from events (lifetime_gt, lifetime_lt) and from scripts (country_lifetime, IModServices.GetLifetime). Their ids, used by scripts, are the order below.

IdcounterCounts
0personnel_lostSoldiers killed in ground combat, missile and air strikes and nuclear blasts.
1regiments_lostRegiments destroyed.
2ships_lostShips sunk.
3aircraft_lostAircraft shot down or destroyed.
4civilians_affectedCivilians affected on the country’s own soil.
5provinces_gainedProvinces that changed owner to this country by treaty.
6provinces_lostProvinces that changed owner away from this country by treaty.
7wars_wonWars that ended with this country clearly ahead.
8wars_lostWars that ended with this country clearly behind.

The counters add up over the whole campaign, and peace does not reset them.

Flags and variables

Flags are on/off marks on a country. Variables are whole numbers kept on each country. Both live until a mod clears or overwrites them, and both are saved with the game and synced in multiplayer.

{ "type": "set_variable", "variable": "mymod_tension", "value": 0 }
{ "type": "change_variable", "variable": "mymod_tension", "value": 2 }
{ "type": "variable_gt", "variable": "mymod_tension", "value": 5 }
{ "type": "flag_age_months_gt", "flag_name": "mymod_referendum", "value": 18 }
  • set_variable makes the variable equal value. change_variable adds value to it (negative to subtract). A variable that was never set counts as 0. Values are whole numbers between -1,000,000,000 and 1,000,000,000.
  • Reading. variable_gt, variable_lt and variable_eq compare the variable with value.
  • Flag age. flag_age_months_gt and flag_age_months_lt compare how long ago the flag was set. set_flag on a flag the country already has changes nothing, so the age keeps counting from the first time; clear_flag then set_flag restarts it.
  • The limit. A country keeps at most events.max_flags_per_country flags (64 in the base game) and, separately, the same number of variables. A flag or variable past the limit is dropped, with a line in Player.log. Changing a variable that already exists always works.
  • Scope. A variable normally lives on a country. Add "scope": "mod" to set_variable, change_variable and the variable conditions, and it is one number for your whole mod instead: shared by every country, saved with the game, and the same store your scripts read and write (state_get, state_set, state_add). Another mod’s key of the same name is separate. Omit scope, or write "country", for the country’s own variable.
  • Names. Start them with your mod’s id (mymod_tension) so two mods do not share one. Flags and variables are separate: a flag and a variable may share a name.
  • In the event popup. An option’s expected impact lists these effects in plain words. To show names instead, add an event.flag.<flag_name> key (for a variable, event.variable.<variable>) to your language files. The id itself is not shown.
  • Hiding bookkeeping. Add "hidden": true to a set_flag, clear_flag, set_variable or change_variable effect to leave it out of the popup’s expected impact. The effect runs all the same. On any other effect hidden is ignored, with a warning when the mod loads.

Scripts set flags with the country_set_flag import and its companions; see Permissions.

Province conditions

owns_province, not_owns_province, controls_province and not_controls_province let an event fire when a province changes hands. value is the province id (see Province ids).

{ "type": "controls_province", "value": 2276, "target_country": "OTT" }
  • Owns means the legal owner. It changes only when the province is transferred, for example by a peace deal. Taking the province with an army does not change the owner.
  • Controls means the occupier if the province is occupied, otherwise the owner. It changes as soon as an army captures the province.
  • Subject. Without target_country the condition tests the country that would get the event. With it, the condition tests the named country instead, so the example above is true for every country once OTT controls province 2276. Add { "type": "not_controls_province", "value": 2276 } to leave out the controller itself.
  • A target_country that does not exist owns and controls nothing, and so does any country for an unknown province id. The not_ variants are then true.
  • Timing. Conditions are checked at the monthly evaluation, not at the moment of capture.
  • An event that should fire once per country when a province changes hands needs fire_once: true.

Effects

EffectNotes
modify_stat, add_relation, set_flag, clear_flag, add_treasury, modify_unrest, impose_sanction, lift_sanction, engage_diplomatically, withdraw_forces, change_government, modify_resource_price (alias global_modifier), fire_eventBasic effects.
set_variable, change_variableSee Flags and variables.
annex_province, annex_countrySee Territory effects.
create_unitSee Unit effect and Invasion waves.
upgrade_unitsSee Converting units.
grant_command_authority, revoke_command_authoritySee Shared command.
modify_militarySee Military modifiers.
start_espionage_mission, steal_technology, sabotage_militarySee Covert operations.
declare_war, sign_peace, sign_truce, form_alliance, break_allianceSee Diplomacy effects.
create_organization, join_organization, leave_organization, invite_to_organizationSee Alliance organization effects.
start_world_ceasefire, end_world_ceasefireSee World ceasefire effects.
open_institution_item, interest_group_approval, institution_membershipSee Institution effects.
grant_specialist, remove_specialistspecialist: the id. grant_specialist makes the event’s country employ it for free, with no hire cost, slot limit, year or flag requirement, taking it from another country that employs it. remove_specialist stops employing it; nothing is refunded. An unknown id does nothing and gets a warning at load. See Specialists.
start_researchAccepted, but it has no effect (warning at load).

Several effects in one option run in the order you wrote them.

Diplomacy effects

The country the event reached acts on the country in target (required). The effects run through the same commands the player and the AI use, so allies are called to arms, script hooks and reactive triggers fire, trust and relations change as usual, and a war is a real war.

{ "type": "declare_war", "target": "TEU", "casus_belli": "territorial", "force": true }
{ "type": "sign_peace", "target": "TEU" }
{ "type": "sign_truce", "target": "TEU", "months": 60 }
{ "type": "form_alliance", "target": "POL" }
{ "type": "break_alliance", "target": "POL" }
  • declare_war. Without force the war is skipped, with a warning in Player.log, while a truce, a non-aggression pact or an alliance holds between the two countries, or when they are already at war. With "force": true the truce ends, the pact and the alliance are broken, and the war is declared. casus_belli is one of scripted (default), territorial, ideological, humiliation, defense, reconquest; liberation is accepted and read as humiliation. scripted counts as neither aggression nor an unjustified attack: no aggressive-expansion gain, no goodwill drop with third countries, no automatic embargo. The others behave as when a player picks them. A world ceasefire that refuses declarations is a gate too: without force the war is skipped while it holds between the two countries.
  • sign_peace. A white peace: the war between the two ends with no demands, and the usual truce follows. Skipped when they are not at war.
  • sign_truce. A truce for months months (1 to 600; absent uses the game’s usual truce length) between two countries not at war, replacing any truce in force. Skipped while they are at war.
  • form_alliance. A bilateral alliance. Without force the normal rules decide, and a human country is asked in its inbox. With "force": true it forms at once. Skipped when already allied or at war.
  • break_alliance. Ends the bilateral alliance, with the usual relations and trust penalty. Skipped when they have no bilateral alliance. Membership in organizations is not touched.

Alliance organization effects

A named alliance organization can be founded by events, scripts and the scenario, and countries can join, leave and be invited. These effects share the registry that a scenario’s startingDiplomacy.organizations fills (see Starting diplomacy).

{ "type": "create_organization", "id": "SOUTHERN_LEAGUE", "collective_defense": true }
{ "type": "join_organization", "id": "SOUTHERN_LEAGUE", "target": "ARG" }
{ "type": "leave_organization", "id": "SOUTHERN_LEAGUE" }
{ "type": "invite_to_organization", "id": "SOUTHERN_LEAGUE", "target": "CHL" }
  • id. 4 to 24 letters, digits or underscores, upper-cased by the game, not starting with IDX. The display name is the text of the key org.<id in lower case>.name in your localization; otherwise the id is shown.
  • create_organization. The event’s country founds the organization and joins it. collective_defense: true makes it a defence pact: an attack on one member is answered by all the others, and a member that attacks another is expelled. Without it the organization is a plain membership. Skipped when the id is in use.
  • join_organization. The event’s country, or target when you name one, joins a mod organization or a built-in one. Skipped for a country already inside, and for a country at war with a member of a defence pact unless "force": true.
  • leave_organization. The event’s country leaves. Skipped when it is not a member.
  • invite_to_organization. The event’s country, which must be a member, invites target (required). A human player gets an invitation in the diplomatic inbox. An AI country answers on the spot.
  • Institutions. When one of these effects names an institution, it follows the institution’s own rules; see below.
  • Members of a defence pact count as allies for wars, joins and the call to arms. They do not share map vision or transit.
  • Scripts do the same with the WriteDiplomacy permission; see Permissions.

Institution effects

The institutions take decisions on an agenda: an item is drafted, members state positions, then vote, and the result takes effect. Events can put items on the agenda, move interest groups, and move members in and out.

{ "type": "open_institution_item", "decision": "un.ga.condemnation", "target": "RUS", "sponsor": "best_sponsor", "severity": "deplores", "urgent": true }
{ "type": "interest_group_approval", "group": "military", "value": 5 }
{ "type": "institution_membership", "institution": "brics", "action": "join" }
  • open_institution_item. decision is institution.organ.decision; target is the country the item is about. sponsor is self (default), best_sponsor or a country’s ISO3. severity, for condemnations, is concern, deplores or condemns (default). urgent uses the urgent windows where the decision has them.
  • interest_group_approval. Moves the approval of one interest group of the event’s country (group: workers, entrepreneurs, military, religious, environmentalists, or all, the default) by value (-50 to 50, not 0).
  • institution_membership. institution is the id; action is join, leave or invite. target on join or leave makes that country move instead. "force": true joins or leaves at once, with no vote and no notice period.

World ceasefire effects

start_world_ceasefire suspends every running war and refuses every declaration of war until it is ended. end_world_ceasefire ends it at once. They act on the world, not on the event’s country. See World ceasefire for what suspended means.

{ "type": "start_world_ceasefire", "months": 6, "until_flag": "armistice_broken" }
{ "type": "end_world_ceasefire" }
  • months. 1 to 600. The ceasefire ends that long after the effect runs. Absent means no end date.
  • until_flag. The ceasefire also ends the moment any country holds this event flag.
  • A ceasefire started by an effect covers every country. Use the scenario header to scope one. Starting one while another runs replaces it.
  • end_world_ceasefire is skipped, with a warning in Player.log, when none is running.

Territory effects

annex_province gives one land province to a country. annex_country gives every province of one country to the country that got the event.

{ "type": "annex_province", "province_id": 2276, "target": "OTT" }
{ "type": "annex_country", "target": "CYP" }
  • annex_province. province_id must be a land province id, 1 to 5000; sea zones start at 5001. target names the receiver. Without it, the event’s country receives the province. A file that puts the id in value also loads.
  • annex_country. target is required: the country to annex. The event’s country takes every province that country owns when the effect runs, and the annexed country is then eliminated as after a peace deal that takes its last province.
  • What changes. The receiver becomes each province’s owner and controller at once. Occupation and siege there end. The receiver gains no aggressive expansion.
  • Script hooks see on_province_captured once for each province that changed owner.

Unit effect

create_unit gives a country one stack of units.

{ "type": "create_unit", "unit_id": "atl_hydro_sub", "count": 2, "province_id": 3277, "target": "HYP" }
  • unit_id is a unit type id, at most 29 bytes: from the base game, from any active mod’s Content/units.json, or from the scenario’s unit types. Case does not matter.
  • unit_category (ground, air, naval or special) can replace unit_id: the receiver gets its best available unit of that category when the effect runs. With both keys, unit_id wins.
  • count is how many units the stack gets, 1 or more. The default is 1, and a count above the game’s cap is clamped with a note at load.
  • Who. target names the receiver. Without it, the event’s country receives the units.
  • Where. province_id is optional and must be a land province. The stack starts there if the receiver owns and controls it; otherwise in the receiver’s capital, or in another suitable province. Naval units need a coastal province; air units need an airfield with a free wing slot.
  • What the stack is like. It is a normal army, fleet or air wing. It costs nothing, needs no building, and is a separate stack.
  • Skipped, with a warning in Player.log, when no unit type has that id, the unit is a missile, the scenario disables the unit or its category, the receiver has been eliminated, or the receiver has no suitable province.

Invasion waves

The same create_unit can spawn a wave: several stacks that carry one id, are sent at a target drawn from a list, and that conditions can count until none is left.

{ "type": "create_unit", "unit_id": "hyp_reaper", "count": 6, "target": "HYP",
  "stacks": 3, "wave_id": "wave_2",
  "assault_target_pool": [2276, 2281, 2290], "assault_coastal": true, "spread": "split",
  "on_arrival": "release", "timeout_days": 180 }
{ "type": "wave_eliminated", "wave_id": "wave_2" }
{ "type": "wave_remaining_lt", "wave_id": "wave_2", "value": 5, "measure": "units" }
FieldDescription
wave_idTags every stack the effect spawns: 1 to 24 lower-case letters, digits or underscores, per mod.
stacksHow many stacks to spawn, 1 to 20, each with count units.
spawn_poolThe receiver’s own provinces to spawn in, at most 256; one is drawn at random among those that suit the unit.
spawn_modeowned or landing. landing spawns ground stacks directly in their drawn target when the receiver is at war with whoever holds it.
assault_target_poolCandidate target provinces, at most 256.
assault_owned_by, assault_region, assault_coastalNarrow the candidates, or choose them on their own when there is no list: an ISO3, a region name as the region condition takes it, and coastal provinces only.
assault_include_controlledDefault false. Provinces the receiver already holds are skipped unless this is true.
spreadtogether (default) gives every stack the same spawn province and target. split draws one per stack.
on_arrivalrelease or hold. A released stack becomes an ordinary army once its owner controls the target; hold keeps it standing there.
timeout_days0 to 3650. The stack gives up after this many days. 0 means no limit.
  • Each ground stack gets an assault order and marches to the target. Ships and aircraft in a wave are tagged and counted but not ordered.
  • The draw is random but identical on every multiplayer machine.
  • wave_eliminated is true once the wave was spawned and none of its stacks is left, however they were lost. A later create_unit with the same wave_id adds to the wave.
  • Put a declare_war before the create_unit in the same option when the wave should land at war.
  • There is no reactive trigger for a wave. Use a second event with a wave_eliminated condition and fire_once: true.

Converting units

upgrade_units turns a country’s stacks of one unit into another.

{ "type": "upgrade_units", "from_unit_id": "infantry", "to_unit_id": "atl_power_armor", "target": "FRA",
  "months": 3, "cost_per_regiment": 50000000, "preserve_hp_pct": 100,
  "province_id": 2276, "region": "western_europe", "wave_id": "wave_2", "retire_old": true }
  • The pair. from_unit_id and to_unit_id must differ and be in the same category. Missiles do not convert.
  • Who. The country in target, otherwise the event’s country.
  • When. months 0 (the default) converts at once. 1 to 120 starts a refit programme: on its last day everything in scope at that moment converts and is paid for. A country runs at most 16 programmes at a time.
  • Cost. cost_per_regiment (default 0) is paid from the treasury per converted regiment, ship or aircraft.
  • Health. preserve_hp_pct (0 to 100, default 100) is how much of each regiment’s damage the converted unit keeps.
  • Scope. province_id, region and wave_id narrow it; together they all apply.
  • retire_old: true takes the old unit off that country’s recruit list, for the player and the AI alike.

Shared command

grant_command_authority lends a country’s armies, fleets and air wings to another country’s command. revoke_command_authority takes them back.

{ "type": "grant_command_authority", "source_country": "USA", "controller_country": "TUR",
  "unit_kinds": ["army", "fleet", "air"], "filter": "in_region", "region": "western_asia",
  "months": 6, "locked": false, "keep_after_peace": false }
{ "type": "revoke_command_authority", "source_country": "USA", "controller_country": "TUR" }
  • Who. controller_country (required) commands the units of source_country (absent means the event’s country). The two must differ.
  • Which units. unit_kinds lists army, fleet and/or air (all three by default). filter is all (default), in_region (with region), in_province (with province_id) or wave (with wave_id). Missiles are not lent.
  • What the controller gets. It orders the units like its own. The owner pays their upkeep and takes their losses, and the controller can only send them against countries the owner is at war with.
  • How it ends. After months (0 to 120; 0 means no time limit); when the war the two countries share ends, unless keep_after_peace; when either country is gone; when the two go to war with each other; on a revoke; or when the owner recalls the units, unless locked.

Covert operations

Events can start, observe and react to the game’s espionage missions.

{ "type": "start_espionage_mission", "mission_type": "steal_technology", "target": "RUS" }
{ "type": "steal_technology", "target": "RUS" }
{ "type": "sabotage_military", "target": "RUS", "field": "military.tanks", "pct": 10 }
  • start_espionage_mission. The event’s country launches a real mission against target (required, except for counter_intelligence). mission_type is one of gather_intelligence, sabotage_economy, steal_technology, influence_government, counter_intelligence, satellite_surveillance. It goes through the same launch rules as the player’s and the AI’s missions. When the rules refuse it, the effect is skipped with a warning in Player.log.
  • steal_technology. Shorthand for a steal_technology mission against target.
  • sabotage_military. Immediately destroys pct percent (0.1 to 50) of the stock named by field (military.manpower, military.reserve, military.tanks, military.aircraft, military.ships) in target. It is not a mission and cannot be caught.
  • on_espionage_resolved is the reactive trigger raised when a mission reaches an outcome. Use mission_caught_recently to tell a caught mission from a success.

Military modifiers

modify_military changes the military of the country that got the event.

{ "type": "modify_military", "stat": "attack", "value": 0.15, "months": 24 }
{ "type": "modify_military", "stat": "morale", "value": -20 }
  • stat (required): attack or defense add value as a fraction to the country’s army and fleet combat power (allowed from -0.9 to 5). morale_recovery adds value as a fraction to how fast idle armies regain morale (up to 10). morale adds value points once to every army’s morale (-100 to 100) and ignores months.
  • months (0 to 600): how long the change lasts. Empty or 0 is permanent.
  • Stacking. Modifiers of the same stat add up. A country holds at most 32 at a time; once full, another is skipped with a warning.

Testing your events in the game

The dev console has commands for checking an event chain without playing months of game time.

CommandWhat it does
event fire <id> [ISO3]Queues the event for the country (default: the player) at once. Conditions, MTTH and cooldowns are not checked.
event fire! <id> [ISO3]The same, and a fire_once event fires again.
event why <id> [ISO3]Shows which of the event’s conditions pass or fail for the country. It changes nothing.
event pending [ISO3]Lists the country’s waiting events, its chained events and running cooldowns.
flags [ISO3]Lists the country’s event flags and variables.
flag set <name> [ISO3], flag clear <name> [ISO3]Sets or clears an event flag on a country.
mod hooksShows mod hook subscribers and the last delivered hook events.

The commands that change the world (event fire, flag set, flag clear) are for testing; see Console and admin panel for where the console is available.

Event errors

Mod events are checked strictly. These problems skip the whole event:

  • an unknown type, category, target, condition, effect or trigger type;
  • an unknown stat field, continent, region or government name;
  • a date that is not "YYYY-MM";
  • a specific_country event without target_country;
  • fewer than 1 or more than 6 options;
  • a fire_event without chain_event, or a flag effect or condition without a flag name;
  • a condition or effect whose required field is missing or outside the range given on this page, for example an annex_province without a land province id or a create_unit without unit_id or unit_category.

A duplicate id skips the later event. An unknown chain target keeps the event and drops the chain. Text longer than its field is cut off, with a warning: 125 bytes for titles, keys and option labels, 509 bytes for tooltips.

Problems appear in the Mod Builder’s VALIDATE report, on the MOD LOADOUT panel, in the RELOAD & TEST message and in Player.log. Each message names the mod, the file, the event id and the reason.

Firing from a script

The fire_event script import (and ModHookBus.FireEvent in C#) looks the id up among the base game’s events and every active mod’s engine events. A match is added to that country’s queue at once, without checking its conditions or cooldowns: the script decides. It is refused when the event targets the player and no human controls that country, when it is a fire_once event that has already fired, and when it is already pending for that country. A queued event raises the on_event_fired hook like any other. If the id is not an engine event, a legacy event with that id is shown instead. Firing needs the FireTriggers permission. See the WASM scripting page.

Editing a mod in a running game

In a single-player game with a local mod active, you can open the Mod Builder from the pause menu, edit the mod, and press APPLY TO RUNNING GAME instead of RELOAD & TEST. It saves your edits and reloads the mod’s events, localization, script and number settings into the game you are playing.

  • Every event that exists keeps its place, so pending events and scheduled chains keep working. A changed event is updated in place, an added one goes after the last one, and a deleted or broken one stops firing.
  • Settings that are plain numbers take effect at once: the game_settings.json sections population, diplomacy, advanced_diplomacy, world_order, ai_weights, fog_of_war, intelligence, map_interaction, satellite, step42_diplomacy and political_drift, and the event settings. economy, technology, nuclear, military and buildings are not re-applied; a new game picks them up.
  • The Events page’s FIRE NOW button queues the selected event for your country at once.
  • Not reloaded: C# code, a changed mod.json, and content such as buildings, units, doctrines, laws, resources and goals.
  • It is refused in multiplayer.

Event saves and multiplayer

  • Mod events are saved by id. If you load a save after removing or renaming an event, its pending entries for that event are dropped, with a warning.
  • Every Content/events/*.json file is part of the multiplayer lobby check. Players with different event files cannot join the same game.

Play Global Protocol: New World Order

Out now in Early Access on Steam, with online multiplayer for 2–8 players.