Wiki menu

Data overrides: rules and numbers

Mod files that change rules and numbers: game settings, currencies, demography, scenario province data and scenario victories.

Last updated for v0.5.35
On this page

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

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.

FileCoversDocumented at
overrides/game_settings.jsonBalance 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.jsonThe game_settings sections of the same names, as separate files.Game settings, Game flow
overrides/doctrines.jsonDoctrine values, effects and text; whole-branch replacement; added branches and tiers.Doctrines, Mod research
overrides/laws.jsonLaw values, appended categories and options, disabled options.Laws
overrides/interest_groups.jsonThe electorate: age bands, interest groups, law and doctrine bonuses, country overrides.Interest groups
overrides/military_markers.jsonMap marker pictures for units.Marker art
overrides/localization_<language>.csvText, 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

SectionsHow they are applied
population, diplomacy, advanced_diplomacy, world_order, ai_weights, fog_of_war, intelligence, map_interaction, satellite, economy, technology, step42_diplomacy, political_drift, nuclearLaid over the running game’s config when the mods load.
military, buildingsApplied through the military and building configs, which are rebuilt with your values.
events, envoys, game_flowRead 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.log as 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_rate
  • economy.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_usd and economy.trade.throughput.bonus_scale_usd
  • step42_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"] }
  ]
}
FieldTypeDescription
baseCurrency.id, baseCurrency.namestringId and display name of the unit the simulation counts in.
baseCurrency.symbolstring1 to 8 characters. Shown to spectators, in menus and for countries without a currency. The scenario header’s currencySymbol wins over it.
baseCurrency.symbolPositionstring"prefix" (default) or "suffix".
currencies[].idstringRequired. Lower-case letters, digits and underscores.
currencies[].namestringDisplay name.
currencies[].symbolstringRequired. 1 to 8 characters.
currencies[].symbolPositionstring"prefix" (default) or "suffix".
currencies[].exchangeRateToBasenumberRequired. Local units per one base unit. Must be above 0.
currencies[].associatedCountriesstring[]ISO3 codes of the countries that use the currency.
erastringA 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.json in load order, then the scenario’s currenciesFile. A later file replaces a currency with the same id, and its baseCurrency replaces 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.

FieldDescription
cohortsmale and female arrays of 101 whole-number headcounts, one per year of age from 0 to 100.
bandsExactly 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.
regionA name from World regions, written exactly, for example WesternAsia. Its template shape fills in what the row does not give. Omitted: the World template.
templateISO3 of another row to start from. A row cannot be its own template.
le, le_male, le_femaleLife expectancy at birth, in years. Must lie inside the model’s life-table grid.
tfrTotal fertility rate. Must lie inside the model’s fertility grid.
sex_ratio_at_birthMale births per female birth, 0.9 to 1.2.
cbr_target, cdr_targetCalibration targets: crude birth rate and crude death rate, per thousand.
calibrationmortality_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 region that is not a world region name (for example a continent such as Europe) is such a rule.
  • A scenario country that names a templateISO3 and 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.

FieldDescription
populationPeople 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.
terrainPlains, 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.
resourcesLatent 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_modereplace (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.

FieldDefaultDescription
idnoneRequired. Unique in the file. The saved game remembers the ending by it.
title_keynoneRequired. Text key of the title shown on the end screen. Define it in your localization files.
description_keynoneText 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_year0The ending is not checked before this calendar year. 0 means no limit.
conditionsnoneAll 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:

valueShows
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>.remainingUnits 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.

Play Global Protocol: New World Order

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