A mod is one folder: a mod.json manifest at the top, and under it the files the game finds by a fixed name or by a path the manifest gives. This page lists where that folder goes and what it can hold, every mod.json field, what the Mod Builder’s VALIDATE check and a Workshop upload do with the folder, and how the game orders mods that are enabled together. Use it when you lay out a mod by hand, or when you need the exact rule behind a load error.
- Mod folder layout
- One mod per folder
- What a Workshop upload contains
- Validate Mod
- Manifest fields
- Runtime policy
- Load order, dependencies and game version
Mod folder layout
Where the game looks
On Windows the game searches these places, in this order. Each mod sits in its own subfolder.
| Order | Folder | Notes |
|---|---|---|
| 1 | %LOCALAPPDATA%\NewWorldOrder\Mods\ | Also holds loadout.json, the list of mods you enabled and the scenario you selected. |
| 2 | Documents\GlobalProtocol\Mods\ | |
| 3 | %USERPROFILE%\AppData\LocalLow\Dorlion Interactive\Global Protocol\Mods\ | Where the Mod Builder creates a mod unless you pick another folder. |
| 4 | The Steam Workshop folder of each item you subscribed to | Steam tells the game where each item is installed. When Steam’s Workshop service is not available, the game looks in steamapps\workshop\content\4500270 of the Steam library the game is installed in, and in the same path under Program Files (x86)\Steam and Program Files\Steam. |
When the same mod id is found in two of these places, the first one in the table loads. A copy in one of your own folders therefore takes the place of the Workshop copy of the same mod.
On other platforms the game uses the same three kinds of folder as the operating system reports them: the local application data folder (NewWorldOrder/Mods), the documents folder (GlobalProtocol/Mods) and the game’s own persistent data folder (Mods).
A Workshop mod uses the same layout as a local mod, inside the Workshop item’s folder.
What goes in the folder
<mods folder>/<mod-id>/
mod.json required manifest
.modignore optional: more files to leave out of a Workshop upload
Content/
buildings.json building roster
units.json unit roster
resources.json resource overrides and disables
currencies.json national currencies (display only)
research_tracks.json the mod's own research tracks
specialists.json specialists
demography/
seeds.json population seed rows
model.json demography model tables
events/ event files (*.json, in this folder only)
localization/ text: one <language>.csv per language
ui/
inject.json toolbar buttons and panel rows (the file entrypoints.ui names)
theme.json HUD theme
layout.json HUD slots to replace or hide
layouts/ <slot>.uxml files that layout.json uses
hud_trackers.json top-bar gauges
icons/
buildings/ replacement icons, one file per id
units/
resources/
doctrines/
research/ icons for research tracks and nodes
markers/ map marker art that overrides/military_markers.json names
images/events/ event pictures, named by an event's "image"
flags/ flag pictures a country names in flagPngPath
portraits/ leader and specialist portraits
overrides/
game_settings.json
game_flow.json
events.json
envoys.json
doctrines.json
laws.json
interest_groups.json
military_markers.json
scenario/
scenario.json required header (must contain scenarioId)
countries_add.json
countries_remove.json
countries_state.json
diplomacy.json
provinces_ownership.json
units_define.json
units_deploy_armies.json
units_deploy_fleets.json
units_deploy_air.json
national_goals.json the file nationalGoalsFile names
victories.json the file victoryFile names
provinces_data.json the file provinceDataFile names
institutions.json
trade_arrangements.json
Mods/ compiled C# assemblies (*.dll)
Every file except mod.json is optional. The table says what each part is for and where it is documented.
| Path | What it is | Documented on |
|---|---|---|
mod.json | The manifest: id, name, version, permissions, entry points. | Manifest fields |
.modignore | Patterns for files that stay out of a Workshop upload. | What a Workshop upload contains |
Content/buildings.json, Content/units.json, Content/resources.json | Content rosters: merge into, replace or cut down the game’s buildings, units and resources. | Content rosters |
Content/currencies.json | The currencies money is shown in. Display only. | Currencies |
Content/research_tracks.json | Research tracks of your own. | Mod research |
Content/specialists.json | Specialists a country can employ. | Specialists |
Content/demography/seeds.json, Content/demography/model.json | Population seed rows and demography model tables. | Demography |
Content/events/*.json | Events. The game reads every .json file directly in this folder, in file-name order. | Events |
Content/localization/<language>.csv | Text keys per language. | Localization |
Content/ui/inject.json | Toolbar buttons and extra rows on the province and country panels. The file name is free: the game reads the file entrypoints.ui names. Content/ui/inject.json is where the Mod Builder writes it. | UI injection |
Content/ui/theme.json | Colours, sizes and rules that restyle the HUD. | HUD theming |
Content/ui/layout.json, Content/ui/layouts/<slot>.uxml | HUD slots to replace or hide, and the replacement layouts. | HUD layout |
Content/ui/hud_trackers.json | Up to three gauges on the top bar. | HUD trackers |
icons/buildings/, icons/units/, icons/resources/, icons/doctrines/, icons/research/ | Replacement icons, named by id. The game also reads the same folders under Content/icons/, after these. | Icons and event pictures |
images/events/ | Event pictures. Content/images/events/ is read after it. | Icons and event pictures |
icons/markers/, overrides/military_markers.json | Map marker art. The JSON file names each picture by path; icons/markers/ is where the Mod Builder puts the pictures it imports. | Marker art |
flags/, portraits/ | Flag pictures (a country’s flagPngPath; the Mod Builder copies flags to flags/<ISO3>) and portraits (a country’s leaderPortraitPath, the portraits/<ISO3>/ bank for later leaders, and specialist portraits). | Flags and portraits |
overrides/game_settings.json | Sparse changes to the game’s rule numbers. | Game settings |
overrides/game_flow.json | The game_flow section of the game settings as its own file. | Game flow |
overrides/events.json, overrides/envoys.json | The events and envoys sections of the game settings as their own files. | Config override files |
overrides/doctrines.json | Changes to the Knowledge Network’s doctrines. | Doctrines |
overrides/laws.json | Changes to laws. | Laws |
overrides/interest_groups.json | Changes to interest groups and the electorate. | Interest groups |
scenario/scenario.json and the nine split files | The scenario: header, countries, starting diplomacy, province ownership and starting forces. The split file names are fixed. | Split-folder scenario, Country overrides |
scenario/national_goals.json | National goals. Any file name works: the header’s nationalGoalsFile names it. | National goals |
scenario/victories.json | Scenario victories, named by victoryFile. | Scenario victories |
scenario/provinces_data.json | Per-province starting data, named by provinceDataFile. | Scenario province data |
scenario/institutions.json, scenario/trade_arrangements.json | Institution and trade arrangement definitions for the scenario. The game reads these two fixed file names from the active scenario’s folder and merges them into its own definitions. A file that is not valid JSON is skipped with a warning. | |
Mods/*.dll | Compiled C# assemblies with the mod’s code. | Runtime policy |
The scenario header can name more files in the scenario folder (buildingsOverrideFile, unitsOverrideFile, resourcesOverrideFile, currenciesFile). See Scenario header fields.
Files the game does not read. A loose .uss style sheet in a mod is not loaded: restyle the HUD with Content/ui/theme.json. Content/tech_tree.json is ignored: research is the Knowledge Network, changed through overrides/doctrines.json and Content/research_tracks.json. VALIDATE warns about any other JSON file directly in Content/ or overrides/ that the game does not read.
One mod per folder
The game searches each mods folder, and every folder below it, for files named mod.json. A folder whose mod.json is valid JSON and has an id is a mod.
- Nested manifests never load. A
mod.jsoninside another mod’s folder (aworkshop_content/staging copy, a backup, a sample mod) is ignored. The outer mod loads, and the MOD LOADOUT panel and the Mod Builder’s RELOAD & TEST message name the inner file. - Two folders, one id. When two folders in the same mods folder use the same
id, the one nearest the top of that mods folder loads. If both are at the same depth, the path that sorts first (by character code) loads. The MOD LOADOUT panel warns about the other. - Same id in two mods folders. The folder earlier in the search order loads, without a warning.
Keep the folder name equal to the id, so a duplicate is plain to see. VALIDATE warns when they differ.
What a Workshop upload contains
Publishing uploads a clean copy of the mod folder, never the folder itself. The copy leaves out, at any depth:
- the folders
bin/,obj/,.git/,.vs/,workshop_content/and__MACOSX/; - the files
*.pdb,.DS_Store,Thumbs.db,desktop.iniand._*; - backups whose name ends in
.bak, in.bakplus one more character (.bak2) or in.bak-plus anything (.bak-20260512); - symbolic links and junctions;
- every subfolder that has its own
mod.json; .modignoreitself.
These names are matched without regard to case. A file with .bak in the middle of its name, such as units.bakery.json, is uploaded.
To leave out more, add a .modignore file to the mod root. It cannot leave out the root mod.json, which is always uploaded.
# One pattern per line. A line starting with # is a comment.
# No "/": matches a file or folder name anywhere.
*.psd
# A leading "/" or an inner "/": a path from the mod root.
/notes.txt
# A trailing "/": folders only.
drafts/
# "*" stays within one folder, "**" crosses folders, "?" is one character.
docs/**/*.md
Matching ignores case. A # after a pattern is part of the pattern, not a comment. A line starting with ! (re-include) is not supported and is skipped.
If the root mod.json is itself a symbolic link or junction, the upload is refused: replace it with a real file.
The Mod Builder’s Publish page shows the number of files, the upload size and what is left out before you press the button.
Validate Mod
The Mod Builder’s VALIDATE button, next to SAVE ALL, saves your edits, then checks the mod folder without loading it. The report groups what it finds by file. Click a line to open the page that edits that file. COPY REPORT copies the list as plain English text for a bug report.
Each line has one of three levels:
| Level | Means | Effect on a Workshop upload |
|---|---|---|
| Error | The game rejects or drops this. | Stops the upload. |
| Warning | It loads, but probably does not do what you meant. | Needs one extra confirmation. |
| Note | Information only, such as what the upload leaves out. | None. |
Only the files the upload would contain are checked.
What it checks
Schema. Files are checked against the game’s JSON Schemas (see JSON schemas).
- A mismatch is an error in
mod.json,Content/currencies.json,Content/specialists.json,Content/research_tracks.json,Content/demography/seeds.jsonandmodel.json,Content/ui/theme.json,layout.jsonandhud_trackers.json, the split scenario files, and the files the scenario header names withnationalGoalsFile,victoryFile,currenciesFileandprovinceDataFile. - The
overrides/*.jsonfiles and theContentrosters only list what they change. They are checked without the required fields, and a mismatch is a warning. A roster field set tonullwhere the schema wants text ("required_building": null) reads as unset and is not reported. A roster file that cannot be read as a roster at all is an error. - A field the schema does not know is a warning in every file, because the game ignores it. It is usually a misspelling.
- A JSON file directly in
Content/oroverrides/that the game never reads is a warning. So is a file inContent/localization/that is not named after one of the game’s languages.
Manifest.
| Check | Level |
|---|---|
id uses only lowercase letters and digits, joined by single dots, dashes or underscores | warning |
The folder is named after the id (not checked for a Workshop install) | warning |
version is semver | error |
wasmAbiVersion is one this game supports (1 to 4) | error |
managedSdkVersion has the same major version as the game’s SDK (not checked when runtimePolicy is wasm_only) | error |
world.read or flags.write declared while a shipped script declares wasmAbiVersion below 4 | warning |
A WASM module imports a function that needs a higher wasmAbiVersion or a permission the mod did not declare | error |
iconPath and thumbnailPath exist and are part of the upload | warning |
entrypoints.wasm, entrypoints.ui, defaultScenarioFile and scenarioFolder exist and are part of the upload | error |
gameVersion is a range the game can read | error |
The running game is inside the gameVersion range | warning |
A dependencies entry is malformed, or names the mod itself | error |
| A dependency is not installed on this computer, or is installed at a version outside the range | warning |
| The mod ships a WASM script (macOS players get its data only) | note |
Content. The scenario loads, and every file it names exists. Starting diplomacy and the world ceasefire are consistent (known countries, valid organization ids, a truce with a length, dates in order). The content roster checks that RELOAD & TEST runs. The game_settings sections the game does not apply (see Game settings). Problems in the law, interest group, research, specialist, demography, province data, victory and goal files. Marker art and interface files that point at missing pictures or unknown keys, and interface files in a mod without the InjectUI permission. Text keys defined in some languages but not in others (see Localization). The Events page’s checks (see Events).
Packaging. Folders with their own mod.json (a warning), and a note of what the upload leaves out.
The lighter check at load
The game runs a lighter version of the same check whenever mods load, for every active mod. What it finds lands in the same places as other load problems:
- Errors are listed in the MOD LOADOUT panel’s error bar and raise the mod’s LOAD ERROR badge. They also appear in the Mod Builder’s RELOAD & TEST list.
- Warnings are listed in RELOAD & TEST only, marked
(warning). They never mark the mod as failing. - Notes are dropped.
To keep loading fast, this run:
- reads only the JSON files under
Content/,overrides/and the scenario folder; - skips any file over 512 KB;
- does not walk the rest of the folder and does not compare languages;
- leaves out what the load reports by itself: events, the WASM ABI and managed SDK,
gameVersion, dependencies, the roster checks and thegame_settingssections that are not applied.
The whole pass has a budget of 250 ms. If it runs out, one line on the MOD LOADOUT panel says how many mods were not checked. With no mod enabled, nothing is read at all. Use VALIDATE for the full report.
Before a Workshop upload
Publishing runs the full check first.
- Any error stops the upload before Steam is contacted, so no Workshop item is created. The report opens.
- Warnings stop it once. Press the publish button again to publish with exactly those warnings. A warning that was not in the report you saw asks again.
Manifest fields
mod.json holds what is true of the mod as a whole: identity, permissions, Workshop data, pictures and entry points. Scenario and game-state setup belongs in the scenario files, not here.
{
"id": "com.myname.mymod",
"displayName": "My Mod",
"version": "1.0.0",
"author": "My Name",
"description": "A short summary of what the mod changes.",
"gameVersion": "^0.5.0",
"dependencies": ["example.base@^1.2.0"],
"scenarioFolder": "scenario",
"entrypoints": { "wasm": "Content/mod.wasm", "ui": "Content/ui/inject.json" },
"wasmAbiVersion": 4,
"permissions": ["InjectUI", "FireTriggers", "world.read"]
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | yes | Unique id, for example com.myname.mymod. A mod.json without an id is not a mod. Use lowercase letters and digits joined by single dots, dashes or underscores, and name the folder after it. | |
displayName | string | yes | The name on the mod’s row in MOD LOADOUT. | |
version | string | yes | Semver MAJOR.MINOR.PATCH, for example 1.0.0. VALIDATE reports any other form, and id@range dependencies of other mods are matched against it. Raise it when you update the mod: players with different versions of a mod cannot join the same multiplayer game. | |
description | string | Short summary. Pre-fills the Workshop description on the Publish page. | ||
author | string | Author name. Informational. | ||
tags | string[] | Category tags such as scenario or balance. Informational: they never change how the mod loads. | ||
iconPath | string | Path, relative to the mod folder, of a small picture of the mod. | ||
thumbnailPath | string | Path of a larger preview picture. Pre-fills the Workshop preview image on the Publish page. | ||
era | string | Optional era label. Informational: the game does not act on it. | ||
startYear | integer | Optional suggested start year, 0 or more. Informational: the scenario header’s startYear sets the real start date. | ||
gameVersion | string | Range of game versions the mod was made for, for example ^0.5.0. Outside it the mod loads with a warning badge. See game version. | ||
dependencies | string[] | Mods that must be enabled for this one to load: "other.mod" or "other.mod@^1.2.0". They always load first. | ||
loadOrderHint | integer | 0 | Position among mods that do not depend on each other: lower loads first, higher loads later and wins where two mods change the same thing. | |
enabledByDefault | boolean | false | Enables the mod for a player who has not saved a selection in MOD LOADOUT. | |
defaultScenarioFile | string | Path of a single-file scenario. | ||
scenarioFolder | string | Path of a folder with split scenario files. It must contain scenario.json. Wins over defaultScenarioFile. | ||
entrypoints | object | Paths of the mod’s script and interface files: entrypoints.wasm and entrypoints.ui. | ||
wasmAbiVersion | integer | 1 | The script interface version the WASM module was built for, 1 to 4. Version 4 adds the world-state functions; every older function works at every version. A version the game does not support is a load error, and the script does not run. See the WASM scripting page. | |
runtimePolicy | string | "coexist" | How the mod’s WASM module and C# assemblies run together: coexist, wasm_only or csharp_only. See Runtime policy. | |
enableComponentRuntime | boolean | false | Allows a component-model WASM binary. Leave it false for a core WASM module. | |
managedSdkVersion | string | The SDK version the mod’s C# assemblies were built against, as MAJOR.MINOR (the game provides 1.1). The major number must match, or the assemblies are not loaded. Leave it out when the mod ships no C# code. | ||
permissions | string[] | What the mod’s code and interface files may do. See Permissions. | ||
workshopItemId | string | The Steam Workshop item id. The first publish fills it in. Do not edit it by hand. |
VALIDATE warns about any field that is not in this table. The schema is mod_manifest.schema.json (see JSON schemas).
Icon and thumbnail
The mod’s row in MOD LOADOUT shows the picture thumbnailPath names, or the one iconPath names when there is no thumbnail. Both must point at a file inside the mod folder. The game never looks for a picture by file name, such as icon.png or logo.png in the mod root, so declare the paths if you want a picture.
Scenario
A mod carries at most one scenario. The game takes the first of these that applies:
scenarioFolder, when the folder exists.defaultScenarioFile.- A
scenario/subfolder that containsscenario.json. It is detected without any manifest field.
When more than one enabled mod carries a scenario, the game does not choose between them: no mod scenario loads, and the MOD LOADOUT panel shows No active scenario and lists a warning. The exception is a selectedScenarioModId in loadout.json that names one of them. Enable one scenario mod at a time.
Entry points
| Field | Names | When it is empty or does not point at a file in the mod folder |
|---|---|---|
entrypoints.wasm | The mod’s WASM module. | The game loads scripts/main.wasm if that file exists. A path that was declared but not found adds a load warning. |
entrypoints.ui | The UI injection file. The Mod Builder’s Interface pages edit it and write this field for you. See UI injection. | The game loads ui/panels.json if that file exists. |
Declare both paths in the manifest. VALIDATE reports a declared path that does not exist as an error.
Runtime policy
runtimePolicy says how a mod’s WASM module and its C# assemblies run together.
| Policy | Behaviour |
|---|---|
"coexist" (default) | The WASM module and the C# assemblies both load, and their hooks run side by side. |
"wasm_only" | The mod’s Mods/*.dll files are not loaded. If another enabled mod has already registered C# hooks, the game reports a runtime policy conflict and WASM scripts receive no hooks in that session. |
"csharp_only" | The mod’s WASM module is not loaded. Only its C# assemblies run. |
Managed assemblies
Put compiled assemblies directly in:
<mod-root>/Mods/*.dll
The game loads every .dll in that folder (not in subfolders) and creates each public, non-abstract class that implements IModEntrypoint and has a parameterless constructor. It calls Initialize(IModServices services) on it, and Dispose() when mods unload. Set managedSdkVersion to the SDK you built against.
Component runtime
Set enableComponentRuntime to true only when the WASM binary is in component-model format. Without it, a component-model binary is refused with a load error. A core WASM module leaves it false.
Scripts and multiplayer
The WASM module the game loads and every Mods/*.dll are part of the multiplayer lobby check. Players whose script files differ in any byte cannot join the same game, even with the same mod id and version. The hooks a script can handle, and the functions it can call, are on the WASM scripting page.
On macOS the game has no WASM backend. A mod that ships a WASM module loads its data and content there, with a load warning, and the script does not run.
Load order, dependencies and game version
Load order
Every stage that layers mods (content rosters, config overrides, events, localization, icons) applies them in one load order. Where two mods change the same thing, the later mod wins.
There is one exception. An engine event’s id (see Events) belongs to the first mod in load order that defines it. A later mod’s engine event with the same id is skipped with a load error, and the earlier one stays. A patch mod therefore cannot replace another mod’s event: ship yours under a different id.
The game computes the order from the enabled mods’ manifests:
- Dependencies first. A mod always loads after every mod in its
dependencies. - Then
loadOrderHint, ascending, among mods that do not depend on each other. The default is0. Use a negative hint for a base or library mod, and a positive one for a patch meant to win. - Then the mod id, compared character by character, to break ties. With no dependencies and no hints anywhere, the order is by id alone.
The MOD LOADOUT panel shows each enabled mod’s position as [n] after its name. There are no up and down buttons: the order comes only from the manifests, never from one player’s list. In multiplayer every player must load the same mods in the same order, and the lobby’s mod check covers dependencies and loadOrderHint.
Dependencies
A dependency is written as "other.mod" (any installed version) or "other.mod@range". The id is everything before the first @ and cannot contain a space.
A mod does not load when a dependency:
- is not installed;
- is installed but not enabled (enable it and reload; the mod stays enabled meanwhile);
- has a
versionoutside the range, or one that is not semver; - could not load itself;
- is part of a dependency cycle.
A malformed entry, and a mod that lists itself, stop the mod from loading too. Other mods keep loading.
The mod’s row shows a red badge that names the problem (NEEDS with the entry, BAD DEPENDENCY with the entry, or DEPENDENCY CYCLE), and the panel lists a load error.
Version ranges
Ranges in dependencies and gameVersion use the npm style.
| Form | Means |
|---|---|
1.2.3 or =1.2.3 | exactly that version |
>=1.2.0, >1.2.0, <2.0.0, <=1.4.0 | comparisons |
>=0.5.0 <0.7.0 | both (a space means AND) |
^1.2.3 | >=1.2.3 <2.0.0. For ^0.5.1: >=0.5.1 <0.6.0. For ^0.0.3: >=0.0.3 <0.0.4. |
~1.2.3 | >=1.2.3 <1.3.0 |
1.2, 1.2.x, 1, * | any matching version (* matches every version) |
1.2.3 - 2.0.0 | inclusive range |
^1.0.0 || ^2.0.0 | either (|| means OR) |
- A version is
MAJOR.MINOR.PATCH, with an optional pre-release tag (1.0.0-beta.1) and optional build metadata (+build5), which is ignored. Numbers have no leading zeros. Avprefix is not accepted. - A pre-release version sorts before its release, by semver precedence, and a range treats it like any other version:
<2.0.0matches2.0.0-beta.1.
Game version
gameVersion is compared with the running game’s version, for example 0.5.35.
- Outside the range, the mod loads all the same. Its MOD LOADOUT row shows an amber FOR GAME badge with the range, and the panel lists a warning.
- A range the game cannot read is ignored. The row shows an amber BAD GAME VERSION badge, and the panel lists a warning.