Skip to content

Transport Simulation Core API#

Transport Simulation Core (TSC) is the backend serving MTR 4, it is responsible for holding all simulation data such as Stations / Depots / Rails, as well as performing the simulation itself.

When developing scripts, you may encounter several types which are related to TSC. The following provides some commonly used fields/functions for those types.

Type#

Siding#

Represents a siding rail.

References

Functions And Objects Description
Siding.getName(): String Returns the siding name / siding number.
Siding.getHexId(): String Get the id of the siding, formatted in hexadecimal and returned as a String.
Siding.getId(): long Returns the id of the siding.
Siding.getRailLength(): double Returns the length of the siding in meters.
Siding.getDepotName(): String Returns the name of the depot containing this siding.
Returns empty string if there's no data reference to the depot.
Siding.getEarlyVehicleIncreaseDwellTime(): boolean Returns whether vehicle will extend it's dwell time if early.
Siding.getMaxVehicles(): int Returns the maximum number of vehicles for this siding.
Returns 0 if unlimited vehicles.
Siding.getIsUnlimited(): boolean Returns whether the siding allows unlimited vehicles.
Same as checking Siding.getMaxVehicles() == 0
Siding.getDelayedVehicleSpeedIncreasePercentage(): int Returns the percentage in which train will increase it's speedif running late.
Unit is percentage in integer form.
Siding.getDelayedVehicleReduceDwellTimePercentage(): int Returns the percentage in which train will reduce it's dwell time if running late.
Unit is percentage in integer form.
Siding.getMidPosition(): Position Returns the Position in the middle of the siding rail.
Siding.containsPos(pos: Position): boolean Whether pos is equal to the start or end of the rail position.

Platform#

Represents a platform rail.

References

Functions And Objects Description
Platform.routes: ObjectAVLTreeSet<Route> A list of routes that goes through this platform.
Platform.routeColors: IntAVLTreeSet All colors of route that goes through this platform.
Platform.getName(): String Returns the platform name / platform number.
Platform.getHexId(): String Get the id of the platform, formatted in hexidecimal and returned as a String.
Platform.getId(): long Returns the id of the platform.
Platform.getDwellTime(): long The dwell time duration of the platform in millisecond.
Platform.getMidPosition(): Position Returns the Position in the middle of the platform rail.
Platform.containsPos(pos: Position): boolean Whether pos is equal to the start or end of the rail position.

Station#

Represents a Station area.

References

Functions And Objects Description
Station.getHexId(): String Get the id of the station, formatted in hexidecimal and returned as a String.
Station.getId(): long Returns the id of the station.
Station.getName(): String Returns the station name.
Station.getColor(): int Returns the RGB color of the station.
Station.getColorHex(): String Returns the RGB color of the station, formatted in hexidecimal and returned as a String.
Station.getZone1(): long Returns Fare Zone 1 of the station.
Station.getZone2(): long Returns Fare Zone 2 of the station.
Station.getZone3(): long Returns Fare Zone 3 of the station.
Station.getMinX(): long Returns the minimum X position of the station area.
Station.getMinY(): long Returns the minimum Y position of the station area.
Station.getMinZ(): long Returns the minimum Z position of the station area.
Station.getMaxX(): long Returns the maximum X position of the station area.
Station.getMaxY(): long Returns the maximum Y position of the station area.
Station.getMaxZ(): long Returns the maximum Z position of the station area.
Station.inArea(pos: Position): boolean Whether a Position is inside the station area.
Station.isTransportMode(mode: TransportMode): boolean Whether the given TransportMode is the same as the station's assigned transport mode.
Station.getCenter(): Position Returns the Position of the station area's center point.
Station.getExits(): List<StationExit> Returns a list of station exits. (StationExit)

StationExit#

Represents a Station Exit entry.

References

Functions And Objects Description
StationExit.getName(): String Returns the name of the exit. (i.e. Exit letter)
StationExit.getDestinations(): List<String> Returns a list of destinations configured for the exit.
The 1st entry in the list is the chosen destination to be displayed by MTR Railway Signs.

