The overall plan with the lines mod is to have a timetable scheduling system which is integrated with the other advtrains functions, especially the stop rails. This is the concept for it.

This is currently a draft, and subject to discussion before I will start implementing it. Please bring in your ideas, suggestions or critics. Just add them under the relevant headline and sign them with your name (use the “signature” button in the editor toolbar)

• All times used in the timetable are Railway times
• Timetables should support trains stopping at a station regularily (with arrival,departure and minimum stop time), trains passing through a location without stopping and trains stopping at a location only when the departure time is not due (e.g. for a freight train to let another scheduled train pass)
• Locations for the timetable are always Station/Stop rails (even if it's just a pass-through point)
• The system should be able to measure the travel times between stations, and the user should be able to create and update the timetable for a train semi-automatically from the travel times
• For every line in the timetable, it should be possible to deposit an xATC program (when xatc is ready)
• A system for guaranteed connections should be thought of (possibly aided by xATC)
• (later) Splitting and joining trains should be supported somehow
• The timetable system should export all data transparently to LuaATC and to something queriable from a plain Luacontroller, so that various kinds of departure displays can be built at stations

A timetable is a structure consisting of multiple “timetable items”. Every timetable item belongs to a Location and an optional Track code, and identifies one stop rail that the train should stop at or pass.

The timetable item holds:

• The station code of the station to which the item belongs
• (optional) a Track code, if defined a stop rail matches only when this is equal to the Track property
• (optional) the scheduled arrival time (not needed for pass-through places; maybe it is sufficient to compute this via the travel time)
• the scheduled departure time
• a “Stop Mode”, which is one of “regular stop”, “pass-through without stopping” or “wait for departure time or pass through” *
• (for regular stop) the minimum stop time. Train waits at least this time before continuing, even if it is late (for this, a global default could be defined)
• the travel time from the previous timetable item (that is, the time that the train needs to physically travel the distance between the two locations)
• some flags (such as “reverse here”)

* The stop modes should get better names — orwell 2021/04/19 22:11

All arrival and departure times in the timetable are relative to the initial departure time of any given train. That means, the timetable only defines after how many minutes/seconds after its initial departure at the first location it should be where.

Every timetable has an unique name and is saved globally.

When a timetable is assigned to a train, the train forms a Service of the line the timetable belongs to. The train then gets an instance of the timetable.

In the timetable instance, the relative times are replaced by the actual absolute railway times by adding them to the planned initial departure of the train. The lines in the timetable instance gain additional “computed properties”:

• The expected arrival time - calculated by adding the travel time to the expected departure time of the previous line
• The expected departure time - the scheduled departure time or the “ready time”, whichever is later

The “ready time” is determined from the expected arrival time. For a normal stop, this is the arrival + stop time, for “wait for departure” just the arrival time. When guaranteed connections are involved, they might affect the ready time too. For pass-through items, for which the departure time is only an orientation and the train never stops, there is no “ready time”.

At arrival and departure at every place, the expected arrival/departure times for this place become known and are saved, they are then called “actual departure/arrival time”. Every arrival and departure cause the subsequent expected arr/dep times to be recalculated.

This expected/real times system forms the base for departure displays both in trains and in stations.

This could use a better name — orwell 2021/04/19 22:11

At the first station in the timetable, trains “enter” the timetable and get timetable instances. For this, the timetable defines a service interval by means of two times:

• Interval: “every xx;xx”
• Offset: “plus xx;xx”

For example, interval 05;00 offset 02;00 would result in a train every 5 minutes at minutes 02,07,12,17…

We call such a possible initial departure time a slot.

When a train arrives at the timetable entry point, it picks the next slot and constructs its timetable instance from it. If the first timetable item has a minimum stop time, this is taken into account too.

It may be considered whether to add a “late departure threshold”, say the train arrives a few seconds after a slot has passed, instead of waiting for the next slot, it departs at the previous slot and carries an initial delay then.

The system must ensure that each slot for each timetable has maximum 1 train using it. Slots may however be missed, in this case a departure display could display “train cancelled”. So, advtrains must somehow keep a mapping which train is assigned to which slot.

A train can enter a timetable in one of two ways: either as follow-up to another service (another timetable), or initiated.

Follow-up service:

• Train arrives at the terminus of a line
• The timetable says that the train should continue as <new timetable id>
• train switches to new timetable and finds next departure slot

For such a follow-up service, the end point of the old timetable should obviously be the same as the start point of the new one.

Initiated:

• Either the driver manually or luaatc code activates the timetable to the train
• The train behaves as if it had no timetable until it sees the stop rail associated with the first timetable item
• The train stops at the first timetable item and finds the next slot.

… to be continued …