Wiki menu

Scenario files

The scenario header, split scenario files, starting diplomacy, world ceasefire, province ownership and starting military deployments.

Last updated for v0.5.35
On this page

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.

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:

FileRoot keyHolds
countries_add.jsonaddCountriesCountries to add or re-skin (Adding countries)
countries_remove.jsonremoveCountriesCountries to remove (Removing countries)
countries_state.jsoncountryStateOverridesStarting economy, politics and military of existing countries (State overrides)
diplomacy.jsonstartingDiplomacyDay-one organizations, alliances, treaties, wars and relations (Starting diplomacy)
provinces_ownership.jsonprovinceOwnerOverrides, regionOwnerOverridesProvince and region reassignments (Province and region ownership)
units_define.jsonunitTypesCustom unit types (Custom unit types)
units_deploy_air.jsoninitialAirWingsAir wing placements (Air wing stacks)
units_deploy_armies.jsoninitialArmiesArmy placements (Army stacks)
units_deploy_fleets.jsoninitialFleetsFleet 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.json itself accepts.
  • Lists are appended. A later file adds to what an earlier file or scenario.json listed; 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

FieldTypeDefaultDescription
scenarioIdstringnoneRequired. Unique identifier of the scenario.
displayNamestringemptyDisplay name of the scenario.
versionstringemptyVersion text, for example 1.0.0.
startYearint0Year the game starts in, from 1 to 3000. 0 or absent keeps the base game’s start year.
startMonthint11 to 12.
startDayint11 to 31 in the schema. The game’s months have 30 days.
startTickint0Absolute tick to start on. 0 derives the tick from the date.
economicEraLabelstringemptyAccepted and stored with the scenario. No game system reads it.

Diplomacy reset

FieldTypeDefaultDescription
clearDiplomaticRelationshipsboolfalseWipes the base game’s diplomatic relationships before the scenario’s own are written.
clearDiplomacyScopestring"extended""core" or "extended": how much is wiped. See Diplomacy clear scopes. Wars are only cleared by "extended".
rebuildNeutralRelationsbooltrueAfter clearing, gives every pair of countries a neutral relation row again.

Money and population scale

FieldTypeDefaultDescription
gdpScalefloat1.0Multiplies every country’s money once, when a new game starts. Must be above 0. See below.
unownedProvincePopulationScalefloat1.0Multiplies 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.
currencySymbolstring"$"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.

  • countryStateOverrides values are absolute and are applied after the scale. A country whose gdp is 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.json or overrides/laws.json is already your scenario’s money and is used as written.
  • Pick the scale your own numbers use. If countryStateOverrides set the GDPs, gdpScale should 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.

FieldNamesDocumented at
nationalGoalsFileThe scenario’s national goals. By default it replaces the base game’s goals for the Agenda and the AI.National goals
victoryFileThe scenario’s own endings, extra end-screen rows, and the switch that turns the base victories off.Scenario victories
provinceDataFilePer-province population, terrain and resource deposits.Scenario province data
currenciesFileNational currencies. Applied after every mod’s Content/currencies.json.Currencies
buildingsOverrideFileA buildings roster. Applied after every mod’s Content/buildings.json.Content rosters
unitsOverrideFileA units roster.Content rosters
resourcesOverrideFileA resources file.Resources
techOverrideFileIgnored. Research is the Knowledge Network. A file named here only produces a message pointing at overrides/doctrines.json.Doctrines

Disabled content

FieldTypeDescription
disabledUnitCategoriesstring[]Unit categories removed from recruitment and build eligibility: Ground, Air, Naval, Missile, Special. See Unit categories.
disabledUnitTypeIdsstring[]Specific unit ids, same effect.
restrictOwnersToOwnedUnitsboolDefault 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.
disabledBuildingCategoriesstring[]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.
disabledBuildingIdsstring[]Specific building ids, same effect. To drop most of the base roster, use a replace-mode roster instead; see Roster modes.
disabledDoctrineBranchesstring[]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

