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,Content/resources.json - Doctrines:
overrides/doctrines.json - Mod research: new branches, extra tiers and
Content/research_tracks.json - Laws:
overrides/laws.json - Interest groups:
overrides/interest_groups.json - National goals: the scenario’s
nationalGoalsFile - Specialists:
Content/specialists.json - Events:
Content/events/*.json
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:
| Mode | What 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 entries | Start 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": trueis accepted as a shorthand for"mode": "replace". Do not combine it with a contradictingmode.- The entries may live under
overrides(what the Mod Builder writes) or under the base config’s own root key:buildings,unitsorresources. - A building’s
categoryis one ofeconomic,military,infrastructure,research,social,defense,intelligence. A unit’scategoryis one ofground,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 id | Used for |
|---|---|
naval_base | Fleet recruitment and docking |
airfield | Air wing bases and starting airfields |
barracks, military_base | Land unit recruitment (units name them in cost.required_building) |
submarine_pen, trade_port | Coastal building rules |
intelligence_hq, cyber_ops_center, counterintel_bureau | Espionage |
satellite_launch_facility | The 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 asdoctrines.jsonwrites 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.flagis the name aset_flageffect 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, ashas_flagdoes.prerequisites.hidden_until_flag: truehides 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 aflag.- The flag gate sits beside
prerequisites.tech: both must be met.prerequisitesis replaced as a whole, so keep thetechyou want when you add aflag. - Only a flag that a mod event, a goal’s
on_complete_flagor 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.
settingsmerges sparsely,starting_grantsreplaces the base grants when present, and the legacy tech map is always the base game’s.- Names and descriptions come from your
name_keyanddesc_keyrows in the mod’s localization CSVs. Icons come fromicons/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.branchescreates branches shown under Mod research in the Knowledge Network. A branch has 1 to 9 tiers and an optionalmilestone, granted once every tier has a researched card.append.tiersextends a base branch (branchis 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) andmonths(minimum duration) default to the base values for the same tier number; tiers above 5 use tier 5’s. - A card has
idandname(required),description,icon,requires_flag,effectsandai. Its effects use the same keys as a base card (seedoctrines.schema.json); an unknown key is an error. The loader also readsprerequisiteson a card: other cards or base gates that must be researched first. - Ids are 1 to 24 characters of
a-z,0-9and_, 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
aiaxes (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.
| Field | Description |
|---|---|
settings.slots | Mod research slots that run at once, 1 to 4. Default 2. |
settings.points_share | The 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, name | Required. 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, cost | Required. cost is in research points, above 0. |
node months | Minimum months to research, however many points a country has. |
node prerequisites | All of these must be researched first: node ids, tech:<id> keys or doctrine gate keys such as military_t3. |
node any_of | At 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_flag | An event flag the country must hold. |
node effects | Doctrine effect lanes, the same keys as a doctrine card. |
node ai, ai_weight | The five AI axes, and an extra AI preference added to the node’s score. |
node position | [column, row] in the track view. |
starting | Nodes 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_techcondition 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_weightabove 0. - Every appended category needs at least one option without a doctrine gate and a complete
defaultsblock.defaultsnames 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,optionsanddefaults. An option hasid,name_key,desc_key,bloc_stanceandmodifiers. The modifier keys are listed inlaws.schema.json. - Law names and descriptions come from
politics.law.*keys in the mod’sContent/localization/<language>.csvfiles.
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_overridesthat 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_bandsandgroupsentries are matched byidand merge key by key, so the example changes one number. The band ids areyouth,young,middle,senior. The group ids areworkers,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
leanand a group’sbloc_affinityhave four keys, each from -1 to 1:liberal_capitalist,socialist_communist,nationalist_conservative,authoritarian_theocratic. law_bonuses(matched bycategory+option+group, with abonusfrom -0.5 to 0.5) anddoctrine_bonuses(matched bybranch+group, with aper_tierfrom -0.1 to 0.1) update the matching entry or append one.country_overrides,religiosity_by_religionandneutrality_reference_sharesmerge key by key.gdp_factor_thresholdsreplaces the list. A country override hasshares, an optionalreligiosityand amodeoffixedordelta.
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;
fixedcountry overrides list every group and sum to 1;- demand multipliers stay neutral: weighted by the world age mix for bands, or by
neutrality_reference_sharesfor 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
| Field | Description |
|---|---|
| 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. |
id | Required, 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_key | Looked 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. |
type | expansion, 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. |
priority | starter, primary, secondary, aspirational. An unknown value is reported and read as secondary. |
ai_weight | 0 to 1, default 0.5: how strongly AI countries pursue the goal. |
target_countries | ISO3 codes the goal is aimed at, for AI countries that pursue it. |
agenda_panel_id, agenda_subject | Optional 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_effects | Paid 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_flag | An 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_event | An 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. |
tasks | The 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.type | params |
|---|---|
own_provinces | province_owner: counts owned provinces whose base-map country is this code. |
alliance_with | target_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_independence | target_iso3. |
sphere_member | target_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_relations | target_iso3 (optional), min_value (default 50). |
build_in_provinces | province_owner (optional). |
built_since_start | building_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_above | unit_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_tech | None. The number of completed doctrine tiers is the progress. |
treasury_above, gdp_above | min_value, in the base money unit. |
country_stat | stat: 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_objective | objective_id. |
has_flag, not_has_flag | flag_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_BASICgoals) 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_withis 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 } } ]
}
| Field | Description |
|---|---|
mode | merge (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_assigned | How many specialists one country employs at once, 1 to 8. Default 2. |
id, name | Required. The id is 1 to 24 characters of a-z, 0-9 and _. |
description | Text shown for the specialist. |
role | scientist, engineer or other. Display only. |
portrait | A 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. |
country | ISO3 of the country that employs the specialist at the start of a new game. Empty means anyone can hire. |
available_from | The first year the specialist can be hired, 0 to 3000. 0 means from the start. |
hire_cost | One-off cost, paid from the treasury. |
upkeep_monthly | Monthly cost while the specialist is employed. |
requires_flag | An event flag a country must hold before it can hire the specialist. |
ai_weight | Extra preference the AI gives this specialist when it chooses whom to hire. |
effects | Only 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_specialistandremove_specialistand the conditionhas_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 exampleatlas_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
| Field | Default | Description |
|---|---|---|
id | none | Required. |
type | none | scripted, procedural or reactive. Required for an engine event. |
category | none | geopolitical_crisis, economic_shock, military_incident, diplomatic_opportunity, technology_breakthrough, natural_disaster, internal_politics or social_cultural. |
target | none | Who can get the event: player, any_country, specific_country, all, global or every_country (described below). The schema also lists random_matching. |
target_country | none | ISO3. Required for a specific_country event. |
title, description | none | Plain text, used when no key is given or found. |
title_key, description_key | none | Localization keys, looked up in your Content/localization/<language>.csv. |
image | none | The popup’s picture, by file name without extension (see below). |
priority | 5 | 1 to 10. |
mean_time_to_happen_months | 12 | Sets the chance per roll, 1 - e^(-1/MTTH). |
immediate | false | No random roll (see below). |
fire_once | false | The event fires at most once per country. |
cooldown_months | 0 | A cooldown for this event alone. |
pause_game | by category | Whether the popup pauses the game when it opens. |
conditions | none | See Conditions. |
triggers | none | For reactive events; see Reactive triggers. |
options | none | Required, 1 to 6. |
chain_event, chain_delay_months | none, 0 | An event-level chain; see Chains. |
Each option has:
| Field | Default | Description |
|---|---|---|
text, text_key | none | The button text, and its localization key. |
tooltip, tooltip_key | none | The hover text, and its localization key. |
ai_weight | 1.0 | Base AI preference for the option, before personality. |
ai_personality_factors | none | Multipliers per AI personality trait: military_investment, economic_priority, diplomacy_focus, tech_investment, alliance_loyalty, isolationism, nuclear_threshold. |
conditions | none | Conditions for the option to be available. |
hide_when_unavailable | false | Hide the option while its conditions fail, instead of showing it greyed out. |
effects | none | Required. 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 themean_time_to_happen_monthsyou write is ignored. A country with an unanswered event gets this one queued behind it, up tomax_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 respectsfire_onceandcooldown_months. A repeatable one waits at leastrepeatable_immediate_min_cooldown_daysbetween its own firings. Countries are judged in ISO3 order on every player’s game. Eliminated countries are skipped.allbehaves likeany_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"andspecific_countryevents are the exception: humans roll them every month at the MTTH you wrote. Animmediateevent 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
immediateevents 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_monthsadds a cooldown for one event. A repeatableimmediateevent with nocooldown_monthswaits at leastrepeatable_immediate_min_cooldown_days(60 in the base game) after its own firing. A mod can raise these in theeventssection ofoverrides/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 eligibleimmediateevent 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_weightand 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.
| Trigger | Raised when | The event goes to (source_country) | target_country |
|---|---|---|---|
on_war_declared | A country declares war | The country that declared | The defender |
on_peace_signed | A peace deal is signed | The country that proposed it | The other party |
on_alliance_formed | Two countries form an alliance | The country that proposed it | The partner |
on_alliance_broken | An alliance ends: broken, or the ally is attacked, or a call to arms is dishonoured | The country that broke it | The former ally |
on_sanction_applied | A country imposes sanctions | The country that imposed them | The sanctioned country |
on_tech_researched | A country completes a doctrine tier, or a mod research node | That country | None |
on_country_collapse | A country is eliminated (its last province is lost) | The fallen country | None |
on_building_completed | A building finishes construction | The country that owns the province | None |
on_coup, on_revolution, on_leader_death | The government changes that way, or the leader dies | That country | None |
on_nuke_launched | A country launches a nuclear strike | The launching country | None |
on_espionage_resolved | An espionage mission reaches an outcome: success, failure or caught | The country that ran the mission | The 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_countryset the other way round and a condition that only the other side meets. - Filters. A trigger’s
source_countryandtarget_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, afire_onceevent 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.
0or 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_onceevent that the recipient has already had is dropped. A chainedtarget: "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_eventlooks 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.
| Condition | Fields and meaning |
|---|---|
date_after | value: "YYYY-MM" (a day part is ignored). Counts by month and includes the month itself: "2026-06" passes from June 2026. |
date_before | value: "YYYY-MM". Excludes the month itself. |
country_stat_gt, country_stat_lt | field and a numeric value. The fields that work are listed under the table. |
at_war, not_at_war | Optional target_country: at war with that country. |
has_nuclear | The country has nuclear warheads. |
has_flag, not_has_flag | flag_name. See Flags and variables. |
flag_age_months_gt, flag_age_months_lt | flag_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_eq | variable and value (a whole number). Optional scope. A variable that was never set reads 0. |
espionage_active | The country has an espionage mission running. Optional mission_type and target_country. See Covert operations. |
mission_caught_recently | months (1 to 1200): one of the country’s missions was caught within that many months. Optional target_country. |
lifetime_gt, lifetime_lt | counter and value (0 to 2,000,000,000). See Lifetime counters. |
government_type | value: the same names as change_government. |
continent, not_continent | value: africa, americas, asia, europe, oceania, antarctica. |
region, not_region | value: 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_lt | value: average national unrest, 0 to 100. |
owns_province, not_owns_province | value: a province id. True when the country is the province’s legal owner. Optional target_country. See Province conditions. |
controls_province, not_controls_province | value: a province id. True when the country controls the province. Optional target_country. |
alliance_member | target_country: the country is allied with that country. Without one it does not pass. |
relation_above, relation_gt, relation_below, relation_lt | target_country and value (-100 to 100): the country’s relation toward that country is above, or below, the value. |
stakeholder | target_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_tech | value: 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_specialist | specialist: a specialist id. True when the country employs it. |
wave_eliminated | wave_id: a wave of the same mod has no stack left. See Invasion waves. |
wave_remaining_gt, wave_remaining_lt | wave_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_lt | province_id, value, optional owner_country and measure (stacks, the default, or units): the armies standing in that province. |
province_stat_gt | field: 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_organization | id: an organization’s id: a mod’s own organization, a built-in one such as NATO, or an institution. |
institution_seat | organ: a council as institution.organ, for example "un.unsc"; optional seat: any (default), permanent or elected. |
institution_item_open | decision: 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_force | Optional 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_arrangement | Optional arrangement: a trade arrangement’s key, or any (the default). True when the country is a member. |
world_ceasefire_active | No fields. True while a world ceasefire holds. |
defcon_level | value: 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_is | Not 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.
| Id | counter | Counts |
|---|---|---|
| 0 | personnel_lost | Soldiers killed in ground combat, missile and air strikes and nuclear blasts. |
| 1 | regiments_lost | Regiments destroyed. |
| 2 | ships_lost | Ships sunk. |
| 3 | aircraft_lost | Aircraft shot down or destroyed. |
| 4 | civilians_affected | Civilians affected on the country’s own soil. |
| 5 | provinces_gained | Provinces that changed owner to this country by treaty. |
| 6 | provinces_lost | Provinces that changed owner away from this country by treaty. |
| 7 | wars_won | Wars that ended with this country clearly ahead. |
| 8 | wars_lost | Wars 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_variablemakes the variable equalvalue.change_variableaddsvalueto 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_ltandvariable_eqcompare the variable withvalue. - Flag age.
flag_age_months_gtandflag_age_months_ltcompare how long ago the flag was set.set_flagon a flag the country already has changes nothing, so the age keeps counting from the first time;clear_flagthenset_flagrestarts it. - The limit. A country keeps at most
events.max_flags_per_countryflags (64 in the base game) and, separately, the same number of variables. A flag or variable past the limit is dropped, with a line inPlayer.log. Changing a variable that already exists always works. - Scope. A variable normally lives on a country. Add
"scope": "mod"toset_variable,change_variableand 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. Omitscope, 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": trueto aset_flag,clear_flag,set_variableorchange_variableeffect to leave it out of the popup’s expected impact. The effect runs all the same. On any other effecthiddenis 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_countrythe 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 onceOTTcontrols province 2276. Add{ "type": "not_controls_province", "value": 2276 }to leave out the controller itself. - A
target_countrythat does not exist owns and controls nothing, and so does any country for an unknown province id. Thenot_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
| Effect | Notes |
|---|---|
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_event | Basic effects. |
set_variable, change_variable | See Flags and variables. |
annex_province, annex_country | See Territory effects. |
create_unit | See Unit effect and Invasion waves. |
upgrade_units | See Converting units. |
grant_command_authority, revoke_command_authority | See Shared command. |
modify_military | See Military modifiers. |
start_espionage_mission, steal_technology, sabotage_military | See Covert operations. |
declare_war, sign_peace, sign_truce, form_alliance, break_alliance | See Diplomacy effects. |
create_organization, join_organization, leave_organization, invite_to_organization | See Alliance organization effects. |
start_world_ceasefire, end_world_ceasefire | See World ceasefire effects. |
open_institution_item, interest_group_approval, institution_membership | See Institution effects. |
grant_specialist, remove_specialist | specialist: 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_research | Accepted, 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. Withoutforcethe war is skipped, with a warning inPlayer.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": truethe truce ends, the pact and the alliance are broken, and the war is declared.casus_belliis one ofscripted(default),territorial,ideological,humiliation,defense,reconquest;liberationis accepted and read ashumiliation.scriptedcounts 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: withoutforcethe 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 formonthsmonths (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. Withoutforcethe normal rules decide, and a human country is asked in its inbox. With"force": trueit 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 withIDX. The display name is the text of the keyorg.<id in lower case>.namein your localization; otherwise the id is shown.create_organization. The event’s country founds the organization and joins it.collective_defense: truemakes 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, ortargetwhen 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, invitestarget(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
WriteDiplomacypermission; 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.decisionisinstitution.organ.decision;targetis the country the item is about.sponsorisself(default),best_sponsoror a country’s ISO3.severity, for condemnations, isconcern,deploresorcondemns(default).urgentuses 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, orall, the default) byvalue(-50 to 50, not 0).institution_membership.institutionis the id;actionisjoin,leaveorinvite.targetonjoinorleavemakes that country move instead."force": truejoins 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_ceasefireis skipped, with a warning inPlayer.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_idmust be a land province id, 1 to 5000; sea zones start at 5001.targetnames the receiver. Without it, the event’s country receives the province. A file that puts the id invaluealso loads.annex_country.targetis 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_capturedonce 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_idis a unit type id, at most 29 bytes: from the base game, from any active mod’sContent/units.json, or from the scenario’s unit types. Case does not matter.unit_category(ground,air,navalorspecial) can replaceunit_id: the receiver gets its best available unit of that category when the effect runs. With both keys,unit_idwins.countis 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.
targetnames the receiver. Without it, the event’s country receives the units. - Where.
province_idis 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" }
| Field | Description |
|---|---|
wave_id | Tags every stack the effect spawns: 1 to 24 lower-case letters, digits or underscores, per mod. |
stacks | How many stacks to spawn, 1 to 20, each with count units. |
spawn_pool | The receiver’s own provinces to spawn in, at most 256; one is drawn at random among those that suit the unit. |
spawn_mode | owned or landing. landing spawns ground stacks directly in their drawn target when the receiver is at war with whoever holds it. |
assault_target_pool | Candidate target provinces, at most 256. |
assault_owned_by, assault_region, assault_coastal | Narrow 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_controlled | Default false. Provinces the receiver already holds are skipped unless this is true. |
spread | together (default) gives every stack the same spawn province and target. split draws one per stack. |
on_arrival | release or hold. A released stack becomes an ordinary army once its owner controls the target; hold keeps it standing there. |
timeout_days | 0 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_eliminatedis true once the wave was spawned and none of its stacks is left, however they were lost. A latercreate_unitwith the samewave_idadds to the wave.- Put a
declare_warbefore thecreate_unitin 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_eliminatedcondition andfire_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_idandto_unit_idmust differ and be in the same category. Missiles do not convert. - Who. The country in
target, otherwise the event’s country. - When.
months0 (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,regionandwave_idnarrow it; together they all apply. retire_old: truetakes 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 ofsource_country(absent means the event’s country). The two must differ. - Which units.
unit_kindslistsarmy,fleetand/orair(all three by default).filterisall(default),in_region(withregion),in_province(withprovince_id) orwave(withwave_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, unlesskeep_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, unlesslocked.
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 againsttarget(required, except forcounter_intelligence).mission_typeis one ofgather_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 inPlayer.log.steal_technology. Shorthand for asteal_technologymission againsttarget.sabotage_military. Immediately destroyspctpercent (0.1 to 50) of the stock named byfield(military.manpower,military.reserve,military.tanks,military.aircraft,military.ships) intarget. It is not a mission and cannot be caught.on_espionage_resolvedis the reactive trigger raised when a mission reaches an outcome. Usemission_caught_recentlyto 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):attackordefenseaddvalueas a fraction to the country’s army and fleet combat power (allowed from -0.9 to 5).morale_recoveryaddsvalueas a fraction to how fast idle armies regain morale (up to 10).moraleaddsvaluepoints once to every army’s morale (-100 to 100) and ignoresmonths.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.
| Command | What 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 hooks | Shows 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_countryevent withouttarget_country; - fewer than 1 or more than 6 options;
- a
fire_eventwithoutchain_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_provincewithout a land province id or acreate_unitwithoutunit_idorunit_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.jsonsectionspopulation,diplomacy,advanced_diplomacy,world_order,ai_weights,fog_of_war,intelligence,map_interaction,satellite,step42_diplomacyandpolitical_drift, and the event settings.economy,technology,nuclear,militaryandbuildingsare 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/*.jsonfile is part of the multiplayer lobby check. Players with different event files cannot join the same game.