Wiki menu

Country overrides

How a scenario adds, re-skins, removes and adjusts countries: identity, leaders, population, flags and starting state.

Last updated for v0.5.35
On this page

A scenario changes the cast of countries with three lists: addCountries adds a country or re-skins an existing one, removeCountries takes countries out, and countryStateOverrides sets the starting economy, politics and military of a country that exists. This page lists every field of the three and explains how leaders, identity and population behave. The lists live in scenario.json or in the split files named below; see Split-folder scenario.

Adding countries

addCountries, in countries_add.json. The only required field is iso3. The Mod Builder’s Country roster page edits the list. Its schema is mod_scenario_countries_add.schema.json.

{ "addCountries": [
  { "iso3": "OTT", "templateISO3": "TUR", "name": "Ottoman Empire", "mapColor": "#C8392B",
    "capital": "Edirne", "capitalProvince": "Edirne", "population": 9000000,
    "governmentType": "Theocracy", "governmentSubtype": "Sultanate", "ideology": "Islamist",
    "flagPngPath": "flags/OTT.png", "leaderName": "Murad II", "leaderTitle": "Sultan",
    "continent": "Asia", "region": "WesternAsia",
    "dominantReligion": "Islam", "dominantEthnicity": "Turkish", "primaryCulture": "Ottoman" }
] }

Core fields

FieldTypeDescription
iso3stringRequired. Three upper-case letters. Use a code no base-game country has, unless you mean to re-skin that country (see Reusing a base-game code). A code that belongs to a base-game country the scenario removes gives the new country that country’s population pyramid and demographic rates, and the game logs a load warning.
templateISO3stringAn existing country to copy from: economy, military, AI personality, political starting state and every field this entry leaves out. There is no fully custom country. When it is omitted, the country whose ISO3 sorts first (ABW in the base game) is used and a warning is logged; that fallback’s identity fields are not copied. Ignored for a re-skin.
namestringDisplay name.
mapColorstringMap colour as #RRGGBB.
mapColorVibrant, mapColorGloomystringThe country’s colour in the vibrant and gloomy map palettes, as #RRGGBB. Each falls back to mapColor when absent.
flagPngPathstringThe country’s flag image; see Flag file.
capitalstringDisplay name of the capital city.
capitalProvincestringThe capital’s province: a province name, or a province id written as a string.
populationintTotal population, spread over the country’s provinces. See Population.
areaKm2numberTerritory area in square kilometres.
governmentTypestringSee Government types.
governmentSubtypestringSee Government subtypes.
ideologystringSee Ideologies.
continentstringSee Continents.
regionstringSee World regions.
homelandTermstringThe noun the game uses for the homeland, for example "Federation".
neighborsstring[]ISO3 codes of land neighbours.
seaNeighborsstring[]ISO3 codes of neighbours across the sea.
militaryUnitTypeIdsstring[]The country’s unit roster. Non-empty: the country recruits only these unit types plus any it owns. Empty or omitted: the default set. See Who can recruit a unit type.
neutralboolMilitary neutrality. Omitted keeps the template’s setting. An AI-controlled neutral forms no military alliances or defence pacts, gives no guarantees, joins no coalitions and answers no calls to arms. It honours guarantees it already holds and calls its own allies when attacked. A human player is unrestricted.

Leader and identity fields

FieldTypeDescription
leaderNamestringName of the starting leader.
leaderTitlestringTitle of the starting leader, for example "Chancellor".
leaderGenderstring"male" or "female": the starting leader’s gender, which picks a gender-matched portrait. Omitted: the first leaderNamePool entry decides if it has a gender, otherwise the template’s.
leaderPortraitPathstringA PNG or JPG inside the mod folder, shown for the starting leader instead of the placeholder.
leaderNamePoolobject[]Names later leaders are drawn from, instead of the regional pool. Each entry is { "name": "...", "title": "...", "gender": "male" }; title and gender are optional.
lockLeaderTitlebooltrue keeps leaderTitle on every leader drawn from leaderNamePool, whatever the government becomes.
dominantReligionstringLargest religion, for example "Islam". At most 29 bytes. Drives kinship and the religiosity of the interest groups.
dominantEthnicitystringLargest ethnic group, for example "Turkish". At most 29 bytes. Drives kinship.
primaryCulturestringCulture shown on the country overview, for example "Ottoman". At most 29 bytes.
ethnicHomogeneitynumber0 (very diverse) to 1 (homogeneous). Shown on the country overview when a culture or ethnicity is set.

