23. Appendices
23.1. Units of Measure
Open Rails supports the same default units of measure as MSTS which are mostly, but not exclusively, metric.
When creating models just for Open Rails, we recommend you do not use defaults but specify units for all values that represent physical quantities.
As shown below, Open Rails provides a wider choice of units than MSTS.
Measure |
Default unit |
Applies to |
OR accepts |
MSTS accepts |
Comment |
---|---|---|---|---|---|
Mass |
kg |
kg |
kg |
||
t |
t |
metric tonne (1000 kg) |
|||
lb |
lb |
||||
t-uk |
Imperial ton (2240 lb) |
||||
t-us |
US ton (2000 lb) |
||||
Distance |
mm |
||||
cm |
cm |
||||
m |
m |
m |
|||
km |
|||||
in |
in |
||||
in/2 |
in/2 |
half-inch – historic unit for tyre diameters |
|||
ft |
|||||
mile |
|||||
Area |
m^2 |
||||
*(m^2) |
*(m^2) |
||||
ft^2 |
ft^2 |
||||
*(ft^2) |
*(ft^2) |
||||
Volume |
l |
diesel fuel |
l |
liter |
|
m^3 |
|||||
*(m^3) |
|||||
in^3 |
|||||
*(in^3) |
|||||
ft^3 |
other |
*(ft^3) |
*(ft^3) |
e.g. BoilerVolume |
|
g-uk |
Imperial gallons |
||||
g-us |
US gallons |
||||
gal |
US gallons |
||||
gals |
gals |
US gallons |
|||
Time |
s |
s |
|||
m |
|||||
h |
|||||
Current |
amp |
amp |
|||
A |
|||||
Voltage |
volt |
V |
|||
kV |
|||||
Mass Flow |
g/h |
||||
kg/h |
|||||
lb/h |
lb/h |
lb/h |
|||
Volumetric Flow |
m^3/s |
air flow meters |
m^3/s |
||
ft^3/min |
|||||
L/min |
|||||
L/s |
|||||
Speed |
m/s |
other |
m/s |
m/s |
meter per second |
cm/s |
centimeters per second |
||||
mm/s |
millimeters per second |
||||
km/h |
|||||
kph |
kph |
kilometer per hour |
|||
kmh |
kmh, kmph |
misspelling accepted by MSTS |
|||
mph |
dynamic brake |
mph |
mph |
miles per hour, legacy dynamic brake parameters use mph default |
|
ft/s |
feet per second |
||||
in/s |
inches per second |
||||
Frequency |
Hz |
Hz |
Hertz |
||
rps |
revolutions per second |
||||
rpm |
|||||
Force |
N |
N |
N |
Newton |
|
kN |
kN |
||||
lbf |
Pounds force |
||||
lb |
|||||
Power |
W |
W |
Watt |
||
kW |
|||||
hp |
horsepower |
||||
Stiffness |
N/m |
N/m |
N/m |
Newton per meter |
|
Resistance |
N/m/s |
N/m/s |
N/m/s |
Newton per meter per second |
|
Ns/m |
Newton seconds per meter |
||||
Angular Resistance |
N/rad/s |
N/rad/s |
|||
Pressure |
psi |
air pressure |
psi |
pounds per square inch |
|
bar |
atmospheres |
||||
kPa |
KiloPascal |
||||
inHg |
vacuum |
inHg |
inches of mercury |
||
Pressure Rate of Change |
psi/s |
psi/s |
|||
psi/min |
|||||
bar/s |
|||||
bar/min |
|||||
kpa/s |
|||||
inHg/s |
|||||
Energy Density |
kJ/kg |
kJ/kg |
kiloJoule per kilogram |
||
J/g |
|||||
btu/lb |
Board of Trade Units per pound |
||||
Temperature Difference |
degC |
degC |
|||
degF |
|||||
Angle |
radians |
– |
|||
deg |
|||||
Angular Speed |
rad/s |
– |
rad/s |
||
Other |
– |
lb/hp/h |
e.g. CoalBurnage |
23.2. Folders used by Open Rails
The following folders are also written to by Open Rails.
(In this table, we assume a user called Joe.)
Purpose |
Folder (all beginning C:\Users\Joe\) + Sample File |
---|---|
Logs |
Desktop\OpenRailsLog.txt |
Data dumps |
Desktop\OpenRailsDump.csv |
Screenshots |
Pictures\Open Rails\Open Rails 2021-09-21 07-26-58.png |
Saves |
AppData\Roaming\Open Rails\shunt_1 2021-07-18 19.46.35.save |
Save images |
AppData\Roaming\Open Rails\shunt_1 2021-07-18 19.46.35.png |
Replays |
AppData\Roaming\Open Rails\shunt_1 2021-07-18 19.46.35.replay |
Evaluations |
AppData\Roaming\Open Rails\shunt_1 2021-07-18 19.46.35.dbfeval |
Loading progress bar |
AppData\Roaming\Open Rails\Cache\Load\3cd9… …0ce2.cache-or |
Timetable path files |
AppData\Roaming\Open Rails\Cache\Path\4ae2… …4132.cache-or |
23.3. Signal Functions
This is an overview of the functions available in OR for use in signal scripts, known as SIGSCRIPT functions.
23.3.1. Original MSTS Functions
The following are basic MSTS functions:
23.3.2. Extended MSTS Functions
The following are extensions of basic MSTS functions.
23.3.3. SIGNAL IDENT Functions
When a function is called which requires information from a next signal, a search is performed along the train’s route to locate the required signal. If multiple information is required from that signal, and therefore multiple functions are called requiring that next signal, such a search is performed for each function call.
This process can be made much more efficient by using the signal ident of the required signal. Each signal in a route has a unique ident. A set of functions is available to obtain the signal ident of the required signal. Also available are functions which are equivalent to normal signal functions, but use the signal ident and do not perform a search for the required signal. Obviously, using these functions it must be checked that the retrieved signal ident is valid (i.e. a valid signal is found), and the integrity of the variable holding this ident must be ensured (the value must never be altered).
The following functions are available to obtain the required signal ident. The functions return the signal ident for the signal as found. If no valid signal is found, the value of -1 is returned.
The following functions are equivalent to basic functions but use Signal Ident to identify the required signal.
Note there are other functions which also use the signal ident as detailed below.
23.3.4. Signal SubObject functions
In the original MSTS signal definition, a number of specific Signal SubObjects could be used as flags (USER_1 … USER_4). Other items (NUMBER_PLATE and GRADIENT) could also be used as flag but were linked to physical items on the signal. The number of flags available in this way was very restricted. In OR, an additional functions has been created which can check for any Signal SubObject if this SubObject is included for this particular signal or not. This function can be used on any type of Signal SubObject. By setting SubObjects of type ‘DECOR’, additional flags can be defined for any type of signal. SubObjects defined in this manner need not be physically defined in the shape file. The information is available at signal level, so all heads on a signal can use this information. The function uses the SubObject number to identify the required SubObject, the name of the SubObject is irrelevant. The maximum of total SubObjects for any shape is 32 (no. 0 … 31), this includes the actual signal heads.
23.3.5. Approach Control Functions
Approach Control is a method used in some signalling systems which holds a signal at danger until the approaching train is at a specific distance from the signal, or has reduced its speed to below a certain limit. This functionality is used in situations where a significant reduction in speed is required for the approaching train, and keeping the signal at danger ensures the train has indeed reduced its speed to near or below the required limit.
The following set of Approach Control Functions is available in OR.
The required distance and speed can be set as constants (dimensions are m and m/s, these dimensions are fixed and do not depend on any route setting).
It is also possible to define the required distance or speed in the signal type definition in sigcfg.dat. The values defined in this way can be retrieved using the pre-defined variables Approach_Control_Req_Position and Approach_Control_Req_Speed.
23.3.6. CallOn Functions
CallOn functions allow trains to proceed unto a track section already occupied by another train. CallOn functions should not be confused with ‘permissive’ signals as often used in North American signal systems.
A ‘permissive’ signal will always allow a train to proceed on occupied track, following a previous train. Such signals are generally only used in situations where a signal covers a ‘free line’ section only, i.e. a section of track without switches or crossings etc.
The CallOn facility, on the other hand, will only allow the train to proceed in certain specific situations and is primarily used in station and yard areas.
The CallOn functions are specifically intended for use is timetable mode, and are linked directly to a number of timetable commands. Trains will be allowed to proceed based on these commands.
23.3.6.1. CallOn functions in timetable mode
The following conditions will allow a train to proceed.
The route beyond the signal leads into a platform, and the $callon parameter is set for the related station stop.
The train has an $attach, $pickup or $transfer command set for a station stop or in the #dispose field, and the train in the section beyond the signal is static or is the train as referenced in the command (as applicable). If the command is set for a station stop, the route beyond the signal must lead into a platform allocated to that station. If the command is set in the #dispose field, there are no further conditions.
The train action is part of a $stable command in the #dispose field.
The route beyond the signal is a Pool Storage path, and the train is booked to be stored in that pool.
CallOn may also be allowed if the route does not lead into a platform depending on the function call.
23.3.6.2. CallOn functions in activity mode
CallOn is never allowed if the route beyond the signal leads into a platform. CallOn may be allowed in other locations depending on the actual function call.
23.3.6.3. Available functions
23.3.7. SignalNumClearAhead Functions
The SignalNumClearAhead (SNCA) value sets the number of signals ahead which a signal will need to clear in order to be able to show the required least restrictive aspect. The value is set as a constant for each specific signal type in the sigcfg.dat file. However, it may be that certain signal options require that value to be changed. For instance, a signal type which optionally can display an advance approach aspect, needs a higher value for SNCA in case this advance approach is required. This may even depend on the route as set from that signal. In OR, functions are available to adjust the value of SNCA as required, which prevents the need to always set the possible highest value which could lead to a signal to clear a route too far ahead. Note that these functions always use the default value of SNCA as defined in sigscr.dat as starting value. Repeated calls of these functions will not lead to invalid or absurd values for SNCA.
23.3.8. Local signal variables
Originally, the only means of interfacing between signals, or between signal heads within a signal, is through the signal aspect states. This sets a severe restriction of the amount of information that can be passed between signals or signal heads.
In OR, local signal variables have been introduced. These variables are specific for a signal. The variables are persistent, that is they do retain their value from one update to the next. Because the variables are assigned per signal, they are available to all signalheads which are part of that signal. The variables can also be accessed by other signals.
Each signalhead which is part of a signal can access the variables for both reading and writing.
Each signalhead from other signals can access the variables for reading only.
Each variable is identified by an integer number. The variables can contain integer values only.
23.3.9. Functions for Normal Head Subtype
Although there can be different types of signal, and OR allows the definition and additional of any number of type, only signals of type NORMAL will affect the trains.
Certain signal systems, however, have different types of signals, e.g. main and shunt signals, which require different behaviour or different response. In order to be able to distinguish between such signals, OR has introduced a Subtype which can be set for a NORMAL signal.
The subtype can be defined for any signal in the sigcfg.dat file, in the same way as the signal type. A number of functions is available to query a signal to identify its subtype.
23.3.10. Functions to verify full or partial route clearing
As mentioned, some signal systems differentiate between main and shunt signals (e.g. in Germany, UK). This may affect the clearing of a signal in locations where both such types occur on the same route. If a train requires the full route from a main signal to the next main signal, in locations where there are shunt signals inbetween, the first main signal may not clear until the full route to the next main signal is available, and will then clear to a main aspect. If, however, the train only requires a partial route (e.g. for shunting), the signal may clear as soon as (part of) this route is available, and will generally then clear only to a restricted or auxiliary aspect (shunt aspect).
The original MSTS signal functions could not support such a situation, as the signal would always clear as soon as the first part of the route became available, because it was not possible to distinguish between the different types of signal.
Due to the introduction of the Normal Subtype as detailed above, such a setup is not possible. A number of functions have been introduced to support this.
Use of these functions is, however, fairly complicated, and only a brief description of these functions is provided in this document.
23.3.11. Miscellaneous functions
A number of miscellaneous functions which are not part of any of the groups detailed above.
23.3.12. Timing Functions
These two functions allow time-triggered actions on signals, e.g. a fixed time-triggered delay on clearing etc..
23.4. OR-specific additions to SIGCFG files
Detailed below are OR-specific additions which can be set in the SIGCFG file to set specific characteristics or enhance the functionality of the signal types.
23.4.1. General definitions
The following are general definitions which must be set before the definitions of the signal types, immediately following the lighttextures and lightstab definitions.
23.4.2. ORTSSignalFunctions
Additional signal types can be defined in OR, over and above the standard MSTS signal types. The additional types must be predefined in the sigcfg.dat file using the ORTSSignalFunctions definition.
The defined ORTS signal types can be set in the signal type definition and used in signal script functions in the same way as the default MSTS types.
By default, a custom signal function will have the same behaviour as an INFO signal function: it will have no impact on the block sections and will not be able to set a speed limit. You can tell the simulator to consider a custom function to have the same behaviour as one of the MSTS signal functions. You can add a MSTS function as a second parameter to the ORTSSignalFunctionType parameter. The use of the NORMAL signal function is currently forbidden. To define several types of NORMAL signals, please use the ORTSNormalSubtypes parameter.
Note that SPEED is a fixed signal type which is available in OR without explicit definition (see below for details on SPEED type signals). Also note that any type definition starting with “OR_” or “ORTS” is not valid, these names are reserved for future default types in OR.
Syntax:
ORTSSignalFunctions ( n
ORTSSignalFunctionType ( "CUSTOM_SIGNAL_FUNCTION" )
ORTSSignalFunctionType ( "CUSTOM_SPEED_SIGNAL_FUNCTION" "SPEED" )
. . .
)
The value n indicates the total number of definitions. The value CUSTOM_SIGNAL_FUNCTION is the name of the additional type.
23.4.3. ORTSNormalSubtypes
As detailed above, subtypes can be defined for NORMAL type signals which allows to distinguish different use of NORMAL type signals.
The Normal Subtype must be predefined in the sigcfg.dat file using the ORTSNormalSubtypes definition.
The Subtype can be set in the type definition for NORMAL type signals using the ORTSNormalSubtype statement, see below.
The subtype can be used in specific signal script functions as detailed above.
Syntax:
ORTSNormalSubtypes ( n
ORTSNormalSubtype ( "subtype" )
. . .
)
The value n indicates the total number of definitions. The value subtype is the name of the subtype.
23.4.4. Signal Type definitions
The following section details OR specific additions to the signal type definition.
23.4.4.1. Glow settings
Signal Glow is a feature in OR to improve the visibility of signals at larger distances. The required glow setting can de set per signal type in the signal definition. The value is a real number, and sets the intensity of the glow. Value 0.0 defines that there is no glow effect.
Default program values for glow are:
Notes :
For signal types which have “Semaphore” flag set, the Day value = 0.0.
For signals of type INFO and SHUNTING, both Day and Night value are set to 0.0 (no glow).
Syntax:
ORTSDayGlow ( d )
ORTSNightGlow ( n )
The values d and n are the day and night glow values, as real numbers.
23.4.5. Light switch
There were many signalling systems where semaphore signals did not show lights during daytime. This effect can be simulated using the ORTSDayLight setting.
Syntax:
ORTSDayLight( l )
The value l is a logical value, if set to false, the signal will not show lights during daytime.
23.4.6. Script Function
Normally, each signal type must have a linked signal script, with the same name as defined for the signal type. However, often there are a series of signal types which may differ in definition, e.g. due to differences in the position of the lights, but which have the same logic scripts.
In OR, a signal type can have a definition which references a particular script which this signal type must use. Different signal types which have the same logic can therefore all use the same script. This script may be defined using the name of one of these signal types, or it may have a generic name not linked to any existing signal type.
Syntax:
ORTSScript( name )
The value name is the name of the signal script as defined in the sigscr.dat file.
23.4.7. Normal Subtype
As detailed above, a signal type of type NORMAL may have an additional subtype definition.
Syntax:
ORTSNormalSubtype( subtype )
The value subtype is the subtype name and must match one of the names defined in ORTSNormalSubtypes.
23.4.8. Approach Control Settings
The required values for approach control functions for a particular signal type can be defined in the signal type definition. These values can be referenced in the signal script as defined for the approach control functions.
Syntax:
ApproachControlSettings (
PositionDefinition ( position )
SpeedDefinition ( speed )
)
23.4.8.1. Possible position definitions
23.4.8.2. Possible speed definitions
The value position is the required position value in dimension as set by the relevant parameter. The value speed is the required speed value in dimension as set by the relevant parameter. Inclusion of speed definition is optional and need not be set if only approach control position functions are used.
23.4.9. Signal aspect parameters
The following parameters can be included in signal aspect definitions.
Can be used in combination with a speed setting. Its function, combined with the speed setting, is as follows.
If set, the speed as set applies until overruled by a speedpost or next signal setting a higher speed value;
If not set, speed as set applies until the next signal and will not be overruled by a speedpost.
Speed as set always applies until overruled by a speedpost or next signal setting a higher speed value, this flag has no effect in timetable mode.
For signal aspects “STOP_AND_PROCEED” and “RESTRICTING”, trains will reduce speed to a low value on approach of the signal. If this flag is set, trains are allowed to pass the signal at normal linespeed.
23.4.10. SPEED Signal
A new standard signaltype, “SPEED”, has been added to OR.
Signals defined as type “SPEED” are processed as speedposts and not as signals. The required speed limit can be set using the speed setting of the signal aspect definition.
The advantages of using “SPEED” signals over speedposts are :
“SPEED” signals can be scripted, and can therefore be conditional, e.g. a speed restrictions in only set on approach to a junction if a restricted route is set through that junction.
“SPEED” signals can set a state according to their setting, and this state can be seen by a preceeding signal. This can be used to set up variable speed warning signs.
A “SPEED” signalhead can be part of a signal which also contains other heads, but for clarity of operation this is not advisable.
23.5. INI File and User Settings
By default, Open Rails keeps the user’s settings and options in the Window’s Registry.
If you want to have a set of alternative settings which bypass the settings kept in the Registry, then you can use an INI text file for this.
Create an empty file OpenRails.ini in the same folder as OpenRails.exe and start Open Rails. The program will attempt to load settings from the file, using default values for settings that cannot be found and populates the INI file with these settings.
If you change the settings and options, then these will be saved automatically to the INI file.