Subway Builder

The trains API lets you create new train types or modify existing ones.

Register a Train Type#

javascript

window.SubwayBuilderAPI.trains.registerTrainType({
    id: 'commuter-rail',
    name: 'Commuter Rail',
    description: 'High-capacity regional rail for longer distances',
    stats: {
        maxAcceleration: 0.8,
        maxDeceleration: 1.0,
        maxSpeed: 40, // m/s (~90 mph)
        maxSpeedLocalStation: 15,
        capacityPerCar: 150,
        carLength: 25,
        minCars: 4,
        maxCars: 12,
        carsPerCarSet: 2,
        carCost: 3_000_000,
        trainWidth: 3.2,
        minStationLength: 200,
        maxStationLength: 400,
        baseTrackCost: 40_000,
        baseStationCost: 60_000_000,
        trainOperationalCostPerHour: 600,
        carOperationalCostPerHour: 60,
        scissorsCrossoverCost: 20_000_000
    },
    compatibleTrackTypes: ['commuter-rail'],
    appearance: {
        color: '#8b5cf6'
    }
});

Train Type Properties#

Property	Type	Description
`id`	string	Unique identifier
`name`	string	Display name
`description`	string	Description text
`stats`	object	Performance and cost stats
`compatibleTrackTypes`	string[]	Track types this train can use
`appearance.color`	string	Hex color for train

Stats Properties#

Stat	Type	Description
`maxAcceleration`	number	Acceleration (m/s²)
`maxDeceleration`	number	Deceleration (m/s²)
`maxSpeed`	number	Top speed (m/s)
`maxSpeedLocalStation`	number	Speed at local stations (m/s)
`capacityPerCar`	number	Passengers per car
`carLength`	number	Car length (meters)
`minCars`	number	Minimum cars per train
`maxCars`	number	Maximum cars per train
`carsPerCarSet`	number	Cars purchased together
`carCost`	number	Cost per car
`trainWidth`	number	Train width (meters)
`minStationLength`	number	Min station platform length
`maxStationLength`	number	Max station platform length
`baseTrackCost`	number	Cost per track segment
`baseStationCost`	number	Base station cost
`trainOperationalCostPerHour`	number	Operating cost per hour
`carOperationalCostPerHour`	number	Car operating cost per hour
`scissorsCrossoverCost`	number	Crossover junction cost

Modify Existing Train Type#

Modify built-in train types:

javascript

// Make heavy metro faster and cheaper
window.SubwayBuilderAPI.trains.modifyTrainType('heavy-metro', {
    stats: {
        maxSpeed: 30, // Faster top speed
        carCost: 2_000_000 // Cheaper cars
    },
    appearance: {
        color: '#ef4444' // Red instead of blue
    }
});

Get Train Types#

javascript

// Get all train types
const allTypes = window.SubwayBuilderAPI.trains.getTrainTypes();
console.log(Object.keys(allTypes)); // ['heavy-metro', 'light-metro', ...]

// Get specific train type
const heavyMetro = window.SubwayBuilderAPI.trains.getTrainType('heavy-metro');
console.log(heavyMetro.stats.maxSpeed);

Custom Elevation Cost Multipliers#

Override elevation cost multipliers for specific train types:

javascript

window.SubwayBuilderAPI.trains.registerTrainType({
    id: 'tram',
    name: 'Streetcar',
    description: 'Light rail for street running',
    stats: {
        baseTrackCost: 15_000
        // ... other stats
    },
    compatibleTrackTypes: ['tram'],
    appearance: { color: '#f59e0b' },

    // Override elevation multipliers
    elevationMultipliers: {
        AT_GRADE: 0.5, // Cheaper at grade (designed for streets)
        ELEVATED: 1.8, // More expensive elevated
        CUT_AND_COVER: 1.2 // Slightly more expensive tunnels
        // DEEP_BORE and STANDARD_TUNNEL use global defaults
    }
});

Elevation types:

Type	Depth Range	Description
`DEEP_BORE`	< -30m	Deep tunnels
`STANDARD_TUNNEL`	-30m to -8m	Standard tunnels
`CUTANDCOVER`	-8m to -3m	Shallow tunnels
`AT_GRADE`	-3m to 4.5m	Street level
`ELEVATED`	> 4.5m	Above ground

At-Grade Road Crossing#

Enable at-grade road crossing for trams/streetcars:

javascript

window.SubwayBuilderAPI.trains.registerTrainType({
    id: 'tram',
    name: 'Streetcar',
    description: 'Light rail for street running',
    stats: { /* ... */ },
    compatibleTrackTypes: ['tram'],
    appearance: { color: '#f59e0b' },

    // Allow tracks to cross roads at grade
    allowAtGradeRoadCrossing: true
    // Or use the alias: canCrossRoads: true
});

Note: Runways and taxiways still block at-grade tracks regardless of this setting.

Example: Light Rail System#

javascript

window.SubwayBuilderAPI.trains.registerTrainType({
    id: 'light-rail',
    name: 'Light Rail',
    description: 'Modern light rail for urban transit',
    stats: {
        maxAcceleration: 1.2,
        maxDeceleration: 1.3,
        maxSpeed: 25,
        maxSpeedLocalStation: 12,
        capacityPerCar: 80,
        carLength: 20,
        minCars: 1,
        maxCars: 4,
        carsPerCarSet: 1,
        carCost: 1_500_000,
        trainWidth: 2.65,
        minStationLength: 50,
        maxStationLength: 100,
        baseTrackCost: 20_000,
        baseStationCost: 15_000_000,
        trainOperationalCostPerHour: 200,
        carOperationalCostPerHour: 30,
        scissorsCrossoverCost: 5_000_000
    },
    compatibleTrackTypes: ['light-rail'],
    appearance: {
        color: '#10b981'
    },
    elevationMultipliers: {
        AT_GRADE: 0.7,
        ELEVATED: 1.5
    },
    allowAtGradeRoadCrossing: true
});