Flag file

flagPngPath names a PNG. The game does not enforce a size; the base game’s flags are 320 pixels wide.

  • A relative path is looked up in the mod folder (the one holding mod.json) first, then in the scenario folder (the split scenario folder, or the folder of a single-file scenario).
  • The path must stay inside the mod folder. An absolute path, or one whose .. leaves the mod folder, is refused: Validate Mod reports an error and the flag does not load.
  • A path that matches no file is reported with the mod’s load problems. The country then shows the base game’s flag for its ISO3 (a re-skin) or an empty flag frame (a new code).
  • A changed flag shows when the scenario is loaded again: a new game, or the Mod Builder’s RELOAD & TEST.

Leader identity

  • leaderName, leaderTitle and leaderGender set the starting leader. A country with a leaderNamePool but no leaderName starts with the pool’s first entry: its name, its title if it has one, its gender. A country that declares neither keeps the template’s leader.
  • leaderNamePool replaces the regional name pool for that ISO3. It also replaces a base-game pool when the entry re-skins a base-game country. Elections, coups, revolutions and leader deaths draw from it. An entry’s title overrides the title the government type would give.
  • Names hold at most 61 bytes of UTF-8 and titles 29. Longer ones are shortened, and Validate Mod says so.
  • lockLeaderTitle: true gives every pool entry the country’s leaderTitle, so successors keep it whatever the government type becomes. It needs both leaderTitle and a leaderNamePool. Without a pool, the regional pool picks successors and the title follows the government type; Validate Mod warns.
  • leaderPortraitPath is shown for the starting leader. A relative path is tried against the mod folder, then the scenario folder, and the file must lie inside the mod folder. An absolute path, or one that climbs out with ../, is refused: an error in Validate Mod, and the placeholder is shown.
  • Leaders who take over later use the mod’s portraits/<ISO3>/ folder when you ship it: files named <ISO3>_m_01.jpg for men and <ISO3>_f_01.jpg for women (.jpg, .jpeg or .png, numbered from 01). The picture is chosen by leader number, so every player sees the same one. Without that folder they get the base game’s portrait for that country if it has one, otherwise the placeholder.

Leader titles and homeland terms are shown translated when your localization files define a key for them under country.leader_title. and country.homeland.term.; otherwise the text is shown as written.

The name pools are rebuilt from the loaded scenario each session. They are not saved, and a loaded game gets them back.

Reusing a base-game code

An entry whose iso3 the base game already has (for example FRA in a 1450 scenario) does not create a second country. It is a re-skin: its fields are applied onto the existing country.

  • Applied: name, map colours, leader, government, ideology (which reseeds the electorate, as a state override does), neutrality, homeland term, area, capital, continent, region, the identity fields and population.
  • militaryUnitTypeIds and flagPngPath apply per ISO3 in either case.
  • Not applied: templateISO3, neighbors and seaNeighbors.
  • Anything the entry leaves out keeps the existing country’s value. The country keeps its own provinces, economy, military, relations and politics. Use State overrides and Province and region ownership to change those.
  • The country keeps its starting missile stockpile (nuclear warheads, cruise and ballistic missiles). Listing Missile in disabledUnitCategories switches off missile units, not the stockpile.
  • If addCountries lists the same ISO3 twice, only the first entry is applied, with a warning.
  • A new name replaces the base game’s country.name.<ISO3> text in every language your localization CSV does not translate. Put translations there; see Localization.

A re-skinned country keeps its base-game land. It keeps every base-game province that no ownership override reassigns, even when removeCountries also lists it, and its declared population is spread over those provinces too. A 1450 COL (Electorate of Cologne) that is only given one German province also owns every province Colombia has in the base game, and most of its people would live there. Give each such province to a country in provinces_ownership.json, or leave it unowned as described under Removing countries.

Identity and kinship

Two countries with the same dominantReligion, or the same dominantEthnicity, are kin: their relations warm over time, and the AI is slower to attack them and quicker to ally with them.

  • These labels are never kin, and neither is an empty value: Other, Mixed, None, Unknown, Black, White, European, European_Descent, South_Asian.
  • A label is stored in 29 bytes of UTF-8. That is 29 ASCII letters, but fewer accented or non-Latin ones: a Cyrillic letter takes 2 bytes, a CJK character 3. A longer label is cut short and a warning is logged. The schema’s maxLength counts characters, so it cannot catch this.
  • Each of the four identity fields (dominantReligion, dominantEthnicity, primaryCulture, ethnicHomogeneity), when omitted, keeps the template’s value. Without a templateISO3 all four start empty rather than inheriting the fallback’s, and the country has no kin. A re-skin applies the fields it sets and keeps the rest.
  • Labels are shown translated through the localization keys demographics.religion.<Label> and demographics.identity.<Label>. A label without a key is shown as written, with underscores as spaces.

