Wiki menu

Old World Order: the scenario

How Old World Order builds the world of 1450 from the files in its scenario folder, file by file, with real excerpts and the traps to avoid.

Last updated for v0.5.35
On this page

Everything that makes the Old World Order map a map of 1450 is in one folder: scenario/. This page goes through its files one by one, shows a few real lines of each, and points out the mistakes the mod’s own tools exist to catch. The three roster files in the same folder (units, buildings, resources) are on the content page.

How the folder is read

The manifest’s scenarioFolder points at the folder. The game reads scenario.json first, then merges the fragment files it finds, in a fixed order. Every fragment is optional, and the game looks for these exact names:

FileHoldsIn Old World Order
scenario.jsonThe headerStart date, money scale, file names, disabled lists
countries_add.jsonNew countries137 entries
countries_remove.jsonCountries to removeThe base game’s modern countries
countries_state.jsonEach country’s starting state137 entries
diplomacy.jsonDay-one diplomacyOrganizations, alliances, treaties, wars, relations
provinces_ownership.jsonWho owns which province3,593 entries, generated by a tool
units_define.jsonScenario unit types33 ids (see content)
units_deploy_armies.jsonStarting armies141 stacks
units_deploy_fleets.jsonStarting fleets34 fleets

The header names the other files itself, with paths relative to the scenario folder: national_goals.json, victory.json, provinces_data.json, currencies.json, and the three rosters units_override.json, buildings_override.json and resources_override.json.

The header: scenario.json

scenario/scenario.json, with the list of disabled unit ids shortened:

{
    "scenarioId": "old_world_order.1450",
    "displayName": "Old World Order (1450)",
    "version": "0.10.0",
    "startYear": 1450,
    "startMonth": 1,
    "startDay": 1,
    "gdpScale": 0.001,
    "unownedProvincePopulationScale": 0.035,
    "economicEraLabel": "Florins",
    "currencySymbol": "fl.",
    "nationalGoalsFile": "national_goals.json",
    "victoryFile": "victory.json",
    "provinceDataFile": "provinces_data.json",
    "clearDiplomaticRelationships": true,
    "clearDiplomacyScope": "extended",
    "rebuildNeutralRelations": true,
    "unitsOverrideFile": "units_override.json",
    "disabledUnitCategories": ["Air", "Missile", "Special"],
    "disabledUnitTypeIds": ["infantry", "mechanized_infantry", "armor", "..."],
    "buildingsOverrideFile": "buildings_override.json",
    "resourcesOverrideFile": "resources_override.json",
    "currenciesFile": "currencies.json",
    "disabledDoctrineBranches": ["cyber", "space", "energy"]
}
  • scenarioId is the only required field.
  • gdpScale multiplies every country’s GDP, trade, treasury and opening budgets once, when a new game starts. It also converts the base game’s fixed money amounts, such as law change costs and intelligence mission costs. Values in countries_state.json are absolute and are applied after it.
  • unownedProvincePopulationScale shrinks the population of land nobody owns at the start, so unclaimed land does not carry its modern headcount.
  • currencySymbol is the symbol of the base currency. It wins over the base symbol in the currencies file.
  • The three clear… and rebuild… lines wipe the modern world’s diplomacy and re-seed neutral opinion before diplomacy.json writes the 1450 one.
  • The disabled lists switch off whole unit categories, 17 modern unit ids and three doctrine branches.

A file name in the header that does not resolve, or a file that does not parse, is listed in the MOD LOADOUT panel rather than skipped in silence.

The Scenario page of the Mod Builder with Old World Order loaded, listing the scenario id, display name, start year 1450, the scope for clearing diplomacy and the province data, national goals and victory file names.
Old World Order in the Mod Builder: the Scenario page shows the header file's fields, from the start year to the files it points at.

Countries

Removing the modern world

countries_remove.json is a list of country codes under one key:

{
  "removeCountries": [
    "ABW",
    "AFE",
    "AFG",

A removed country takes its armies, fleets and air wings with it. Its land becomes unowned unless the ownership file hands it to someone.

Adding 137 nations

Each entry in countries_add.json describes one nation. The Ottoman entry, with its unit roster and name pool shortened:

{
  "iso3": "OTT",
  "name": "Ottoman Empire",
  "mapColor": "#C8392B",
  "capital": "Edirne",
  "capitalProvince": "Edirne",
  "population": 9000000,
  "areaKm2": 520000,
  "governmentType": "Theocracy",
  "governmentSubtype": "Sultanate",
  "ideology": "Islamist",
  "militaryUnitTypeIds": ["ottoman_janissary", "ottoman_sipahi", "..."],
  "flagPngPath": "flags/OTT.png",
  "leaderName": "Murad II",
  "leaderTitle": "Sultan",
  "continent": "Asia",
  "region": "WesternAsia",
  "homelandTerm": "THE SULTANATE",
  "dominantReligion": "Islam",
  "dominantEthnicity": "Turkish",
  "primaryCulture": "Ottoman",
  "ethnicHomogeneity": 0.65,
  "mapColorVibrant": "#F1220E",
  "mapColorGloomy": "#79433E",
  "leaderNamePool": [
    { "name": "Mehmed II", "title": "Sultan", "gender": "male" },
    "..."
  ],
  "lockLeaderTitle": true,
  "leaderPortraitPath": "portraits/leaders/OTT.png"
}

Things to copy from it:

  • Codes. Three upper-case letters. The mod avoids codes of modern countries where it can: MYN for the Ming rather than MNG, VNC for Venice rather than VEN.
  • Enum values are case-sensitive: Theocracy, Sultanate, WesternAsia. The lists are on Permissions and enums.
  • militaryUnitTypeIds is the nation’s unit roster. All 137 entries have one, and 34 of them list no ships.
  • flagPngPath is relative to the mod folder: flags/<code>.png, 128×80 pixels.
  • Leader identity. Twenty nations carry a leaderNamePool for later rulers, lockLeaderTitle so the title survives a change of government, and a leaderPortraitPath.
  • neutral is true on three nations, which keeps them out of military alliances while the AI plays them.
  • dominantReligion and dominantEthnicity drive kinship: countries that share one warm to each other over time.

Two rules about country codes.

An entry can name a templateISO3, the country to copy unlisted values from. Without one, the game copies from the alphabetically first country and leaves the identity fields empty. The mod writes every nation out in full instead: each entry spells out its identity fields, and countries_state.json sets the whole starting state.

A code that a base-game country already uses does not add a country. The entry re-skins the existing one, which keeps every base-game province that no ownership entry reassigns. The mod’s France and Portugal carry the base game’s FRA and PRT this way. When you re-use a code, decide the owner of each province of the base-game country in the ownership file. python dev/curate_browse.py free iso FRA lists the provinces of a modern country that the curation has not assigned.

Country state

countries_state.json sets the numbers a new game starts with:

{
  "iso3": "OTT",
  "stability": 0.72,
  "corruption": 0.2,
  "treasury": 5000,
  "gdp": 1500000,
  "manpower": 120000,
  "reserve": 40000,
  "techLevel": 1,
  "governmentType": "Theocracy",
  "ideology": "Islamist"
}

stability and corruption are fractions from 0 to 1: 0.72 is 72. treasury and gdp are in the scenario’s base money, florins here. techLevel starts a country with that many tiers of every visible doctrine branch completed; most nations get 1.

Province ownership

provinces_ownership.json is a flat list:

{
  "regionOwnerOverrides": [],
  "provinceOwnerOverrides": [
    {
      "provinceId": 3,
      "ownerISO3": "MAJ"
    },
    {
      "provinceId": 4,
      "ownerISO3": "BRU"
    },

It assigns 3,593 of the map’s 4,604 land provinces. The rest are left unowned on purpose. Nobody edits this file by hand: it is generated.

The curation tools

The source is dev/province_curation.json, one list of province ids per nation:

{
 "_comment": "Hand-curated province ownership. Provinces omitted are intentionally UNOWNED (neutral 1450 wilderness). Seeded from prior provinces_ownership.json; being trimmed region by region.",
 "ABY": [
  27,
  29,
  369,

Three Python 3 tools in dev/ work on it. Run them from the repository root.

CommandWhat it does
python dev/curate_browse.py iso FRALists a modern country’s provinces with id, name, position, area and curated owner. Other modes: name york, box 35 50 -90 -65, near 1249 600 (within 600 km of a province). Put free first to see only unassigned provinces.
python dev/build_province_ownership.py --checkValidates without writing: every owner must exist in countries_add.json, every id must exist, and no province may have two owners. A capital outside its own nation’s list is a warning.
python dev/build_province_ownership.pyThe same checks, then writes scenario/provinces_ownership.json. It refuses to write when a check fails.
python dev/audit_ownership.pyCompares each nation’s owned area with its declared areaKm2 (flagging more than 2.5 times or less than 0.3 times) and flags a nation whose provinces span more than 3,500 km.

The tools read dev/province_registry.json, a slim copy of the game’s province table. To redraw the map for your own mod, keep the registry and the scripts, empty the curation file, and work region by region: browse, add ids to a nation, check, build, audit. The ids are listed on Province ids.

Province data

The header’s provinceDataFile names provinces_data.json, keyed by province id:

{
  "provinces": {
    "1": {
      "population": 8400,
      "terrain": "Plains",
      "resources_mode": "replace",
      "resources": [
        {
          "resource": "Wheat",
          "intensity": 0.8
        },

The mod gives every land province all four fields. A province population wins over the share the province would get from its owner’s declared total. resources_mode: "replace" means the province has exactly the listed deposits, and the strongest one becomes what it produces. terrain changes movement and combat, not the colours of the map.

Starting armies and fleets

units_deploy_armies.json places stacks by province id:

{
  "ownerISO3": "OTT",
  "provinceId": 516,
  "units": [
    { "unitTypeId": "ottoman_janissary", "count": 3 },
    { "unitTypeId": "ottoman_sipahi", "count": 2 },
    { "unitTypeId": "ottoman_topcu", "count": 1 }
  ]
}

Every nation has at least one of the 141 stacks. units_deploy_fleets.json has the same shape plus "inHarbor": true, which all 34 fleets use. A stack may only name unit ids the mod defines: the modern ids are disabled in the header, and a removed country’s base-game forces are gone.

Diplomacy at the start

Because the header clears every relationship, diplomacy.json starts from a blank sheet. One entry of each kind, on one line each:

{ "id": "KALMAR_UNION", "nameKey": "owo.org.kalmar_union.name", "type": "CollectiveDefense", "founder": "DAN", "members": ["DAN", "SWD"] }
{ "a": "FRA", "b": "SCT", "type": "Military" }
{ "type": "truce", "a": "HUN", "b": "OTT", "months": 36 }
{ "id": "HUNDRED_YEARS_WAR", "attackers": ["FRA"], "defenders": ["ENG"], "casusBelli": "Territorial", "callAllies": true }
{ "a": "FRA", "b": "ENG", "opinion": -100, "trust": -100, "mutual": true, "rival": true, "anchor": true }

The file holds eight organizations, 15 alliances, 30 treaties (truces, non-aggression pacts, trade agreements and guarantees), five wars that are already running on the first day, and 32 relation entries. An organization’s nameKey is a text key from the mod’s own language files. anchor makes a relation the level it drifts back to, so an old rivalry does not fade. The block is written once, when a new game starts.

The Diplomacy page of the Mod Builder with Old World Order loaded, with folded groups for organizations, alliances and treaties and the list of wars open.
Old World Order in the Mod Builder: the Diplomacy page, with the scenario's organizations, alliances, treaties and the wars already running on day one.

Victory

victory.json opens with "disable_base_victories": true, so only the mod’s nine endings can end the game. One of them:

{
  "id": "sultan_i_rum_caliphate",
  "title_key": "owo.victory.sultan_i_rum.title",
  "description_key": "owo.victory.sultan_i_rum.desc",
  "outcome": "victory",
  "winner": "player",
  "min_year": 1480,
  "conditions": [
    { "type": "has_flag", "flag_name": "constantinople_conquered" },
    { "type": "lifetime_gt", "counter": "provinces_gained", "value": 80 },
    { "type": "lifetime_gt", "counter": "wars_won", "value": 8 },
    { "type": "lifetime_lt", "counter": "wars_lost", "value": 2 },
    { "type": "lifetime_lt", "counter": "regiments_lost", "value": 120 }
  ]
}

An ending can only test flags, variables, dates and the lifetime counters the game keeps for every country. The flag here is set by one of the mod’s events, which is how story and ending connect. The file closes with seven end_screen_rows that print lifetime counters on the end screen.

National goals

nationalGoalsFile replaces the base game’s goals. national_goals.json has a _BASIC block with two starter goals every country sees, and two or three goals each for 26 nations. The first Ottoman goal, shortened:

{
  "id": "ott_heir_of_rome",
  "title": "Heir of Rome",
  "title_key": "owo.goal.ott_heir_of_rome",
  "type": "territorial",
  "priority": "starter",
  "ai_weight": 0.95,
  "target_countries": ["BYZ"],
  "on_complete_effects": { "prestige": 50, "stability": 5 },
  "tasks": [
    {
      "id": "war",
      "title_key": "owo.task.ott_heir_of_rome.war",
      "title": "Declare war on the Byzantine Empire",
      "condition": { "type": "declare_war_on", "params": { "target_iso3": "BYZ" } }
    }
  ],
  "on_complete_flag": "constantinople_fallen"
}

The next Ottoman goal lists "prerequisites": ["ott_heir_of_rome"], which is how the mod builds a chain. Each text has a key and a plain fallback. A starter goal’s id must begin with basic_ to appear in the starter list.

Currencies

currenciesFile names currencies.json. Currencies only change how money is shown: the simulation counts in one unit, the base currency. The akçe entry, shortened:

{
  "id": "akce",
  "name": "Ottoman Akçe",
  "symbol": "ak.",
  "exchangeRateToBase": 45.0,
  "associatedCountries": ["CND", "DUL", "KAR", "OTT", "RAM", "TRE"],
  "symbolPosition": "suffix"
}

exchangeRateToBase is how many units of the currency one unit of base money buys, associatedCountries lists the nations that see it, and symbolPosition puts the symbol before or after the number. At a rate of 45, the Ottoman treasury of 5,000 florins is shown to an Ottoman player as 225.0K ak. The file lists 17 currencies, the florin included.

The safety net

install.bat runs dev/validate_scenario.ps1 before every deploy that builds, and stops if it fails. It exists for one specific mistake: a fragment written as a bare list, such as ["FRA", "PRT"], instead of an object with the expected key. The script’s own header explains that such a file breaks the scenario load and the game falls back to the base game.

For every .json file in scenario/ it checks that the file starts with { and parses. For the fragments it knows by name it also checks the top-level key, such as removeCountries in countries_remove.json.

The script checks shapes. For ids, enum values and references between files, press VALIDATE in the Mod Builder, or point your editor at the JSON schemas.

Play Global Protocol: New World Order

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