The Traffic Timetable File

Preface

This is the description of the syntax and semantics of the Timetable file in the Traffic Screensaver

This description is not a course book - it endeavors to cover the entire subject, but not in a didactic form. If you are new to the Traffic Screensaver, you should read also the "How to write a Timetable file for the Traffic Screensaver" file. That document shows the step by step usage of several commands, starting with some very simple examples, with several illustrations. It is the suggested introduction--even when not complete; it does not cover all the commands and possibilities the program is capable of.

This document describes the elements of the Timetable file from the top down: it begins with the commands--complex structures of the Timetable file you'll see if you read such a file--and expands on the constituent syntactical elements. You will better understand a command (especially the Movement commands) if you follow this rubric and read all the information about the ingredients and the syntax elements used.

Special thanks for James McDonald, who revised this description - not only correcting its language, but sometimes explaining things, which seemed for the author evident.

Zoltán Szabó


Index

General Rules
Conditional Evaluation

Global Timetable Commands

$ABOVE
$BELOW
$BGCOLOR
$DEF
$END
$ENDGROUP
$ENDLINE
$ENDSECTION
$GROUP
$INCLUDE
$LINE
$MAXLINE
$MINSPACE
$NOSTOPONCLICK
$NOSTOPONKEY
$NOSTOPONMOVE
$OPT
$RANDOM
$SECTION
$SKIPERR
$SPEED
$STOCK
$USECACHE
$WAY

Sections, groups, lines

Movements

M=SIMPLE
M=FOLLOW
M=STOP
M=BACK
M=CUT
M=CHANGE
M=OPEN
M=UNIT
M=PUT
M=GET
M=ECHG
M=HEAD
M=PUSH

Composing a Train

Global modifiers
[MI: ]
[MP: ]
[PD]
, [PLU], [PRU], [PMU], [P4U], [PDU], [PA],
[PFU], [PBU], [PFIU], [PBIU], [PHU], [PTU]

Inputting a vehicle with phase pictures

Modifiers

