Wiki menu

Folder layout and manifest

Where a mod's files go, what mod.json declares, how Validate Mod and Workshop uploads treat the folder, and how load order and dependencies work.

Last updated for v0.5.35
On this page

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

Where the game looks

On Windows the game searches these places, in this order. Each mod sits in its own subfolder.

OrderFolderNotes
1%LOCALAPPDATA%\NewWorldOrder\Mods\Also holds loadout.json, the list of mods you enabled and the scenario you selected.
2Documents\GlobalProtocol\Mods\
3%USERPROFILE%\AppData\LocalLow\Dorlion Interactive\Global Protocol\Mods\Where the Mod Builder creates a mod unless you pick another folder.
4The Steam Workshop folder of each item you subscribed toSteam 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.

PathWhat it isDocumented on
mod.jsonThe manifest: id, name, version, permissions, entry points.Manifest fields
.modignorePatterns for files that stay out of a Workshop upload.What a Workshop upload contains
Content/buildings.json, Content/units.json, Content/resources.jsonContent rosters: merge into, replace or cut down the game’s buildings, units and resources.Content rosters
Content/currencies.jsonThe currencies money is shown in. Display only.Currencies
Content/research_tracks.jsonResearch tracks of your own.Mod research
Content/specialists.jsonSpecialists a country can employ.Specialists
Content/demography/seeds.json, Content/demography/model.jsonPopulation seed rows and demography model tables.Demography
Content/events/*.jsonEvents. The game reads every .json file directly in this folder, in file-name order.Events
Content/localization/<language>.csvText keys per language.Localization
Content/ui/inject.jsonToolbar 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.jsonColours, sizes and rules that restyle the HUD.HUD theming
Content/ui/layout.json, Content/ui/layouts/<slot>.uxmlHUD slots to replace or hide, and the replacement layouts.HUD layout
Content/ui/hud_trackers.jsonUp 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.jsonMap 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.jsonSparse changes to the game’s rule numbers.Game settings
overrides/game_flow.jsonThe game_flow section of the game settings as its own file.Game flow
overrides/events.json, overrides/envoys.jsonThe events and envoys sections of the game settings as their own files.Config override files
overrides/doctrines.jsonChanges to the Knowledge Network’s doctrines.Doctrines
overrides/laws.jsonChanges to laws.Laws
overrides/interest_groups.jsonChanges to interest groups and the electorate.Interest groups
scenario/scenario.json and the nine split filesThe scenario: header, countries, starting diplomacy, province ownership and starting forces. The split file names are fixed.Split-folder scenario, Country overrides
scenario/national_goals.jsonNational goals. Any file name works: the header’s nationalGoalsFile names it.National goals
scenario/victories.jsonScenario victories, named by victoryFile.Scenario victories
scenario/provinces_data.jsonPer-province starting data, named by provinceDataFile.Scenario province data
scenario/institutions.json, scenario/trade_arrangements.jsonInstitution 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/*.dllCompiled 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.json inside another mod’s folder (a workshop_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.ini and ._*;
  • backups whose name ends in .bak, in .bak plus one more character (.bak2) or in .bak- plus anything (.bak-20260512);
  • symbolic links and junctions;
  • every subfolder that has its own mod.json;
  • .modignore itself.

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:

LevelMeansEffect on a Workshop upload
ErrorThe game rejects or drops this.Stops the upload.
WarningIt loads, but probably does not do what you meant.Needs one extra confirmation.
NoteInformation 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.json and model.json, Content/ui/theme.json, layout.json and hud_trackers.json, the split scenario files, and the files the scenario header names with nationalGoalsFile, victoryFile, currenciesFile and provinceDataFile.
  • The overrides/*.json files and the Content rosters only list what they change. They are checked without the required fields, and a mismatch is a warning. A roster field set to null where 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/ or overrides/ that the game never reads is a warning. So is a file in Content/localization/ that is not named after one of the game’s languages.

Manifest.

CheckLevel
id uses only lowercase letters and digits, joined by single dots, dashes or underscoreswarning
The folder is named after the id (not checked for a Workshop install)warning
version is semvererror
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 4warning
A WASM module imports a function that needs a higher wasmAbiVersion or a permission the mod did not declareerror
iconPath and thumbnailPath exist and are part of the uploadwarning
entrypoints.wasm, entrypoints.ui, defaultScenarioFile and scenarioFolder exist and are part of the uploaderror
gameVersion is a range the game can readerror
The running game is inside the gameVersion rangewarning
A dependencies entry is malformed, or names the mod itselferror
A dependency is not installed on this computer, or is installed at a version outside the rangewarning
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 the game_settings sections 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"]
}
FieldTypeRequiredDefaultDescription
idstringyesUnique 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.
displayNamestringyesThe name on the mod’s row in MOD LOADOUT.
versionstringyesSemver 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.
descriptionstringShort summary. Pre-fills the Workshop description on the Publish page.
authorstringAuthor name. Informational.
tagsstring[]Category tags such as scenario or balance. Informational: they never change how the mod loads.
iconPathstringPath, relative to the mod folder, of a small picture of the mod.
thumbnailPathstringPath of a larger preview picture. Pre-fills the Workshop preview image on the Publish page.
erastringOptional era label. Informational: the game does not act on it.
startYearintegerOptional suggested start year, 0 or more. Informational: the scenario header’s startYear sets the real start date.
gameVersionstringRange 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.
dependenciesstring[]Mods that must be enabled for this one to load: "other.mod" or "other.mod@^1.2.0". They always load first.
loadOrderHintinteger0Position among mods that do not depend on each other: lower loads first, higher loads later and wins where two mods change the same thing.
enabledByDefaultbooleanfalseEnables the mod for a player who has not saved a selection in MOD LOADOUT.
defaultScenarioFilestringPath of a single-file scenario.
scenarioFolderstringPath of a folder with split scenario files. It must contain scenario.json. Wins over defaultScenarioFile.
entrypointsobjectPaths of the mod’s script and interface files: entrypoints.wasm and entrypoints.ui.
wasmAbiVersioninteger1The 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.
runtimePolicystring"coexist"How the mod’s WASM module and C# assemblies run together: coexist, wasm_only or csharp_only. See Runtime policy.
enableComponentRuntimebooleanfalseAllows a component-model WASM binary. Leave it false for a core WASM module.
managedSdkVersionstringThe 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.
permissionsstring[]What the mod’s code and interface files may do. See Permissions.
workshopItemIdstringThe 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:

  1. scenarioFolder, when the folder exists.
  2. defaultScenarioFile.
  3. A scenario/ subfolder that contains scenario.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

FieldNamesWhen it is empty or does not point at a file in the mod folder
entrypoints.wasmThe 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.uiThe 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.

PolicyBehaviour
"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:

  1. Dependencies first. A mod always loads after every mod in its dependencies.
  2. Then loadOrderHint, ascending, among mods that do not depend on each other. The default is 0. Use a negative hint for a base or library mod, and a positive one for a patch meant to win.
  3. 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 version outside 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.

FormMeans
1.2.3 or =1.2.3exactly that version
>=1.2.0, >1.2.0, <2.0.0, <=1.4.0comparisons
>=0.5.0 <0.7.0both (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.0inclusive range
^1.0.0 || ^2.0.0either (|| 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. A v prefix 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.0 matches 2.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.

Play Global Protocol: New World Order

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