A scenario is the part of a mod that sets up the world a new game starts in: the start date, the countries that exist, who owns each province, who is allied or at war, and which armies, fleets and air wings stand where. This page covers the scenario header, the split scenario files, starting diplomacy, the world ceasefire, province ownership and military deployments. Countries themselves are on the Country overrides page.
- Single-file scenario
- Split-folder scenario
- Scenario header fields
- Starting diplomacy
- World ceasefire
- Province and region ownership
- Military deployments
mod.json holds the mod’s own metadata and says where the scenario is (defaultScenarioFile or scenarioFolder, see Manifest fields). The scenario files hold game-state setup only.
Single-file scenario
Put everything in one scenario.json and point defaultScenarioFile in mod.json at it. The file holds the header fields and, as root keys, any of the lists described on this page and on the Country overrides page.
A minimal scenario:
{
"scenarioId": "com.mymod.cold_war_2030",
"displayName": "Cold War 2030",
"version": "1.0.0",
"startYear": 2030,
"startMonth": 1,
"startDay": 1,
"clearDiplomaticRelationships": true
}
Split-folder scenario
Point scenarioFolder in mod.json at a folder. The loader reads scenario.json first. It must exist and contain scenarioId. The loader then merges these files, in this order:
| File | Root key | Holds |
|---|---|---|
countries_add.json | addCountries | Countries to add or re-skin (Adding countries) |
countries_remove.json | removeCountries | Countries to remove (Removing countries) |
countries_state.json | countryStateOverrides | Starting economy, politics and military of existing countries (State overrides) |
diplomacy.json | startingDiplomacy | Day-one organizations, alliances, treaties, wars and relations (Starting diplomacy) |
provinces_ownership.json | provinceOwnerOverrides, regionOwnerOverrides | Province and region reassignments (Province and region ownership) |
units_define.json | unitTypes | Custom unit types (Custom unit types) |
units_deploy_air.json | initialAirWings | Air wing placements (Air wing stacks) |
units_deploy_armies.json | initialArmies | Army placements (Army stacks) |
units_deploy_fleets.json | initialFleets | Fleet placements (Fleet stacks) |
- Every file is optional. A missing file is skipped.
- Each file is a JSON object whose root key holds a list, the same keys
scenario.jsonitself accepts. - Lists are appended. A later file adds to what an earlier file or
scenario.jsonlisted; it does not replace it. - A file that fails its checks stops the whole scenario from loading, and the error names the file.
- These nine names are the only ones the loader picks up on its own. Other files in the folder (goals, victories, province data, currencies, roster files) load only when a header field names them, so you choose their file names.
Each split file has its own JSON schema, named mod_scenario_*.schema.json. See JSON schemas.
Scenario header fields
The header is scenario.json in a split folder, or the top of a single-file scenario. The Mod Builder’s Scenario page edits it. Its schema is mod_scenario_header.schema.json.
Identity and start date
| Field | Type | Default | Description |
|---|---|---|---|
scenarioId | string | none | Required. Unique identifier of the scenario. |
displayName | string | empty | Display name of the scenario. |
version | string | empty | Version text, for example 1.0.0. |
startYear | int | 0 | Year the game starts in, from 1 to 3000. 0 or absent keeps the base game’s start year. |
startMonth | int | 1 | 1 to 12. |
startDay | int | 1 | 1 to 31 in the schema. The game’s months have 30 days. |
startTick | int | 0 | Absolute tick to start on. 0 derives the tick from the date. |
economicEraLabel | string | empty | Accepted and stored with the scenario. No game system reads it. |
Diplomacy reset
| Field | Type | Default | Description |
|---|---|---|---|
clearDiplomaticRelationships | bool | false | Wipes the base game’s diplomatic relationships before the scenario’s own are written. |
clearDiplomacyScope | string | "extended" | "core" or "extended": how much is wiped. See Diplomacy clear scopes. Wars are only cleared by "extended". |
rebuildNeutralRelations | bool | true | After clearing, gives every pair of countries a neutral relation row again. |
Money and population scale
| Field | Type | Default | Description |
|---|---|---|---|
gdpScale | float | 1.0 | Multiplies every country’s money once, when a new game starts. Must be above 0. See below. |
unownedProvincePopulationScale | float | 1.0 | Multiplies the population of every province that is still unowned after removeCountries and the ownership overrides, once, when a new game starts. Must be above 0. |
currencySymbol | string | "$" | Symbol shown in every money display, at most 8 characters, for example "fl.". Empty keeps "$". With national currencies it is the base currency’s symbol and wins over the currencies file’s baseCurrency.symbol. See Currencies. |
What gdpScale changes. It multiplies each country’s GDP, GDP per capita, exports, imports, foreign reserves, treasury and opening monthly budgets (revenue, expenses, defence and research). Ratios such as debt to GDP, tax rates and growth are left alone.
countryStateOverridesvalues are absolute and are applied after the scale. A country whosegdpis overridden has its opening monthly budgets and its trade re-based on that GDP.- The base game’s fixed money amounts are converted by the same factor: the money keys of
game_settings.json(spot-market and trade floors, intelligence costs and similar), the envoy recruit cost, law change costs, envoy operation outcomes and the sphere court minimum. The tutorial’s treasury rewards are paid times the scale too. - An amount your mod writes itself in
overrides/game_settings.jsonoroverrides/laws.jsonis already your scenario’s money and is used as written. - Pick the scale your own numbers use. If
countryStateOverridesset the GDPs,gdpScaleshould be roughly their total divided by the base game’s world GDP.
What unownedProvincePopulationScale changes. Provinces are baked with the base game’s headcounts, and unowned land brings those people back when it is colonised. A historical scenario sets the scale to roughly its world population divided by the base-game population of the provinces its countries own. A scaled province keeps at least 100 people, or its own population if that is smaller. Owned provinces follow each country’s declared population instead; see Population.
Files the header names
Each path is relative to the scenario folder. A path that does not resolve, or a file that does not parse, is listed on the MOD LOADOUT panel and in the Mod Builder’s RELOAD & TEST message.
| Field | Names | Documented at |
|---|---|---|
nationalGoalsFile | The scenario’s national goals. By default it replaces the base game’s goals for the Agenda and the AI. | National goals |
victoryFile | The scenario’s own endings, extra end-screen rows, and the switch that turns the base victories off. | Scenario victories |
provinceDataFile | Per-province population, terrain and resource deposits. | Scenario province data |
currenciesFile | National currencies. Applied after every mod’s Content/currencies.json. | Currencies |
buildingsOverrideFile | A buildings roster. Applied after every mod’s Content/buildings.json. | Content rosters |
unitsOverrideFile | A units roster. | Content rosters |
resourcesOverrideFile | A resources file. | Resources |
techOverrideFile | Ignored. Research is the Knowledge Network. A file named here only produces a message pointing at overrides/doctrines.json. | Doctrines |
Disabled content
| Field | Type | Description |
|---|---|---|
disabledUnitCategories | string[] | Unit categories removed from recruitment and build eligibility: Ground, Air, Naval, Missile, Special. See Unit categories. |
disabledUnitTypeIds | string[] | Specific unit ids, same effect. |
restrictOwnersToOwnedUnits | bool | Default false. A unit type with an ownerIso3 is exclusive to that country. When true, a country that owns unit types may recruit only those. When false, owners keep every other available unit too. See Who can recruit a unit type. |
disabledBuildingCategories | string[] | Economic, Military, Infrastructure, Research, Social, Defense, Intelligence. Buildings of these categories are removed from every build menu, from starting seeding, from the AI and from the build command. |
disabledBuildingIds | string[] | Specific building ids, same effect. To drop most of the base roster, use a replace-mode roster instead; see Roster modes. |
disabledDoctrineBranches | string[] | Knowledge Network branches hidden from research: military, government, economy, industry, diplomacy, intelligence, cyber, space, energy, society. Their tier gates never open, so everything gated behind them stays locked. |
The header also accepts worldCeasefire, described under World ceasefire.
Starting diplomacy
A scenario can start with the diplomacy it needs: an organization that answers an attack on one member, a defence pact, a non-aggression treaty, a war that is already running, hostile or friendly relations. Put a startingDiplomacy block in scenario/diplomacy.json, or inline in scenario.json. Lists from both are appended.
The block is written once, when a new game starts. A loaded save keeps the diplomacy it has. The Mod Builder’s Diplomacy page edits the file. Its schema is mod_scenario_diplomacy.schema.json.
{ "startingDiplomacy": {
"organizations": [
{ "id": "WARSAW_PACT", "nameKey": "org.warsaw_pact.name", "type": "CollectiveDefense",
"founder": "SOV", "members": ["SOV", "POL", "CZE"] }
],
"alliances": [ { "a": "USA", "b": "GBR", "type": "Military" } ],
"treaties": [
{ "type": "nap", "a": "DEU", "b": "SOV" },
{ "type": "truce", "a": "ITA", "b": "ESP", "months": 24 }
],
"wars": [
{ "id": "korea", "attackers": ["PRK", "CHN"], "defenders": ["KOR", "USA"],
"casusBelli": "Territorial", "callAllies": false }
],
"relations": [
{ "a": "USA", "b": "SOV", "opinion": -60, "trust": -40, "mutual": true, "anchor": true, "rival": true }
]
} }
Every country is the ISO3 code of a country the scenario has: a base-game country the scenario keeps, or one in addCountries. An unknown country skips that entry with a warning in Player.log.
Organizations
| Field | Type | Default | Description |
|---|---|---|---|
id | string | none | Required. 4 to 24 upper-case letters, digits or underscores, never starting with IDX. It is the organization’s identity in saves and multiplayer. |
nameKey | string | empty | Localization key of the display name, at most 60 characters, shipped in the mod’s own text. Blank uses org.<id in lower case>.name when the mod has it, then the id. |
type | string | CollectiveDefense | CollectiveDefense, Economic, Political or InternationalOrg. An unknown value is read as CollectiveDefense with a warning. |
founder | string | empty | ISO3. The founder is a member. |
members | string[] | empty | The other members, joined in list order. |
- A
CollectiveDefenseorganization is a mutual-defence pact: an attack on one member is answered by all, and a member that attacks another is expelled. Its members count as allies of each other. The other three types are plain memberships. - An organization gives no shared map vision or transit. That needs a bilateral alliance.
- The id of a built-in organization, such as
NATO, adds your members to it. - An organization defined twice keeps its first type.
- Mod organizations do not count towards the prestige of the built-in G7, G20 and UN memberships.
Alliances
A bilateral alliance between a and b (both required). type is Military (the default; the ally can be called into an offensive war) or DefensePact (defends only). Both sides hold it from day one, and the AI does not drop it on its own, as with the base game’s own starting pacts. A player can break it.
Treaties
type | Meaning | months |
|---|---|---|
nap | Non-aggression pact between a and b. | Not used. |
truce | Truce between a and b. | Required, at least 1, in 30-day months. A truce without it is skipped with a warning. |
trade_agreement | Trade agreement between a and b on the default terms. | Not used. |
guarantee | a guarantees the independence of b. | How long it lasts. 0 or absent uses the game’s guarantee length from the diplomacy settings. |
months accepts 0 to 1200. An unknown type is skipped with a warning.
Wars
| Field | Type | Default | Description |
|---|---|---|---|
id | string | war | A label used in log messages. |
attackers | string[] | none | Required, at least one country. The first is the lead attacker. |
defenders | string[] | none | Required, at least one country. The first is the lead defender. |
casusBelli | string | Scripted | Scripted, Territorial, Ideological, Humiliation, Defense or Reconquest. Case does not matter. Liberation is accepted and read as Humiliation. An unknown value is read as Scripted with a warning. |
callAllies | bool | false | When false, the war has exactly the listed sides. When true, allies are called to arms as in a normal declaration. |
- The lead attacker opens the war on the lead defender through the normal war declaration. The other attackers and defenders then join their side.
- A starting war carries no aggression penalty, whichever
casusBelliit has: no aggressive-expansion gain, no goodwill drop with third countries, no embargo. - A truce between the two lead countries is removed by the war.
- A country that is allied to someone on the other side stays out of the war, with a warning.
- A country listed on both sides fights on the attackers’ side only.
- The war is created shortly after the scenario applies, before the first game tick, so the scenario’s starting armies fight from the first day.
Relations
| Field | Type | Default | Description |
|---|---|---|---|
a, b | string | none | Required. The entry sets how a sees b. |
opinion | int | unset | -100 to 100: how much a likes b. |
trust | int | unset | -100 to 100: how much a trusts b. |
mutual | bool | false | Also sets b’s view of a to the same values. |
anchor | bool | false | Makes the values the level that relations drift back to, so they do not fade towards the regional baseline. |
rival | bool | false | Makes the two countries rivals (both ways when mutual is set). |
In multiplayer the block is part of the scenario every player loads, and everything it writes is saved and hashed like any other diplomacy.
World ceasefire
A world ceasefire silences the wars between the countries it covers, from the first day or from a date you choose. It is the header field worldCeasefire. When the block is absent there is no ceasefire. Events and scripts can start and end one too; see World ceasefire effects and Permissions.
{
"worldCeasefire": {
"startDate": "1914-09-01",
"endDate": "1915-01-01",
"untilFlag": "armistice_broken",
"countries": ["FRA", "DEU", "GBR"],
"blockDeclarations": true,
"suspendWars": true
}
}
| Field | Default | Description |
|---|---|---|
startDate | The scenario’s first day | YYYY-MM-DD, with the game’s 30-day months (day 1 to 30). A date in the future arms the ceasefire: it begins that day. |
endDate | None | YYYY-MM-DD. The ceasefire ends on this day. |
untilFlag | None | The ceasefire also ends the moment any country holds the event flag with this name (written by a set_flag effect). |
countries | Every country | ISO3 codes. A pair of countries is covered only when both are listed. |
blockDeclarations | true | A declaration of war between covered countries is refused, for the player, the AI, the call to arms and coalition wars alike. A declare_war effect with "force": true goes through, and that one war stays live while the ceasefire holds. |
suspendWars | true | The wars running between covered countries are suspended. |
With neither endDate nor untilFlag, the ceasefire lasts until an end_world_ceasefire effect or a script ends it. Validate Mod warns when nothing in the mod can end it.
What suspended means
The war, its participants, its occupations and its peace terms all stay, and a peace deal can be signed. For each suspended pair of countries:
- no battle starts, and a battle in progress stops (the armies stand down where they are);
- sieges and occupations freeze: no progress, no recovery, nothing cleared;
- war score and war exhaustion stop moving, and occupation costs stop accumulating;
- air strikes, close air support, ground fire and air interception between them stop, a blockade is lifted and raised again afterwards, and nuclear and conventional missile strikes against the other side are refused;
- armies cannot enter the other side’s land;
- neither can declare war on the other or join a war against it.
The scenario’s own startingDiplomacy.wars are declared first and then suspended, so a scenario can open in the middle of a war with the guns silent. The Diplomacy panel shows a World ceasefire pill and suspended wars are tagged Suspended. The ceasefire is saved and hashed with the game, so saving, loading and multiplayer resyncs keep it.
Province and region ownership
provinces_ownership.json reassigns provinces. Its schema is mod_scenario_provinces_ownership.schema.json.
Province by province:
{ "provinceOwnerOverrides": [
{ "provinceId": 1234, "ownerISO3": "DEU" }
] }
A whole region at once:
{ "regionOwnerOverrides": [
{ "regionName": "WesternEurope", "ownerISO3": "FRA" }
] }
| Field | Type | Description |
|---|---|---|
provinceId | int | Required. A province id, 1 or higher. See Province ids. |
regionName | string | Required. A region name from World regions. Case does not matter. The loader also accepts a name from Continents, which the schema does not list. |
ownerISO3 | string | Required. The new owner, three upper-case letters. |
Region overrides are applied before province overrides, so a province entry wins over the region it lies in.
To leave a province unowned, assign it to a country the scenario removes and does not add back. See Removing countries.
Military deployments
Deployments place the scenario’s starting forces. units_define.json adds unit types; the three units_deploy_*.json files place stacks of units.
Custom unit types
units_define.json holds a unitTypes list. Its schema is mod_scenario_units_define.schema.json.
| Field | Type | Description |
|---|---|---|
id | string | Required. Unique type id, at most 29 bytes. A longer id is cut off. |
category | string | Required. infantry, cavalry, artillery, armor, special_forces, naval or air. |
ownerIso3 | string | Only this country can recruit the unit; everyone else is denied it. The owner keeps every other unit unless the scenario sets restrictOwnersToOwnedUnits. |
displayName | string | Name shown in the game. |
attack, defense, hp, speed | number | Base stats, 0 or higher. |
manpower | int | Manpower cost. |
airAttack, antiAir, range | number | Air-related stats. |
terrainPlains, terrainMountain, terrainDesert, terrainForest, terrainUrban | number | Terrain modifiers. 1.0 is neutral. |
Note the spelling: ownerIso3 here, ownerISO3 in the deployment and ownership files.
A unit type whose id no content file defines (Content/units.json or the scenario’s unitsOverrideFile) becomes a recruitable unit. It copies cost, upkeep, required building, prerequisites and equipment from a base unit chosen by its category, and the fields above replace that unit’s name, stats and terrain modifiers. A field you leave out keeps the base unit’s value.
category | Base unit copied |
|---|---|
infantry | infantry |
cavalry | infantry, with the cavalry map marker |
artillery | artillery |
armor | armor |
special_forces | special_forces |
naval | frigate |
air | fighter |
| any other value | infantry |
When a content file does define the id, that definition is used and the stats here are ignored. Set costs and requirements there; see Content rosters.
Who can recruit a unit type
The game decides in this order:
- A disabled category or unit id (
disabledUnitCategories,disabledUnitTypeIds) is never available. - A country always has the unit types it owns (
ownerIso3). - A country with a roster, a non-empty
militaryUnitTypeIdsinaddCountriesorcountryStateOverrides, recruits only the unit types its roster lists. A roster is an explicit grant: it may list another country’s exclusive unit. - With
restrictOwnersToOwnedUnits, a country that owns unit types recruits nothing else. - A unit type that is exclusive to another country is unavailable.
- Otherwise the unit type is available.
Roster ids are matched without regard to case. Ids that no unit definition has, and rosters for countries the game does not contain, are reported as warnings at game start. A scenario that uses none of these (nothing owned, no rosters, no disabled lists) leaves every unit available.
Stack unit entries
Armies, fleets and air wings all list their units the same way, in a units array.
| Field | Type | Default | Description |
|---|---|---|---|
unitTypeId | string | none | Required. A unit type id. |
unitDefIndex | int | -1 | Index into the country’s unit definition list. -1 resolves it from unitTypeId. |
count | int | 1 | Number of units of this type in the stack. |
currentHp | float | -1 | Health override. -1 is full health. |
Army stacks
units_deploy_armies.json holds an initialArmies list.
| Field | Required | Description |
|---|---|---|
ownerISO3 | yes | Owner country. |
provinceId | yes | A land province id. |
morale | 0 to 1. Leave it out for full morale. | |
units | yes | Array of stack unit entries, at least one. |
Fleet stacks
units_deploy_fleets.json holds an initialFleets list. A fleet takes the same fields as an army, plus inHarbor (bool, default false). provinceId is a sea zone or a coastal province.
Air wing stacks
units_deploy_air.json holds an initialAirWings list. An air wing takes the same fields as an army, plus:
| Field | Description |
|---|---|
missionType | The wing’s starting mission, for example "CloseAirSupport". Values are listed under Air mission types. |
readiness | 0 to 1. Leave it out for full readiness. |