trains

api.trains. 4 members.

registerTrainType#

api.trains.registerTrainType(trainType: TrainTypeStatsItem): void

Register a train type.

Stores trainType in the registry under trainType.id, replacing any existing entry wholesale.

No stat defaults are filled. A missing required stat stays undefined. trainType.id is prepended to compatibleTrackTypes when absent (an omitted array becomes [id]), and to compatibleStationTrackTypes when that array is present and lacks it. The registry is pushed to the sim host worker when one is running; the worker replaces its own copy. An id absent from the owned-cars ledger gets a 0 entry. In development builds logs [Modding API] Registering train type: <name> (<id>), or Updating for an existing id. reloadMods keeps registered types.

Parameter trainType (TrainTypeStatsItem): complete TrainTypeStatsItem; id required.

Errors: falsy object or missing id: logs [Modding API] Invalid train type - must have id, does nothing.

Side effects: TRAIN_TYPES[id]; sim host worker constants push when one is running; store ownedCarsByType[id] = 0 when absent.

// registerTrainType fills no defaults: start from a built-in type and change what differs
const base = api.trains.getTrainType('heavy-metro');
api.trains.registerTrainType({
    ...base,
    id: 'my-express-metro',
    name: 'Express Metro',
    description: 'Faster, longer trains for trunk lines',
    compatibleTrackTypes: ['heavy-metro'],
    stats: { ...base.stats, maxSpeed: 33, maxCars: 12, carCost: 3_000_000 },
    appearance: { ...base.appearance, color: '#f59e0b' },
});

modifyTrainType#

api.trains.modifyTrainType(id: string, overrides: Partial<TrainTypeStatsItem>): void

Patch a registered train type.

Deep-merges overrides into the existing record.

Object values merge recursively into object values. Arrays, primitives, null and undefined replace. After the merge, id is prepended to compatibleTrackTypes when absent, and to compatibleStationTrackTypes when present and lacking it. The registry is pushed to the sim host worker when one is running. In development builds logs [Modding API] Modifying train type: <id>.

Errors: unknown id: logs [Modding API] Train type "<id>" not found, does nothing.

Side effects: TRAIN_TYPES[id]; sim host worker constants push when one is running.

