Wiki menu

Old World Order: scripting and interface

The script behind Old World Order and its three runtimes, the files that add buttons and recolour the HUD, and the permissions the mod asks for.

Last updated for v0.5.35
On this page

Data files cover almost all of Old World Order. The rest is a small script and two interface files: the script shows a briefing when the game starts and answers the mod’s toolbar buttons, and the interface files add those buttons and turn the HUD gold and brown. This page explains the script, the runtimes its source is written for, the interface files, and the permissions a mod declares for them.

One script, three runtimes

A script is code the game calls when things happen: a tick passes, a war is declared, a button is clicked. These calls are hooks. The game runs a script as a compiled C# assembly or as a WebAssembly (WASM) module in a sandbox. The repository holds the script’s source for three runtimes.

RuntimeLanguageSourceShips as
Native C# SDKC#, a netstandard2.0 class libraryContent/mod-csharp/, Content/shared/Mods/OldWorldOrder.ModCSharp.dll
AssemblyScript core WASMAssemblyScript, a TypeScript dialectContent/wasm-as/mod.ts, gp.tsContent/mod.wasm
.NET WASMC# on .NET 10 for WASIContent/wasm-dotnet/, Content/shared/Content/mod.wasm, in component-model format

The README compares the first two like this:

RuntimeStabilityComplexityForAgainst
Native C# SDKHighLow to mediumBest debugging, most mature runtime pathNot sandboxed; managed DLL deploy only
AssemblyScript core WASMMediumMedium to highSmall binary, no .NET workload requiredWeaker type and runtime ergonomics than C#

Which one to choose

  • Start with the C# SDK. It is the default of install.bat and the one the release workflow ships. Build it with install.bat or install.bat /sdk. You need only the .NET SDK.
  • Choose AssemblyScript when you want the script sandboxed and do not want to ship a DLL. Build it with install.bat /as. It needs Node.js. Know one limit first: the game’s WASM runtimes ship for Windows and Linux. On a Mac a mod with a WASM module loads its data, but the script does not run. C# mods are not affected.
  • .NET WASM compiles the shared C# logic to a sandboxed WASM component. The README marks it as experimental, and these pages do not cover it.

Whichever you pick, the script file is part of the multiplayer lobby check: players whose script files differ cannot join the same game.

How the game picks one

Two manifest fields decide. runtimePolicy is coexist (run both kinds), wasm_only or csharp_only. entrypoints.wasm names the WASM module. A C# script needs no entry: the game scans the mod’s Mods/ folder for DLLs and looks for public classes that implement IModEntrypoint. install.bat writes the values that match the build you chose into the deployed mod.json.

Where the code lives

The two C# variants share one file of logic and differ only in a thin wrapper.

  • Content/shared/OldWorldOrder.cs holds the behaviour. It talks to the game only through a three-method interface, IModHost (ShowPopup, Log, GetModVersion), so it does not care which runtime hosts it.
  • Content/mod-csharp/ModEntrypoint.cs is the SDK wrapper. It extends ModBase, the game’s base class for C# mods, which subscribes eight hooks for you as methods to override. The wrapper forwards them to the shared class. The eight are listed on Scripting with WebAssembly and C#.
  • Content/wasm-dotnet/OldWorldOrderWasmMod.cs is the .NET WASM wrapper. Gp.cs wraps the game’s imports, wit/ describes the interface, and generated/ holds generated bindings.
  • Content/wasm-as/mod.ts is a separate port in AssemblyScript. gp.ts beside it wraps the game’s imports in friendlier functions.

The whole SDK wrapper pattern fits in two fragments of ModEntrypoint.cs. The first implements IModHost on top of the game’s popup call:

public sealed class ModEntrypoint : ModBase, IModHost
{
    private OldWorldOrder _shared = null!;

    public void ShowPopup(string title, string body)
    {
        ModHookBus.ShowPopup(OldWorldOrder.ModId, title, body);
    }

The second forwards a hook:

    // Called when a war is declared.
    // attacker / defender are country indices (0 = local player in single-player).
    protected override void OnWarDeclared(int attacker, int defender, int tick)
    {
        _shared?.OnWarDeclared(attacker, defender, tick);
    }

The sdk/ project is a set of stubs with the same assembly name as the game’s own code. It lets the mod compile on a machine without the game. It is never shipped.

What the script does

This section follows the default C# build.

The start-of-game briefing

When the script initialises, it shows a popup titled “Strategic Briefing: 1450 AD”:

