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
| Field | Type | Description |
|---|---|---|
iso3 | string | Required. 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. |
templateISO3 | string | An 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. |
name | string | Display name. |
mapColor | string | Map colour as #RRGGBB. |
mapColorVibrant, mapColorGloomy | string | The country’s colour in the vibrant and gloomy map palettes, as #RRGGBB. Each falls back to mapColor when absent. |
flagPngPath | string | The country’s flag image; see Flag file. |
capital | string | Display name of the capital city. |
capitalProvince | string | The capital’s province: a province name, or a province id written as a string. |
population | int | Total population, spread over the country’s provinces. See Population. |
areaKm2 | number | Territory area in square kilometres. |
governmentType | string | See Government types. |
governmentSubtype | string | See Government subtypes. |
ideology | string | See Ideologies. |
continent | string | See Continents. |
region | string | See World regions. |
homelandTerm | string | The noun the game uses for the homeland, for example "Federation". |
neighbors | string[] | ISO3 codes of land neighbours. |
seaNeighbors | string[] | ISO3 codes of neighbours across the sea. |
militaryUnitTypeIds | string[] | 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. |
neutral | bool | Military 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
| Field | Type | Description |
|---|---|---|
leaderName | string | Name of the starting leader. |
leaderTitle | string | Title of the starting leader, for example "Chancellor". |
leaderGender | string | "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. |
leaderPortraitPath | string | A PNG or JPG inside the mod folder, shown for the starting leader instead of the placeholder. |
leaderNamePool | object[] | Names later leaders are drawn from, instead of the regional pool. Each entry is { "name": "...", "title": "...", "gender": "male" }; title and gender are optional. |
lockLeaderTitle | bool | true keeps leaderTitle on every leader drawn from leaderNamePool, whatever the government becomes. |
dominantReligion | string | Largest religion, for example "Islam". At most 29 bytes. Drives kinship and the religiosity of the interest groups. |
dominantEthnicity | string | Largest ethnic group, for example "Turkish". At most 29 bytes. Drives kinship. |
primaryCulture | string | Culture shown on the country overview, for example "Ottoman". At most 29 bytes. |
ethnicHomogeneity | number | 0 (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,leaderTitleandleaderGenderset the starting leader. A country with aleaderNamePoolbut noleaderNamestarts 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.leaderNamePoolreplaces 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’stitleoverrides 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: truegives every pool entry the country’sleaderTitle, so successors keep it whatever the government type becomes. It needs bothleaderTitleand aleaderNamePool. Without a pool, the regional pool picks successors and the title follows the government type; Validate Mod warns.leaderPortraitPathis 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.jpgfor men and<ISO3>_f_01.jpgfor women (.jpg,.jpegor.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.
militaryUnitTypeIdsandflagPngPathapply per ISO3 in either case.- Not applied:
templateISO3,neighborsandseaNeighbors. - 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
MissileindisabledUnitCategoriesswitches off missile units, not the stockpile. - If
addCountrieslists the same ISO3 twice, only the first entry is applied, with a warning. - A new
namereplaces the base game’scountry.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
maxLengthcounts characters, so it cannot catch this. - Each of the four identity fields (
dominantReligion,dominantEthnicity,primaryCulture,ethnicHomogeneity), when omitted, keeps the template’s value. Without atemplateISO3all 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>anddemographics.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
removeCountriesand 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
countryStateOverridespopulationdoes the same for any country and wins over theaddCountriesone. - An
addCountriespopulationbelow 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 acountryStateOverridespopulationdoes 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
addCountriesalso 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.jsonto 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 }
] }
| Field | Type | Description |
|---|---|---|
iso3 | string | Required. The country to change. |
clearRelationships | bool | Clears this country’s diplomatic state. Default false. |
clearDiplomacyScope | string | "core" or "extended"; see Diplomacy clear scopes. An entry without one uses the header’s scope. |
governmentType | string | New government type; see Government types. |
ideology | string | New ideology; see Ideologies. Changing it reseeds the country’s electorate. |
techLevel | int | Starting 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. |
stability | number | 0.0 to 1.0, a fraction of full stability. 0 or omitted keeps the current value. |
corruption | number | 0.0 to 1.0. Omitted keeps the current value; 0 sets no corruption. |
treasury | number | Treasury balance in the game’s base money unit (US dollars in the base game, not millions). 0 or omitted keeps the current value. |
gdp | number | Annual GDP in the base money unit (not millions). 0 or omitted keeps the current value. |
manpower | int | Available manpower in people (not thousands). 0 or omitted keeps the current value. |
reserve | int | Reserve pool in people (not thousands). 0 or omitted keeps the current value. |
population | int | Starting 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. |
neutral | bool | Sets (true) or clears (false) military neutrality. Omitted keeps the country’s setting. |
militaryUnitTypeIds | string[] | Gives an existing country a unit roster. It replaces an addCountries roster for the same country. |
dominantReligion | string | Sets the largest religion (see Identity and kinship). Omitted keeps the current one. |
dominantEthnicity | string | Sets the largest ethnic group. Omitted keeps the current one. |
primaryCulture | string | Sets the culture shown on the country overview. Omitted keeps the current one. |
ethnicHomogeneity | number | 0 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.