Skip to content

How It Works

pvvlvz edited this page Nov 16, 2026 · 3 revisions

This section is for the curious and for contributors.

One train, one source of truth

A train is not a set of minecarts pushing each other. The locomotive owns a Train object: the ordered list of its coaches, a track path (the rail segments the train occupies, from the rear to the front), its speed, throttle, settings and schedule. The whole train is saved inside the locomotive's entity data. Coaches only store the id of their locomotive.

Every server tick the locomotive moves the front of the path forward and places every car on the path at a fixed distance from the front. Each car rests on two bogie points half a wheelbase either side of its centre, sits at their midpoint and faces along the line between them. Spacing is exact by construction, on curves and slopes too, and cars can't drift because their positions are recomputed from the path every tick.

flowchart TD
    T["Locomotive tick"] --> C["Keep chunk tickets<br>while active"]
    C --> L{"Every coach loaded?"}
    L -- no --> W["Freeze the whole train,<br>keep holding its track"]
    L -- yes --> M{"Mode"}
    M -- automatic --> A["Steer through junctions, then plan around<br>stations, signals, trains and bookings"]
    M -- manual --> D["Read the driver's W, S and Space keys"]
    A --> V["Move along the track path"]
    D --> V
    V --> H["Claim track: under the train,<br>stopping distance, booked stretch"]
    H --> P["Place every car on the path"]
Loading

Track geometry

Each rail block is a straight segment between two exit points on its block edges: the middle of an edge for flat rails, one block higher at the top of a slope, and diagonal across the block for curves, like vanilla. Two rails connect when an exit point of one is exactly an exit point of the other. That single rule handles flat track, slopes up and down, peaks and curves.

Seats

Vanilla keeps passengers in a list that it reorders, so "seat = position in the list" would swap people around. Tiny Trains records which entity sits in which seat in synced entity data, and positions riders from that on both sides.

Safety

A per-dimension TrackClaims table records which train holds which rail block, and in which direction. A claim is only valid for the tick it was made in, so a removed or unloaded train can never leave a stale claim behind. Automatic trains additionally claim the single-track stretch they've booked, up to the next junction. A train treats a rail as blocked if another train holds it as occupied, or holds it in the opposite direction.

Chunk loading

A custom ticket type, tinytrains:train, with the same flags as vanilla's portal ticket (persistent, loading, simulation, keeps the dimension active). The front chunk gets radius 3, other car chunks radius 2. Tickets are refreshed every 5 s and removed as soon as the train parks, or right away if its chunk loading is switched off.

NeoForge edition: NeoForge forced chunks from a ticket controller, tinytrains:train, owned by the locomotive's UUID and ticking. The front chunk and its 8 neighbours are forced, plus every chunk with a car in it. They are released as soon as the train parks, right away if its chunk loading is switched off, and when the locomotive is destroyed or leaves the dimension. After a restart each train takes its own chunks back when it next ticks, and any no train claims within 15 s are released.

Detector rails

A small Mixin changes vanilla's detector rail check ("is a minecart on me?") to also count a train standing on the rail. Every tick, trains and parked coaches report the detector rails under them, and switch on any that are still off. From then on vanilla does the rest exactly as for minecarts: it re-checks every second and switches the rail off once nothing is on it. Those re-checks are saved with the world, so a rail is never left stuck on.

Persistence

Data Where it lives
Train (coaches, path, speed, settings, schedule) In the locomotive entity
A coach's locomotive In the coach entity
Station name and waiting time In the station block entity
List of station names per dimension Saved world data (tinytrains:stations; on NeoForge data/tinytrains_stations.dat)
Where every train was last seen, and pending operator stops Saved world data (tinytrains:trains; on NeoForge data/tinytrains_trains.dat)
Next train due at a station Not saved: trains report it about once a second
Chunk tickets of running trains Vanilla's ticket storage (NeoForge: its forced chunk storage)

← Reporting Bugs · Home · Tests →

Clone this wiki locally