Lifecycle Hooks

React to game events with lifecycle hooks

Hooks let your mod respond to game events. Register a callback function that will be called when the event occurs.

Available Hooks#

onGameInit#

Called when the game initializes. Use this to set up your mod.

javascript
window.SubwayBuilderAPI.hooks.onGameInit(() => {
    console.log('Game initialized!');
});

onDayChange#

Called when the in-game day changes. Receives the new day number.

javascript
window.SubwayBuilderAPI.hooks.onDayChange((day) => {
    if (day % 100 === 0) {
        console.log(`Milestone: Day ${day}!`);
    }
});

onCityLoad#

Called when a city is loaded. Receives the city code.

javascript
window.SubwayBuilderAPI.hooks.onCityLoad((cityCode) => {
    console.log(`Loaded city: ${cityCode}`);
    if (cityCode === 'MTL') {
        // Do Montreal-specific initialization
    }
});

onMapReady#

Called when the map is fully loaded. Receives the MapLibre map instance.

javascript
window.SubwayBuilderAPI.hooks.onMapReady((map) => {
    console.log('Map is ready!', map);
    // Access raw MapLibre instance
    map.on('click', (e) => {
        console.log('Clicked:', e.lngLat);
    });
});

onStationBuilt#

Called when a station is constructed from blueprint.

javascript
window.SubwayBuilderAPI.hooks.onStationBuilt((station) => {
    console.log(`Station built: ${station.name}`);
});

onRouteCreated#

Called when a new route is created.

javascript
window.SubwayBuilderAPI.hooks.onRouteCreated((route) => {
    console.log(`New route: ${route.name} with ${route.stations.length} stations`);
});

onTrackBuilt#

Called when blueprint tracks are constructed.

javascript
window.SubwayBuilderAPI.hooks.onTrackBuilt((tracks) => {
    console.log(`${tracks.length} tracks constructed`);
});

onBlueprintPlaced#

Called when the player places blueprint tracks (before construction).

javascript
window.SubwayBuilderAPI.hooks.onBlueprintPlaced((tracks) => {
    console.log(`${tracks.length} blueprint tracks placed`);
});

onDemandChange#

Called when demand/population data is loaded for a city.

javascript
window.SubwayBuilderAPI.hooks.onDemandChange((popCount) => {
    console.log(`Demand data loaded: ${popCount} commuter groups`);
});

onTrackChange#

Called when tracks are added or removed.

javascript
window.SubwayBuilderAPI.hooks.onTrackChange((changeType, count) => {
    console.log(`Tracks ${changeType}: ${count} tracks`);
    // changeType is 'add' or 'delete'
});

onTrainSpawned#

Called when a new train is generated.

javascript
window.SubwayBuilderAPI.hooks.onTrainSpawned((train) => {
    console.log(`Train spawned on route ${train.routeId}`);
});

onTrainDeleted#

Called when a train is removed from service.

javascript
window.SubwayBuilderAPI.hooks.onTrainDeleted((trainId, routeId) => {
    console.log(`Train ${trainId} deleted from route ${routeId}`);
});

onRouteDeleted#

Called when a route is deleted.

javascript
window.SubwayBuilderAPI.hooks.onRouteDeleted((routeId, routeBullet) => {
    console.log(`Route ${routeBullet} deleted`);
});

onPauseChanged#

Called when the game is paused or resumed.

javascript
window.SubwayBuilderAPI.hooks.onPauseChanged((isPaused) => {
    console.log(`Game ${isPaused ? 'paused' : 'resumed'}`);
});

onSpeedChanged#

Called when game speed changes.

javascript
window.SubwayBuilderAPI.hooks.onSpeedChanged((newSpeed) => {
    console.log(`Game speed changed to: ${newSpeed}`);
    // newSpeed is 'slow', 'normal', 'fast', or 'ultrafast'
});

onMoneyChanged#

Called when the player's money changes.

javascript
window.SubwayBuilderAPI.hooks.onMoneyChanged((newBalance, change, type, category) => {
    console.log(`${type}: $${Math.abs(change)} (${category || 'general'})`);
    console.log(`New balance: $${newBalance}`);
    // type is 'revenue' or 'expense'
    // category is present for expenses (e.g., 'construction', 'trainOperational')
});

onGameSaved#

Called after the game is saved (manual or autosave).

javascript
window.SubwayBuilderAPI.hooks.onGameSaved((saveName) => {
    console.log(`Game saved: ${saveName}`);
});

onGameLoaded#

Called after a save is loaded.

javascript
window.SubwayBuilderAPI.hooks.onGameLoaded((saveName) => {
    console.log(`Game loaded: ${saveName}`);
});

Hook Summary#

HookParametersDescription
onGameInitnoneGame initialization
onDayChangeday: numberDay changed
onCityLoadcityCode: stringCity loaded
onMapReadymap: MapLibreMap ready
onStationBuiltstation: StationStation constructed
onRouteCreatedroute: RouteRoute created
onTrackBuilttracks: Track[]Tracks constructed
onBlueprintPlacedtracks: Track[]Blueprints placed
onDemandChangepopCount: numberDemand data loaded
onTrackChangetype: string, count: numberTracks added/removed
onTrainSpawnedtrain: TrainTrain created
onTrainDeletedtrainId: string, routeId: stringTrain removed
onRouteDeletedrouteId: string, bullet: stringRoute deleted
onPauseChangedisPaused: booleanPause state changed
onSpeedChangedspeed: stringSpeed changed
onMoneyChangedbalance, change, type, categoryMoney changed
onGameSavedsaveName: stringGame saved
onGameLoadedsaveName: stringGame loaded