Skip to content
Connected RailsConnected Rails

Multiplayer

The same binary is the dedicated server. --dedicated <port> (or <address>:<port>) builds the world, opens a UDP socket and runs the simulation without a window, a renderer or a sound card — though, being the same binary, it still needs Steam Audio’s library (libphonon.so / phonon.dll) beside it to start. Single player never opens a socket.

A server is started like a run: the same --line, --scenario, --day/--service and --loco flags say what it runs. --date moves the date of an operating day’s service, and --variant <n> sets the livery of the player’s vehicle in a free run or a service, since a server has no menu to pick one in. --time and --weather do nothing on a server: they belong to the screenshot runs of a client, and a client joining a server ignores them along with every other run flag of its own.

TRAINSIM_SERVER_PASSWORD=geheim train-sim --dedicated 27015 --scenario example:probefahrt
train-sim --dedicated 0.0.0.0:27015 --day example:beispieltag --service 2 --server-name "Abend"
  • The password comes from TRAINSIM_SERVER_PASSWORD. --password works as well, but every user of the machine can read it in the process list. Without one, anybody who reaches the port can join, and the log says so. Choose a long one — see How joining works for what an eavesdropper can do with a recorded handshake.
  • --server-name is what the lobby is headed with. Without it, the line’s name.
  • The consist is the server’s. Every client builds its world out of the run the server describes, not out of its own menu: line, scenario, the service and its date and weather, the vehicle of a free run and its livery. Liveries and loads of a scenario’s own trains stand in the scenario (variant: and load: on each entry of a consist’s vehicles, see Scenarios). A client that still builds a different world, because a mod is missing or has another version, is turned away when it joins, not left to drive a train the others cannot see. The fingerprint compares the line, every train and every vehicle in it by name, tare and length, livery and load.

Multiplayer on the title screen opens the server page: the address (host, host:port or an IP; the port defaults to 27015), the name the others see you under, and the password if the server has one. Address and name are remembered in the settings file ([multiplayer]) once the server has let you in, but the password never is. Typing goes into the highlighted field (a click puts the caret there, Enter or Tab move on). The line under the title says how far the connection has got and, if it fails, why: an address that cannot be found, a wrong password, content that differs from the server’s, every train taken, or a server that has gone. A refusal over mods opens the mod manager instead, with the list of what differs.

Once the server lets you in, the lobby lists its trains that nobody drives yet: number, vehicle, length, and whether the AI is driving it or it is standing. The list updates by itself. Picking one is the start, because the rest of the run is the server’s. If the run needs content this machine does not have, every row says so and none can be started. Esc leaves the lobby and the server.

--connect <host:port> does the same from the command line. On its own it opens the server page and connects at once, with --name and --password (or TRAINSIM_SERVER_PASSWORD) filling in the form, and --train <n> takes the server’s train n (counted from 1 — the number the lobby shows for a train that carries no train number of its own) once the lobby offers it; a train it does not offer is reported in the log and the lobby is left to the player. A form filled from the command line is not written to the settings. Next to a run flag (--line, --scenario, --day, …) it builds that run first and joins from the cab, which is the scripted form: start it with the same run flags as the server, or the server turns it away.

netcode’s connect key only says that both ends speak this protocol. It is compiled into every copy of the program and keeps nobody out. On top of it:

  1. The password. The server sends every new connection a random 16-byte challenge and its salt. The client stretches the password into a key with Argon2id under that salt and answers with a BLAKE3 hash of the challenge keyed with it. The password never travels, a recorded answer is worthless for the next connection, and a server that says it has no password is answered with the empty one. Until the answer has been checked, the server sends that connection nothing of the world and takes nothing from it: no levers, no takeover, no weather. A wrong answer is refused, and the client closes the link.

    What this does not do: netcode’s key is the same in every copy, so anyone who can watch the traffic can read a challenge and its answer, and try passwords against them offline. Argon2id makes every guess as expensive as a login, which puts a long password out of reach and a short one not. Nor does the client know it is talking to the right server.

  2. The same mods. The world is built from the mods, so a client has to run exactly the mods the server runs — the same set, the same versions, the same data. The answer to the challenge carries a stamp of every enabled mod: id, version, filebase uuid and a digest of the mod’s *.ron and *.lua files (models, textures and sounds are not compared — they cannot make two simulations drift apart, and they are gigabytes; switching a mod off and on does not count as an edit). The client works the stamps out in the background when it connects and answers once they are ready. The server turns it away, before the lobby and before any world is built, when a mod is missing or switched off, runs in another version or with other files, is a different mod under the same id, or is one the server does not run at all — every script shares one Lua state, and a reference to another mod that the server cannot resolve would resolve on the client. The main menu then opens on Mods with the list. The server logs its own stamps at startup, which is the list to hand to players.

  3. The lobby. An admitted client gets the run and the free trains, and gets them again whenever that changes, until it joins.

  4. The world. The client builds the run it was sent and joins with the fingerprint of what it built. A different fingerprint is a refusal now, not a line in the log. The train it asks for is granted while it is still free, otherwise the first one that is. With none free the join is refused. A train a player has taken over is no longer driven by the AI, and goes back to it when that player leaves, is refused, or walks into another train. A client joining after a console changed the weather is sent that weather with its welcome; a console may change it once every five seconds per player.

An operating day needs nothing beyond that: which of its services are out is a pure function of the clock, and they claim their units in departure order, so server and client keep dispatching the same trains at the same indices for as long as the run lasts, without a message about any of it. A client that joins hours into the day takes the server’s clock over and catches up. A train it was granted that its own world has not dispatched yet is taken over as soon as it has. The AI that drives the trains stays the server’s.

Leaving a run closes the link, and the next run connects afresh.

The server does not check the address a client names for it. netcode would, and behind a port forward or bound to every interface the server is reached under an address it does not know (its public one, the LAN’s), so it would turn every such client away. The check keeps nobody out who means harm, since anybody can make a connect token with the key every copy of the program carries. Who may come in is the password’s question.

What travels is the driver’s levers and, ten times a second, the position of each train on the track — (edge, s, dir, v, a), about 17 bytes, not a transform. Every peer runs the same deterministic simulation on those levers; the positions only correct the drift, and they do it through the speed rather than by setting anything, so nothing ever jumps. Trains further than 3 km away are corrected once a second, past 20 km not at all. The HUD line Server shows the connection, the train, the round trip time and the correction still pending — in normal running it stays under a handful of centimetres. See PLAN.md ch. 20 for the why.

A scenario’s script runs on the server only. What it decides — a train built, a task set, a shunt job handed out, the run ended — goes to every client as its commands, and a client that joins late is first sent all of them so far (Scenario scripting). A train is addressed by its index on every peer, so once the world is built every source of new trains — the operating day, the script, uncoupling — fills a sequence of indices of its own: which of them happens first on which machine no longer decides where a train ends up.

Still open:

  • Nothing is encrypted beyond netcode’s shared key. The password is protected as described above, the levers and positions are not, which for a train simulation is fine.
  • A refused or silent connection is shut out but not kicked: lightyear offers no server-side disconnect, and its connection filter sees only the id a client chose for itself, not its address. Such a connection holds its slot until it closes the link or times out, and nothing limits how often one address may try.
  • Looking up a host name blocks the menu for as long as the resolver takes.
  • A gamepad alone cannot fill in the server page: there is no on-screen keyboard.