Changed: the namesake id is restored in compatibleTrackTypes after the merge, and in compatibleStationTrackTypes when that array is present (PR #1090).

api.trains.modifyTrainType('heavy-metro', { stats: { maxSpeed: 30 }, appearance: { color: '#ef4444' } });
// other stats and appearance fields keep their values

getTrainTypes#

api.trains.getTrainTypes(): Record<string, TrainTypeStatsItem>

The live train type registry, keyed by id.

Returns: Record<string, TrainTypeStatsItem>. the registry object itself; a direct mutation is not pushed to the sim host worker.

for (const [id, t] of Object.entries(api.trains.getTrainTypes())) {
    console.log(`${id}: ${t.name}, ${t.stats.maxSpeed} m/s, ${t.stats.capacityPerCar} per car`);
}

getTrainType#

api.trains.getTrainType(id: string): TrainTypeStatsItem | undefined

One train type record by id.

Parameter id (string): train type id.

Returns: TrainTypeStatsItem | undefined. the live record; undefined for an unknown id. The game's internal getTrainType helper falls back to heavy-metro.

const t = api.trains.getTrainType('heavy-metro');
if (t) console.log(`${t.name}: ${(t.stats.maxSpeed * 3.6).toFixed(0)} km/h`);

TrainTypeStatsItem#

One registry record. Defines a train type and the track type of the same id.

Every track type id in any compatibleTrackTypes must itself be a registry key. The namesake record supplies the track's build cost, geometry limits and grade-crossing rules. Built-in ids: heavy-metro, light-metro, light-rail, commuter-rail, commuter-rail-diesel, plus tram behind the ENABLE_TRAM feature flag. The game's internal getTrainType helper resolves an unknown id to heavy-metro.

TrainTypeStatsItem.stats#

defaultCars: Car count a brand-new route of this type is seeded with (newRoutePanel's create flow, generateRoute). Optional: unset falls back to minCars, which is right whenever minCars is itself a sane starting train. Set this explicitly when minCars is lowered to widen a floor (e.g. heavy metro's 2-car minimum for light-metro upgrades, #1179) without also shrinking the default size of every new line. Read via getDefaultCarsForTrainType.

maxCantMm: mm; optional; omitted falls back to RULES.CANT_MAX_APPLIED_MM (150 mm); applied-cant cap on cant-enabled running track; RULES.CANT_STATION_MAX_MM (0 mm) caps it on station track and RULES.CANT_STREET_RUNNING_MAX_MM (0 mm) on street-running track; with feature flag CANT_MECHANICS on, RULES.CANT_MAX_STOPPED_MM (150 mm) caps it within RULES.CANT_STOP_ZONE_LENGTH_M (200 m) of a junction or station end and cant builds at RULES.CANT_RAMP_MM_PER_S (45 mm/s) along the track; legacy tracks ignore it and use maxLateralAcceleration.

Performance, geometry, capacity and cost figures. Required fields have no fallback. An omitted one stays undefined. In sandbox mode the costs below are recorded as expenses without reducing money, except a route train-type conversion (behind the ROUTE_TYPE_CONVERSION feature flag, off by default), which takes its cost straight off money in every mode.

Curve speed on cant-enabled track: sqrt((cant + maxCantDeficiencyMm) / 150 * radius) m/s with radius floored at minTurnRadius, rounded, and never above the limit already in force; with feature flag CANT_MECHANICS off, cant is the full context cap; with it on, cant is the ramped profile and the sum is floored at 20 mm.

TrainTypeStatsItem.appearance#

TrainTypeStatsItem.compatibleStationTrackTypes#

Subset of compatibleTrackTypes whose stations this train can stop at. The other compatible track types are run-through only. Absent means every compatible track type's stations. Ids outside compatibleTrackTypes have no effect. The record's own id is prepended when the array is present and lacks it.

TrainTypeStatsItem.invisible#

true hides the type from the buy-trains picker, the new-route and route-details type selectors (the new-route selector keeps it while selected), route type switch offers, the construction track picker, the train types panel, the by-type grouping of the trains list, the measure tool and the map key. Lookups by id, existing trains, tracks and routes keep working. Only the exact value true hides.

TrainTypeStatsItem.allowHighwayAtGradeCrossing#

true lifts the hardcoded highway block in road-collision validation for this type: roads with roadClass/index-type highway are then treated like any other road for allowAtGradeRoadCrossing (street-running) and allowGradeCrossing (gated grade crossing) checks, instead of always being blocked. Workaround for OSM roads miscategorized as highways that a real tram/bus route should be able to cross at grade. gradeCrossingTphLimit.highway (when set to null) still forbids crossings for allowGradeCrossing types even with this on. Does not affect street-running metadata (speed limit/road name), which still excludes highways.

TrainTypeStatsItem.trackConversions#

Directional upgrades the electrify tool offers for track of this type: { to, costPerMeter, stationCost? }. The first valid entry is used; an entry is skipped when to is missing, this id or not a registry key, or costPerMeter is not a finite number >= 0; a non-finite or negative stationCost reads as 0. Absent or empty means not convertible. Route type switch offers also use it: a blocking track group counts as reachable when its conversion target can host the new type.

AccelerationCurve#

Three-stage tractive-effort model, evaluated per tick to cap acceleration at the current speed (SI units).

speed <= v1: a = a0 + (a1 - a0) * speed / v1 (a0 when v1 is 0). v1 < speed <= v2: a = v1 * a1 / speed. speed > v2: a = v1 * a1 * v2^(exponent - 1) / speed^exponent. The result is capped at stats.maxAcceleration and floored at 0.05 m/s^2. A NaN result falls back to stats.maxAcceleration.

ElevationMultipliers#

Per-train-type construction cost multipliers keyed by elevation band.

The train types panel lists the overrides. Construction cost (the charge and the drawing preview) uses a set band in place of the global rule; unset bands and maintenance costs read the rule. Bands by track elevation (m): DEEP_BORE <= -24; STANDARD_TUNNEL -24 to -10; CUT_AND_COVER -10 to -4; TRENCHED -4 to -1; AT_GRADE -1 to 0; RAMP 0 to 5 exclusive; ELEVATED >= 5. Each upper bound belongs to the deeper band; 5 belongs to ELEVATED.

Grade Crossings#

A train type with allowGradeCrossing: true builds track that crosses roads at ground level; the game places a gated grade crossing at each crossing point. The fields sit at the top level of the train type, beside stats. Built in, commuter-rail, commuter-rail-diesel and light-rail allow grade crossings; heavy-metro and light-metro do not.

Build cost per crossing is gradeCrossingBaseCost times three multipliers:

Both rule tables are read at call time, so modifyConstants changes take effect on the next price. An omitted or 0 gradeCrossingBaseCost makes crossings free.

api.trains.modifyTrainType('commuter-rail', {
    gradeCrossingBaseCost: 400_000,
    gradeCrossingMaintenancePerDay: 6_000, // $ per built crossing per in-game day
    gradeCrossingTphLimit: { highway: null, major: 10, medium: 12, minor: 14 }, // null forbids the class
    gradeCrossingSpeedLimit: { major: 11.2, medium: 13.4 }, // m/s; minor stays uncapped
    gradeCrossingSpeedLimitApproachDistance: 150, // m on each side of the crossing
});

Custom Elevation Cost Multipliers#

elevationMultipliers on a train type stores per-band overrides (see ElevationMultipliers above). The train types panel lists them, but construction and maintenance costs do not read them: every train type pays the global CONSTRUCTION_COSTS.ELEVATION_MULTIPLIERS. Change those with modifyConstants to reprice elevation bands for all types.

Track cost also scales with lane count: CONSTRUCTION_COSTS.TUNNEL.SINGLE_MULTIPLIER (0.75) for single track and CONSTRUCTION_COSTS.TUNNEL.QUAD_MULTIPLIER (1.5) for quad track, in construction and maintenance.

At-Grade Road Crossing#

allowAtGradeRoadCrossing: true permits street running: at-grade track may run along roads other than highways, the track drawing cursor snaps to roads, and the track carries street-running metadata (road segments, speed limit). The built-in tram type, registered only when the ENABLE_TRAM feature flag is on, sets it. canCrossRoads is an older alias that only road-collision validation and the train types panel read, so set allowAtGradeRoadCrossing.

This is separate from grade crossings: street running lets track occupy the road, while allowGradeCrossing lets track cross it.

api.trains.modifyTrainType('light-rail', { allowAtGradeRoadCrossing: true });

Highway At-Grade Crossing#

allowHighwayAtGradeCrossing: true is a mod-only opt-in that lifts the hardcoded highway block in road-collision validation for this type: roads OSM tags highway (sometimes a miscategorized road a tram or bus route should realistically cross) are then checked like any other road class for both allowAtGradeRoadCrossing (street running) and allowGradeCrossing (gated crossing), instead of always failing. It's off by default and no built-in train type sets it. gradeCrossingTphLimit.highway: null still forbids the crossing even with this on, as a separate, explicit "forbidden" signal that wins over the flag. It doesn't change street-running metadata (speed limit/road name), which still excludes highways.

api.trains.modifyTrainType('light-rail', { allowHighwayAtGradeCrossing: true });

Example: Light Rail System#

A complete train type written out field by field. registerTrainType fills no defaults, so every required stat is present. The game ships its own light-rail; registering that id replaces the built-in wholesale, so this uses a new id. To tweak the built-in, use modifyTrainType('light-rail', ...).

const api = window.SubwayBuilderAPI;

api.trains.registerTrainType({
    id: 'my-light-rail',
    name: 'My Light Rail',
    description: 'Modern light rail for urban transit',
    stats: {
        maxSpeed: 25, // m/s
        maxSpeedLocalStation: 12,
        maxAcceleration: 1.2, // m/s²
        maxDeceleration: 1.3,
        maxLateralAcceleration: 0.9,
        maxSlopePercentage: 6,
        crossoverSpeed: 6.7,
        stopTimeSeconds: 20,
        turnaroundTimeSeconds: 90,
        minTurnRadius: 25, // m
        minStationTurnRadius: 100,
        parallelTrackSpacing: 3.0,
        trackClearance: 0.75,
        minCars: 1,
        maxCars: 4,
        carsPerCarSet: 1,
        capacityPerCar: 80,
        carLength: 20,
        trainWidth: 2.65,
        minStationLength: 20,
        maxStationLength: 80,
        carCost: 1_500_000,
        baseTrackCost: 20_000, // $ per m
        baseStationCost: 15_000_000,
        trainOperationalCostPerHour: 200,
        carOperationalCostPerHour: 30,
        trackMaintenanceCostPerMeter: 150,
        stationMaintenanceCostPerYear: 40_000,
        tphLimit: 50,
    },
    compatibleTrackTypes: ['my-light-rail'], // optional, defaults to [id]
    appearance: { color: '#10b981', roofStyle: 'rounded' },
    allowAtGradeRoadCrossing: true, // street running on roads other than highways
    portalCost: 4_000_000, // $ per tunnel portal
    rampCost: 2_000_000, // $ per ramp up to elevated track
    maxOverpassSpan: 80, // m
});