Getting started
The mods folder, the manifest fields the loader enforces, enabling a mod and reloading.
Prerequisites#
- The Subway Builder desktop app. Mods load in the desktop app only; the loader skips mod loading when
window.electronis absent. - A text editor and some JavaScript.
Mods Folder Location#
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/metro-maker4/mods/ |
| Windows | %APPDATA%\metro-maker4\mods\ |
| Linux | ~/.config/metro-maker4/mods/ |
Settings > Advanced > Mod Manager > Open Mods Folder opens it. The Mod Manager is reachable from the home screen and from the pause menu.
One folder per mod. The folder name is free; the loader identifies a mod by the id in its manifest.
mods/
my-first-mod/
manifest.json
index.jsManifest#
Create manifest.json in the mod folder.
{
"id": "com.yourname.my-first-mod",
"name": "My First Mod",
"version": "1.0.0"
}| Field | Enforced | Rule |
|---|---|---|
id | yes | String without /, \ or ... Identifies the mod in the enabled list and in storage |
name | yes | Shown in the Mod Manager |
version | yes | Shown in the Mod Manager. Any truthy value passes |
main | no | Script file name. Default index.js. A path whose resolved form does not start with the mod folder path fails with Invalid script path |
A manifest missing id, name or version lists the folder under its folder name with the error Manifest missing required fields (id, name, version) and a disabled toggle. description, author, homepage, minGameVersion, maxGameVersion, dependencies and requiresRestart are read by the scan and shown in the Mod Manager; icon is read and shown nowhere. None of them is enforced.
Script#
Create index.js. First mod has the skeleton. The script runs through new Function inside a strict-mode function: import and export statements are syntax errors, top-level await is a syntax error, top-level return works, and assigning to an undeclared variable throws.
Enable#
A new mod starts disabled.
- Open Settings > Advanced > Mod Manager.
- If the mod is missing from the list, click the refresh icon (tooltip
Scan for new mods). - Toggle the mod on.
- Click Reload Now in the toast, press Ctrl+Shift+R (Cmd+Shift+R on macOS), or restart the game.
The enabled list is stored in settings.json next to the mods folder.
Reload#
Ctrl+Shift+R (the default binding), the Reload Mods button the Mod Manager shows after a toggle, and await window.SubwayBuilderAPI.reloadMods() in the DevTools console do the same thing: clear the API state, rescan the folder and re-run every enabled script. Debugging lists what a reload clears and keeps. The shortcut is listed as Reload Mods in the shortcuts dialog (Settings > Controls > View and customize shortcuts).