TransportMode#

References

Represents a type of transport.

Functions And Objects Description
static TransportMode.TRAIN: TransportMode Returns an instance of TransportMode, representing rail transport.
static TransportMode.BOAT: TransportMode Returns an instance of TransportMode, representing boat transport.
static TransportMode.CABLE_CAR: TransportMode Returns an instance of TransportMode, representing cable car transport.
static TransportMode.AIRPLANE: TransportMode Returns an instance of TransportMode, representing air transport.
TransportMode.maxLength: int Returns the maximum vehicle length allowed for the transport.

Depot#

Represents a Depot area.

References

Functions And Objects Description
Depot.getHexId(): String Get the id of the depot, formatted in hexidecimal and returned as a String.
Depot.getId(): long Returns the id of the depot.
Depot.getName(): String Returns the depot name.
Depot.getColor(): int Returns the RGB color of the depot.
Depot.getColorHex(): String Returns the RGB color of the depot, formatted in hexadecimal and returned as a String.
Depot.getRouteIds(): List<Long> Returns a list of route ids assigned to this depot.
Depot.getLastGeneratedMillis(): long Returns the timestamp (In millisecond) of the last successful path generation.
Depot.getRepeatInfinitely(): boolean Whether the depot is configured to repeat route instructions.
Depot.getUseRealTime(): boolean Whether the depot uses real-time schedule, or Minecraft time.
Depot.getRealTimeDepartures(): List<Long> A list of assigned departure time, if using real-time schedule.
Depot.getMinX(): long Returns the minimum X position of the depot area.
Depot.getMinY(): long Returns the minimum Y position of the depot area.
Depot.getMinZ(): long Returns the minimum Z position of the depot area.
Depot.getMaxX(): long Returns the maximum X position of the depot area.
Depot.getMaxY(): long Returns the maximum Y position of the depot area.
Depot.getMaxZ(): long Returns the maximum Z position of the depot area.
Depot.inArea(pos: Position): boolean Whether a Position is inside the depot area.
Depot.isTransportMode(mode: TransportMode): boolean Whether the given TransportMode is the same as the depot's assigned transport mode.
Depot.getCenter(): Position Returns the Position of the depot area's center point.

SimplifiedRoute#

References

A Route object designed for consumption by the client-side, with several fields stripped out to save bandwidth.

Note: Hidden routes are never transmitted to the client, therefore it is guarenteed that all SimplifiedRoute must not be hidden.

Access of Route Number

Route Number (a.k.a. Light Rail Route Number) is not transferred as part of SimplifiedRoute.
It may be obtained via VehicleExtraData

Functions And Objects Description
SimplifiedRoute.getName(): String Returns the route name.
SimplifiedRoute.getId(): long Returns the id of the route.
SimplifiedRoute.getColor(): int Returns the RGB color of the route.
SimplifiedRoute.getCircularState(): Route.CircularState Returns the Circular State of the route
SimplifiedRoute.getPlatforms(): List<SimplifiedRoutePlatform> Returns a list of SimplifiedRoutePlatform object, representing the list of stop of the route.
SimplifiedRoute.getPlatformIndex(platformId: long): int Given a platform id, returns the index of the first instance of the platform appearing in the route.
Returns -1 if the platformId is not found in SimplifiedRoute's platform list.

SimplifiedRoutePlatform#

References

Equivalent to a stop the train will make.

Functions And Objects Description
SimplifiedRoutePlatform.getPlatformId(): long Returns the id of the platform.
SimplifiedRoutePlatform.getStationId(): long Returns the id of the belonging station area.
SimplifiedRoutePlatform.getStationName(): String Returns the name of the belonging station area.
SimplifiedRoutePlatform.getDestination(): String Returns the destination string of this platform in the route

Route.CircularState#

References

Represents a circular state of a route.

