Wiki menu

Old World Order: build and publish

The working loop of the Old World Order mod: edit, deploy with install.bat, test in the game, stage, upload to the Workshop and cut a GitHub release.

Last updated for v0.5.35
On this page

After every change to a mod you build it, put it in front of the game and look. Old World Order turns that loop into two batch files and a handful of small tools. This page follows it from an edited file to a Workshop update and a GitHub release.

The loop at a glance

  1. Edit the JSON, CSV or script files in the repository.

  2. Deploy with install.bat /local. It builds the script, checks the scenario files and copies a clean mod folder into the game.

  3. Test in the game: MODS, switch the mod on, NEW GAME. Repeat until it is right.

  4. Publish: bump the version, run install.bat /workshop, then publish_workshop.bat, then push a version tag for the GitHub release.

Edit

Every data file is plain text. Two habits from the repository are worth copying.

Check against the schemas. docs/modding/schemas/ holds a JSON schema for the manifest, the scenario files and the main content files. An editor that understands JSON Schema marks a misspelt field as you type. See JSON schemas.

Run the quick checks before you deploy. The repository lists four, all run from its root:

powershell -NoProfile -File dev\validate_scenario.ps1        # fragment shapes (install.bat runs this)
python dev\build_province_ownership.py --check               # curation sanity
python dev\audit_ownership.py                                # area / continent audit
python scripts\audit_inventory.py                            # missing icons (run from repo root)

scenario/provinces_ownership.json is generated: edit dev/province_curation.json and rebuild, as the scenario page describes.

Deploy with install.bat

install.bat works in three phases.

1. Build

/local and /workshop choose the target; the flag table is on the tour page. The build depends on the runtime flag (/sdk is the default):

FlagWhat runsResult
/sdkdotnet build "Content\mod-csharp\OldWorldOrder.ModCSharp.csproj" -c ReleaseOldWorldOrder.ModCSharp.dll under Content\mod-csharp\bin\Release\
/asnpm install on the first run, then npx asc mod.ts --target release -o ..\mod.wasm --runtime stub --use abort= --exportRuntimeContent\mod.wasm

If a tool is missing, the script says which one and where to get it.

2. Validate

powershell -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%dev\validate_scenario.ps1" -ScenarioDir "%SCRIPT_DIR%scenario"

Every .json file in scenario/ must be an object, must parse, and (for the fragment files) must have its expected top-level key. On a failure the script prints the files at fault and stops before anything is copied:

ERROR: Scenario validation failed. Aborting install to prevent broken deploy.

3. Copy

The deploy is a clean one. The script deletes the target folder, creates it again and copies:

  • mod.json, logo.png and thumbnail.png;
  • scenario/, overrides/, flags/, icons/, images/ and portraits/;
  • overrides/Art/ also as Art/ at the top of the mod;
  • Content/, without the three source folders and without source files (*.ts, *.cs, *.csproj and a few more);
  • for the C# build, the DLL into Mods/.

Right after it copies mod.json it runs dev/set-runtime-settings.ps1 on the copy, so the manifest matches the build: csharp_only with no WASM entry for /sdk, wasm_only for a WASM build.

It also removes an old copy of the mod under %LOCALAPPDATA%\NewWorldOrder\Mods\, if there is one. The game searches that folder too, and should not find the mod twice.

The script then prints where it deployed and waits for a key. To skip the wait in an editor task, pipe an empty line into it, as the repository’s VS Code tasks do: echo.| install.bat /sdk.

The fast path, and its catch

install.bat /local /skip-build copies data and art without compiling: the quick way to test a change to a JSON or CSV file.

/skip-build also skips the validation. A malformed fragment then goes straight into the game, so run dev\validate_scenario.ps1 yourself. With the default C# variant the flag needs the DLL from an earlier full build: the script stops if it cannot find one.

Test in the game

  1. Open the loadout. Start Global Protocol and click MODS on the main menu.

  2. Switch the mod on. In MOD LOADOUT, click the row Global Protocol: Old World Order. A copy deployed by install.bat carries the LOCAL badge. The line at the top of the panel names the active scenario.

  3. Start a new game. Click NEW GAME and pick a nation.

  4. Look for the mod’s signs of life. The briefing popup opens, the HUD has four extra toolbar buttons, the date reads January 1450 and money is counted in florins or a national currency.

What to check when something is off:

  • The loadout panel. A mod that failed to load is marked with a LOAD ERROR badge, and the panel lists files that could not be applied as written.
  • A new game, not a save. Scenario data is written once, when a new game starts. An older save keeps the world it was made with.
  • The Mod Builder. Its VALIDATE button checks far more than the batch file: schemas, the manifest, text keys missing from some languages, events and packaging. See The Mod Builder.
  • Two copies. If you are also subscribed on the Workshop, the game finds two folders with one id. What mods can change explains which one loads.

