Balance and rule changes live outside the scenario’s country and ownership lists. This page covers the files that change numbers and rules: the sparse overrides/ documents with game_settings.json at their centre, national currencies, demography, per-province scenario data and scenario victories. Every file here is optional. Files that change content (buildings, units, doctrines, laws, events) are on Data overrides: content.
- Config override files
- Game settings
- Game flow
- Currencies
- Demography
- Scenario province data
- Scenario victories
Config override files
The files in a mod’s overrides/ folder are sparse documents against the base game’s config: write only the keys you want to change.
| File | Covers | Documented at |
|---|---|---|
overrides/game_settings.json | Balance sections: population, economy, technology, diplomacy, world order, AI weights, intelligence, fog of war, map interaction, satellites, political drift, military, buildings, the mod-only nuclear section, plus events and envoys. | Game settings |
overrides/events.json, overrides/envoys.json, overrides/game_flow.json | The game_settings sections of the same names, as separate files. | Game settings, Game flow |
overrides/doctrines.json | Doctrine values, effects and text; whole-branch replacement; added branches and tiers. | Doctrines, Mod research |
overrides/laws.json | Law values, appended categories and options, disabled options. | Laws |
overrides/interest_groups.json | The electorate: age bands, interest groups, law and doctrine bonuses, country overrides. | Interest groups |
overrides/military_markers.json | Map marker pictures for units. | Marker art |
overrides/localization_<language>.csv | Text, at the older location. Use Content/localization/ for new mods. | Localization |
When several enabled mods override the same key, the mod that loads later wins. See Load order, dependencies and game version.
Game settings
overrides/game_settings.json is a sparse copy of the base game’s game_settings.json. A key you write replaces the shipped value, and every key you leave out keeps it. Nested objects use the same names as the shipped file:
{
"economy": { "central_bank": { "ai_rate_adjust_speed": 0.4 } },
"step42_diplomacy": { "guarantee": { "expire_ticks": 240 } },
"political_drift": { "corruption_target_convergence_rate": 0.05 },
"events": { "max_flags_per_country": 96 }
}
The file’s schema is game_settings.schema.json, which lists every key with a description; see JSON schemas. The Mod Builder’s Game settings page edits the file.
Sections the game applies
| Sections | How they are applied |
|---|---|
population, diplomacy, advanced_diplomacy, world_order, ai_weights, fog_of_war, intelligence, map_interaction, satellite, economy, technology, step42_diplomacy, political_drift, nuclear | Laid over the running game’s config when the mods load. |
military, buildings | Applied through the military and building configs, which are rebuilt with your values. |
events, envoys, game_flow | Read by their own loading stage. Each can also be written as its own file: overrides/events.json, overrides/envoys.json, overrides/game_flow.json. |
step42_diplomacy holds guarantees, rivals, aggressive expansion, coalitions, opinion, trust and embassies. political_drift holds drift, elections, coups, corruption and the stability target.
- A top-level key that starts with
_, and$schema, are treated as comments and skipped. - Any other top-level section is not applied. The Mod Builder’s RELOAD & TEST message and Validate Mod name it.
- Inside an applied section, a key the game cannot place is listed in
Player.logas unknown and skipped. - Values are written as you give them, without the range clamping the base game’s own import applies. Keep them sensible.
Keys with no effect
These keys exist in the shipped file, but a mod’s value for them does not reach the running game:
economy.price_shock_decay_rateeconomy.resource_strategic_caps(the whole block)economy.trade_agreement_defaults(the whole block)economy.terrain_productivity(province terrain multipliers come from province data)economy.trade(the whole block), except three money floors that do apply:economy.trade.negotiation.min_offer_usd,economy.trade.private_finance.floor_usdandeconomy.trade.throughput.bonus_scale_usdstep42_diplomacy.sphere(the whole block)
One key applies only as a fallback: satellite.max_per_facility. Launch capacity comes from a building effect, and this key is read only when no building in the roster carries that effect. See Satellite launch capacity.
The nuclear section
nuclear is mod-only: it has no counterpart in the shipped game_settings.json. It overrides the base game’s nuclear_config.json and takes that file’s sub-objects with the same key names: nuclear_consequences, recovery, fallout, deterrence, missile_defense, retaliation, defcon_escalation and ai_first_strike. The DEFCON level table and the missile type list cannot be patched.
A stronger missile shield, for example (the base values are 0.6 and 0.3):
{ "nuclear": { "missile_defense": { "base_intercept_chance": 0.8, "radar_bonus_cap": 0.4 } } }
Money amounts and scenario scale
When the active scenario sets gdpScale, the base game’s fixed money amounts in game_settings.json are multiplied by it. An amount your mod writes in overrides/game_settings.json is taken as your scenario’s own money and used as written. See Scenario header fields.
Event timing keys
The events section holds the numbers the event engine runs on, such as generated_post_event_cooldown_days, reactive_post_event_cooldown_days, player_event_auto_decide_days, repeatable_immediate_min_cooldown_days, max_active_events_per_country, max_flags_per_country and chain_event_delay_months. What each one does is described under When events fire.
Game flow
The game_flow section (or overrides/game_flow.json) holds autosave_interval_seconds, autosave_enabled, max_save_slots and default_player_country. These are each player’s own settings, stored in the player’s settings file and changed from the Settings screen. The loader reads a mod’s game_flow, but the player’s values are the ones in force, so a mod cannot change them in practice. The Mod Builder does not offer the section.
Currencies
Countries can show money in their own currency. This is display only: the simulation keeps one money unit, the base currency, and every amount is converted when it is shown. Currencies are therefore not part of the multiplayer lobby check.
The file is Content/currencies.json. A scenario can also name one with currenciesFile in its header. The schema is mod_currencies.schema.json, and the Mod Builder’s Currencies page edits the file.
{
"baseCurrency": { "id": "florin", "name": "Florin", "symbol": "fl." },
"currencies": [
{ "id": "akce", "name": "Ottoman Akçe", "symbol": "ak.", "symbolPosition": "suffix",
"exchangeRateToBase": 45.0, "associatedCountries": ["OTT", "CRA"] }
]
}
| Field | Type | Description |
|---|---|---|
baseCurrency.id, baseCurrency.name | string | Id and display name of the unit the simulation counts in. |
baseCurrency.symbol | string | 1 to 8 characters. Shown to spectators, in menus and for countries without a currency. The scenario header’s currencySymbol wins over it. |
baseCurrency.symbolPosition | string | "prefix" (default) or "suffix". |
currencies[].id | string | Required. Lower-case letters, digits and underscores. |
currencies[].name | string | Display name. |
currencies[].symbol | string | Required. 1 to 8 characters. |
currencies[].symbolPosition | string | "prefix" (default) or "suffix". |
currencies[].exchangeRateToBase | number | Required. Local units per one base unit. Must be above 0. |
currencies[].associatedCountries | string[] | ISO3 codes of the countries that use the currency. |
era | string | A free-form label for the author. The game does not read it. |
- At a rate of 45, an amount of 1,000 in the base currency is shown to an Ottoman player as
45.0K ak.. - A currency without an id, without a symbol, or with a rate that is not a positive number is dropped with a warning.
- A leading symbol of two or more characters that ends in a letter or
.is written with a space:fl. 1.2K. - A country listed under two currencies keeps the first one, with a warning.
- Files stack like content rosters: every active mod’s
Content/currencies.jsonin load order, then the scenario’scurrenciesFile. A later file replaces a currency with the sameid, and itsbaseCurrencyreplaces the base fields it sets. - Each player sees their own country’s currency. Spectators, menus and countries without a currency see the base currency. Settings › Gameplay › Show money in the base currency switches every amount to the base currency.
- Money written directly into localized prose keeps the symbol the text was written with.
Demography
A mod can give countries their own starting age pyramids and demographic rates, and can replace sections of the demography model. The files are Content/demography/seeds.json and Content/demography/model.json. Their schemas are mod_demography_seeds.schema.json and mod_demography_model.schema.json. The Mod Builder’s Demography page edits them.
{
"countries": {
"TUR": { "bands": [0.2, 0.25, 0.3, 0.25], "region": "WesternAsia", "tfr": 1.6 },
"ATL": { "template": "NLD", "le": 82 }
}
}
Seed rows
Each key of countries is a three-letter ISO3 code. A row gives the country’s starting age pyramid and demographic scalars. Only the shape of the pyramid matters: it is scaled to the country’s population.
| Field | Description |
|---|---|
cohorts | male and female arrays of 101 whole-number headcounts, one per year of age from 0 to 100. |
bands | Exactly four shares: youth (0 to 18), young (19 to 36), middle (37 to 56) and senior (57 and over). They must sum to 1, within 0.01. The shares are spread over single years using the region template. |
region | A name from World regions, written exactly, for example WesternAsia. Its template shape fills in what the row does not give. Omitted: the World template. |
template | ISO3 of another row to start from. A row cannot be its own template. |
le, le_male, le_female | Life expectancy at birth, in years. Must lie inside the model’s life-table grid. |
tfr | Total fertility rate. Must lie inside the model’s fertility grid. |
sex_ratio_at_birth | Male births per female birth, 0.9 to 1.2. |
cbr_target, cdr_target | Calibration targets: crude birth rate and crude death rate, per thousand. |
calibration | mortality_child, mortality_adult and fertility factors, each above 0. |
- What a row leaves out is inherited from the country’s shipped row, its
template, or the region template. - A row that breaks a rule is skipped, with a message in the log and in the Validate Mod report. A
regionthat is not a world region name (for example a continent such asEurope) is such a rule. - A scenario country that names a
templateISO3and has no row here inherits that template’s row, when a mod ships demography. - Rows apply to a new game only: seeds are read at game start, and a loaded save keeps its pyramids. With no demography file the shipped model is used unchanged.
Model sections
model.json replaces whole sections of the shipped demography model: sex_gap_male_weight, mortality, fertility, migration, crisis_excess_shape, preston, region_templates and world_reference_bands. A section you write must be complete and must pass the same validation as the shipped file. If it is rejected, the shipped tables stay.
Scenario province data
A scenario can set the population, terrain and resource deposits of single provinces. Name the file in scenario.json with "provinceDataFile": "provinces_data.json", relative to the scenario folder. The schema is mod_scenario_provinces_data.schema.json.
{
"provinces": {
"1021": { "population": 250000 },
"1022": { "terrain": "Mountain", "resources_mode": "add", "resources": [ { "resource": "Iron", "intensity": 0.8 } ] }
}
}
Keys are land province ids, 1 to 5000 (see Province ids). Every field is optional, and an unset field keeps the shipped value. An entry that changes nothing is reported.
| Field | Description |
|---|---|
population | People in the province at the start, 0 to 5,000,000,000. Written when a new game starts, after the scenario’s declared country populations, so a province entry wins over the spread of a declared country total. The owning country’s total, GDP per capita and age pyramid follow. A loaded save keeps what it saved. |
terrain | Plains, Mountain, Desert, Forest, Jungle, Tundra, Coastal, Urban or Wetland. Replaces the province’s terrain for movement, combat, building sites and the terrain map mode. The map’s terrain colours do not change. Ocean is refused. |
resources | Latent deposits: a list of at most 8 entries, each with a resource name (for example Oil, Iron, Wheat) and an intensity above 0 and at most 1. A resource may be listed once. |
resources_mode | replace (default): the province has exactly the listed deposits, and an empty list removes them all. add: the listed deposits join the shipped ones, and a resource that is already there is overwritten. |
- In replace mode the strongest listed resource becomes the province’s produced resource in a new game.
- Terrain and resources are static data. They are applied again every time the world starts, so loaded saves see them too.
- Starting buildings are not covered.
- Unknown province ids, terrains and resources are reported by Validate Mod, and the entry is skipped.
Scenario victories
A scenario can end the game in ways of its own. The header’s victoryFile names a JSON file in the scenario folder. The game loads whatever file the header names; the Mod Builder’s Endings page creates it as victories.json. The schema is mod_scenario_victory.schema.json. The file has three optional parts:
{
"disable_base_victories": true,
"mod_victories": [
{ "id": "atlantis_saved", "title_key": "mymod.end.saved", "description_key": "mymod.end.saved.desc",
"outcome": "victory", "winner": "player", "min_year": 2040,
"conditions": [
{ "type": "has_flag", "flag_name": "atlantis_gate_sealed" },
{ "type": "lifetime_lt", "counter": "civilians_affected", "value": 1000000 },
{ "type": "variable_gt", "variable": "refugees_saved", "scope": "mod", "value": 50 } ] },
{ "id": "world_lost", "title_key": "mymod.end.lost", "outcome": "defeat", "winner": "any",
"conditions": [ { "type": "has_flag", "flag_name": "atlantis_flooded" } ] }
],
"end_screen_rows": [
{ "label_key": "mymod.row.ships", "value": "lifetime.ships_lost" },
{ "label_key": "mymod.row.refugees", "value": "mod_state.refugees" } ]
}
Endings
mod_victories lists the scenario’s endings. They are checked once a month, in file order. For each ending the countries it names are tried in ISO3 order, and the first country for which all the conditions hold is the winner: the game ends, the end screen opens with the ending’s title, and the on_game_ended script hook fires.
| Field | Default | Description |
|---|---|---|
id | none | Required. Unique in the file. The saved game remembers the ending by it. |
title_key | none | Required. Text key of the title shown on the end screen. Define it in your localization files. |
description_key | none | Text key of a line shown under the title. |
outcome | "victory" | "victory" shows the victory screen when the winner is the player. "defeat" shows the defeat screen even though the conditions held, for an ending such as a world that ended. |
winner | "player" | Who is tried: "player" (the human players), "any" (every country that still exists) or a three-letter country code (only that country). |
min_year | 0 | The ending is not checked before this calendar year. 0 means no limit. |
conditions | none | All must hold for the winner. An ending with no conditions holds at its first check. |
Conditions use the event condition format with the same fields, limited to these types: has_flag, not_has_flag, flag_age_months_gt, flag_age_months_lt, variable_gt, variable_lt, variable_eq (with scope "country" or "mod"), lifetime_gt, lifetime_lt, date_after and date_before. They test the country being tried as the winner. A condition with a target_country, or of another type, is rejected and the ending is dropped; the load log and Validate Mod say which. The types are described under Conditions, Flags and variables and Lifetime counters.
Turning the base victories off
"disable_base_victories": true stops the five base victories (military, economic, diplomatic, technological and nuclear) from being checked in this scenario, so only your endings can end the game. The default is false.
End-screen rows
end_screen_rows adds lines to the end screen’s mod record. They are shown on every end screen of this scenario, whichever way the game ended. Each row needs a label_key (a text key of your mod) and a value:
value | Shows |
|---|---|
lifetime.<counter> | A lifetime counter of the player’s country, for example lifetime.ships_lost. |
mod_state.<key> | A value from your mod’s own saved state. |
variable.<name> | An event variable of the player’s country. |
wave.<wave id>.remaining | Units still alive in an invasion wave of your mod. Also .remaining_stacks, .spawned and .spawned_stacks. |
Scripts add rows with register_end_screen_row (WASM) or IModServices.RegisterEndScreenRow (C#); see the WASM scripting page.
Multiplayer and checks
Every player’s game checks the same endings in the same order, so every player’s game picks the same winner on the same tick. The ending reached is saved with the game and is part of the state hash. Validate Mod checks the file: duplicate ids, a missing title, a condition a victory cannot use, an unknown lifetime counter in a row. A game without a victory file runs none of this.