Wiki menu

Old World Order: events and localization

How Old World Order writes its events, chains and event pictures, and how its 13 language files are built, with the rules that keep text from breaking.

Last updated for v0.5.35
On this page

Old World Order tells its history through 60 events and keeps their text in 13 language files. Both are plain text you can read on GitHub. This page takes one event apart, shows how the mod chains events and attaches pictures, and then explains the language files and the rules the game applies to them.

The event files

The events are in Content/events/:

FileEventsSubject
historical_events_1450.json42The story of the period, from 1450 into the 1490s
historical_diplomacy_1450.json18Diplomatic choices offered in the opening months

Each file is a JSON list of event objects. The game reads every .json file in the folder, in file-name order, and accepts three shapes: a bare list (used here), a single object, or { "events": [...] }, which is what the Mod Builder writes.

Every one of the 60 objects has a type, which makes it an engine event: the game evaluates it monthly, shows the popup, lets AI countries choose, applies the effects and saves it. An object without type is only a popup that a script must fire.

The Events page of the Mod Builder with Old World Order loaded: the event list on the left, one event's settings in the middle and a preview of its popup with its picture on the right.
Old World Order in the Mod Builder: the Events page, with one event open and its popup preview on the right.

Anatomy of one event

The first event in the file, condensed, with its second option left out:

{
  "id": "fall_of_constantinople_1453",
  "type": "scripted",
  "category": "geopolitical_crisis",
  "priority": 10,
  "fire_once": true,
  "target": "specific_country",
  "target_country": "OTT",
  "immediate": true,
  "conditions": [
    { "type": "controls_province", "value": 2276 }
  ],
  "options": [
    {
      "effects": [
        { "type": "modify_stat", "field": "government.stability", "value": 10 },
        { "type": "add_treasury", "value": 500 },
        { "type": "annex_province", "province_id": 2276, "target": "OTT" },
        { "type": "set_flag", "flag_name": "constantinople_conquered" },
        { "type": "set_flag", "flag_name": "constantinople_fallen" }
      ],
      "text_key": "owo.event.fall_of_constantinople_1453.option_1"
    }
  ],
  "title_key": "owo.event.fall_of_constantinople_1453.title",
  "description_key": "owo.event.fall_of_constantinople_1453.description",
  "image": "fall_of_constantinople"
}
FieldWhat it does here
idThe event’s name in saves and chains. An id that a base-game event or an earlier mod already uses is skipped, not replaced.
typescripted: checked on the monthly evaluation. The mod has 55 of these and five reactive ones.
categoryPicks the default picture, whether the popup pauses the game, and whether a notification setting may hide it.
priority1 to 10. Used to choose between events that are ready in the same month.
fire_onceThe event happens once per country. All 60 events set it.
target, target_countryWho can get it. specific_country with OTT means the Ottomans only.
immediateNo random roll: the event fires at the first monthly check where its conditions hold. 51 of the mod’s 60 events use it.
conditionsAll must hold. controls_province is true when the country occupies the province, or owns it with nobody occupying it.
optionsThe buttons. Each has a text and a list of effects.
title_key, description_key, text_keyText keys from the language files.
imageThe popup’s picture, by file name without extension.

So this event waits until the Ottomans hold province 2276, then fires at the next monthly check. Its effects transfer ownership with annex_province, pay the treasury, and set two flags.

What the flags are for

A flag is a named mark on a country, and it is how separate files talk to each other. constantinople_conquered is tested by one of the endings in scenario/victory.json. Other events test flags with has_flag and not_has_flag, and national goals set flags with on_complete_flag.

One event, two audiences

The same moment has a second event, for everyone else:

  "id": "fall_of_constantinople_1453_christendom",
  "type": "scripted",
  "category": "geopolitical_crisis",
  "priority": 10,
  "fire_once": true,
  "target": "any_country",
  "mean_time_to_happen_months": 2,
  "conditions": [
    {
      "type": "continent",
      "value": "europe"
    },
    {
      "type": "controls_province",
      "value": 2276,
      "target_country": "OTT"
    },
    {
      "type": "not_controls_province",
      "value": 2276
    }
  ],

A condition normally tests the country that would receive the event. With target_country it tests the named country instead. Together the three conditions say: a European country, while the Ottomans hold the city, and not the holder itself.

Options and effects

Every option is a list of effect objects. The effects the mod uses most:

EffectExample from the mod
modify_stat{ "type": "modify_stat", "field": "government.stability", "value": 10 }
add_treasury{ "type": "add_treasury", "value": 500 }
set_flag{ "type": "set_flag", "flag_name": "auld_alliance_renewed" }
add_relation{ "type": "add_relation", "target": "SCT", "value": 80 }
modify_unrest{ "type": "modify_unrest", "value": -5 }
create_unit{ "type": "create_unit", "unit_id": "france_knight", "count": 1, "target": "FRA" }
form_alliance{ "type": "form_alliance", "target": "SCT", "force": true }
grant_specialist{ "type": "grant_specialist", "specialist": "johannes_gutenberg" }

It also uses annex_province, engage_diplomatically, modify_military, sign_truce, sign_peace, declare_war, break_alliance and fire_event. The diplomacy effects run through the same commands a player uses, so an alliance formed by an event is a real alliance.

Write effects as objects. An event that writes an effect as a string, in the "stability:0.10" style, is loaded as a plain popup whose buttons do nothing, with a warning. Every effect in the mod is an object with a type.

Chains