FieldTypeDefaultDescription
idstringnoneRequired. 4 to 24 upper-case letters, digits or underscores, never starting with IDX. It is the organization’s identity in saves and multiplayer.
nameKeystringemptyLocalization 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.
typestringCollectiveDefenseCollectiveDefense, Economic, Political or InternationalOrg. An unknown value is read as CollectiveDefense with a warning.
founderstringemptyISO3. The founder is a member.
membersstring[]emptyThe other members, joined in list order.
  • A CollectiveDefense organization 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

typeMeaningmonths
napNon-aggression pact between a and b.Not used.
truceTruce between a and b.Required, at least 1, in 30-day months. A truce without it is skipped with a warning.
trade_agreementTrade agreement between a and b on the default terms.Not used.
guaranteea 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

FieldTypeDefaultDescription
idstringwarA label used in log messages.
attackersstring[]noneRequired, at least one country. The first is the lead attacker.
defendersstring[]noneRequired, at least one country. The first is the lead defender.
casusBellistringScriptedScripted, 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.
callAlliesboolfalseWhen 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 casusBelli it 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

FieldTypeDefaultDescription
a, bstringnoneRequired. The entry sets how a sees b.
opinionintunset-100 to 100: how much a likes b.
trustintunset-100 to 100: how much a trusts b.
mutualboolfalseAlso sets b’s view of a to the same values.
anchorboolfalseMakes the values the level that relations drift back to, so they do not fade towards the regional baseline.
rivalboolfalseMakes 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
  }
}
FieldDefaultDescription
startDateThe scenario’s first dayYYYY-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.
endDateNoneYYYY-MM-DD. The ceasefire ends on this day.
untilFlagNoneThe ceasefire also ends the moment any country holds the event flag with this name (written by a set_flag effect).
countriesEvery countryISO3 codes. A pair of countries is covered only when both are listed.
blockDeclarationstrueA 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.
suspendWarstrueThe 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" }
] }
FieldTypeDescription
provinceIdintRequired. A province id, 1 or higher. See Province ids.
regionNamestringRequired. A region name from World regions. Case does not matter. The loader also accepts a name from Continents, which the schema does not list.
ownerISO3stringRequired. 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.

FieldTypeDescription
idstringRequired. Unique type id, at most 29 bytes. A longer id is cut off.
categorystringRequired. infantry, cavalry, artillery, armor, special_forces, naval or air.
ownerIso3stringOnly this country can recruit the unit; everyone else is denied it. The owner keeps every other unit unless the scenario sets restrictOwnersToOwnedUnits.
displayNamestringName shown in the game.
attack, defense, hp, speednumberBase stats, 0 or higher.
manpowerintManpower cost.
airAttack, antiAir, rangenumberAir-related stats.
terrainPlains, terrainMountain, terrainDesert, terrainForest, terrainUrbannumberTerrain 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.

categoryBase unit copied
infantryinfantry
cavalryinfantry, with the cavalry map marker
artilleryartillery
armorarmor
special_forcesspecial_forces
navalfrigate
airfighter
any other valueinfantry

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:

  1. A disabled category or unit id (disabledUnitCategories, disabledUnitTypeIds) is never available.
  2. A country always has the unit types it owns (ownerIso3).
  3. A country with a roster, a non-empty militaryUnitTypeIds in addCountries or countryStateOverrides, recruits only the unit types its roster lists. A roster is an explicit grant: it may list another country’s exclusive unit.
  4. With restrictOwnersToOwnedUnits, a country that owns unit types recruits nothing else.
  5. A unit type that is exclusive to another country is unavailable.
  6. 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.

FieldTypeDefaultDescription
unitTypeIdstringnoneRequired. A unit type id.
unitDefIndexint-1Index into the country’s unit definition list. -1 resolves it from unitTypeId.
countint1Number of units of this type in the stack.
currentHpfloat-1Health override. -1 is full health.

Army stacks

units_deploy_armies.json holds an initialArmies list.

FieldRequiredDescription
ownerISO3yesOwner country.
provinceIdyesA land province id.
morale0 to 1. Leave it out for full morale.
unitsyesArray 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:

FieldDescription
missionTypeThe wing’s starting mission, for example "CloseAirSupport". Values are listed under Air mission types.
readiness0 to 1. Leave it out for full readiness.

Play Global Protocol: New World Order

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