Functions And Objects Description
static CircularState.NONE: CircularState The route is not circular.
static CircularState.CLOCKWISE: CircularState The route is clockwise circular.
static CircularState.ANTICLOCKWISE: CircularState The route is anti-clockwise circular.

Vehicle#

References

A vehicle formation / consists.

Functions And Objects Description
Vehicle.vehicleExtraData: VehicleExtraData The real-time data of the vehicle, related to operations. (Such as speed target, stop index etc.)
See VehicleExtraData

VehicleExtraData#

References

Represents real-time data of a vehicle.

Functions And Objects Description
VehicleExtraData.getDepotId(): long Returns the id of the depot this vehicle's siding belongs to.
VehicleExtraData.getSidingId(): long Returns the id of the siding this vehicle belongs to.
VehicleExtraData.getStopIndex(): int Returns the next stop index along the PathData.
VehicleExtraData.getIsTerminating(): boolean Returns whether the train has reached the last stop or beyond.
VehicleExtraData.getStoppingPoint(): double Returns the absolute railProgress distance in which the train is expected stop.
VehicleExtraData.getSpeedTarget(): double Returns the target speed the train should accelerate and follow against.
Unit is in m/millisecond, multiply by 1000 to get m/s.
-1 when vehicle is approaching to a stop.
VehicleExtraData.iterateRidingEntities(callback: Consumer<VehicleRidingEntity>): void Executes a callback, providing all VehicleRidingEntity of the current vehicle.
Functions And Objects Description
VehicleExtraData.getPreviousRouteId(): long Returns the id of the route in previous stops.
Returns 0 if there's no previous stop.
VehicleExtraData.getPreviousRouteColor(): int Returns the id of the route's color in previous stops, in RGB format.
Returns 0 if there's no previous stop.
VehicleExtraData.getPreviousRouteName(): String Returns the route name in previous stops.
Returns an empty string if there's no previous stop.
VehicleExtraData.getPreviousRouteNumber(): String Returns the route number (In MTR 3, a lightRailRouteNumber) in previous stops.
Returns an empty string if there's no previous stop.
VehicleExtraData.getPreviousRouteCircularState(): Route.CircularState Returns the route's CircularState in previous stops.
Returns Route.CircularState.NONE if there's no previous route.
VehicleExtraData.getPreviousRouteType(): RouteType Returns the route's RouteType in previous stops.
Returns RouteType.NORMAL if there's no previous stop.
VehicleExtraData.getPreviousRouteDestination(): long Returns the route's destination of the last stop.
Returns an empty string f there's no previous stop / station area in previous stop.
VehicleExtraData.getPreviousPlatformId(): long Returns the platform id of the last stop.
Returns 0 if there's no previous stop.
VehicleExtraData.getPreviousStationId(): long Returns the station id of the last stop.
Returns 0 if there's no previous stop / station area in previous stop.
VehicleExtraData.getPreviousStationName(): long Returns the station name of the last stop.
Returns an empty string if there's no previous stop / station area in previous stop.

Equivalent function exists for:

  • Current Stop (When docked) / Previous Stop (When moving)
    • Function prefix: getThis (e.g. VehicleExtraData.getThisRouteId())
  • Next Stop
    • Function prefix: getNext (e.g. VehicleExtraData.getNextRouteId())

Lift#

References

A lift.

Functions And Objects Description
Lift.getHeight(): double Returns the configured height of the lift, in meters.
Lift.getWidth(): double Returns the configured width of the lift, in meters.
Lift.getDepth(): double Returns the configured depth of the lift, in meters.
Lift.getOffsetX(): double Returns the configured offset X of the lift, in meters.
Lift.getOffsetY(): double Returns the configured offset Y of the lift, in meters.
Lift.getOffsetZ(): double Returns the configured offset Z of the lift, in meters.
Lift.getIsDoubleSided(): boolean Whether the lift is configured to have doors on both sides.
Lift.getStyles(): String Returns the style id (Texture) of the lift.
Lift.getAngle(): Angle Returns the Angle rotation of the lift.
Lift.getDoorValue(): float Returns the door open value of the lift, from 0 (Closed) to 1 (Opened).

