Setting Engine Controllers

Index

Introduction

Control Format

Key Open Rails Parameters for Engine Controllers

Sample Engine Controller Code

Useful Links


Introduction

EngineControllers definitions are used in OR to define controls for a locomotive. These controls can be operated from a keyboard command or from a Cabview if so defined. This page only describes the configuration of the controllers typically operated by key command. Sometimes a controller needs to be configured to enable a particular feature in Open Rails.

If you wish to provide any feedback on this page, please use the contact page. It would be great to have some feedback, as this helps to ensure the accuracy of the information.

top


Control Format

There are five types of controller, TwoState, TriState, VarControl - Continuous Operation, VarControl - Notched Operation and CombinedControl. Each of these different types will be described below in more detail.

TwoState

A simple control with two states typically used for buttons eg on-off and valves eg open-closed, eg Wipers ( 0 1 0 ). A two state control has an on value, an off value and a default value and is specified as follows:
ControlName ( on-value off-value default-value )

Where:
off-value = value when the device is in the OFF position. Typically will be zero.
on-value = value when the device is in the ON position (key press). Typically will be one.
default-value = position that the device will be in when Open Rails initially starts. 0 = OFF, 1 = ON.

TriState

Used for a control with three positions - an example used in the game is headlights (on-dim-full) and the format is specified as follows:
ControlName ( value1 value2 value3 default-value )

Where:
value1 = value when the device is in the OFF position. Typically will be zero.
value2 = value when the device is in the first ON position (key press). Typically will be a value between 0 and 1.
value3 = value when the device is in the second ON position (2nd key press). Typically will be one.
default-value = position that the device will be in when Open Rails initially starts. A value selected from value1, value2 or value3.

VarControl - Continuous Operation

A variable control has a range of positions and is typically used for levers eg brake, throttle, reverser, regulator etc.. A variable control may have a smooth range of movement, notched movement or a combination of the two. It has a minimum value, a maximum value, a step value and a default value. The default value is the starting value in the game eg you can use this to start with brakes on or off. The step value is the increment used when increasing /decreasing the control setting in the game for un-notched controls and the smooth ranges in notched controls. If no notches are used then NumNotches must be set to 0.

A variable control without notches is specified as follows:
ControlName ( min-value max-value step-value default-value
NumNotches ( notch-count ) )

Where:
min-value = value when the device is in the OFF position. Typically will be zero.
max-value = value when the device is in the ON position. Typically will be one.
step-value = value when the device is in the ON position. Typically will be one.
default-value = position that the device will be in when Open Rails initially starts. 0 = OFF, 1 = ON.
notch-count = Number of notches, in the case of a continuous controller this value will be 0.

VarControl - Notched Operation

Notches can be added to a variable control so that the operation give the look/feel of notched movement. Each Notch ( ) has a value for its positions - this must be greater then or equal to min-value and less than or equal to max-value and be specified in increasing order. A notch may have smooth movement between it and the next notch and this is specified in data per Notch ( ) as 0 = notch, 1 = smooth. A notch also has a token string associated with it which allows us in the case of the brake systems to associate a given notch position with its real life function. If a notch does not have a specific function the "Dummy" string is used. The general rule is that all brakes must have named notches and other controls don't.

A variable control with notches is specified as follows:
ControlName ( min-value max-value step-value default-value
NumNotches ( notch-count
Notch ( notch-position notch-graduation notch-token )
) )

Where:
min-value = value when the device is in the OFF position. Typically will be zero.
max-value = value when the device is in the ON position. Typically will be one.
step-value = value when the device is in the ON position. Typically will be one.
default-value = position that the device will be in when Open Rails initially starts. 0 = OFF, 1 = ON.
notch-count = Number of notches.
notch-position = Point where the notch becomes active, typically a value between 0 and 1.
notch-graduation = Graduation method of movement from this notch to the next. 1 = smooth, and 0 = steps to next notch.
notch-token = Token describing the operation of the notch.

Combined Controllers
A combined controller (such as the combined power handle in the Dash 9) is a combination of two other controls (in the Dash 9ís case, a throttle and a dynamic brake). It must always be a combination of Throttle and one of the brake systems. The referenced controls must be specified as normal, the presence of the combined controller will prevent direct control of them by the player. The linked control names must be one of 'throttle', 'dynamic', 'train', 'independent'.

A combined control is specified as follows:
ControlName ( min-value max-value split default-value control1 control2 )

Where:
min-value = value when the device is in the OFF position. Typically will be zero.
max-value = value when the device is in the ON position. Typically will be one.
split = value when the device changes from one control type to another.
default-value = position that the device will be in when Open Rails initially starts. 0 = OFF, 1 = ON.
control1 = Name of first controller type.
control2 = Name of second controller type.

top


Key Open Rails Parameters for Engine Controllers

The key engine controller parameters are described on the following web page.

Standard Parameters for EngineControllers (updated Jan 2022)

top


Sample Engine Controller Code

TwoState


    WaterScoop ( 0 1 0 )

TriState


    Headlights ( 0 0.25 1 0 )

VarControl - Continuous Operation


    Injector2Water ( 0 1 0.1 0
                NumNotches( 0 )
          )

VarControl - Notched Operation


Brake_Train ( 0 1 0.01 0.65
          NumNotches( 3
                   Notch(0 1 TrainBrakesControllerReleaseStart )
                   Notch(0.4 1 TrainBrakesControllerRunningStart )
                   Notch(0.5 1 TrainBrakesControllerApplyStart )
          )
       )

Combined Control


Combined_Control( 0 1 0.5 0.5 throttle dynamic )

top


Useful Links

top