The helper tools

All of these run from the repository root.

ToolUse
dev/validate_scenario.ps1, dev/set-runtime-settings.ps1The two helpers install.bat calls.
dev/curate_browse.py, dev/build_province_ownership.py, dev/audit_ownership.pyBrowse provinces, build the ownership file, audit the result. dev/owo_provinces.py holds their shared code.
dev/curate_country_palettes.pyComputes mapColorVibrant and mapColorGloomy from each nation’s mapColor and validates the file against its schema. Needs the jsonschema package.
dev/curate_cultural_identities.pyWrites the religion, ethnicity, culture and neutrality fields of every nation from one table in the script.
dev/add_national_goals.py, dev/add_event_localization.py, dev/add_worldwide_events_localization.py, dev/upgrade_all_events.pyOne-off generators the authors ran to add goals, event options and event text.
scripts/audit_inventory.pyLists buildings, units and doctrines without an icon, and specialists without a portrait.
scripts/process_image.pyTurns an art file into a 512×512 icon under icons/<category>/. Needs opencv-python and numpy.

The generators rewrite data files in place. Commit your work before you run one.

Stage and publish to the Workshop

Stage

install.bat /workshop

This runs the same build, validation and clean copy, but into workshop_content\ in the repository, a folder git ignores. It is a snapshot: stage again after every change you want in the upload.

Upload

publish_workshop.bat uploads that folder with SteamCMD. It refuses to start unless three things exist: workshop_content\mod.json, thumbnail.png (the preview image) and steamcmd on your PATH. Then it:

  1. reads workshopItemId from the repository’s mod.json;
  2. asks for your Steam username;
  3. asks for the visibility, 0 public, 1 friends-only or 2 hidden, with hidden as the default;
  4. asks for an optional change note;
  5. writes a small upload description to your temp folder and runs steamcmd +login <username> +workshop_build_item <file> +quit.

SteamCMD itself asks for your password and Steam Guard code. The script does not store them.

  • A first upload. With no workshopItemId in mod.json, Steam creates a new item. Save the id it returns into mod.json, or the next upload creates another one.
  • Somebody else’s item. You can only update an item you have Steam rights on. A copy of this repository carries Old World Order’s item id: remove it before your first upload.

The Workshop title and description come from the TITLE and DESCRIPTION lines at the top of the script, on every upload.

The Mod Builder can publish too, and runs its validation first. The batch route checks fragment shapes only, so press VALIDATE yourself.

Versioning

The version lives in mod.json, in MAJOR.MINOR.PATCH form. The repository’s own release commit shows everything that moves with it:

FileWhat changes
mod.jsonversion
scenario/scenario.jsonversion
Content/wasm-as/package.json, package-lock.jsonversion
Content/wasm-as/mod.tsThe version string, which is a literal in the code

Between versions, keep ids stable. Saves store events by id, so renaming an event breaks it in existing saves. Units and buildings a mod adds are stored in roster order, so add new ones at the end and do not remove or reorder the old ones.

GitHub releases

.github/workflows/release.yml builds a release whenever a tag that starts with v is pushed:

on:
  push:
    tags:
      - "v*"

On a Linux runner it:

  1. runs dev/validate_scenario.ps1, the same check as the batch file;
  2. builds the C# script with dotnet build;
  3. assembles a staging folder from the mod’s files, with Content stripped of sources and the DLL in Mods/;
  4. patches the staged mod.json for the C# build with jq;
  5. zips it twice, as old-world-order-<tag>.zip and old-world-order-latest.zip;
  6. creates the release, named after the tag, with both files attached.

So a release is cut with two commands, for a manifest version of 0.10.0:

git tag v0.10.0
git push origin v0.10.0

The release is named after the tag, so give the tag the same number as the version in mod.json.

When you adapt the workflow, list your own folders. The package step names each folder it copies, and so does the copy phase of install.bat. Put every folder your mod ships in both.

Checklist before publishing

  • dev\validate_scenario.ps1 passes, and build_province_ownership.py --check reports no errors.
  • scripts\audit_inventory.py shows no [MISSING] line.
  • Every text key exists in all 13 language files.
  • The Mod Builder’s VALIDATE shows no errors.
  • A new game starts, the briefing opens, the buttons work, an event popup shows its picture, and MOD LOADOUT shows no LOAD ERROR badge.
  • The version is bumped everywhere it appears.
  • workshopItemId is your item, not the one you copied.
  • You staged with install.bat /workshop after the last change, with the runtime you mean to ship.
  • Multiplayer testers all have the same build: players whose script files differ cannot join the same game.
  • The tag you push equals the version you uploaded.

Play Global Protocol: New World Order

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