(More to be documented)

RouteType#

References

Represents the type of route.

Functions And Objects Description
static RouteType.NORMAL: RouteType Normal Heavy Rail route.
static RouteType.LIGHT_RAIL: RouteType A light rail route.
static RouteType.HIGH_SPEED: RouteType A high speed rail route.

PathData#

References

Represents 1 section (i.e. 1 rail) of a generated path.

Functions And Objects Description
PathData.getStartDistance(): double Returns the starting distance of the path. You can compare that with vehicle's railProgress.
PathData.getEndDistance(): double Returns the ending distance of the path. You can compare that with vehicle's railProgress.
PathData.getRail(): Rail Returns the Rail this path is for.
PathData.getOrderedPosition1(): Position Returns a Position representing the starting position in the world.
PathData.getOrderedPosition2(): Position Returns a Position representing the ending position in the world.
PathData.isSameRail(other: PathData): boolean Returns if a PathData is equivalent. (In terms of starting & ending position)
PathData.isOppositeRail(other: PathData): boolean Returns true if another PathData is a reversed version of the current path data. (e.g. For vehicle reversal/turnback, there may be 1 path representing the forward direction, and 1 path going in reverse, but they share the same piece of rail.)
PathData.getSpeedLimitKilometersPerHour(): long Returns the speed limit of this rail in km/h.
PathData.getRailLength(): double Returns the length of the path in meters.
PathData.isDescending(): boolean Returns true if the ending Y position is lower than the starting Y position.
PathData.getDwellTime(): long Returns the dwell time for this path in millisecond.
Values higher than 0 indcates the vehicle should stop and open the door.

Rail#

References

Represents a single rail section. (Node to Node)

Functions And Objects Description
Rail.getTransportMode(): TransportMode Returns the type of TransportMode this rail is for.
Rail.getStyles(): List<String> Returns a list of rail model ids (a.k.a. styles) applied to this rail.
Rail.canAccelerate(): boolean Returns whether the train can accelerate to the rail's speed limit, or should it hold the current speed.
False if it's a platform or a turnback rail.

ArrivalResponse#

References

Represents a single estimated time of arrival (ETA) entry. (Same as one used for PIDS reference time)