Population

A declared population is made true of the provinces, not only of the country record.

  • Once removeCountries and the ownership overrides are done, the country’s provinces are rescaled in proportion to their base-game populations so that they sum exactly to the declared figure. Each province keeps at least 100 people when the total allows it.
  • A country that owns no province keeps the figure only until the first monthly population update; a warning is logged.
  • A countryStateOverrides population does the same for any country and wins over the addCountries one.
  • An addCountries population below the template’s (or, for a re-skin, below the country’s own) also scales down the AI’s peacetime army floor, which the country otherwise inherits from its template. A country with a tenth of the people keeps a tenth of it. A larger population does not raise it, and a countryStateOverrides population does not change it.
  • Provinces left unowned keep their base-game people unless the header sets unownedProvincePopulationScale; see Scenario header fields.
  • A single province’s population can be set directly with Scenario province data, which is applied after the country totals.

All of this happens once, when a new game starts. Saves and multiplayer joins keep the populations they carry.

Removing countries

removeCountries, in countries_remove.json: an array of ISO3 strings.

{ "removeCountries": ["XXX", "YYY"] }
  • An ISO3 that addCountries also lists is never removed. Its entry re-skins the existing country instead, and the country keeps every base-game province that no ownership override reassigns.
  • To leave a province unowned, assign it in provinces_ownership.json to a country your scenario removes and does not add back. After the ownership overrides, land held by a removed country becomes unowned land.
  • A removed country takes its base-game military with it: its armies, fleets and air wings are destroyed at game start.
  • Loading a save never removes stacks. The save already holds the stacks the game had.

State overrides

countryStateOverrides, in countries_state.json: one entry per country whose starting state you change. The Mod Builder’s Starting states page edits the list. Its schema is mod_scenario_countries_state.schema.json.

{ "countryStateOverrides": [
  { "iso3": "FRA", "governmentType": "Monarchy", "stability": 0.6, "corruption": 0.3,
    "treasury": 2500000, "gdp": 40000000, "manpower": 60000, "population": 15000000 }
] }
FieldTypeDescription
iso3stringRequired. The country to change.
clearRelationshipsboolClears this country’s diplomatic state. Default false.
clearDiplomacyScopestring"core" or "extended"; see Diplomacy clear scopes. An entry without one uses the header’s scope.
governmentTypestringNew government type; see Government types.
ideologystringNew ideology; see Ideologies. Changing it reseeds the country’s electorate.
techLevelintStarting Knowledge Network level, 0 to 10. Tiers 1 to techLevel of every doctrine branch start completed, except branches hidden by disabledDoctrineBranches. A branch has 5 tiers, so 6 to 10 act as 5. Tiers the country already has are kept. New games only. 0 or omitted grants nothing.
stabilitynumber0.0 to 1.0, a fraction of full stability. 0 or omitted keeps the current value.
corruptionnumber0.0 to 1.0. Omitted keeps the current value; 0 sets no corruption.
treasurynumberTreasury balance in the game’s base money unit (US dollars in the base game, not millions). 0 or omitted keeps the current value.
gdpnumberAnnual GDP in the base money unit (not millions). 0 or omitted keeps the current value.
manpowerintAvailable manpower in people (not thousands). 0 or omitted keeps the current value.
reserveintReserve pool in people (not thousands). 0 or omitted keeps the current value.
populationintStarting population, spread over the country’s provinces as described under Population. Wins over an addCountries population for the same country. 0 or omitted keeps the current one.
neutralboolSets (true) or clears (false) military neutrality. Omitted keeps the country’s setting.
militaryUnitTypeIdsstring[]Gives an existing country a unit roster. It replaces an addCountries roster for the same country.
dominantReligionstringSets the largest religion (see Identity and kinship). Omitted keeps the current one.
dominantEthnicitystringSets the largest ethnic group. Omitted keeps the current one.
primaryCulturestringSets the culture shown on the country overview. Omitted keeps the current one.
ethnicHomogeneitynumber0 to 1. Omitted keeps the current value.

treasury and gdp are absolute: they are applied after the header’s gdpScale and are not multiplied by it.

Play Global Protocol: New World Order

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