A chain is one event queueing another. The mod does it with a fire_event effect on an option, so the follow-up only happens if that option is chosen. The Teutonic Order’s choice in prussian_confederation_revolt_1454:

        {
          "type": "fire_event",
          "chain_event": "casimir_incorporation_of_prussia_1454",
          "delay_months": 1
        },

The chained event is a specific_country event for Poland, so it goes to Poland, not to the country that clicked. Its own conditions are checked when the delay is over. The mod’s longest chain runs from columbus_atlantic_enterprise_1492 through new_world_discovered_1492 to treaty_of_tordesillas_1494.

Five events are reactive. They wait for something to happen rather than for a date:

    "triggers": [
      {
        "type": "on_peace_signed",
        "source_country": "FRA",
        "target_country": "ENG"
      },

When an event fires

Three rules of the event engine explain most “my event did not fire” questions:

  • Events are evaluated once per in-game month, on day 6 to 8. A condition that becomes true on the 10th is noticed the following month.
  • A country with an unanswered event gets no new one that month. An immediate event waits its turn too.
  • AI countries roll scripted events in turns, about one month in five. An AI-run country can receive an immediate event some months after its conditions passed.

The category matters as well. A player who turns event notifications down has social_cultural and technology_breakthrough events resolved with their first option. A story event the player must see belongs in geopolitical_crisis, military_incident, natural_disaster or internal_politics.

Event pictures

image is a file name, not a path. The game looks for it in the mod’s images/events/ folder, then in Content/images/events/, with the extension .png, .jpg or .jpeg, and falls back to the base game’s pictures and then to the category’s default.

The mod’s 60 events share 47 pictures, all in Content/images/events/ and all 1000×400 pixels. The popup shows a band about 180 pixels tall and crops around the centre, so a wide picture shows almost whole.

Localization

Thirteen files

The text is in Content/localization/, one file per language the game ships: cz, de, en, es, es-419, fr, ja, ko, pt, pt-br, ru, tr, zh. The English file has 1,202 rows.

A few rows of en.csv:

country.name.OTT,Ottoman Empire
country.leader_title.grand_prince,Grand Prince
country.homeland.term.the_sultanate,THE SULTANATE
owo.event.fall_of_constantinople_1453.title,Conquest of Constantinople (Ottoman Triumph)
owo.event.fall_of_constantinople_1453.option_2,Guarantee Orthodox patriarchate rights and revive Black Sea trade.
building.barracks.name,Garrison & Muster Ground
politics.law.labor_law.reduced_workweek,Feast Day Sabbath Observance

The same keys in tr.csv:

country.name.OTT,Osmanlı İmparatorluğu
country.leader_title.grand_prince,Büyük Prens
country.homeland.term.the_sultanate,SULTANLIK
owo.event.fall_of_constantinople_1453.title,İstanbul'un Fethi (Osmanlı Zaferi)

The format rules

  • UTF-8, with no byte-order mark.
  • No header row. The first line is already a key.
  • One row per key: key,value.
  • The row is split at the first comma. A value may contain commas and needs no quotes.
  • The repository’s .gitattributes keeps the files on LF line endings.

No fallback for keys only the mod defines

For each player the game layers the base game’s text, then the game’s text in the player’s language, then the mod’s file for that one language. A key of your own that exists only in en.csv is therefore shown as the raw key, owo.goal.ott_heir_of_rome, to everyone who does not play in English.

So a mod should carry every key of its own in all 13 files. A key that overrides a base-game key is different: leave it out of a language and that language falls back to the base game’s own text.

The key families

KeysText forNamed in
country.name.<code>Country namesLooked up by country code
country.leader_title.<token>, country.homeland.term.<token>Leader titles and homeland termsLooked up from the value (below)
owo.event.<event id>.title, .description, .option_1Eventstitle_key, description_key, text_key
owo.goal.*, owo.task.*National goals and their taskstitle_key, description_key
owo.doctrine.*, owo.group.*Doctrines and interest groupsname_key, desc_key
owo.victory.*, owo.endscreen.*Endings and end-screen rowstitle_key, label_key
owo.org.*Organization namesnameKey in diplomacy.json
building.<id>.name, .descriptionBuildingsThe game’s own keys for those ids
politics.law.<category>.<option>Law optionsThe game’s own keys

Keys under owo. are the mod’s own, and a JSON file names them. Keys such as building.barracks.name are the game’s keys: a row for one overrides the game’s text in that language.

Unit names follow the second pattern. A unit’s name in units_override.json fills unit.<id>.name for every language that has no row for that key, and a unit.<id>.name row in a language file gives that language its own name for the unit.

How names, titles and homeland terms are looked up

For three pieces of country text the game builds the key itself.

  • Country names. The game looks for country.name. plus the country code: country.name.OTT. Without that row it shows the name from countries_add.json.
  • Leader titles. The game turns the leaderTitle value into a token: lower case, apostrophes dropped, every other run of characters that are not letters or digits replaced by one underscore. "Grand Prince" becomes grand_prince, and the game looks for country.leader_title.grand_prince.
  • Homeland terms. The same token rule on homelandTerm: "THE SULTANATE" looks up country.homeland.term.the_sultanate.

A missing row is harmless: the game shows the value as written. The mod has no rows for King or Sultan, because the base game already translates those.

Adding text without breaking a language

  • Add a key to all 13 files in the same commit.
  • The Mod Builder’s Translations page adds or removes a key across all 13 files at once and marks rows whose text matches the English value. Its VALIDATE reports keys that some languages define and others do not.

Play Global Protocol: New World Order

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