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
-
Edit the JSON, CSV or script files in the repository.
-
Deploy with
install.bat /local. It builds the script, checks the scenario files and copies a clean mod folder into the game. -
Test in the game: MODS, switch the mod on, NEW GAME. Repeat until it is right.
-
Publish: bump the version, run
install.bat /workshop, thenpublish_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):
| Flag | What runs | Result |
|---|---|---|
/sdk | dotnet build "Content\mod-csharp\OldWorldOrder.ModCSharp.csproj" -c Release | OldWorldOrder.ModCSharp.dll under Content\mod-csharp\bin\Release\ |
/as | npm install on the first run, then npx asc mod.ts --target release -o ..\mod.wasm --runtime stub --use abort= --exportRuntime | Content\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.pngandthumbnail.png;scenario/,overrides/,flags/,icons/,images/andportraits/;overrides/Art/also asArt/at the top of the mod;Content/, without the three source folders and without source files (*.ts,*.cs,*.csprojand 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
-
Open the loadout. Start Global Protocol and click MODS on the main menu.
-
Switch the mod on. In MOD LOADOUT, click the row Global Protocol: Old World Order. A copy deployed by
install.batcarries the LOCAL badge. The line at the top of the panel names the active scenario. -
Start a new game. Click NEW GAME and pick a nation.
-
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.
| Tool | Use |
|---|---|
dev/validate_scenario.ps1, dev/set-runtime-settings.ps1 | The two helpers install.bat calls. |
dev/curate_browse.py, dev/build_province_ownership.py, dev/audit_ownership.py | Browse provinces, build the ownership file, audit the result. dev/owo_provinces.py holds their shared code. |
dev/curate_country_palettes.py | Computes mapColorVibrant and mapColorGloomy from each nation’s mapColor and validates the file against its schema. Needs the jsonschema package. |
dev/curate_cultural_identities.py | Writes 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.py | One-off generators the authors ran to add goals, event options and event text. |
scripts/audit_inventory.py | Lists buildings, units and doctrines without an icon, and specialists without a portrait. |
scripts/process_image.py | Turns 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:
- reads
workshopItemIdfrom the repository’smod.json; - asks for your Steam username;
- asks for the visibility,
0public,1friends-only or2hidden, with hidden as the default; - asks for an optional change note;
- 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
workshopItemIdinmod.json, Steam creates a new item. Save the id it returns intomod.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:
| File | What changes |
|---|---|
mod.json | version |
scenario/scenario.json | version |
Content/wasm-as/package.json, package-lock.json | version |
Content/wasm-as/mod.ts | The 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:
- runs
dev/validate_scenario.ps1, the same check as the batch file; - builds the C# script with
dotnet build; - assembles a staging folder from the mod’s files, with
Contentstripped of sources and the DLL inMods/; - patches the staged
mod.jsonfor the C# build withjq; - zips it twice, as
old-world-order-<tag>.zipandold-world-order-latest.zip; - 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.ps1passes, andbuild_province_ownership.py --checkreports no errors.scripts\audit_inventory.pyshows 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.
workshopItemIdis your item, not the one you copied.- You staged with
install.bat /workshopafter 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.