Conditional modifiers
[#A: ] Default Acceleration
[#B: ] Default Deceleration
[#V: ] Default Speed
[#W: ] Default Right of Way
[A: ] Animation Definition
[B: ] Block Fill
[BT: ] Block Transparent
[C: ] Color Change
[CB: ] Couple Base
[CL: ] Couple Left
[CR: ] Couple Right
[CP: ] Copy Part
[D: ] Define Overlay
[DA: ] Door Animations
[DB: ] Define Overlay Behind
[DID: ] Door Inner Double
[DIL: ] Door Inner Left
[DIR: ] Door Inner Right
[DOD: ] Door Outer Double
[DOL: ] Door Outer Left
[DOR: ] Door Outer Right
[DT: ] Define Overlay Transparent
[E: ] Pantograph Single
[ED: ] Pantograph Down
[EM: ] Pantograph Mirrored
[EU: ] Pantograph Both Up
[EX: ] Pantograph Exchanged
[F: ] Flood Fill
[L: ] Label
[M: ] Mirror
[MP: ] Mirror Part
[MX: ] Mirror Exchange
[N: ] Neighbor Connection
[NAME: ]
[NC: ]
Neighbor Connection Clear
[NCL: ] Neighbor Connection Clear Left
[NCR: ] Neighbor Connection Clear Right
[NL: ] Neighbor Connection Left
[NR: ] Neighbor Connection Right
[NT: ] Neighbor Connection Type
[O: ] Overlay
[OB: ] Overlay Behind
[OT: ] Overlay Transparent
[P: ] Point
[PB: ] Point Behind
[PD], [PLU], [PRU], [PMU], [P4U], [PDU], [PA],
[PFU], [PBU], [PFIU], [PBIU], [PHU], [PTU]
[PT: ]
Point Transparent
[R: ] Reverse
[T: ] Text
[TL: ] Transparent Neighbor Connection Left
[TN: ] Transparent Neighbor Connection
[TR: ] Transparent Neighbor Connection Right
[TT: ] Transparent Neighbor Connection Type

Syntax Elements

<Acceleration>
<AnimationRules>
<Boolean>
<Color>
<Deceleration>
<Direction>
<Filename>
<FgBg>
<Integer>
<IntList>
<Language>
<Name>
<NewColor>
<Place>
<Point>
<PointList>
<Real>
<RoW>
<Simple>
<Speed>
<Text>
<Train>

<TrainList>
<WaitTime>
<W>, <H>
<X>, <Y>
<#>


General Rules

The Timetable file is a text file which determines the composition of trains and their Movements on the screen, as well as contains settings for the configuration of the program.

Each command in the Timetable should be in a single line of code. This, however, can be difficult to read when programming so there are a few conventions to be aware of which make reading and programming easier.

Attentive observers will notice that there are often commands or parameter values which have different codes but identical meanings. This is because these codes are often abbreviations in different languages. You can choose the one you can most easily remember.

In the following syntax descriptions the double equal sign ( == ) means "is defined as" and the double vertical bar ( || ) means "or." Bold characters denote exactly the character or text which appears in bold. The elements between   <   and   >  are the syntax elements defined by abstract rules. At the moment there are only parts of the syntax shown in these abstract forms. How does one read these syntax descriptions ?

Let's see a simple example:

Here we see the definition of an integer number. A digit is - not surprisingly - one of the number characters. The double bars between the numbers mean: one of them. Digit is 0 or 1 or 2 or 3 ... and so on. What does <Simple> mean? The left part of the rule says: <Simple> == <Digit>, that is, a single digit (a number character) corresponds to the definition. The second part you can read so: <Simple> == <Simple> <Digit> . Which means: if you have already a character sequence which corresponds to the rules of <Simple>, you can append a digit to it, and you get also a <Simple> . This recursive definition describes the entity <Simple> completely: an integer number.

The syntax check of the Timetable file is not as strict as one would find in a compiler. If you use a correct expression suitable for the following rules, you should get the behavior described in this document - even in a future release of the program. If you use an expression violating the rules here, perhaps you will get an error message. These appear in the form of a message box, or in the form of a white square traveling in the place of the vehicle picture, with the error text written on it. Or perhaps you will get some functional result. For example, giving a real number in the place where only an integer number is specified, can lead to error, but can also lead to the usage of the same number rounded to the next integer. Using special characters in picture names can cause errors or misinterpretation in some expressions or-- with some luck-- you may get the result you desire. However, it is better to avoid such constructs - perhaps the same expression will cause an error in the next program version, or invoke a new feature - with undesired results.

Conditional Evaluation

You can customize your Timetable file by using conditional evaluations. Conditional evaluations ask "what if," the operative part of the evaluation being "if." The syntax of these conditional strings is as follows:

{ <condition> ? <true_part> ? <false_part> }

These conditions are evaluated first, and only the lines or line parts passed through the conditional statement will be analyzed and acted upon. You can modify any element of a Timetable file (commands, Movements, single parameters, vehicle names, modification commands) with these conditional expressions.

The configuration options must be referenced in the first few lines of the Timetable file by using the $OPT command described below. The value of these options (selected or unselected) can then be modified from the Traffic main window using the Options menu commands.

Individual configuration strings can be linked together to create combinations of their outcomes. The linking process is similar to an algebraic equation. The individual options can be enclosed in parentheses and are linked together with either & (meaning "and") or | (meaning "or"). Placing a ! (exclamation point) in front of the string returns the opposite or negative value of the string. If you place a ! in front of a command string contained in parentheses it will return the negative value of whatever the final outcome of the command(s) in parentheses is.

The second question mark and the <false_part> parameter are optional. Individual parts of the statement can be fed into each other. For example: {Norway?E116|E117{Diesel?|Di6}}

The conditional evaluations described here and the conditional modifiers controlled by criteria are fully different things. The conditional modifiers ( [<Condition>!<Command>:...] or [< <Command>:...]) base their outcome on the existence of the criteria modifiers in the train expressions - you can select in the Timetable file among the possibilities (to obey a modifier or not) you defined in macro definitions in the same Timetable file, in an included Timetable file or in the Stock List; and you can select among the possibilities based on the actual direction of the trains - it can be the result of a random decision made by the computer. The conditional modifiers help to define the vehicles generally - with and without smoke, with and without load, the same picture for vehicles traveling left or right (by mirroring the whole vehicle or only parts of it). The conditional evaluation ( { <condition> ? <true_part> ? <false_part> } ) based on the options in contrary relies on the decision of the human - as the options can be set and cleared in the configuration menu. The same conditional modifier can behave differently along a screensaver run, as it's decision is based on the actual environment - in which context the vehicle macro is invoked. The same conditional evaluation behaves always the same way in a single run, as the value of the options is analyzed at program start, and only that parts of the Timetable file will be stored and obeyed, which fulfill the conditions in the { ? } constructs.

Timetable Commands

Timetable commands begin with the $ symbol. Several Timetable command have multiple names - you can select between short and descriptive names. These forms are fully identical in their syntax and behavior.

$OPTION K=<Name>; V=<Boolean>; N=<Text>; <Language>=<Text>;
$OPT

For entering limited expressions. The $OPT command lines should appear at the very top of the Timetable file! They should be therefore in the original Timetable file, invoked directly, they cannot be in a file included by the $INCLUDE command.

K = <Name>; Keyword (internal name) of the limited expression
V = <Boolean>; The default value of the option, if nothing has otherwise been set in the configuration window.
N = <Text>; The default name of the option which is seen in the menu, if the name is not given in the actual language.
<Language> = <Text>;   The name of the option in the menu in the applicable language.

The names of the options are shown in the Options menu of the configuration window of the screensaver in the actual language (or the default language, if there is no name in the currently selected language). You can set or clear the options by checking them off in the menu. These selections will be preserved between the runs.

If several Timetable files have the same options (the same keyword), a common value will be stored for this option. The screensaver will show the menu entry with the text the actually selected Timetable file defines it, the value of the option (if it is selected or not) is inherited from the previous Timetable file having the same option keyword.

$INCLUDE <Filename>
$INC

This reads the <Filename> Timetable file. It works, as if the whole content of the <Filename> file appears where the $INCLUDE line is placed. You can recursively include files - up to a 10 file depth. There is no limit for the total amount of included files, only for the maximum depth.

$END
$EXIT

End of the file. Any lines appearing after this are not read. If you use the $END command in an included file, it terminates the included file, but it will not be seen as the end point of the the including file.

$STOCK <Filename>

Defines the Stock List file. This command overrides the "Stock List Definition File Name" in the configuration window - you can use different Stock List files for different Timetable files without needed to change the setting in the configuration window every time. The setting in the configuration window determines the picture collection used by the viewing and editing commands ("Stock List", "Description Editor", "Graphic Testpad", and is the default value, if the $STOCK command is not present in the Timetable.

The ability to have more than one Stock List file per Timetable was implemented to use picture collections in several scales not compatible with each other. (Traffic can use the pictures of the 30dot and 120dot Train Side View pictures, the pictures drawn for the NSME screensaver etc. - but the scale of these pictures is different).

$USECACHE <Simple>

Defines the use of the cache. This command checks the "Cache" value from the configuration window. The possible values are:

The purpose of this command is let you have different settings for working with the picture collection - including and changing new pictures - and for running as a screensaver The usage of the cache can be annoying if you're creating new pictures, testing and then correcting them because once the Traffic program loads the picture into its cache, no further changes to the graphic's source file will be reflected until you restart the Traffic program, or, if you use the 3 setting, until you explicitly clear the cache. On the other hand, the usage of the cache can speed up the screensaver's ability to run.

$PHASESTEP <Real>
$PH   $PHSTEP

$NOSTOPONMOVE <Boolean>

The screensaver does not stop when the mouse is moved.

If this command is not specified in the Timetable file, the settings from the configuration window are used.

$NOSTOPONCLICK <Boolean>

The screensaver does not stop when the mouse is clicked.

If this command is not specified in the Timetable file, the settings from the configuration window are used.

$NOSTOPONKEY <Boolean>

The screensaver does not stop when keys are pressed on the keyboard. (Only the ESC and Enter keys will stop the program)

If this command is not specified in the Timetable file, the settings from the configuration window are used.

$SKIPERR <Boolean>

If there are any errors in the Timetable file commands the program skips the whole line and proceeds with the next vehicle line according to the $RANDOM setting. Without this setting the vehicles with errors are shown as moving squares - instead of the vehicles.

Some trivial syntax errors in the Timetable file, such as parentheses matching problems, are not affected by this setting. The user is warned by a popup window.

If this command is not specified in the Timetable file, the settings from the configuration window (the menu item Special | Skip Erroneous Lines) is used.

The only purpose of this setting is to skip nonexistent pictures in Timetable files which are created by the program author or others. The screensaver can use picture from sources, and some of these sources are not free (for example: the full version of the MM&MM Screensaver V2 or V3, pictures from the BahnLand program or the Nimo Extension Kit). If the Timetable file specifies such pictures and you run it on another machine not having these pictures, you can avoid the many error messages by using this setting. This setting is not intended to skip syntax errors in the Timetable file. If you develop or extend a Timetable file yourself, you should switch off both the settings in the $SKIPERR command and in the configuration window while debugging.

$BGCOLOR <Color>
$BACKGROUND

The background color. Default value: the background color defined in the Stock List file. Sometimes it is useful to have different background colors in the Stock List windows - for example to see which pictures are transparent and which are opaque - and when the program runs as a screensaver, to use the background of the opaque pictures as the background for the screen - black.

It is not possible to use the coordinate switch with the <Color> parameter.

$SPEED <Integer>

$WAY A=<Row>; E=<Row>; M=<Row>; R=<Row>; T=<Row>; L=<Row>;

In the Stock List one can select the appropriate right of way (Row) for the vehicles. This command can modify which Row pictures will be used for each type. The default settings:

Street a
E Electric locomotives and railcars   3E
M Third rail electric 3M
R Other railway vehicles 3
T Trams and trolleybusses ae
L Catenaries set lower 3L

$DEF <Name> = <Text>
$DEFINE   $DEFINE_MACRO

Defines a macro. Macros can be a vehicle, a part of a train or even an entire train. They are useful when there is something which must be used or done multiple times. Macros can also be nested within other macros. For example:

$DEF BR218=BR218BB|BR218ROT
$DEF DIESEL_FUR_PERSONENZUG=3:BR218|BR211

The same macro name can be defined many times. The macros are read in reverse order that is, from the end to the beginning (from the last macro defined to the first macro defined). In the case of nested macros the individual macros will be read from the position of the expanded macro backwards. This strategy allows one to redefine a macro or a picture name many times. The intended usage for this feature is to append modifiers to the pictures (if this wasn't done in the Stock List) or to change the behavior of some vehicles.

Sections, Groups and Lines

The most important elements of the Timetable File are the Movements - the lines not beginning with $ and which are not comments. They describe trains (sets of single vehicles back to back), and how they are moved on the screen. The Movements (in this program version) use always a single track.

The Movements need space on the screen in order to run. The screensaver reads the next Movement (selected according to the $RANDOM command) from the Timetable file and then checks if there is enough space for the Movement on the screen. If there are multiple possibilities, it selects a vertical position for the Movement by random, allocates the space, and starts the Movement (first by drawing its background and foreground picture(s), when used). Then it selects the next Movement, places it, and so on. If it cannot find sufficient room for the Movement, it waits until other Movements finish and free up space on the screen.

A section (the commands $SECTION , the corresponding terminate command $ENDSECTION , and the Movements and further sections contained between them) behaves like a single Movement: it requires a defined amount of screen area, occupies it and runs a while, terminates and frees the screen area. However, inside the section, it behaves like a screen: it provides space on the screen for its subsections ("children"), the Movements and other sections contained between its $SECTION and $ENDSECTION commands.

The $GROUP is a simpler construct - it behaves not like a screen, but like a single line. It can only contain Movements but it cannot contain any further $SECTION, $GROUP or $LINE commands in between the $GROUP and $ENDGROUP commands. All the Movements will run in the exact same area of the screen. If the $GROUP command has any of the FG= ; BG= ; W= ; WP= ; parameters the background and foreground image(s) (or simply the right of way) will be drawn before the first Movement starts and will be deleted after the last Movement finishes. That means, the background picture remains on the screen during the entire run of anything contained in the $GROUP. (The points along the track are defined along with the right of way or foreground/background picture(s) so in this case you cannot define points in the Movements individually; you should do so in the $GROUP command.)

The first version of the Traffic Screensaver was able to use only fixed lines - all the Movements ran on a set of lines and their positions were fixed at the program's start. The number and the positions of the lines were calculated based on the ABOVE, BELOW, MINSPACE, MAXLINE parameters (and the IMGY parameter, the maximal vehicle height, which was fixed at the value contained in the Stock List). The primary method of placing lines for the Movements in the present version is by random selection, but you can get the fixed method back by placing $LINE commands into the Timetable file. As a $SECTION command acts for its child lines as if it were the whole screen, you can place $LINE commands not only on their own in the Timetable, but inside a $SECTION command too. The possible number of such fixed lines and their position (the distance between them) will be calculated according to the values of the ABOVE, IMGY, BELOW, MINSPACE, MAXLINE parameters: the MAXLINE parameter determines the number of lines possible. If the height of the screen or the section divided by the amount of space needed by each individual line (the sum of the ABOVE, IMGY, MINSPACE and MAXLINE parameter) results in a different value - the lesser of them is used. This calculation determines the possible number and positions of the fixed lines inside a section or inside the screensaver window (the implicit section).

The Movements between a $LINE and a following $ENDLINE command belong to that line. For compatibility (and because you cannot recursively insert a $LINE into another $LINE) you do not have to close the set of Movements belonging to the $LINE command with a corresponding $ENDLINE command. The set is automatically closed by a $ENDSECTION, $GROUP, $SECTION or by the next $LINE command.

There are two formats for the $LINE command: with and without the L= ; line number parameter. If a $LINE command has this parameter, it will occupy exactly the lines that are listed in this parameter. If there is more than one line, the Movements will be dynamically selected for these lines from the set of the Movements belonging this $LINE command. That is, the track which has just finished its Movement will get the next Movement (selected accordingly to the SEQUENCE parameter). If there are numbers in the line list greater than the number of available lines, these numbers will be discarded. If all the numbers of a line list are discarded the Movements belonging to this $LINE command will never be executed.

If the $LINE command has no L= parameter the Movements belonging to this $LINE command will occupy all the remaining tracks after all of the $LINE commands with line numbers are processed. In this case all of the space on the screen (or inside a section) is allocated to fixed lines. No groups, segments or Movements beyond the Movements belonging to a $LINE command can run (they will be ignored by the program).

If you use only some $LINE commands with an explicit line list, it is possible that sufficient space remains in the section or on the screen to run elements beyond the range of the $LINE commands too. This other Movements will be placed at random positions inside the section, selecting only places not occupied by the $LINE commands.

How long do the complex elements (sections, groups, fixed lines) remain on the screen? The fixed lines have no lifetime of their own, they exist only as long as their containing section exists. The implicit section (the window or full screen the screensaver is running in) exists until the user terminates the program by pressing a key on the keyboard, by a menu item, or by a mouse movement (if the $NOSTOPONMOVE command or the similar configuration setting allows it). The default lifetime of a section or a group is until all of their children are run one time. You can change this lifetime with some parameters - the lifetime can be limited by the exact number of the Movements to be run, by time in seconds, or it can be unlimited.

All of the sections, groups and lines have their own set of Movements (or - in case of sections - perhaps some included subsections too). They select the next Movement to appear on the screen according their own sequence setting. If a dedicated sequence setting is missing, they inherit the sequence setting from their parent section. You can set the sequence for the implicit section by the top level command $SEQUENCE. If it is missing, the configuration window contains the default setting (selectively for full screen and windowed mode).

The lifetime of a section and the sequence of the Movements contained within it are two independent properties. Each section "remembers" which of its Movements were already run. If the lifetime of the section is shorter than all of the Movements in the section (some Movements were not shown in the first lifetime), and the selected sequence is not the full random sequence, the section will continue its work the next time it comes on the screen. When FIXED or CONTINUED sequence is turned on it continues with the next Movement following the last Movement started in the previous run. When RANDOM_SEQUENCE is on, it will avoid repeating a Movement until all the Movements are run. The only difference between the FIXED and CONTINUED sequences is when you stop the screensaver, and then it starts again (or you start it with the Test button in the configuration window) the FIXED sequence always starts from the beginning, the CONTINUED sequence remembers to start up right where it left off.

In the following paragraph we describe the individual parameters of the $SECTION, $GROUP and $LINE commands. The common parameters defining lifetime, sequence and default values for the Movements are described together with the corresponding commands (referring to the implicit section, the whole window) in a subsequent chapter.

$LINE L=<LineList>; PathwayParameters;

<LineList> == <LineListItem> || <LineList>,<LineListItem>
<LineListItem> == <Simple>
|| <Simple> - <Simple>

List of numbers or intervals of numbers separated by commas (1,3-6,8) - the number of the lines the Movements belonging to this $LINE command will be shown.

If one of the right of way, the waypoints, the foreground and/or the background (W=, FG=, BG=, WP=) parameters is set in the $LINE command, then these will appear on the screen immediately upon the program's or section's start, and will remain on the screen between the Movements too. In this case, the W=, FG=, BG= and WP= parameters in the individual Movement are superseded by those of the $LINE command - the environment won't be changed by them. If neither the W=, nor the FG=, BG= or WP= are present in the $LINE command, the same parameters in the Movement commands determine the environment. In this case, the street, rail, catenary, and, when applicable, foreground and background pictures will be drawn on the screen before the Movement starts, and will be cleared only after the one Movement finishes.

$ENDLINE
$EL   $ENDL   $ELINE

$SECTION HEIGHT=<BlockHeight>; N=<Simple>; SEQ=<RandomP>; LifetimeParameters; DimensionParameters; PathwayParameters;
$SECT

$ENDSECTION
$ES   $ENDS   $ESECT   $ESECTION

$GROUP SEQ=<RandomP>; LifetimeParameters; DimensionParameters; PathwayParameters;

$ENDGROUP
$EG   $ENDG   $EGRP   $EGROUP

You can treat the whole screen (or the window surface of the screensaver's window in windowed mode), as an implicit section. Several parameters of the $SECTION and $GROUP commands consequently have a command equivalent - these command equivalents apply only to this implicit section: the initial screen surface of the screensaver In the following chapter these command equivalents and the corresponding $SECTION or $GROUP parameters are discussed together.

Lifetime Parameters

The lifetime parameters determine how long a $SECTION or $GROUP command (and consequently the Movements belonging to these commands) remain on the screen. As described already, it is independent of the Movement sequence but you can select a lifetime allowing all the Movements to run once inside a section.

If the lifetime is over, the section will not start more Movements. Additionally, you can also specify how fast the section disappears from the screen: is it allowed to finish the Movements already running, or it should abort all Movements immediately.

The lifetime parameters do not have a command format - the implicit section (the screensaver window) is active until user intervention.

SEQUENCE = <RandomP>;
SEQ= ;   RANDOM= ;
$RANDOM
<RandomC>
$SEQ   $SEQUENCE

<RandomP> == 0 || F || FIX ||
            1 || C || CONTINUED ||
            2 || Q || RSEQ || RANDOM_SEQUENCE ||
            3 || R || RANDOM
<RandomC> == 0
|| 1 || 2 || 3

Defines the running order

If the command is not specified in the Timetable file, the settings from the configuration window are used for the implicit section. If the parameter is not specified in a subsection, the value of the parent section is inherited.

The command format can only be the numeric values, not the text equivalents.

LIMIT_TIME = <Integer>;
LT= ;   TIME= ;

LIMIT_MOVEMENT = <Integer>;
LC= ;   COUNT= ;

UNLIMITED;
NL;   NO_LIMIT;

FINISH_MODE = <FinMode>;
FIN= ;

Dimension Parameters

VEHICLE_HEIGHT = <Simple>;
VH= ;   IMGY= ;
$VEHICLE_HEIGHT
<Simple>
$IMGY

ABOVE = <Simple>;
AB= ;
$ABOVE
<Simple>
$AB

The maximum height of the foreground and background pictures above the vehicle. This amount of space will be reserved for a line on the screen. Using a foreground or background picture that is higher than this parameter specifies will result in the extra height being truncated. The same thing happens if the container of a command (the screen / test window height, or the parent $SECTION height) is smaller - the above parameter will be adjusted in order to fit into the container.

The default setting is 1 pixel for catenary for the command (for the implicit section). The default for the parameter is the value of its parent.

BELOW = <Simple>;
BL = ;
$BELOW
<Simple>
$BL

The maximum height of foreground and background pictures beneath the vehicles. It behaves similar to the ABOVE= parameter (see above). The default setting is 7 for ballasted right of way.

MINSPACE = <Simple>;
MS = ;
$MINSPACE
<Simple>
$MS

The minimum height in pixels between the lines/trains (between the bottom of the rail and the top of the catenary of the line below, or between foreground / background pictures, if they are used. More precisely, the minimal distance between two lines is the sum of the parameters ABOVE, MINSPACE, BELOW and the maximum height of the vehicles (the VEHICLE_HEIGHT parameter).

MAXLINE = <Simple>;
ML = ;
$MAXLINE
<Simple>
$ML

LEFT=<Integer>;

WIDTH=<Integer>;

Pathway Parameters

BG = <FgBg>;

FG = <FgBg>;

W = <Row>;

WP = <PointList>;

Movements

Strings which do not start with $ are the train consist (Movement) commands. The basic syntax is:

M = <Movement>; <ParamName> = <Value>; ...

The type of Movement determines which values one can or should input. The Movements have more than one name - these names are, however, identical in behavior.

The default setting for the Movement type is M=SIMPLE; . If there is no M= parameter in the line, the trains themselves are input with the parameter C= and ended with a semicolon ";". The C=<Train>; of every Movement must always be input in order to have a train. Without any other parameters modifying it, the default commands apply or are specified by those values carried by the individual vehicles in their respective Stock List entries ([#A: ],[#B: ],[#V: ],[#W: ], the setting of the right of way in the Stock List, etc.)

In the following tables the common parameters which always have the same meaning will not be discussed individually - see the description of the corresponding syntax element. Some special considerations are mentioned for the first Movements but are not repeated for each Movement. The screensaver treats the different Movements similarly if possible.

A Train is defined as a vehicle consist - vehicle pictures back to back. A train may consist of a single picture - and, odd as it may seem, perhaps even a picture of an airplane, a car, a ship, a bird - it should not be strictly a train.

The Movement commands and their parameters:

M=SIMPLE;
M=M1;

Simple runby. This is the default setting - the simplest form of a Movement is to write a single C=<Train>; parameter as a Movement command.

C = <Train>;   The list of vehicles comprising the train.
D = <Direction>;   The direction the train travels across the screen.
V = <Speed>;   The speed the train travels across the screen.
W = <Row>;   A simple track picture, which will be shown below (and, in the case of catenary, above) the moving train.
WP = <PointList>;   Waypoints defining animation actions which are triggered when the train passes them.
FG = <FgBg>;   Foreground pictures in front of the moving train.
BG = <FgBg>;   Background pictures behind the moving train.

M=FOLLOW;
M=M2;

Multiple vehicles/trains follow each other in close proximity. The trains will not collide, even if their speeds are not equal.

A = <Acceleration>;   Acceleration rate of the trains: if the first train disappears from the screen and the following train has a higher maximum speed, they speed up to that higher speed with this acceleration rate.
B = <Deceleration>;   Deceleration rate of the trains: if a train running slower precedes a train, it must slow down as not to collide with the other. This deceleration value will be used for the slowing down (it determines also how far from its predecessor a train must begin to brake).
C = <TrainList>;   The trains which follow each other. The trains must be separated from each other by semicolons ( ; ) - therefore you should enclose the train list in parentheses, because the semicolon terminates the parameters.
D = <Direction>;   The direction all trains pass across the screen.
V = <Speed>;   The speed the trains pass across the screen. It is only a single parameter, but you can specify a random expression on place of this parameter which will give you different vehicle speeds and a more pleasing appearance on the screen. If you omit the parameter, and no vehicle of the first train has a default speed modifier ([#A: ]), the screensaver selects different random speeds for the different trains.
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=STOP;
M=M3;

The train stops at <Place> , waits for the <WaitTime> and then proceeds.

A = <Acceleration>;   The acceleration rate the train speeds up after it starts from the stopping point.
B = <Deceleration>;   The deceleration rate as the train stops.
C = <Train>;  
D = <Direction>;   The direction the train comes in from. Also the direction the train leaves the screen.
P = <Place>;   Stopping point of the train C. The middle alignment denotes the middle of the train.
T = <WaitTime>;   Waiting time the train stays stopped. You can specify a combined parameter, a sequence of time values in seconds as well as animation actions started during the wait.
V = <Speed>;   The speed the train enters the screen at and the maximum speed the train speeds up to when it restarts. If the stopping point is too close to the side of the screen from whence the trains enters, and the given deceleration rate is not enough to stop the train, the program brakes the train with higher a deceleration value in order to stop it at the specified point. If the stopping point is too close to the side of the screen that the train leaves the screen from (and also if the train is short), the maximum speed will not be attained - the specified acceleration won't be exceeded.
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=BACK;
M=M4;

The train stops at <Place> and then waits for <WaitTime> and then returns from whence it came.

A = <Acceleration>;   The acceleration rate the train speeds up to after its start from the stopping point.
B = <Deceleration>;   The deceleration rate the train stops with.
C = <Train>;  
D = <Direction>;   Direction from which the train enters the screen. It will leave the screen in the opposite direction.
P = <Place>;   Stopping point of the train C. The middle alignment denotes the middle of the train.
T = <WaitTime>;   Waiting time the train stays stopped. You can specify a combined parameter, a sequence of time values in seconds as well as animation actions started during the wait.
V = <Speed>;   The speed the train enters the screen at and the maximum speed the train speeds up to when it restarts.
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=CUT;
M=M5;

Trains C1 and C2 travel together in direction D with speed V and stop at place P with deceleration rate B. Then after a wait time T1 one of them departs. After a second wait time T2 the other follows.
(This Movement is especially useful for splitting multiple unit motor cars and double headed trains)

A1 = <Acceleration>;   Acceleration rate of the left train section C1
A2 = <Acceleration>;   Acceleration rate of the right train section C2
B = <Deceleration>;   Deceleration rate of the combined train C1,C2
C1 = <Train>;   The left train section
C2 = <Train>;   The right train section
D = <Direction>;   Direction from which the two sections come in together
D1 = <Direction>;   Direction which the left section of the train leaves the screen
D2 = <Direction>;   Direction which the right section of the train leaves the screen.
P = <Place>;   Stopping point of the train C1,C2. The middle alignment denotes the contact point of C1 and C2.
T1 = <WaitTime>;   Waiting time and animation actions from the trains' halt until the first part starts.
T2 = <WaitTime2>;   Waiting time and animation actions from the moment the first train leaves the screen until the second train starts.
V = <Speed>;   Speed with which the combined train enters the screen.
V1 = <Speed>;   Maximum speed the left section of the train speeds up to.
V2 = <Speed>;   Maximum speed the right section of the train speeds up to.
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=CHANGE;
M=M6;

Train C1 with C travels in direction D at speed V and stops at place P at a deceleration rate of B1. Then, after a wait time T1, train C1 departs with acceleration A1 and speed V1. Then, after a wait time T2, train C2 arrives with a speed V2 and comes to a stop with deceleration rate B2, couples to train C and, after wait time T3, departs with acceleration rate A2 and speed V3.
This Movement makes it possible to change locomotives or to add/remove one or more wagons from a train. C1 and C2 can also be locomotives, but can be locomotives with wagons or railcars too.

A1 = <Acceleration>;  
A2 = <Acceleration>;  
B1 = <Deceleration>;  
B2 = <Deceleration>;  
C = <Train>;  
C1 = <Train>;  
C2 = <Train>;  
D = <Direction>;  
P = <Place>;   Stopping point of the train C1, C
T1 = <WaitTime>;  
T2 = <WaitTime>;  
T3 = <WaitTime>;  
V = <Speed>;  
V1 = <Speed>;  
V2 = <Speed>;  
V3 = <Speed>;  
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=OPEN;
M=M7;

The train stops at place <Place> and then after a pause <WaitTime> departs. If the train has DOOR or the OPEN and CLOSE animations the train's doors open upon halting and then close before departing.

This Movement exists for compatibly purposes only. The same result can be achieved by using the M=STOP; Movement with a T= parameter built by concatenating the values of the T1= ; T2= ; T3= ; parameters with the OPEN and CLOSE action names.

A = <Acceleration>;   Acceleration rate of the train after its stop
B = <Deceleration>;   Deceleration rate of the train before its stop
C = <Train>;   The vehicle pictures composing the train
D = <Direction>;   The direction of the train's travel. The train continues its way in the same direction after the stop.
P = <Place>;   Stopping point of the train C
T1 = <WaitTime>;   Wait time and animations run before the opening the doors
T2 = <WaitTime>;   Wait time and animations run while the doors are open
T3 = <WaitTime>;   Wait time and animations run after the doors close
V = <Speed>;   Rate of speed the train enters the screen at and maximum speed the train accelerates to after restarting
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=UNIT;
M=M8;

The first train arrives and comes to a halt. Then a second train arrives and couples to the first. The two then depart coupled together.

C1 = <Train>;   The vehicles of the first train
D1 = <Direction>;   The direction the first train comes in from
V1 = <Speed>;   The rate of speed the first train comes in at
B1 = <Deceleration>;   Deceleration rate the first train stops with
C2 = <Train>;   The vehicles of the second train
D2 = <Direction>;   The direction the second train comes in from
V2 = <Speed>;   The rate of speed the second train comes in at
B2 = <Deceleration>;   Deceleration rate the second train stops at
P = <Place>;   Stopping point of the train C1,C2
D = <Direction>;   Direction which the coupled train leaves the screen
A = <Acceleration>;   Acceleration rate of the coupled train
V = <Speed>;   Speed to which the coupled train accelerates
T1 = <WaitTime>;   Wait time and animations run after the first train stops until the second train enters the screen
T2 = <WaitTime>;   Wait time and animations run after the second train stops until the coupled trains start
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=PUT;
M=M9;

Parts of the train are coupled to the rear of a train. The train C arrives and comes to a stop. C1 appears with C2 from behind, couples C2 to C and then C1 departs. After C1's departure, C departs with C2.

C = <Train>;   The vehicles composing the train
D = <Direction>;   The direction the train comes in from
V = <Speed>;   Speed the train comes in at
B = <Deceleration>;   Deceleration rate the train stops with
A = <Acceleration>;   Acceleration rate the train and the new wagons start with
P = <Place>;   Stopping point of the train C,C2 (the middle alignment specifies the end point of the original train. The alignment opposite of the train's direction is the end point of the added wagons)
V3 = <Speed>;   Maximum speed the departing train with the added wagons accelerates to
C1 = <Train>;   The shunting locomotive
V1 = <Speed>;   Speed the shunting locomotive with the wagons to be added enters the screen at
B1 = <Deceleration>;   Deceleration rate the shunting locomotive with the wagons to add stops with
C2 = <Train>;   The wagons to be added
A2 = <Acceleration>;   Acceleration rate the shunting locomotive starts to leave the screen at
V2 = <Speed>;   Maximum speed the shunting locomotive accelerates to as it leaves the screen
T1 = <WaitTime>;   Waiting time and animation actions run after the original train stops until the shunting locomotive with the additional wagons enters the screen
T2 = <WaitTime>;   Waiting time and animation actions run after the additional wagons are coupled to the train until the shunting locomotive starts
T3 = <WaitTime>;   Waiting time and animation actions run after the shunting locomotive leaves the screen until the train with the added wagons starts
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=GET;
M=M10;

Remove wagons from the end of a train. The opposite of the M=PUT; Movement.

C = <Train>;   The train remaining after the wagons are removed from its end
D = <Direction>;   Direction of the whole train
V = <Speed>;   Speed the C,C1 train comes in at
B = <Deceleration>;   Deceleration rate the C,C1 train stops at
A = <Acceleration>;   Acceleration rate the C train starts with
P = <Place>;   Stopping point of the train C,C1
V3 = <Speed>;   Maximum speed the departing C train speeds up to
C1 = <Train>;   The wagons which will be removed
V1 = <Speed>;   The speed of the shunting locomotive C2
B1 = <Deceleration>;   Deceleration rate of the shunting locomotive C2
C2 = <Train>;   The shunting locomotive
A2 = <Acceleration>;   Acceleration rate of the shunting locomotive and the uncoupled wagons C1,C2
V2 = <Speed>;   Maximum speed which the departing shunting locomotive with the wagons C1,C2 speeds up to.
T1 = <WaitTime>;   Waiting time between the C,C1 train arrival and the shunting locomotive's C2 appearance on the screen.
T2 = <WaitTime>;   Waiting time while the shunting locomotive C2 is coupled to the wagons C1
T3 = <WaitTime>;   Waiting time between the shunting locomotive with the wagons C1,C2 leaving the screen until the shortened train C departs
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=ECHG;
M=SYSTEM_CHANGE;   M=ECHANGE;   M=M11;

This Movement is intended to model a border station between two different electric systems where there is not the facility to switch the voltage of the track. The train comes in (the electric locomotive with lowered pantographs, or the pantographs will be lowered shortly after the locomotive enters the screen - see the WP= parameter), stops, a switching locomotive comes in and brings the electric locomotive away; then a third locomotive comes in, couples to the train, and the train continues on its way. Of course, you can use this Movement to model other things too: the exchange of a damaged locomotive, for example. Therefore, it does not mean that the first locomotive need necessarily be an electric locomotive.

C = <Train>;   The train without the locomotive
D = <Direction>;   Direction the train enters and leaves the screen
V = <Speed>;   Speed the C1,C train is arrives at
B = <Deceleration>;   Deceleration rate the C1,C train stops with
P = <Place>;   Stopping point of the train C1,C
C1 = <Train>;   The (electric) locomotive, which will be changed
V1 = <Speed>;   The speed of the shunting locomotive C2
B1 = <Deceleration>;   Deceleration rate of the shunting locomotive C2
C2 = <Train>;   The shunting locomotive
A2 = <Acceleration>;   Acceleration rate of the shunting locomotive and the removed locomotive C2,C1
V2 = <Speed>;   Maximum speed the departing shunting locomotive with the removed locomotive C2,C1 speeds up to.
C3 = <Trains>; The new locomotive
V3 = <Speed>; The speed the new locomotive enters the screen at
B3 = <Deceleration>;   Deceleration rate as the new locomotive stops
A4 = <Acceleration>;   Acceleration rate the C3,C train starts with
V4 = <Speed>;   Maximum speed the departing C3,C train speeds up to
T1 = <WaitTime>;   Waiting time from when the C1,C train arrives until the shunting locomotive C2 enters the screen.
T2 = <WaitTime>;   Waiting time while the shunting locomotive C2 is coupled to the locomotive to remove C1 until they start moving
T3 = <WaitTime>;   Waiting time from when the shunting locomotive with the removed locomotive C2,C1 leaves the screen until the new locomotive C3 enters the screen
T4 = <WaitTime>; Waiting time from when the new locomotive is coupled with the train until the combined train starts
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=HEAD;
M=TERMINUS_ARRIVE;   M=XBACK;   M=M10;

The train arrives in a terminus. Another locomotive (or a shunting locomotive) follows it, and brings the wagons away backwards. The original locomotive follows them.

Of course this Movement can be used for other purposes too, as neither the "shunting locomotive" nor the "original locomotive" must be single vehicle. By using locomotives together with multiple coaches or railcars you can get other effects too.

C = <Train>;   The train alone - without the old and new locomotives.
C1 = <Train>;   The original (old) locomotive
D = <Direction>;   Direction the train C1,C arrives from.
V1 = <Speed>;   Speed the C1,C train arrives at
B1 = <Deceleration>;   Deceleration rate the C1,C train stops with
P = <Place>;   Stopping point of the train C1,C
C2 = <Train>;   The new locomotive which will be coupled to the rear of the train
V2 = <Speed>;   The speed the new locomotive C2 comes in at
B2 = <Deceleration>;   Deceleration rate of the new locomotive C2
V3 = <Speed>;   The maximum speed the new locomotive with the train C,C2 accelerates to
A3 = <Acceleration>;   Acceleration rate of the new locomotive with the train C,C2
V4 = <Speed>;   Maximum speed old locomotive C1 speeds up to as it departs.
A4 = <Acceleration>; Acceleration rate of the departing old locomotive C1.
T1 = <WaitTime>;   Waiting time from when the C1,C train arrives until the new locomotive C2 enters the screen.
T2 = <WaitTime>;   Waiting time from when the new locomotive C2 is coupled to the train C until they start moving
T3 = <WaitTime>;   Waiting time from when the new locomotive with the train C,C2 leave the screen until the old locomotive C1 starts moving
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

M=PUSH;
M=TERMINUS_DEPART;   M=M13;

A shunting locomotive pushes a train into a terminus, and leaves backwards. A road locomotive comes from the same direction, couples to the train and departs backwards too. (For railcars arriving at a terminus use the M=BACK; Movement.)

C = <Train>;   The train without the shunting locomotive
C1 = <Train>; The shunting locomotive
D = <Direction>;   Direction the train is pushed in from
V1 = <Speed>;   Speed the C,C1 train is pushed in at
B1 = <Deceleration>;   Deceleration rate the C,C1 train stops at
P = <Place>;   Stopping point of the train C,C1
A2 = <Acceleration>;   Acceleration rate the C1 shunting locomotive starts with
V2 = <Speed>;   Maximum speed the departing C1 shunting locomotive speeds up to
C2 = <Train>;   The road locomotive for the train
V3 = <Speed>;   The speed the locomotive C2 comes in at
B1 = <Deceleration>;   Deceleration rate of the locomotive C2
A4 = <Acceleration>;   Acceleration rate of the train C,C2
V4 = <Speed>;   Maximum speed the departing train C,C2 speeds up to.
T1 = <WaitTime>;   Waiting time from when the C,C1 train is pushed in until the shunting locomotive C1 starts back
T2 = <WaitTime>;   Waiting time from when the shunting locomotive C1 leaves the screen until the locomotive C2 enters the screen.
T3 = <WaitTime>;   Waiting time from when the locomotive C2 couples to the train C until the train C,C2 starts.
W = <Row>;  
WP = <PointList>;  
FG = <FgBg>;  
BG = <FgBg>;  

(Other Movements are in development. I'd be grateful for any suggestions.)

 

Composing Trains

<Train> == <VehicleList> || <GlobalModifiers> <VehicleList>
<GlobalModifiers> == <GlobalModifier>
|| <GlobalModifiers> <GlobalModifier>
<GlobalModifier> == <
|| > || [MP:<Number>] || [MI:<Number>] || <PantographState>
<VehicleList> == <Repetition>
|| <VehicleList> , <Repetition>
<Repetition> == <SelElement>
|| <RepeatCount> * <SelOrElem> || <RepeatCount> @ <SelOrElem>
<SelOrElem> == <Element>
|| <Selection>
<Selection> == <Choice> | <Choice>
|| <Selection> | <Choice>
<Choice> == <Element>
|| <Probability> : <Element>
<Element> == <Vehicle>
|| ( <VehicleList> )
<Probability> == <Simple>
<RepeatAmount> == <Integer>

A train is - in its simplest form - a list of vehicles separated by commas (or a single vehicle). You can use random selections (simple or weighted), and repetitions in the list.

<Choice1> | <Choice2> | ... <Choices>

Random choice.

<Probability1> : <Choice1> | <Probability2> : <Choice2> | ...

Random selection with probability weights.
The <Probability> default value is 1, therefore, one can mix these forms.
(This form can also be used when selecting numbers.)

<RepeatCount> * <SelOrElem>

The program repeats the vehicle or part of a train as many times as is specified in <RepeatCount>. The result is a mixed selection if more than one <Choice> is specified. If you use this in combination with parenthetical commands, it will give you a mixed result. More specifically, if you have 3*DR_GBS1500|DR_GAGMSV it will give you three of either wagon type.

<RepeatCount> @ <SelOrElem>

The program repeats the vehicle or part of a train as many times as is specified in <RepeatAmount>. The result is a fixed selection if more than one <Choice> is specified. If you use this in combination with parenthetical or commands, it will give you a fixed result. More specifically, if you have 3@DR_GBS1500|DR_GAGMSV it will give you three of one of the two choices. This is useful for making up unit trains.

The repetition number does not need to be a single number, it can also be a range (3-6), a selection (3|4|7|8), and a selection based on probabilities (3:1|5:2|10:4).

These forms can be enclosed in parentheses. For example:

BR103|(BR218BB,BR218ROT),(4:0|6:1)*DM,3-5*(BPMZ|BVMZ),2@(AVMZ|APMZ)

This string means that there is a 50% chance that the train will appear with a BR103 or two BR218s and a 60% chance that it will come with mail car. Then it has three, four or five Bpmz or Bvmz coaches and either two Avmz or two Apmz coaches at the end.

Global Modifiers

The vehicle pictures of trains should generally be input in the direction of travel and separated from each other by commas. The following symbols can modify the composition of a train or the vehicles contained in it when placed in front of its command string:

<

The pictures follow each other from left to right..

>

The pictures follow each other from right to left. This is independent of the direction of travel. This is particular useful for push-pull trains where the train must appear as a solid unit regardless of direction.

[!<Criteria>]

Sets the condition <Criteria> true for all vehicles contained in the train - you can switch some options prepared in the Stock List. If you have various open and flat freight wagons with loads, you can remove all the loads - thus creating the empty train - if all loaded vehicles have the [E!BT: ... ] modifier, which deletes that picture part showing the load. You can use a criteria with the reverse sense too.

[MP:<Number>]

Maximum length of a train in pixels

[MI:<Number>]

Maximum length of a train in number of wagons.

[PDO], [PNO], [PD], [PN] - All pantographs down
[PLU], [P1U] - Left pantograph up
[PRU], [P2U] - Right pantograph up
[PMU], [P3U] - Third (usually the inner or inner left) pantograph up
[P4U] - Fourth (inner right) pantograph up
[PDU], [P12U], [PU] - First and second (on a standard locomotive that means all) pantographs up
[PFU] - Forward pantograph up (relative to direction of travel)
[PBU] - Rear pantograph up (relative to direction of travel)
[PFIU] - Forward inner pantograph up (relative to direction of travel - useful for multi-system locomotive)
[PBIU] - Rear inner pantograph up (relative to direction of travel - useful for multi-system locomotive)
[PHU] - First pantograph of the train up relative to direction of travel (useful for multi-unit trains)
[PTU] - Last pantograph of the train up relative to direction of travel (useful for multiunit trains)

The pantograph commands change only the behavior of the vehicles having no other pantograph commands built into the vehicle macro.

The pantographs should be input in the following order:

    1. outer left
    2. outer right
    3. inner left
    4. inner right

Inputting a Vehicle with Phase Pictures

To replicate a vehicle's moving parts (spoked wheels, side rods, etc.) several pictures, each making up a frame or "phase" of the whole motion, are used. If the vehicle is moving on the screen these phase pictures are shown one after another in sequence. As the vehicle moves along, the part of the picture showing the moving parts is changed at predetermined distances using a mathematical equation to determine what part of the phase should be shown at the particular point or "step" of the motion.

The syntax is:

The first picture <BasePicture> is the picture of the entire vehicle. For the MM&MM screensaver these multi-phasic base pictures are denoted with a _0 suffix. The first picture can have a direction-dependent overlay. The subsequent phase pictures are then attached with the + sign. The + sign has additional modifiers allowing one to specify exactly how the pictures connect.

+> The phase picture connects to the right
+< The phase picture connects to the left
+ The phase picture connects in the middle
+* The phase picture connects in the middle
+<Simple>: The phase picture connects +<Simple> pixels from the left

Phase pictures always appear at the bottom of the base picture. The phase pictures should only contain the rectangular area of the part that changes. If the phase pictures are transparent, the transparent pictures are copied to the vehicle picture too. The transparency of the vehicle can change as the moving parts (spokes, rods) let you see through to the background in different places.

So that the vehicle's motion appears to change at realistic times, the phase pictures replace each other in sequence when the vehicle has traveled a specific length in pixels. This length can be input in pixels with the parameter:

There is another way to input the phase speed:

where the number is the diameter of the wheel. In the default setting all vehicles are given a geometrically correct value, but with the command $PHSTEP one can set the phase speed to one's own taste. The number given in the $PHSTEP command multiplied with the wheel diameter determines how many pixels must be traversed for a complete rotation of the wheel, thereby timing the phases to occur at points which reflect realistic motion. In the Traffic Screensaver it is possible to use more (or less) than four phase pictures. Without the $PHSTEP command, the basic setting is 3.14 (pi). If a faster phase transition is desired a smaller number can be used. (The +/<Diameter> parameter is equivalent with a parameter in the +.<PixelStep> form having the value:

If the phase pictures do not show a full wheel rotation, rather, only part of it (for example with bogies, showing the movement of the wheels), the +/<Diameter> form is not the best solution.

Modifiers

The modifiers apply to the entire phase picture. One can apply as many to the phase picture as one desires, but the base picture can only expand on it's vertical axis. (It can become higher say, for example, with a load). The coordinates are measured from the bottom left, and begin at 0. The coordinates and sizes are integer numbers in pixels.

Customization commands:

[<Condition> <CommandCode> : <Parameter> , <Parameter> ... ]

One condition can be the direction of travel: the < sign means left and the > sign means right. You can define other conditions by appending an exclamation mark ! to a name: [<Criteria> ! <CommandCode>: <Parameter> ... ]. This criteria is fulfilled if the expanded vehicle macro contains an [!<Criteria>] element.

Some criteria names are used by the standard Stock List. At the moment no function fixes these names explicitly, but some editing commands in the Macro Editor/Graphic Testpad window menus rely on these names already:

It is suggested you use this convention as perhaps in a future version of Traffic some commands or modifiers will rely on this convention (it is expected that the L and C criteria will be implemented in the near future).

If the vehicle is composed of phase pictures, you can use the modification commands after each individual phase picture, or after the full picture. Being used after the full picture means that the modification command(s) appear after the +.<Integer> or +/<Integer> parameter, or, if the distance at which the picture changes is not given, after a single + character.

Do not forget: if you append a [...] modifier directly after the last phase picture's name, without having a step distance or a single plus sign in-between, the modifier acts only on the last phase picture, not on the whole animated picture!

Modification Commands beginning with the # sign set default values for certain properties and apply to the entire train. These values can be superseded by parameters in the lines defining the Movements in the Timetable file. If in a single train there are several vehicles which have the same modification command, only the last (in sequence, not in direction of travel) command will have precedence. Such modification commands are generally only applied to locomotives and railcars in the Stock List. They define the default behavior of the vehicle.

[#A:<Acceleration>]

Value of the acceleration rate.

[#B:<Deceleration>]

Value of the deceleration rate.

[#V:<Speed>]

Value of the rate of speed.

[#W:<Row>]

Value of the right of way. The vehicle will use the right of way which is determined in the Stock List file. This command is only here to ensure compatibility with previous versions. If this command is used in the Timetable file, it has priority over the code in the Stock List file.

[A:<AnimationRules>, <PictureName>, <TargetX>, <TargetY>, <FrameWidth>, <FrameHeight>, <SourceX>, <SourceY>, <Time>, <NumberOfFrames>, <StepX>, <StepY>] (Animation)
[A:<AnimationRules>, <PictureName>, <TargetX>, <TargetY>]

Definition of an animation. Animations are some of the more complex behaviors and have numerous commands. The following section should therefore be read with care.

An animation is a set of frames contained in a single picture (a picture in the Stock List or a picture file), and the rules determining in which sequence and timing these frames are copied to a place on a vehicle or on a foreground / background element. The <AnimationRules> parameter is described above, in the syntax elements chapter.

The parts of the pictures used as single frames for the animation are usually drawn adjoining each other, therefore, the animation picture has the width of <FrameWidth> * <NumberOfFrames>. In this case both the <SourceX> and <SourceY> parameter are 0 - as the first frame is on the left side of the combined picture, <StepX> is the same as <FrameWidth> and <StepY> is null, as the frames adjoin each other. You have other possibilities too: you can draw the frames belonging to the phases beneath each other, or -- what is a more interesting possibly -- you can use the same part of your animation picture for several frames. Imagine a sliding door opening upwards, and the view behind the door homogenous - in this case it is enough to draw the door, and below it view in the opening, behind the door. The first frame is on the top of our animation picture. The next frame is one pixel below: you will see a single row from the inside and the same door raised by one pixel. The next frame shows one more row downwards: it contains two rows of the inner color, and the door is raised by 2 pixels ... and so on. In this case you have the following parameter values:

<SourceX> = 0
<SourceY> = <NumberOfFrames> - 1
<StepX> = 0
<StepY> = -1

This part - the geometrical parameter - describes how to find the frame pictures in the single animation picture. The other part, the <AnimationRules> determines in which sequence the frame pictures are shown.

Let us return to the example animation shown in the beginning of this section. The shorter form [A: ] of the animation command may be used when the additional information is input with the <PictureName> picture. In this case the <PictureName> picture has the following format in its attached macro line:

[ANIM: <AnimationRules>, <FrameWidth>, <FrameHeight>, <SourceX>, <SourceY>, <Time>, <NumberOfFrames>, <StepX>, <StepY>]

- Only the coordinates where the animation's frames are placed on the picture should be given for the base picture when using this statement. All of the other parameters are for the frame pictures.

If the <AnimationRules> is a single name, and not a complex definition, you can write the macro for the frame pictures in a shorter form:

[<EventName>: <FrameWidth>, <FrameHeight>, <SourceX>, <SourceY>, <Time>, <NumberOfFrames>, <StepX>, <StepY>]

<PictureName> A picture with the individual phase pictures composing the animation. (a name which doesn't contain period ".", slash "/" or backslash "\" characters is a picture name in the Stock List, a name containing one of the . / \ characters is a path name of a picture file. If you use a picture file outside the Stock List, you cannot use the short form of the [A: ] command, as only the Stock List file can contain attached macros)

<TargetX>, <TargetY> The placement of the animation in the picture (from left and from the bottom).

<FrameWidth>, <FrameHeight> The measurements of the frames which comprise the animation (in width and height) - the size of the area on the vehicle picture the animation frames cover. The frames should always have the same dimensions regardless if whether the size of the entity in the picture changes. That is, if you have a picture of something, the size of which changes during over course of the animation, the individual frames of the animation must be the same size as the largest frame of the animation, and you should provide the constant parts in the animation picture as well. For example, when animating a pantograph, all of the frames would have to have the same height as the pantograph extended to its highest point and all of the frames would have to have the same width as the pantograph at its widest state (usually down) and any roof details which remain constant must also be included.

<SourceX>, <SourceY> The coordinates of the first frame (from left and from the bottom) inside the <PictureName> picture containing all the frames.

<Time> Time between frames of the animation in 10 ms. intervals.

<NumberOfFrames> Number of frames (phases) in the animation.

<FrameX>, <FrameY> The distance of a frame between each phase of the animation in pixel values (to the right or to the top in positive values, to the left and to the bottom in negative values). These two parameters give you the possibility to reuse parts of a picture for several phases. If you have a sliding door in front of an interior represented only by a solid color, you can draw an animation double the height of the door--the top half showing the interior (a solid dark color)--and on top of that the door frames. The closed state is shown on the top. Each frame is represented by clipping downwards one pixel ( <StepX> = 0, <StepY> = -1 ), so as the animation runs you will see more and more of the interior, and the part of the animation showing the door will appear to be moving upwards because in the clipping area there is less and less of the door's picture.

Animations can be started when a vehicle is at rest or when it passes a predefined point. They can continue to run when a vehicle starts moving.

[DIL:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Inside Left)
[DIR:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Inside Right)
[DID:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Inside Double)
[DOL:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Outside Left)
[DOR:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Outside Right)
[DOD:<Color_or_picture>,<X>,<Y>,<W>,<H>,<Time>,<NumberOfFrames>(Door Outside Double)

[DA:<PictureName>,<Y>,<XList>] (Door Animations)

[E:<#><PictureName>, <TargetX>, <TargetY>, <FrameWidth>, <FrameHeight>, <SourceX>, <SourceY>, <Time>, <NumberOfFrames>, <StepX>, <StepY>] (Electric)
[E:<#><PictureName>, <TargetX>, <TargetY>]

[ED:<#><PictureName>, <X>, <Y> ] (Electric Down)

[EU:<PictureName>, <Y>] (Electric Up)

[EX:<UpX>,<Y>,<W>,<H>,<DownX>] (Electric eXchange)

[EM:<UpX>,<Y>,<W>,<H>,<DownX>] (Electric Mirror)

The modifiers [ED: ], [EU: ], [EX: ], [EM: ], and the usage of the _SAR pictures in a <BasePicture> < <_SAR_Picture> construct are intended only for ease the usage of existing pictures originally drawn for other screensavers. The preferred method for defining pantographs for Traffic is to draw several frame pictures to have a smoothly animated pantograph. The second choice is to draw the locomotive with both pantographs lowered, and to draw the pantographs separately

[L:<Name>] (Label)

[<AnimationRules>: <FrameWidth>, <FrameHeight>, <SourceX>, <SourceY>, <Time>, <NumberOfFrames>, <StepX>, <StepY>]

Defines an animation. This macro is resident in the Stock List as the entry having the phase pictures for the animation. The parameters can also be given with the [A: ... ] command - but when the same animation (for example: doors, pantographs) is used several times it is easier to define the constant parameters only once: with the phase pictures. Using the example of an animation for a door, you should give it the <AnimationName> DOOR, if is it a pantograph, it's animation name is fixed to PAN. The meaning of the parameters is explained in the definition of the [A: ... ] command.

The following pantograph modifiers determine the state of the pantographs the vehicle initially has when it appears on the screen:

[PDO], [PNO], [PD], [PN] - All pantographs down
[PLU], [P1U] - Left pantograph up
[PRU], [P2U] - Right pantograph up
[PMU], [P3U] - Third (usually the inner or inner left) pantograph up
[P4U] - Fourth (inner right) pantograph up
[PDU], [P12U], [PU] - First and second (on a standard locomotive that means all) pantographs up
[PFU] - Forward pantograph up (relative to direction of travel)
[PBU] - Rear pantograph up (relative to direction of travel)
[PFIU] - Forward inner pantograph up (relative to direction of travel - useful for multi-system locomotive)
[PBIU] - Rear inner pantograph up (relative to direction of travel - useful for multi-system locomotive)
[PHU] - First pantograph of the train up relative to direction of travel (useful for multiunit trains)
[PTU] - Last pantograph of the train up relative to direction of travel (useful for multiunit trains)
[PA] - All pantographs up

[CB:<Simple>] (Couple Base)

[CL:<#><PictureName>,<BaseX>,<AddX>,<Y>] (Couple Left)
[CR:<#><PictureName>,<BaseX>,<AddX>,<Y>] (Couple Right)

[N:<#><Type>,<#><PictureName>, <Y>] (Neighbors)

Modification of the end of a vehicle based on its neighbors. With the command [N: ... ] one can close the diaphragms on older passenger stock, connect air hoses or other connections between vehicles, etc. It is a type of relative overlay.

A more comprehensive use of this command is:

[NL:<Type>,<PictureName>,<Y>][NR:<Type>,<#><PictureName>,<Y>][NT:<Type>]

When the neighboring vehicle on the left has a matching <Type>, then the left side of the applicable vehicle is modified with the picture <PictureName> and, conversely, the right side of the vehicle will be modified with a mirrored version of <PictureName>.

When one uses the command like so: [N:<Type>,<PictureName>, <Y>] it has the same meaning as the

[NL:<Type>,<PictureName>,<Y>][NR:<Type>,#<PictureName>,<Y>][NT:<Type>]

command string and means that the original picture recognizes the connection between the two vehicles and the picture referenced in <PictureName> is copied over the original picture when it is coupled to other types of vehicles or is running alone. Any transparent pixels of the overlay picture will be copied to the vehicle pictures: these commands allow existing pixels to be cleared. The following [TN: ... ] [TL: ... ] [TR: ... ] commands make a transparent copy: you can look through the transparent pixels of the overlay picture to the vehicle picture: you cannot clear existing pixels with the [Tx ... ] commands, only add new pixels.

[NL:<#><Type>,<#><PictureName>, <Y>] (Neighbor left)

If the left neighbor vehicle has the type <Type> then the picture <PictureName> is pasted onto the left side of the vehicle.

If there is a # sign placed before the <Type> the action is reversed (the picture is pasted on if the vehicle is not next to a vehicle with the type <Type>.

If there is a # before the <PictureName> picture, then the picture is shown mirrored.

[NR:<#><Type>,<#><PictureName>, <Y>] (Neighbor right)

The same as [NL:...], but applicable to the right side.

[NT:<Type>] (Neighbor type)

Specifies the type of the vehicle for the commands [NL: ... ] and [NR: ... ].

[TN:<#><Type>,<#><PictureName>, <Y>] (Transparent Neighbors)
[TL:<#><Type>,<#><PictureName>, <Y>] (Transparent Neighbor left)
[TR:<#><Type>,<#><PictureName>, <Y>] (Transparent Neighbor right)
[TT:<Type>] (Transparent neighbor Type)

[NC:<Type>,<W>,<H>,<Y>] (Neighbor connection Clear)

[NCL:<Type>,<W>,<H>,<Y>] (Neighbor connection Clear Left)

[NCR:<Type>,<W>,<H>,<Y>] (Neighbor connection Clear Right)

[C:<Color>,<NewColor>, ... ] (Color)

All pixels of the color value specified in <Color> converted to the value specified in <New_Color>.

The color conversion happens in a picture preparation buffer having the same properties as the target screen the screensaver is running in. If this screen has limited color capabilities (runs in 4,8 or 16 bit color depth modes), the colors of a vehicle picture could be a little off. Therefore, it is good practice to define the old color <Color> in its coordinate form by giving a coordinate pair of the pixel in the vehicle picture having the selected color.

You can continue the parameter list by specifying more <Color>,<NewColor> pairs - this form is only a shortcut. All color pairs act, as if they were in separate [C: ] modifiers.

[F:<X>,<Y>,<Color>] (Flood Fill)

Starting from the X,Y coordinates, all identically colored pixels will be changed to the color specified in <Color>

[M:<X>,<Y>,<W>,<H> ... ] (Mirror)

Mirrors the picture (left-right) and then reverse reflects the rectangular area specified by the coordinates <X>,<Y>,<W>,<H>. The simplest form of the command is [M] which does not contain a reverse reflected section. There can be more than one section reflected in reverse in a given image.

[MP:<X>,<Y>,<W>,<H> ... ] (Mirror part)

[MX:<X>,<Y>,<W>,<H>] (Mirror exchange)

[R:<X>,<Y>,<W>,<H> ... ] (Reverse)

This is the same as the [M: ... ] command, but it reverses the sequence the phase pictures are shown (on steam locomotives, for example) - it is needed to let the vehicle run backwards.

[B:<X>,<Y>,<W>,<H>,<Color>] (Block fill)

A rectangular box filled with a color.

[BT:<X>,<Y>,<W>,<H> ... ] (Block Transparent)

A rectangular box filled with the transparent color. With this it is possible to cover up loads or smoke effects.

You can repeat the parameter set <X>,<Y>,<W>,<H> more times - all the rectangular areas will be filled - it is equivalent to many [BT: ] modifiers each having only one parameter set.

[CP:<SourceX>,<SourceY>,<W>,<H>,<TargetX>,<TargetY>] (Copy)

[O:<PictureName>,<X>,<Y>,<D>] (Overlay)

Overlay of <PictureName> picture on a base picture at the coordinates <X>, <Y>. The lower <D> lines of the overlay pictures will be omitted.

Default value for <X> is the middle of the overlay picture to middle of the vehicle, for <Y> is the overlay picture on the top of the original picture, for <D> is 0.

This command can be used to overlay loads, logos, etc. onto vehicles. The parameter <D> is used when, for example, a load is overlaid on a freight wagons whose walls are too high and the load "floats" over the top of the wagon. By entering a pixel value for <D> you can push the load down "behind" the side wall of the wagon to where it appears to be resting on the wagon's natural loading area. The <D> parameter is only useful, if the original picture is not transparent. With a transparent freight car you should use the [OB: ...] command instead, with no <D> parameter.

If the overlay picture has transparent pixels, this transparent pixels will be copied to the vehicle picture too. It is possible therefore to make holes appear in the vehicle - or more realistically, to have a lower side wall, another load etc.

[OT:<PictureName>,<X>,<Y>,<D>] (Overlay transparent)

Similar to the [O: ... ] command, but it uses the transparency of the picture - the transparent pixels won't be copied, the original vehicle picture remains visible through the transparent pixels.

[OB:<PictureName>,<X>,<Y>,<D>] (Overlay behind)

Similar to the [O: ... ] command, but it pastes behind the original picture, not in front of it. (If the original picture is opaque, the same result can be achieved with an [O: ... ] command, specifying a <D> parameter.) This allows you to place loads on wagons which have parts appearing in front of the load, such as with stake wagons.

[P:<PointName>,<X>,<Y>,<D>] (Point)
[PT:<PointName>,<X>,<Y>,<D>] (Point Transparent)
[PB:<PointName>,<X>,<Y>,<D>] (Point Behind)

<PointName> == <Name>

Displays a picture at the coordinates <X>, <Y> from the height <D> in pixel values. After this command a [<Point_Name>:<PictureName>] command can be used and the result is the same as the [O:<PictureName>,<X>,<Y>,<D>] command. The <D> can be omitted, its default value is 0.

Using this command one can make multiple copies with less typing by predefining the point coordinates where overlay pictures (loads, advertising etc.) are generally placed: Usually the [P: ... ] command is stored in the Stock List in the macro belonging to the vehicle or in a macro in the Timetable file, the [<Point_Name>: ... ] command in the moving lines of the Timetable file.

The [P: ... ] command copies the transparent pixels of the overlay picture to the original picture, [PT: ... ] command makes a transparent copy: the transparent pixels won't be copied, you can look through to the original picture, and the [PB: ... ] command copies behind the original picture.

[D:<OverlayName>,<PictureName>,<X>,<Y>,<D>] (Define)
[DT:<OverlayName>,<PictureName>,<X>,<Y>,<D>] (Define transparent)
[dB:<OverlayName>,<PictureName>,<X>,<Y>,<D>] (Define behind)

Displays a picture specified in <PictureName> beginning with the coordinates <X>, <Y> of the vehicle, starting from the height <D> in pixels of the new picture (omitting the lower <D> rows of the picture). If the new picture has transparent pixels, the [D: ] command copies the transparency to the original vehicle too - the vehicle picture can have holes in it, parts of it can disappear - being overwritten with transparent pixels. The [DT: ] command makes a transparent copy: you see through the transparent pixels of the new pictures to the original vehicle picture (or to the background picture or background color). The [dB: ] command pastes an image behind the vehicle picture. (If the original picture is opaque, the result can be achieved with the [D: ] command and a <D> parameter too)

Default value for the <X> position is the middle of the new picture to the middle of the vehicle.

Default for the <Y> is the bottom of the new picture on the top of the vehicle. The top of the vehicle will be adjusted after this copy, including the copied picture too.

The <D> parameter can be omitted. It's default value is 0.

The copy only takes place when the [<OverlayName>] command is invoked. Thereby one can make a copy with the shorter name.
This command is superfluous as you can achieve the same effect using the [O: ] commands together with the named conditions since implemented, but it is preserved for compatibility.

[T:<#><TextToWrite>,<X>,<Y>,<PictureName>,<NewColor>,<Border>]
[ABC:
<Characters>,<Delim>,<CharWidth>,
... ]

[NAME:<PictureName>] (Name)

Input of a picture name. This command is used only by the program itself - helping to determine to appropriate description block for picture, which is generated by a macro in the Stock List.

Syntax Elements

In the syntax description below, the text between the < and > signs show the parameters of the modifiers and the Timetable commands. These parameters can be as follows:

<Filename>

Filename with the complete path ( C:\TRAFFIC\PICTURE.GIF ). Instead of the \ character, the / can also be used.

<Name>

<Name> == <Letter> || <Name> <Letter> || <Name> <Digit> || <Name> _
<Letter> == A
|| B || C || D || E || F || G || H || I || J || K || L || M ||
            N || O || P || Q || R || S || T || U || V || W || X || Y || Z

Text for the names of macros and other objects. The name must begin with one of the 26 English letters and can only contain letters, numbers and the _ (underscore) character. The name field is not case sensitive.

In several cases names containing international characters or special characters can function, but there is no warranty, that they will be functional in the same context in a future version - so do not use other characters in names, as described above. You should specially avoid the usage of operators, as minus - and the point, or period, character.

<PictureName>

<#>

<Simple>

<Integer>

<Real>

<Real> == <SimpleReal> || <RealInterval> || <RealSelection>
<RealInterval> == <SimpleReal> - <SimpleReal>
<RealSelection> == <RealSelItem>
|| <RealSelection> | <RealSelItem>
<RealSelItem> == <SimpleReal>
|| <Simple> : <SimpleReal>
<SimpleReal> == <Simple>
|| <Simple>.<Simple> || .<Simple>

Complete number in decimals. For fractional numbers you should use decimal point (not comma), regardless of what the international settings of your computer are.

You can use an interval or a random selection in place of a real number. The same rules apply to the interval and selection as for the integer numbers.

<Boolean>

<Boolean> == <true> || <false>
<true> == T
|| Y || J || D || I || 1
<false> == F
|| N || H || 0

Characters which denote "true" or "false." The following characters are accepted as meaning "true": T Y J D I 1 . The following characters are accepted as meaning "false": F N H 0 . Only the first character of a word is analyzed: you can ease the readability by writing a full word on this place.

<Direction>

The direction of trains. Possible values:
left: < L B
right: > R J
as the previous: + F A
opposite of the previous: - C T X V

<Speed>

<Speed> == <Real>

Fractional number with a decimal point (not comma) which determines the speed of the vehicle. Before a stop it denotes the speed the train starts at. After a stop it denotes the top speed to be achieved when starting again.

<Acceleration>

<Acceleration> == <Real>

Fractional number with a decimal point (not comma) which gives the value of the acceleration of a vehicle after it begins moving.

<Deceleration>

<Deceleration> == <Real>

Fractional number with a decimal point (not comma) which gives the value of the deceleration of a vehicle before it comes to a stop. Negative values cannot be inserted here..

<Row>

The codes for the Right of Way - track, street, catenary, etc. The capital and lower case letters differentiate the thinner and thicker pictures. These codes are generally composed of 2 characters, one determining the type of initial right of way and the subsequent ones modifying the first.

Codes for the first character:

a b u
A B U
r
R
0
1
2
3
4
5
q
Q
p
P
g
G
j
J
k
K
h H
X nothing, the place is left blank

    Codes for the second character:
nothing - no catenary
Catenary (simple line) at 58 pixel height: e E v V
Subway or Interurban with Third Rail: m M s S
Catenary at less than 58 pixel height: l L + a number. The number gives the height of the catenary wire in pixels. For example L52 = catenary at 52 pixels height.
Catenary for the Budapest Millennium Subway at 31 pixel height:: f F 

    Some short cuts:
Streetcar: one pixel thick rail + catenary: t
Streetcar: two pixel thick rail + catenary: T
Rail, 1 pixel thick roadbed + catenary: e v
Rail, 2 pixel thick roadbed + catenary: E V
Rail, 1 pixel thick roadbed + FAV catenary: f
Rail, 2 pixel thick roadbed + FAV catenary: F
Rail, 1 pixel thick roadbed + third rail: m s
Rail, 2 pixel thick roadbed + third rail:: M S

The X code can be used to invalidate the default code (determined by the vehicle's Stock List entries and modified by the $WAY command) - for example, if you want to change the picture of the track bed and rail from the predefined rail picture to a custom picture specified in the FG= or BG= parameters.

<X>, <Y>

<W>, <H>

<AnimationRules>

<AnimationRules> == <AnimationRule> || ( <AnimRuleList> )
<AnimRuleList> == <AnimationRule>
|| <AnimRuleList> ; <AnimationRule>
<AnimationRule> == <DefaultMark> <Action> = <Sequence>
|| <DefaultMark> <Action>
<DefaultMark> ==
|| * || < || >
<Action> == <Name>
<Sequence> == <SequenceName>
|| <AnimProg>
<SequenceName> == F
|| FW || FORWARD ||
                  B || BW || BACKWARD ||
                  C || CY || CYCLE ||
                  E || EX || END || EXIT

This parameter belongs to the animation definition. An animation is a set of frame pictures having the same size, and the parameters by which the frames are copied to the same place - to a (perhaps moving) vehicle, or to the foreground or background. The frames are usually contained in a single picture of the Stock List, and the parameters of the [A: ] command define how the frames are contained in it.

More than one rule can belong to a frame set. An animation rule consists of a name and the "program," i.e. the sequence in which the frames are shown and the possible wait times between the frames. The <AnimationRules> string is a list of the individual rules separated by semicolons.

One of the rules can be the default - that means, it is already active when the train starts. Bear in mind that the vehicles are treated as coming from very far away. Therefore, if an animation rule is selected as the default that runs once and ends, in most cases by the time the vehicle actually appears on the screen the animation will have completed and only the final position will be shown. If the rule describes an endless loop, the animation will be running when the vehicle enters the screen. Only one rule can be the default - if you mark multiple rules to be default, the Traffic program selects one of them - there is no guarantee, which (at the moment the first one having a default mark, but do not depend on this, it may be changed in future versions).

The default rule is marked by placing an asterisk before the name of the action; in this case this rule is the default independent of the direction of the vehicle. < denotes a rule should be active, when the vehicle enters from the right and travels to the left. On the contrary, if > is assigned to a rule, this rule will be active if the vehicle enters the screen from the left side, moving right.

The <Action> serves as a command name for calling the animations. You can use it in the <WaitTime> construct of the T=, T1=, T2=, T3=, TB=, TE= parameters which define the waiting times and animation actions, and in the WP= parameters defining places along the track and actions when a train passes them.

The <Sequence> is a compact name for the simple frame sequence or a program which defines the steps in detail. The acceptable codes for the simple sequences are:

nothing Each time the animation is started it is shown from the first image to the last.
F , FW or FORWARD The animation runs toward to the last image. It is started from the actual image - if the last image is already shown, nothing happens.
B , BW or BACKWARD The animation runs toward to the first image. It is started from the actual image - if the first image is already shown, nothing happens.
C , CY or CYCLE The animation runs in endless loop from the first to the last image, and repeats indefinitely.
E , EX , END or EXIT Not really an animation: it is used to stop animations running in loop mode. It stops it after the animation reaches the last image.
<AnimProg> The sequence of the frames is defined explicitly, giving the numbers of the frames which should appear.

The syntax for a detailed program:

<AnimProg> == <Step> || <AnimProg> , <Step>
<Step> == <Simple>
|| <Interval> || <Repetition> || ( <AnimProg> ) || W <Simple>
<Interval> == <Simple> - <Simple>
<Repetition> == * <AnimProg>
|| <Simple> * <AnimProg>

A single step is the number of the frame which should be shown. The frames are numbered from 0.

An interval (two integers connected by a minus sign) means show all the frames between the first and second integers in ascending order.

A number preceded by W is not a frame number, but a time (in 10 ms units) that the screensaver should wait before showing the next frame (or starting the next wait time). All of the steps which do not have a W<Integer> element between them will wait according to the <Time> parameter in the comma separated list of the [A: ] command, or the same parameter in the picture's attached macro containing the frames.

The asterisk ( * ) denotes repetition. If there is an integer before the asterisk, is denotes the number of cycles. If the asterisk is missing, it is an endless loop. The frame numbers and intervals should be enclosed in parentheses to form the cycle body (although if only one cycle should be played or run it is acceptable to omit the parentheses).

All of the integers (the image indexes and the cycle counts) are real, whole numbers; they cannot be random selections or fractions.

There are two special animation names having predefined rules - they have the global names DOOR or PAN, and they have some intrinsic predefined rules. Running the DOOR animation is equivalent to making the following declaration:

(DOOR; OPEN=FW; CLOSE=BW)

It is a door: you are able to open and close it. So essentially the DOOR animation is a conditional animation. When you run it, it checks its current state and runs based on that condition: (closes if doors are open, opens if doors are closed).

The PAN animation behaves in a more complex manner. Traffic accepts a set of special pantograph actions which control the state of the pantographs. The specialty: all other animation actions control their animated elements individually. The following pantograph actions control all the pantographs of a single vehicle (up to 4 pantographs) together. These actions look very similar to the modifiers (enclosed in brackets) determining the initial state of the pantographs. The main difference: this actions control only the pantograph states written, they leave the other pantographs unchanged - in contrary to the modifiers, where all modifiers control all the pantographs. If more pantograph state modifiers belong to a vehicle, a priority system decides which is valid: the modifiers attached to the individual vehicle have precedence over the overall modifier for the whole train. With multiple modifiers the last (the one to the right) takes precedence. If multiple pantograph actions act on a vehicle each action controls a subset of the pantographs. However, each action will be executed one after another in turn.

The pantograph actions are as follows:

PLU , P1U Left pantograph up
PRU , P2U Right pantograph up
PMU , P3U Third (usually the inner or inner left) pantograph up
P4U Fourth (inner right) pantograph up
PDU , P12U First and second (on a standard locomotive that means all) pantographs up
PFU Forward pantograph up (relative to direction of travel)
PBU Rear pantograph up (relative to direction of travel)
PFIU Forward inner pantograph up (relative to direction of travel - useful for multi-system locomotives)
PBIU Rear inner pantograph up (relative to direction of travel - useful for multi-system locomotives)
PHU First pantograph of the train up relative to direction of travel (useful for multiunit trains)
PTU Last pantograph of the train up relative to direction of travel (useful for multiunit trains)
PDO , PD , PNO , PN All pantographs down
PLD , P1D Left pantograph down
PRD , P2D Right pantograph down
PMD , P3D Third (usually the inner or inner left) pantograph down
P4D Fourth (inner right) pantograph down
PDD , P12D First and second (on a standard locomotive that means all) pantographs down
PFD Forward pantograph down (relative to direction of travel)
PBD Rear pantograph down (relative to direction of travel)
PFID Forward inner pantograph down (relative to direction of travel - useful for multi-system locomotives)
PBID Rear inner pantograph down (relative to direction of travel - useful for multi-system locomotives)
PHD First pantograph of the train down relative to direction of travel (useful for multiunit trains)
PTD Last pantograph of the train down relative to direction of travel (useful for multiunit trains)

The pantograph actions work correctly only if the pantograph definitions (in the Stock List macros or in the Timetable file, in the bracketed modifiers) are made in the correct sequence: left, right, mid or left mid, right mid.

The pantograph actions cannot act on foreground or background pictures. (You can place an electric locomotive in the background, and you can even move its pantographs too, but these shortcut commands are not the ones used to control them.)

<WaitTime>

<WaitTime> == <WaitElement> || <WaitTime> , <WaitElement>
<WaitElement> == <SecToWait>
|| <AnimCmd> || W
<SecToWait> == <Integer>
<AnimCmd> == <WAction>
|| <TrainSel>.<WAction> || <FgBgSel>.<AAction>
<WAction> == <Action>
|| <WagonSel>.<AAction>
<AAction> == <Action>
|| <AnimSeq>.<Action>
<TrainSel> == C
|| C1 || C2 || C3
<FgBgSel> == FG
|| BG
<WagonSel> == <Tag>
|| <WagonSeq> || @<WagonSeq>
<WagonSeq> == <Simple>
|| -<Simple> || L || LAST
<AnimSeq> == <Simple>
<Tag> == <Name>
<Action> == <Name>

<WaitTime> - in its simplest form - is a number which determines the amount of time between events finishing a phase of a Movement (a train stops on the required position or leaves the screen) and starting the next phase of the Movement (a train start or enters the screen). You cannot input wait times longer than 60 seconds.

Several wait times can be established one after another mixed with animation starts. The animation are defined with the [A:] command, or some other animation definition commands (see above). The wait times and the animation starts are to be separated with a comma. Starting an animation does not automatically cause a wait time to occur. Therefore, more animations can be started in parallel, or an animation can still be running when the train begins to move again. The special "animation" command W (or WAIT) creates a wait until all animations belonging to the vehicles have finished running (but this command does not wait for animations attached to background or foreground picture elements). For example, in T=1,PD,5,PBU,W; the electric locomotive doesn't start moving until the rear pantograph has been raised. For information on special pantograph animation names like PBU see below.

An animation can be called by the name of an action defined in the animation ( [A=<AnimationRules>,<Picture>, ... ] see above). When this happens the animation runs according to the animation definition - if the <AnimationRules> parameter in the [A: ... ] command is a single name, then the animation will run forwards. Some special animations which run backwards, such as doors or pantographs, have predefined specific names:

OPEN: runs the DOOR animation forward
CLOSE : runs the DOOR animation backward
DOOR : runs the DOOR animation in whatever direction is the opposite of its current state (when doors are open it closes them and vice versa).

If one only specifies the animation name then the command is valid for all animations on the entire train and the background and foreground picture(s). For example, a CLOSE command used with a railcar closes all of the railcar's doors - and perhaps the door of the station building in the background too. But one can also specify that the animation be run on just one part of a train, a single wagon, just one part of a wagon or only on the foreground or background pictures. The specific part, or wagon number, is separated and denoted with a period:

C.OPEN - All doors in the train are opened
BG.OPEN - All doors in the background picture are opened
FG.OPEN - All doors in the foreground picture are opened

Multiple train parts are created when the Movement commands CUT, UNIT, GET, PUT, CHANGE are used. The names of the train or train part(s) are the same as the vehicle set defined in the Movement commands.

M=SIMPLE; C=<Train>; - the only train is C,
M=CUT; C1=<Train>; C2=<Train>; - there are C1 and C2 parts which can be referenced individually.

C1.OPEN - All doors in train C1 are opened

You can reference the vehicles in a train individually.

Do not forget: in some Movements two trains are coupled together in several phases of the Movement. The animation commands do not pay attention to this: you should address the two parts individually. If you want to address all of the animations (all trains the Movement contains, and the foreground and background too), then you can omit

The animations on the foreground and background picture are treated as if either the foreground or the background picture was a train having a single "wagon" in it - so you should not (and cannot) select the "wagon." The number after the FG or BG keyword is the sequence number of the animation.

The similar animations in a single wagon can be distinguished, and controlled individually too:

C1.1.3.OPEN - The third door of the first wagon in train C1 is opened.

Individual vehicles can be tagged with the command [L:...] (see above) and referred to by the tag name causing the animation only to operate on the tagged vehicle(s). Each vehicle can have multiple tag names, many vehicles can have the same tag names, so you can build groups by tagging the vehicles, that a single command in the form <Tag>.<Action> can start the same action on a predefined set of vehicles.

With animations on the foreground and background pictures the individual tagging becomes more complicated. As the foreground and background pictures can repeat -- such as when they fill the space between two coordinates with a spacing larger than the size of the picture -- the animations belonging to the picture parts are repeated as well. The sequence numbers can therefore be different than the definition sequence of the animations. If you want to individually control single animation elements in the FgBg, you should use different animation names than for vehicle pictures. You should remember: the number of repetitions of a background element can depend on the screen width, so it can vary between installations. If you intend to write a Timetable file not only for a single computer, but for general use, you should allow background animations repeat with caution.

Pantographs of a vehicle can be controlled together with a variety of special commands, listed in a table at the <AnimationRules> syntax element.

<Place>

Stopping point of a train or placement of a background picture. Syntax can be <number>+<number> or <number>-<number>. The first or the second number in this syntax can be omitted. The first number is a whole number and represents the percentage of the screen width from left to right. The second number is a whole number which determines the distance in pixels - (left) or + (right) from the position determined by the first number. Customization codes include:

< Place at the left end of the vehicle (or background picture)
* Place at the middle of the vehicle (or background picture)
> Place at the right end of the vehicle (or background picture)
@+ Way the front of the vehicle travels through the screen. If the vehicle comes from right to left, both the percentage and pixel distances are measured from right to left.
@- Way the back of the vehicle travels through the screen. If the vehicle comes from right to left, both the percentage and pixel distances are measured from right to left.
@* Way the middle of the vehicle travels through the screen. If the vehicle comes from right to left, both the percentage and pixel distances are measured from right to left.
nothing Place at the front of the vehicle (or middle of background picture)

The definition of left, middle or right is relative to what the program generates. As an example, for the Movements CUT or CHANGE the middle point is between the two units (train parts). In the description of the Movements below, if the description of the P= parameter contains only one unit (train part), the center alignment means the middle point of this unit. If there are two units mentioned, left means the left side of the unit placed at left (which unit is on the left can depend on the direction of travel), right means the right side of the unit placed at right, and center means the contact point of the two units. If one of the two train parts is changed during the Movement, the dimensions of the parts first appearing on the screen determine the middle point.

<Point>

<PointList>

<FgBg>

<FgBg> == <FgBgElem> || ( <FgBgList> )
<FgBgList> == <FgBgElem>
|| <FgBgList> ; <FgBgElem> <
FgBgElem> == <PicList> : <FgBgPlace>
|| <PicList> : <FgBgPlace> , <Bottom>
<PicList> == <PicElem>
|| <PicList> , <PicElem>
<PicElem> == <PictureName>
|| <PicElem> <Modifier>
<FgBgPlace> == <Place>
|| <Place> .. <Place>
<Bottom> == <Integer>

Complex parameters which determine the foreground or background pictures. The pictures should be separated with a semicolon:

<PicList>:<FgBgPlace>,<Bottom>;

These parameters should be enclosed in parentheses if there are more than one (if there is a semicolon in the parameter string).

The <PicList> part is the names of the pictures separated from each other by a comma. The pictures are displayed from left to right abutting each other. Each picture name in the list can have modification commands in brackets - just as the vehicle pictures can. The modification commands apply only to the one picture preceding them.

The <FgBgPlace> can be a simple <Place> construct (see above) or it can define a range by using the syntax <Place>..<Place> (two place expressions separated by two periods). This causes the picture to be displayed exactly between these two coordinates. If the picture is longer than the space dictated by the coordinates, the edges are cut off. If the picture is shorter, it is repeated between the coordinates. The symbols <, >, and * before the number determine what reference point of picture (left, right, center respectively) is used to fit the picture into the space. In this way one can make the backgrounds independent from the width of the screen size.

Some examples:

FG=SAVTE_FG:..,-42;

The high path of the SAVTE trams will be repeated on the screen filling the whole screen width due to the two points being input without any numbers: the left side of the screen (0+0) is the default value for the left point, the right side of the screen (100+0) is the default for the right point. The foreground picture is drawn by 42 pixels below the pathway the trams are running - as it is a way on a bridge. (If you use this example in the Timetable file, you should not forget to extend the place below and above the pathway by the BELOW= and ABOVE= parameters of the $SECTION, $GROUP or $LINE command your Movement contained in. You should use the W=X; parameter so Traffic does not draw the normal right of way picture - two simple lines,one for the rail built into the street and an other for the catenary- as this bridge is used normally by the SAVTE trams.)

FG=SIG_SBB_4:<30+4,-4;BG=SIG_SBB_4[M]:>30-4,-4;

Two signals of the same type are positioned at almost the same position - at 30% of the screen width. The first one, valid for trains traveling from right to left, is placed 4 pixels to the right of the 30% point (the left side of the signal is aligned there). The second one is mirrored ( [M] ), as it applies to the trains coming from left to right. It's right side is placed 4 pixels to the left of the 30% point, so the distance between the two signals is 8 pixels. Both signals are 4 pixel below the rail level. As the signals are on the left side of the rail, the first one is a foreground picture, visible in front of the trains, the second one is a background picture, visible behind the trains.

FG=PLF1EL,3*PLF1O,PLF1L,8*PLF1O,PLF1L,5*PLF1O,20*PLF11, \
3*(PLF1C,5*PLF11,PLF1V,5*PLF11,PLF1T,5*PLF11,PLF1V,5*PLF11), \
PLF1C,20*PLF11,5*PLF1O,PLF1L,8*PLF1O,PLF1L,3*PLF1O,PLF1E:*50,-3;

Let's analyze this platform! The PLF.. pictures are platform elements. The core part is in the middle line: a sequence of single pictures and pictures repeated 5 times near each other consist of a platform part between two pillars. This group is repeated 3 times near each other to build the covered part of the platform. The picture parts in the first and third line build the end of the roof and the uncovered part of the platform. The whole platform, as an unit, will be placed in the middle of the screen: *50 means 50% of the screen width, no pixel offset. The bottom of the platform picture if 3 pixels below the rail level.

<Language>

The language code. The language codes and their values are determined in the first lines of the Stock List files (*.stk). The codes defined at the moment:

E English
G     German
H Hungarian

If you want to translate the program texts into a new language, please contact the program author to get a new language code, and to coordinate such efforts.

<Text>

Text shown by the program. The text may not contain commas as these determine the end of the text string. Parentheses may only be used in pairs. You can enclose the text in between   "   characters - in this case they can contain each visible character. The " should be stored doubled, as "" .

<Color>

<Color> == <HexColor> || <CoordColor> || <DecimalColor>
<HexColor> == #<Hex><Hex><Hex><Hex><Hex><Hex>
<CoordColor> == ( <X>,<Y> )
<DecimalColor> == ( <Integer>,<Integer>,<Integer> )

The color must be input using the hexadecimal form as is commonly used in html coding: The color value always starts with the # sign followed by three pair of hexadecimal values representing red, green and blue respectively (for example, #000000 black, #FFFFFF white, #FF0000 red, #008000 dark green, etc.)

You can specify the color of a single pixel in the vehicle picture by enclosing the coordinates of that pixel in the picture in parenthesis, for example: (6, 10) . The coordinates are measured from the bottom left corner and begin at 0.

The third possibility is to define the R,G and B channel intensities by 3 decimal numbers from 0 to 255, enclosed in parenthesis: For example (255, 0, 0) means red. This third possibility is useful in defining the individual color intensities in random expressions, say, to generate random color variations. For example, the color (0, 128-192, 0) means a random green shade (as the red and blue intensities are set to zero).

<NewColor>

There are two possibilities: One is as specified above in the <Color> command - you get a solid color. The other is in the form <Color>/<Color> which fills the area with the two colors in a checkerboard pattern. For example, some 16 color versions of freight cars have a combination of dark red and black: #800000/#000000

<Train>

Pictures which together make up the train.

<TrainList>


"Traffic" Screensaver Homepage