Functions And Objects Description
ArrivalResponse.getDestination(): String Returns the destination name of the arrival entry.
(Usually the destination's station, or a custom destination string)
ArrivalResponse.getArrival(): long Returns the epoch time (in Millisecond) the vehicle will arrive at.
Use new Date(value: number)to obtain a JS Date object of the arrival time.
ArrivalResponse.getDeparture(): long Returns the epoch time (in Millisecond) the vehicle will depart at.
Use new Date(value: number)to obtain a JS Date object of the departure time.
ArrivalResponse.getDeviation(): long Returns the deviation from the scheduled timetable.
Positive value indicate the train is late.
Negative value indicates the train is early.
ArrivalResponse.getRealtime(): boolean Returns whether the arrival entry is scheduled (i.e. Vehicle not departed), or a real-time estimation (i.e. Vehicle running)
ArrivalResponse.getDepartureIndex(): long Returns the departure index of the vehicle.
The departure index is incremented for every scheduled departure of each individual sidings.
It is wrapped back to 0 at 00:00 UTC (For real-time scheduling).
A departure index of -1 indicates the vehicle has either not yet departed, or it is a manually departed train.
ArrivalResponse.getIsTerminating(): boolean Returns whether the arrival entry will terminate its service at the current platform.
ArrivalResponse.getRouteId(): long Returns the id of the route that the vehicle is running on when arrived.
ArrivalResponse.getRouteName(): String Returns the name of the route that the vehicle is running on when arrived.
ArrivalResponse.getRouteNumber(): String Returns the route number string (Previously called LRT Route Number), empty string if route number is not set.
ArrivalResponse.getRouteColor(): int Returns the color of the route that the vehicle is running on when arrived.
ArrivalResponse.getCircularState(): Route.CircularState Returns the circular state of the route that the vehicle is running on.
ArrivalResponse.getPlatformId(): long Returns the id of the platform that the vehicle will approach at.
ArrivalResponse.getPlatformName(): String Returns the name of the platform that the vehicle will approach at.
ArrivalResponse.getCarCount(): int Returns the number of cars the vehicle has.
ArrivalResponse.iterateCarDetails(consumer: Consumer<CarDetails>): void Allow passing a callback to loop through the CarDetails

CarDetails#

Functions And Objects Description
CarDetails.getVehicleId(): String Returns the id of the vehicle car (As defined in Resource Packs)
CarDetails.getOccupancy(): double Dummy value, always returns 0.
Removed in MTR 4.1, do not use.

Angle#

References

A class containing the 16 compass direction, at 22.5 degree increment each.

Functions And Objects Description
static Angle.E East (0)
static Angle.SEE South-east-east (22.5)
static Angle.SE South-east (45)
static Angle.SSE South-east (67.5)
static Angle.S South (90)
static Angle.SSW South-south-west (112.5)
static Angle.SW South-west (135)
static Angle.SW South-west-west (157.5)
static Angle.W West (180)
static Angle.NWW North-west-west (202.5)
static Angle.NW North-west (225)
static Angle.NNW North-north-west (247.5)
static Angle.N North (270)
static Angle.NNE North-north-east (292.5)
static Angle.NE North-east (315)
static Angle.NEE North-east-east (337.5)
Angle.angleDegrees The bearing in degrees, normalised to the half-open range -180 to 180.
Angle.angleRadians angleDegrees in radian.

Vector#

References

A three-dimensional vector, that is, the coordinates (x, y, z).

One may convert this to a Vector3f by passing this to the Vector3f constructor.

Functions And Objects Description
Vector.x(): double Return the x-axis component of the vector.
Vector.y(): double Return the y-axis component of the vector.
Vector.z(): double Return the z-axis component of the vector.
Vector.multiply(x: double, y: double, z: double): Vector Multiply the vector, and return a new multiplied Vector.
Vector.multiply(vec: Vector): Vector Multiply the vector, and return a new multiplied Vector.
Vector.rotateX(angle: double): Vector Rotate the vector in the x-axis by angle. Returns a new rotated Vector.
Vector.rotateY(angle: double): Vector Rotate the vector in the y-axis by angle. Returns a new rotated Vector.
Vector.rotateZ(angle: double): Vector Rotate the vector in the z-axis by angle. Returns a new rotated Vector.
Vector.distanceTo(vec: Vector): double Returns the distance in meter in comparison to vec.
Vector.normalize(): Vector Normalize the vector. Returns a new normalized Vector.
static Vector.getAverage(vec1: Vector, vec2: Vector): Vector Returns a new Vector representing the average position between vec1 and vec2.

Position#

References

Represents a block position (x, y, z).

Functions And Objects Description
new Position(x: long, y: long, z: long): Position Constructor, create a Position from the specified x y z coordinates.
new Position(railPosition: Vector): Position Constructor, converting a Vector to a Position by rounding down.
Position.getX(): long Return the x position.
Position.getY(): long Return the y position.
Position.getZ(): long Return the z position.
Position.offset(offsetX: long, offsetY: long, offsetZ: long): Position Returns a copy of the position, with the specified offset being added.
Position.offset(pos: Position): Position Returns a copy of the position, with the xyz of the pos being added.
Position.manhattanDistance(pos: Position): long Returns the manhattan distance of the current position and pos.
static Position.getMin(pos1: Position?, pos2: Position?): Position Returns a new Position, with the minimum value for each individual axis (x y z), given 2 position value.
If pos1 is null, it will return pos2.
If pos2 is null, it will return pos1.
static Position.getMax(pos1: Position?, pos2: Position?): Position Returns a new Position, with the maximum value for each individual axis (x y z), given 2 position value.
If pos1 is null, it will return pos2.
If pos2 is null, it will return pos1.