.. _timetable: ************** Timetable Mode ************** Introduction ============ The timetable concept is not a replacement for the activity definition, but is an alternative way of defining both player and computer-controlled (AI and Static) trains. In an activity, the player train is defined explicitly, and all AI trains are defined in a traffic definition. Static trains are defined separately. In a timetable all trains are defined in a similar way. On starting a timetable run, the required player train is selected from the list of available trains. In the timetable definition itself, no distinction is made between running trains -- any of the running trains can be selected as player train, and if not selected as such they will be run as AI trains. Static trains are also defined in the same way but cannot be selected as the player train. As a result, the number of different 'activities' that can be played using the same timetable file is equal to the number of trains which are defined in the timetable, less static trains. **Important aspects where the use of specific OR or MSTS items for timetables differs significantly from its use in an activity are shown in bold**. The development of the timetable concept is still very much a work in progress. As work continues, all items are still subject to change. General ======= Data definition --------------- The timetable data is defined in a Spreadsheet, and saved as a \*.csv file (character separated file) in Unicode format. As the separation character, either ',' (comma), ';' (semi-colon) or the tab character must be used. Do not select space as the separation character. As ';', ',', or tab are possible separation characters, these symbols must not be used anywhere within the actual data. Enclosure of text by quotes (either single or double) has no effect. Also, the character '#' should not be used in train names, since it is the prefix for reserved words in the Timetable. File structure -------------- The saved ``*.csv`` files must be renamed with the extension ``*.timetable-or``. The timetable files must be placed in a subdirectory named ``OpenRails`` created in the route's ``Activities`` directory. Timetable groups ---------------- Multiple timetables can be loaded simultaneously using timetable group files. A group file is a plain text file that has the extension ``.*.timetablelist-or``, that is also located in the ``OpenRails`` subdirectory of the route's ``Activities`` directory, and that contains the filenames of one or more timetable files listed on each line. The first line may also start with a ``#`` symbol, in which case the text that follows will be used as the timetable group's display name in the Open Rails menu. Here is an example of a timetable group file:: #All Northeast Corridor Services - Fri Aug 2018 Amtrak - Fri Aug 2018.timetable-or MARC Camden Line - Fri Aug 2018.timetable-or MARC Penn Line - Fri Aug 2018.timetable-or SEPTA Wilmington-Newark - Fri Aug 2018.timetable-or Pool files ---------- :ref:`Pools ` can be used to store out-of-service trains on a first-come, first-serve basis, without the need to manually program paths into and out of storage tracks. Pool files are located in the same ``OpenRails`` directory as other timetable files. They have the extension ``.pool-or`` or ``.turntable-or``. Weather files ------------- :ref:`Weather files `, a feature exclusive to timetable mode, orchestrate changes in the cloud cover, precipitation, and visibility factors over the course of the timetable day. They are located in a special ``WeatherFiles`` subdirectory of the route's folder and they have the ``*.weather-or`` file extension. The player activates a weather file by selecting it from the timetable mode section of the main menu; this overrides the static weather condition. File and train selection ------------------------ When starting a timetable run, the mode *Timetable* is selected in the menu. The desired timetable file or timetable group file must then be selected in the *Timetable set* display. After selecting the required timetable, a list of all trains contained in that timetable is displayed and the required train can be selected. Season and weather (static or file-defined) can also be selected; these are not preset within the timetable definition. Timetable Definition ==================== General ------- A timetable consists of a list of trains, and, per train, the required timing of these trains. The timing can be limited to just the start time, or it can include intermediate times as well. At present, intermediate timings are limited to 'platform' locations as created using the MSTS Route Editor. Each column in the spreadsheet contains data for a train and each row represents a location. A cell at the intersection of a train and location contains the timing data for that particular train at that location. Special rows and columns can be defined for general information or control commands. The first row for each column contains the train definition. The first column for each row contains the location definition. The cell at the intersection of the first row and first column **must be empty**. This paragraph only lists the main outline, a fuller detailed description will follow in the next paragraphs. Column definitions ------------------ A column is defined by the contents of the first row. Default, the first row defines the train name. Special columns can be defined using the following syntax : - ``#comment``: column contains comment only and is ignored when reading the timetable. - : column is extension of preceding column. Row definitions --------------- A row is defined by the contents of the first column. Default, the first column defines the stop location. Special columns can be defined using the following syntax : - ``#comment``: row contains comment only and is ignored when reading the timetable - : row is extension of row above - ``#path``: defines train path - ``#consist``: defines train consist - ``#start``: defines time when train is started - ``#note``: defines general notes and starting control commands for this train - ``#dispose``: defines how train is handled after it has terminated - ``#speed``, ``#speedmph``, or ``#speedkph``: defines train speed behavior in meters per second, miles per hour, or kilometers per hour, respectively; only one kind of speed row can be used in a single timetable file - ``#restartdelay``: defines randomized delays for a train - ``#briefing``: row contains briefing text for each train and is ignored when reading the timetable Timing details -------------- Each cell which is at an intersection of a train column and a location row, can contain timing details for that train at that location. :ref:`Timing commands ` can be set at locations where the train stops, but can also be set for locations where no timing is inserted as the train passes through that location without stopping. Timetable Data Details ====================== Timetable Description --------------------- Although ``#comment`` rows and columns are generally ignored, the contents of the cell at the intersection of the first ``#comment`` row and first ``#comment`` column is used as the timetable description. This appears as the timetable's name in the Open Rails menu and is used to reference trains from other timetables. Train Details ------------- The train name as defined in the first row must be unique for each train in a timetable file. This name is also used when referencing this train in a train command; see details below. The sequence of trains is not important. Location Details ---------------- At present, the possible locations are restricted to 'platforms' as defined in the MSTS Route Editor. Each location must be set to the 'Station Name' as defined in the platform definitions. The name used in the timetable must exactly match the name as used in the route definition (\*.tdb file), otherwise the location cannot be found and therefore cannot be processed. Also, each location name must be unique, as otherwise its position in the train path could be ambiguous. The sequence of the locations is not important, as the order in which the stations are passed by a train is defined in that train's path. For the same reason, a train's path can be set to just run in between some of the locations, or be set to bypass certain stations. Timing Details -------------- Each cell at an intersection of train and location can contain the timing details of that train at that location. Times are defined as HH:mm, and the 24-hour clock must be used. If a single time is inserted it is taken as the departure time (except at the final location). If both arrival and departure time are to be defined, these must be separated by '-'. Additional :ref:`timing commands ` can be included. Such commands can also be set for locations where the train does not stop and therefore has no timing details, but the train must pass through that location for the commands to be effective. Although a location itself can be defined more than once in a timetable, it is not possible to define timing details for trains for a location more than once. If a train follows a route which takes it through the same location more than once, the train must be 'split' into separate train entries. Special Columns --------------- - ``#comment`` column. A column with the #comment definition in the first row is a comment column and is ignored when reading the timetable, except for the cell at the intersection of the first comment column and the first comment row. - column. A column with a blank (empty) cell in the first row is taken as a continuation of the preceding column. It can be used to insert control commands which apply to the details in the preceding column. This can be useful when timings are derived automatically through formulas in the spreadsheet as inserting commands in the timing cell itself would exclude the use of such formulas. Special Rows ------------ - ``#comment`` row. A row with the #comment definition in the first column is a comment row and is ignored when reading the timetable, except for the cell at the intersection of the first comment column and the first comment row. - row. A row with a blank (empty) cell in the first column is taken as a continuation of the preceding row. - ``#path`` row. The #path row defines the path of that train. The path must be a \*.pat file as defined by the MSTS Activity Editor or by Trackviewer, and must be located in the route's Path directory. This field is compulsory. The timetable uses the same paths as those defined for activities. **However, waiting points must not be defined in paths for use in timetables as the processing of waiting points is not supported in the timetable concept. Waiting points within a timetable must be defined using the specific control commands.** The ``#path`` statement can take a qualifier: ``/binary``. Large timetables can require many paths, and loading those paths can take considerable time (several minutes). To reduce this loading time, the paths can be stored in a processed, binary format. This format is the same as used in the 'save' command. Note that the binary path information cannot be directly accessed by the user, either for reading or for writing. When ``/binary`` is set, the program will check if a binary path exists. If so, it will read that path. If not, it will read the 'normal' path, and will then store this as binary for future use. Binary paths are stored in a subdirectory named ``OpenRails`` which must be created in the Paths directory of the route. Note: If a path or the route is edited, then the binary data will be out of date. If so, it is deleted and re-created automatically when the user starts the route. - ``#consist`` row The ``#consist`` row defines the consist used for that train. This field is compulsory. However, if the train is run as an AI train and it is 'formed' out of another train (see below), the consist information is ignored and the train uses the consist of the train out of which it was formed. For the player train, the consist is always used even if the train is formed out of another train. The consist definition must be a \*.con file as defined by the MSTS Activity Editor or by the TSRE5 consist editor, and must be stored in the defined consist directory. Also a more complex syntax of the consist definition is possible, as described below. This allows a consist definition to be not just a single string directly referring to a file, but a combination of strings, with the possibility to use (part of) the consist in reverse. The general syntax is:: consist [$reverse] [+ consists [$reverse] [+ ...] ] Example: a loco-hauled train, using the same set of coaches, running in both directions. Two consists are defined: ``c_loco`` and ``c_wagons``. The consist definitions which can now be used are: ``c_loco + c_wagons``, and for reverse: ``c_loco $reverse + c_wagons $reverse`` Please note that ``$reverse`` always applies only to the sub-consist with which it is defined, not for the complete combined consist. If this train sometimes has some additional wagons, e.g. during rush hours, the consists can be defined as follows (with ``c_add`` the definition of the additional wagons): ``c_loco + c_wagons + c_add``, and for reverse: ``c_loco $reverse + c_add $reverse + c_wagons $reverse`` Clearly, this can save on the definition of the total required consists, and in particular saves the tedious task of having to define 'reverse' consists. When using multiple units, this is even more useful. Suppose there are two sets of multiple units, running either as single trains or combined. Normally, six different consists would be required to cover all trains, but now only two will suffice : ``set_a`` and ``set_b``. The various combinations are: ``set_a``, reverse ``set_a $reverse``. ``set_b``, reverse ``set_b $reverse``. ``set_a + set_b``, reverse ``set_b $reverse + set_a $reverse``. Consist strings which contain '+' or '$' can be used in timetables but must be enclosed by < >. For instance : ``+<$loco+wagon>$reverse`` - ``#start`` row The ``#start`` row defines the time at which the train is started. It must be defined as HH:mm, and the 24 hour clock must be used. This field is compulsory. Use of start time for AI trains : - When a train is formed out of another train and this other train is included to run in the timetable, the time defined in #start is only used to define when the train becomes active. Use of start time for player train : - The time as defined in ``#start`` is normally used as the start time of the timetable 'activity'. If a train is formed out of another train and this train is included in the timetable, then if this train is delayed and has not arrived before the defined start time, the starting of this train is also delayed until the train out of which it is formed has arrived. This applies to both AI and player train. This means that the start of the player activity can be delayed. The ``#start`` field also accepts a number of :ref:`start commands `. For details on starting and running of trains around midnight see the paragraph :ref:`below `. - ``#note`` row The ``#note`` row can be used to define :ref:`note commands ` which are not location related but apply to the full run of the train. It can also be used to set commands for trains which do not stop at or pass through any defined location. This row is optional. - ``#dispose`` row The ``#dispose`` row defines what happens to an AI train when it has reached the end of its run, i.e. it has reached the end of the defined path. The information in the ``#dispose`` row can detail if the train is to be formed into another train, and, if so, how and where. For details see the :ref:`dispose commands ` as described further down. This row is optional and if included, the use per train is also optional. If the row is not included or the field is not set for a particular train, the train is removed from the activity after it has terminated. The #dispose row presently does not affect the end of the run for the player train. - ``#speed`` row This optional field defines maximum speed for trains, which may restrict the train to lower speed as would otherwise be allowed. Note that any value defined here will never be applied if it exceeds the maximum speed as set through speedposts or signals, or as set in the consist file. If specified, only one ``#speed`` (m/s), ``#speedkph``, or ``#speedmph`` row can be present in a single timetable file. This row also accepts a number of :ref:`speed commands `. - ``#restartdelay`` row Delays are applied when restarting a train from a stop, e.g. at a station or a signal. Default random delays are set for each train. The default values may optionally be overruled using :ref:`delay commands ` in the ``#restartdelay`` field. The random delay is calculated as :math:`\mbox{fixed part} + Random(\mbox{variable part})`, where all values are in seconds. - ``#briefing`` row The ``#briefing`` row is optional and contains text which describes the train operation for the user. This text appears in the Open Rails main window along with description of the route and the loco. The user can also see it in-game in the Briefing tab of the Help Window (F1). A similar entry in the ``#comment`` column provides text which describes the entire timetable. The timetable-or file does not allow the fields to contain line-breaks but if HTML breaks "
" are inserted into the ``#briefing`` field, these will be converted to line-breaks. Control Commands ---------------- General ''''''' Control commands can be set to control train and signaling behaviour and actions. Command Syntax '''''''''''''' All commands have the same basic syntax. A command consists of: - Syntax name : defines the control command. - Syntax value : set the value related to the command. Not all commands take a value. - Syntax qualifiers : adds additional information to the command. Not all commands have qualifiers. Some qualifiers may be optional but others may be compulsory, or compulsory only in combination with other qualifiers. - Syntax qualifier values : a qualifier may require a value Command syntax:: $name = value /qualifier=value Multiple values may be set, separated by '+'. Note that any qualifiers always apply to all values. Train Reference ''''''''''''''' Many commands require a reference to another train. This reference is the other train's name as defined in the first row. If the target train is in a separate timetable of the same timetable group, the reference is in the form of ``train name:timetable description``, where the description is the text at the intersection of the first ``#comment`` row and ``#comment`` column in the other timetable file. Station Commands '''''''''''''''' Station commands apply to all stops for a given station row. They are inserted directly after the station name in the first column. .. _timetable-cmd-hold: ``$hold, $nohold and $forcehold`` If ``$hold`` is set, it defines that the exit signal for that location must be held at danger up to 2 minutes before train departure. An exit signal is allocated to a platform if this signal is beyond the end platform marker (in the direction of travel), but is still within the same track node - so there must not be any points etc. between the platform marker and the signal. **By default, the signal will not be held.** ``$forcehold`` will set the first signal beyond the platform as the 'hold' signal, even if this signal is not allocated to the platform as exit signal. This can be useful at locations with complex layout where signals are not directly at the platform ends, but not holding the signals could lead to delay to other trains. .. _timetable-cmd-forcewait: ``$forcewait`` Force the train to wait if the next signal is at danger even if this signal is not recognized as the exit signal for that platform. .. _timetable-cmd-nowaitsignal: ``$nowaitsignal`` Normally, if a train is stopped at a station and the next signal ahead is still at danger, the train will not depart. But, there are situations where this should be overruled. Some stations are 'free line' stations - that is, they are not controlled by signals (usually small halts, without any switches). The next signal probably is a 'normal' block signal and may be some distance from the station. In that situation, the train does not have to wait for that signal to clear in order to depart. Other situation are for freight trains, light engines and empty stock, which also usually do not wait for the signal to clear but draw up to the signal so as to take as little as time as possible to exit the station. ``$terminal`` The ``$terminal`` command changes the calculation of the stop position, and makes the train stop at the terminating end of the platform. Whether the platform is really a terminating platform, and at which end it terminates, is determined by a check of the train's path. If the platform is in the first section of a train's path, or there are no junctions in the path leading up to the section which holds the platform, it is assumed the train starts at a terminal platform and the end of the train is placed close to the start of the platform. If the platform is in the last section if the path or there are no junctions beyond the section which holds the platform, it is assumed the platform is at the end of the train's path and the train will run up to near the end of the platform in its direction of travel. If neither condition is met, it is assumed it is not a terminal platform after all, and the normal stop position is calculated. The ``$terminal`` option can be set for a station, or for individual trains. If set for a station it cannot be overruled by a train. However, because of the logic as described above, if set for a station which has both terminal platforms as well as through platforms, trains with paths continuing through those platforms will have the normal stop positions. ``$closeupsignal`` Sets a reduced clearance on approach to signal to maximize use of available platform length. ``$extendplatformtosignal`` Sometimes the platform marker is placed some distance from the actual end of the platform where the signal is located, e.g. in case of switches along the platform. Normally this would cause trains to stop far from the end of the platform and then block the switches to the rear. This parameter will place the ‘end of platform’ position not at the position of the platform marker but just ahead of the signal position. ``$restrictplatformtosignal`` Sometimes the platform marker is placed beyond the exit signal for that platform. If the signal is at danger, the train will stop at the signal and if this is a long train, this stop will not be seen as the station stop as the train has not reached the required platform stop position. This parameter will place the ‘end of platform’ position not at the position of the platform marker but just ahead of the signal position. ``$stoptime`` Syntax : ``$stoptime=n`` (n is time in seconds) Sets the required default stop time at this platform, overriding the stoptime definition set in the track database. ``$closeup`` The train will stop close to another train already in the platform. Can only be used if the ``$callon`` timing command is also set for that train. ``$keepclear`` Defines that the stop position must be such that the length of platform as indicated in the command must be kept clear ahead of or behind the train. This may be essential if another train is to be attached or if another train is to be taken into the same platform. Parameters : ``rear = `` (n in meter) The stop location must be such that he minimal distance behind the train is n meter. If the platform has an exit signal, the train will stop in front of the signal even if this means that less than n meter is clear, unless the ``/force`` parameter is set as well. In this situation, the path of the train must continue beyond the exit signal. Note that the train will never proceed beyond the end of its path. ``front = `` (n in meter) The stop location must be such that the minimal platform length available ahead of the train is not less than n meter. If the rear of the train would be outside the platform, the location is calculated such that the rear of the train is at the platform end even if this means that less than n meter is clear, except when the ``/force`` parameter is set as well. ``force`` Forces front or rear section to be kept clear even if train must pass exit signal (for ``rear`` parameter), or rear of train does not fit into platform (for ``front`` parameter). ``$endstop`` When the path of the train continues beyond the station position (e.g. when setting ``$keepclear /rear /force``), the stop is considered to be the end of the path even if the train has not reached the actual final position. .. _timetable-timing: Timing Commands ''''''''''''''' These commands can be set for each timing cell, i.e. at each intersection of train column and location row, or in the ``#note`` row. The commands will apply at and from the location onward (if applicable). For instance, a ``$wait`` command can be set for a station without a stop. The actual wait location can be that station itself, but it could also be a loop or junction somewhere beyond that station. ``$wait`` Syntax : ``$wait= /maxdelay=n /notstarted /atstart /owndelay=n`` Defines that a train is to wait for the referenced train to allow this train to proceed first. The referenced train can be routed in the same or the opposite direction as this train itself. A search is done for the first track section which is common to both trains, starting at the location where the ``$wait`` is defined, or at the start of the path if defined in the ``#note`` row. If the start location is already common for both trains, then first a search is done for the first section which is not common to both trains, and the wait is applied to the next first common section beyond that. If the wait is set, the section will not be cleared for this train until the referenced train has passed this section. This will force the train to wait. The referenced train must exist for the wait to be valid. However, if /notstarted is set, the wait will also be set even if the referenced train has not yet been started. This can be used where the wait position is very close to the start position of the referenced train, and there is a risk that the train may clear the section before the referenced train is started. Care should be taken when defining a $wait at a location where the train is to reverse. As the search is performed for the active subpath only, a $wait defined at a location where the train is to reverse will not be effective as the common section will be in the next subpath after the reversal. In such a situation, the train should be 'split' into two separate definitions, one up to the reversal location and another starting at that location. Command value : referenced train, this is compulsory. Command qualifiers : ``/maxdelay=n``: n is the maximum delay (in minutes) of the referenced train for which the wait is still valid. This delay is compensated for any delay of the train which is to wait, e.g. if maxdelay is 5 minutes, the referenced train has a delay of 8 minutes but this train itself has a delay of 4 minutes, the compensated delay is 4 minutes and so the wait is still valid. This parameter is optional, if not set a maxdelay of 0 minutes is set as default. ``/notstarted``: the wait will also be applied if the referenced train has not yet started. ``/atstart``: the wait is activated at the present position rather than the first non-common position. May be used where a train in opposite direction is to terminate in the same location as this train is started and there may not be any possible passing locations between this starting position and the present position of the other train. ``/owndelay=n`` (n is delay in minutes); the owndelay qualifier command makes the command valid only if the train in question is delayed by at least the total minutes as set for the owndelay qualifier. This can be used to hold a late-running train such that is does not cause additional delays to other trains, in particular on single track sections. ``/trigger=HH:MM`` Experimental option: Restricts this command to trigger only after the specified time. ``/endtrigger=HH:MM`` Experimental option: Restricts this command to trigger only before the specified time. ``$follow`` Syntax : ``$follow= /maxdelay=n /notstarted /owndelay=n`` This command is very similar to the $wait command, but in this case it is applied to each common section of both trains beyond a part of the route which was not common. The train is controlled such that at each section where the paths of the trains re-join after a section which was not common, the train will only proceed if the referenced train has passed that position. The command therefore works as a $wait which is repeated for each such section. The command can only be set for trains routed in the same direction. When a wait location is found and the train is due to be held, a special check is performed to ensure the rear of the train is not in the path of the referenced train or, if it is, the referenced train has already cleared that position. Otherwise, a deadlock would result, with the referenced train not being able to pass the train which is waiting for it. Command value: referenced train, this is compulsory. Command qualifiers: ``/maxdelay=n``: n is the maximum delay (in minutes) of the referenced train for which the wait is still valid. This delay is compensated by any delay of the train which is to wait, e.g. if maxdelay is 5 minutes, the referenced train has a delay of 8 minutes but this train itself has a delay of 4 minutes, the compensated delay is 4 minutes and thus the wait is still valid. This parameter is optional, if not set a maxdelay of 0 minutes is set as default. ``/notstarted``: the follow will also be applied if the referenced train has not yet started. ``/owndelay=n`` (n is delay in minutes): the owndelay qualifier command makes the command valid only if the train in question is delayed by at least the total minutes as set for the owndelay qualifier. This can be used to hold a late-running train such that is does not cause additional delays to other trains, in particular on single track sections. ``/trigger=HH:MM`` Experimental option: Restricts this command to trigger only after the specified time. ``/endtrigger=HH:MM`` Experimental option: Restricts this command to trigger only before the specified time. ``$connect`` Syntax : ``$connect= /maxdelay=n /hold=h`` Defines that a train is to wait at a station until another train has arrived, so as to let passengers make the connection between the trains. The train will be timetabled to allow this connection, and the ``$connect`` command is set to maintain this connection if the arriving train is running late. Note that the ``$connect`` command will not lock the signal. If the paths of this train and the arriving train conflict before the arriving train reaches the station, additional ``$wait`` or ``$hold`` commands must be set to avoid deadlock. Command value: reference to train which is to be waited for, this is compulsory. Command qualifiers : ``/maxdelay=n`` : n is the maximum delay (in minutes) of the arriving train for which this train is held. If the delay of the arriving train exceeds this value the train will not wait. The maximum delay is independent from this train's own delay. This qualifier and its value are compulsory. ``/hold=n`` : n is the time (in minutes) the train is still held after the other train has arrived, and relates to the time required by the passengers to make the connection. This qualifier and its value are compulsory. ``$waitany`` Syntax : ``$waitany= /both /opposite`` This command will set a wait for any train which is on the path section as defined. If the qualifier /both is set, the wait will be applied for any train regardless of its direction, otherwise the wait is set only for trains heading in the same direction as the definition of the path. The path defined in the waitany command must have a common section with the path of the train itself, otherwise no waiting position can be found. This command can be set to control trains to wait beyond the normal signal or deadlock rules. For instance, it can be used to perform a check for a train which is to leave a siding or yard, checking the line the train is to join for any trains approaching on that line, for a distance further back than signalling would normally clear, so as to ensure it does not get into the path of any train approaching on that line. With the /both qualifier set, it can be used at the terminating end of single track lines to ensure a train does not enter that section beyond the last passing loop if there is another train already in that section as this could lead to irrecoverable deadlocks. With the /opposite qualifier set, the command searches only for trains in the opposite direction of the defined path. ``$callon`` This will allow a train to 'call on' into a platform occupied by another train. For full details, see the :ref:`discussion above ` on the relationship between signalling and timetable. ``$hold, $nohold and $forcehold`` These commands are functionally identical to (and take precedence over) their respective station :ref:`commands `, but apply only to the current train. ``$forcewait`` Identical to the station :ref:`command `, but applies only to the current train. ``$nowaitsignal`` Identical to the station :ref:`command `, but applies only to the current train. ``$waitsignal`` Can be used to override and negate a ``$nowaitsignal`` station :ref:`command ` for the current train. ``$noclaim`` Experimental option: The ``$noclaim`` command inhibits the train from claiming track circuit sections if the train is held at a signal. A train with the $noclaim command would always be last in the queue at busy junctions, always giving priority to any other train. .. _timetable-cmd-detach: ``$detach`` Syntax : ``$detach `` Set details for train to detach a portion of that train. Parameters to define the portion to be detached : ``/power`` Will detach the power unit. The system will check for power unit at front or rear, if both are found, front will prevail. If there is no power unit at either end, nothing is detached. ``/leadingpower`` Will detach the front power unit only. If there is no power unit at the front, nothing is detached. ``/allleadingpower`` Will detach all power units at the front of the train. If there are no power units at the front, nothing is detached. ``/trailingpower`` Will detach the power unit which is the rearmost unit on the train. If the rear unit is not a power unit, nothing is detached. ``/alltrailingpower`` Will detach all power units from the rear of the train. If there are no power units at the rear of the train, nothing is detached. ``/nonpower`` All units which are not power units will be detached from the train. The system will determine at which end of the train power units are located, and will then detach all non power units from the other end of the train. If neither end has power units, units will be detached from the rear. If both ends are power units, nothing is detached. ``/units=n`` (n may be <0 or >0 but n=0 is not allowed) Number of units to be detached. If n>0, the units will be detached at the front of the train. If n<0, the units will be detached at the rear of the train. If n exceeds the actual length of the train, n is reduced such that one unit remains on the train. ``/consist=[+[+...]]`` Name of consist(s) to be detached. For use of consist names in detach command, see :ref:`note on consist names ` below. The consist to be detached must be at either end of the train, i.e. it must be the front portion or the rear portion of the train. If a list of consists is defined, it must be in the sequence of the consists to be detached, from the outside looking inward, i.e. if the units are to be detached at the front, the first consist in the list must be the front portion, but if the units are to be detached at the rear the first consist in the list must be the rear portion. If neither front nor rear portion matches the consist or first consist as defined, nothing is detached. Parameters for formed train : ``/forms=`` Detached portion will form train as indicated. ``/static`` Detached portion will form a static consist. .. _timetable-cmd-attach: ``$attach`` Syntax : ``$attach=`` This train will attach to train as indicated, and will therefore cease to exist. If used at station stop, there is no use to define anything beyond this stop, and nothing can be defined in the ``#dispose`` field either. If the other train to which this train must attach is not at the location where the attach is to take place, this train will terminate without the attach taking place. It is therefore advisable to use a ``$wait`` command to ensure the other train is in the location as required. If the ``/firstin`` or ``/setback`` parameter is set, it should be the other way round, in that case a ``$wait`` command should be set for the other train to ensure this train is indeed first in. Parameters (only valid at station stop) : ``/firstin`` This train is in first, and will wait for arrival of the second train to perform the attach. The other train may come in ahead of this train through a switch or from the opposite direction. ``/setback`` This train is in first, and will wait for the other train to come in behind. When the other train has arrived, this train will set back to perform the attach. This should not be used if an engine is to be detached from the other train as this train will not wait for the engine to clear before performing the attach. .. _timetable-cmd-pickup: ``$pickup`` Syntax : ``$pickup= /static`` This train will pick up the train as defined in the command, or will pick up the static consist which is on the location where the pickup is defined. The train which is picked up will cease to exist. The full train is picked up, no changes are made to the consists of either trains (except if combined with $triggers command in #dispose field). If there is no train to pick up at the required location, the train will continue as defined. .. _timetable-cmd-transfer: ``$transfer`` Syntax : ``$transfer= /static `` This train (the "active" train) will transfer units with the train as indicated, or with a static consist placed at the location where the transfer is defined (the "passive" train). With a transfer, units will be transferred from one train to another, but both trains will continue to exist. At least one power unit must remain on the "active" train, this power unit must not be part of the portion to be transferred. The "passive" train need not have power units, or all power units may be detached as part of the transfer. Parameters defining the type of transfer : ``/give`` This train is to give the defined units to the other train, that is units as defined for the "active" train will be moved to the "passive" train. ``/take`` This train is to take the defined units from the other train, that is units as defined for the "passive" train will be moved to the "active" train. ``/keep`` All units except the units as defined for the "active" train will be transferred to the "passive" train. ``/leave`` All units except the units as defined for the "passive" train will be transferred to the "active" train. Parameters defining the units to transfer or to keep on the train : ``/onepower`` : One power unit only. ``/allpower`` : All power units. ``/nonpower`` : All units which are not power units. ``/units=`` If the portion is defined for the "active" train, and exceeds the length of that train, the number is reduced such that one unit will remain on the train. ``/consist=[+consist[+...]]`` Consists names of portions to keep or to transfer. The consist names must be in sequence, and the first (or only) consist name must match the portion at the applicable end of the train. .. _timetable-cmd-activate: ``$activate`` Syntax : ``$activate=`` Will activate the train as indicated, either when the train starts, when the train is at the indicated stop or when it is terminated. .. _timetable-start: Start Commands '''''''''''''' ``$create`` Syntax : ``$create[=