šŸš‡/Docs

Game Actions

Modify game state with action methods

Actions let your mod modify the game state. Use these to add money, control game flow, and more.

Important: Most actions use deferred execution (queueMicrotask) so they are safe to call from inside hooks like onDayChange. The action returns immediately, but the actual state change happens on the next microtask. This means you cannot read the updated state on the very next line ā€” use a hook like onMoneyChanged to react to the change instead.

Exception: issueBond, payBond, getBonds, and getTicketPrice execute synchronously because they return values. Avoid calling these from inside hooks if possible.

Money Actions#

setMoney#

Set the player's money to an exact amount. Triggers the onMoneyChanged hook if the value differs from the current balance.

javascript
window.SubwayBuilderAPI.actions.setMoney(10_000_000);

addMoney#

Add money to the player's balance. The second parameter is optional and currently unused (reserved for future categorization).

javascript
window.SubwayBuilderAPI.actions.addMoney(1_000_000);
window.SubwayBuilderAPI.actions.addMoney(500_000);

subtractMoney#

Subtract money from the player's balance. The second parameter is optional and currently unused (reserved for future categorization).

javascript
window.SubwayBuilderAPI.actions.subtractMoney(500_000);

Game Flow Actions#

setPause#

Pause or resume the game.

javascript
// Pause the game
window.SubwayBuilderAPI.actions.setPause(true);

// Resume the game
window.SubwayBuilderAPI.actions.setPause(false);

setSpeed#

Set the game speed.

javascript
// Available speeds: 'slow', 'normal', 'fast', 'ultrafast'
window.SubwayBuilderAPI.actions.setSpeed('fast');
window.SubwayBuilderAPI.actions.setSpeed('ultrafast');

setTicketPrice#

Set the ticket price (fare). Also updates the default cost for new games.

javascript
window.SubwayBuilderAPI.actions.setTicketPrice(5);

getTicketPrice#

Get the current ticket price. Returns number.

javascript
const price = window.SubwayBuilderAPI.actions.getTicketPrice();

setSpeedMultiplier#

Modify how many game-seconds pass per real second for a given speed tier. Multipliers are always applied to the original base value, so calling this multiple times or across hot reloads will not compound ā€” it safely replaces the previous multiplier.

javascript
// Make "fast" speed 2x faster than default
window.SubwayBuilderAPI.actions.setSpeedMultiplier('fast', 2.0);

// Reset to default
window.SubwayBuilderAPI.actions.setSpeedMultiplier('fast', 1.0);

Bonds#

issueBond#

Issue a new bond to raise capital. Returns { success: boolean, message?: string }.

javascript
const result = window.SubwayBuilderAPI.actions.issueBond('SMALL');
if (result.success) {
    console.log('Bond issued!');
} else {
    console.log('Failed:', result.message);
}

payBond#

Pay down an existing bond. Returns { success: boolean, message?: string }.

javascript
const result = window.SubwayBuilderAPI.actions.payBond('bond-id', 50_000_000);

getBonds#

Get all current bonds. Returns Bond[].

javascript
const bonds = window.SubwayBuilderAPI.actions.getBonds();

Game Constants#

modifyConstants#

Modify game rules and constants at runtime. This is a top-level API method, not under actions.

javascript
window.SubwayBuilderAPI.modifyConstants({
    STARTING_MONEY: 10_000_000_000, // 10B instead of 3B
    DEFAULT_TICKET_COST: 5,
    CONSTRUCTION_COSTS: {
        TUNNEL: {
            SINGLE_MULTIPLIER: 0.5 // Half the normal cost
        }
    }
});

Action Summary#

ActionParametersReturnsDescription
setMoneyamount: numbervoidSet exact money amount (triggers onMoneyChanged)
addMoneyamount: numbervoidAdd money (revenue)
subtractMoneyamount: numbervoidSubtract money (expense)
setPausepaused: booleanvoidPause or resume game
setSpeed`speed: 'slow' \'normal' \'fast' \'ultrafast'`voidSet game speed
setTicketPriceprice: numbervoidSet ticket price
getTicketPricenonenumberGet current ticket price
setSpeedMultiplier`speed: 'slow' \'normal' \'fast' \'ultrafast', multiplier: number`voidModify tick rate (non-compounding)
issueBondbondTypeId: string{ success, message? }Issue a new bond
payBondbondId: string, amount: number{ success, message? }Pay down a bond
getBondsnoneBond[]Get all current bonds
modifyConstants\*constants: objectvoidModify game rules

\* modifyConstants is a top-level method on window.SubwayBuilderAPI, not under .actions.

Example: Day/Night Economy Mod#

javascript
(function () {
    const api = window.SubwayBuilderAPI;

    // Track daily expenses
    let dailyExpenses = 0;

    api.hooks.onMoneyChanged((balance, change, type, category) => {
        if (type === 'expense') {
            dailyExpenses += Math.abs(change);
        }
    });

    api.hooks.onDayChange((day) => {
        // End of day report
        if (dailyExpenses > 1_000_000) {
            api.ui.showNotification(`High spending day! $${dailyExpenses.toLocaleString()}`, 'warning');
        }

        // Reset for next day
        dailyExpenses = 0;

        // Weekly bonus
        if (day % 7 === 0) {
            api.actions.addMoney(100_000);
            api.ui.showNotification('Weekly bonus: $100,000!', 'success');
        }
    });
})();