        // Show startup briefing immediately on initialize so date and overview are accessible before unpausing
        _host.ShowPopup("Strategic Briefing: 1450 AD", BuildBriefingBody(_lastYear, _lastMonth));

The toolbar buttons

Each button in inject.json carries a hookName. A click calls the script’s UI hook with that name and the mod’s id. The script checks the id first, because every mod receives every click:

    public void OnUiAction(string hookName, string modId)
    {
        if (!string.IsNullOrEmpty(modId) && !string.Equals(modId, ModId, StringComparison.OrdinalIgnoreCase))
            return;

        switch (hookName)
        {
            case WelcomeHook:
                _host.ShowPopup("Strategic Briefing: 1450 AD", BuildBriefingBody(_lastYear, _lastMonth));

The four buttons reopen the briefing (owo.welcome), open the ambitions popup (owo.ambitions), open the world chronicle (owo.chronicle) and open the Historian’s Archive (owo.archive).

The Historian’s Archive

Several hooks do one thing: add one to a counter.

    public void OnBuildingCompleted(int provinceId, int buildingDefIndex)
    {
        _buildingsObserved++;
    }

Wars declared, buildings completed, events fired and countries eliminated are counted this way. The Archive popup prints the script’s counters. They are plain fields of the script, reset when it initialises, so they describe the current session.

A hook can also answer with a popup of its own. When a country is eliminated, the script adds one to its counter and shows a bulletin about it.

Popup text and languages. A popup’s title and body can be plain text or a text key. A title or body that is exactly a key, such as mymod.popup.intro.title, is shown in the player’s language. Define such a key in all 13 language files.

The interface files

Both are in Content/ui/. Everything here needs the InjectUI permission.

inject.json

The manifest’s entrypoints.ui names this file. One of its four buttons, and the block that places the toolbar:

{
  "toolbarButtons": [
    {
      "id": "owo.welcome_btn",
      "iconPath": "Content/ui/icons/welcome.png",
      "tooltip": "Strategic Briefing: 1450 AD",
      "hookName": "owo.welcome"
    },
  "style": {
    "keys": [
      "position",
      "top",
      "right",
  • A button needs an id, an iconPath to a 32×32 PNG inside the mod folder, and a hookName. tooltip may be plain text or a text key.
  • style is two parallel lists, keys and values, applied over the toolbar’s default style. The mod uses it to position the toolbar (top 58px, right 32px) and colour it.
  • The same file can add rows to the province panel and to the country overview, under provinceDetailRows and countryPanelRows. A row has a label and a value, and each is shown as written or looked up as a text key. The format is on Adding buttons, rows and popups.

The game injects all of this when you enter the game screen and removes it when you return to the main menu.

theme.json

A theme recolours the HUD in two layers. tokens redefine the game’s named colours, and everything styled through a token changes at once. rules then restyle single elements.

{
  "base": "classic",
  "tokens": {
    "--color-neon-cyan": "#d4af37",
    "--color-neon-cyan-dim": "rgba(212, 175, 55, 0.35)",
    {
      "selector": "#top-bar",
      "background-color": "#181410",
      "border-color": "#8c734b"
    },

The mod sets 49 tokens and 63 rules. A rule can also hide a part of the HUD that has no place in the mod’s era:

    {
      "selector": "#mm-btn-nuclear",
      "display": "none"
    },

That rule removes the nuclear map mode button.

Three limits: tokens reach only what the game styles through tokens, a style the game sets in code wins over any theme rule, and a selector that matches no element changes nothing. Check a theme in a running game.

Other interface files

A mod restyles the interface through the style block of inject.json and through theme.json. It can also replace or hide whole parts of the HUD and add gauges to the top bar, with files of their own in Content/ui/. Those are described on HUD layout: slots and trackers.

Permissions

The manifest declares its permissions in one line:

  "permissions": ["InjectUI", "FireTriggers", "WriteTreasury"],
PermissionWhat it unlocks
InjectUIToolbar buttons, panel rows, the theme, the layout, and popups shown by a script
FireTriggersA script queueing an event or raising an event trigger
WriteTreasuryA script changing a country’s treasury

The buttons, the theme and the popups on this page all come under InjectUI. A call that needs a permission the mod did not declare does nothing. Players see the permissions as badges on the mod’s row in MOD LOADOUT before they enable it. Events in Content/events/ need no permission, whatever their effects.

Play Global Protocol: New World Order

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