🚇/Docs

First Mod

Create a proper mod with manifest.json

Now that you've experimented with the API in the console, let's create a proper mod that can be installed and shared.

Create the Mod Folder#

  1. Navigate to your mods folder (see Getting Started)
  2. Create a new folder for your mod: mods/my-first-mod/

Add manifest.json#

Create manifest.json in your mod folder:

json
{
    "id": "com.yourname.my-first-mod",
    "name": "My First Mod",
    "description": "My first Subway Builder mod!",
    "version": "1.0.0",
    "author": {
        "name": "Your Name"
    },
    "main": "index.js"
}

Manifest fields:

FieldRequiredDescription
idYesUnique identifier (use reverse domain notation)
nameYesDisplay name shown in the mod manager
descriptionNoShort description of what your mod does
versionYesSemantic version number
author.nameYesYour name or username
mainYesEntry point JavaScript file

Add index.js#

Create index.js with your mod code:

javascript
// My First Mod for Subway Builder
(function () {
    const api = window.SubwayBuilderAPI;

    // Log when mod loads
    console.log('[My First Mod] Loaded!');

    // Show a notification when the game starts
    api.hooks.onGameInit(() => {
        api.ui.showNotification('My First Mod is active!', 'success');
    });

    // Give a bonus every 100 days
    api.hooks.onDayChange((day) => {
        if (day % 100 === 0) {
            api.actions.addMoney(1_000_000, 'bonus');
            api.ui.showNotification(`Day ${day} bonus: $1,000,000!`, 'success');
        }
    });

    // Celebrate station milestones
    let stationCount = 0;
    api.hooks.onStationBuilt((station) => {
        stationCount++;
        if (stationCount === 10) {
            api.ui.showNotification('10 stations! Keep growing!', 'success');
        }
    });
})();

Enable the Mod#

  1. Restart Subway Builder (or use hot reload)
  2. Go to Settings > Mods
  3. Find "My First Mod" in the list
  4. Toggle it ON
  5. The mod is now active!

Mod Structure#

Your mod folder should look like this:

mods/
└── my-first-mod/
    ├── manifest.json
    └── index.js

Best Practices#

Wrap in IIFE#

Always wrap your mod code in an Immediately Invoked Function Expression (IIFE) to avoid polluting the global scope:

javascript
(function () {
    // Your mod code here
})();

Use a Prefix for Logging#

Add a prefix to your console logs so they're easy to identify:

javascript
console.log('[My Mod] Something happened');

Handle Errors Gracefully#

Wrap risky operations in try-catch:

javascript
try {
    // Risky operation
} catch (error) {
    console.error('[My Mod] Error:', error);
}

Check API Availability#

Always check if the API is available before using it:

javascript
if (!window.SubwayBuilderAPI) {
    console.error('[My Mod] SubwayBuilderAPI not found!');
    return;
}

Next Steps#