The panel2.cfg file format

■ Contents

---

↷ 1. Overview
↷ 2. Syntax
↷ 3. The This section
↷ 4. The PilotLamp section
↷ 5. The Needle section
↷ 6. The DigitalNumber section
↷ 7. The DigitalGauge section
↷ 8. The LinearGauge section
↷ 9. The Timetable section
↷ 10. Available subjects


■ 1. Overview

---

The panel2.cfg file allows to create 2D panels by defining which elements to use, like lamps, needles, etc., what they are intended to display and where they are to be placed.

The panel2.cfg file is a plain text file encoded in any arbitrary encoding, however, UTF-8 with a byte order mark is the preferred choice. The parsing model for numbers is Loose, however, you are encouraged to produce Strict output nonetheless. The file is required to be located inside the train folder and is expected to be named panel2.cfg. The file is interpreted on a per-line basis, from top to bottom.

ⓘ Layers

All elements in the panel are associated layers. The layer is described as an integer, where small values represent the background and high numbers the foreground. When placing elements, you should make sure that no overlapping elements share the same layer number. The background image of the panel is always associated layer number 0, so elements on top of it should start with layer number 1 or higher. If you want to place elements behind the panel background image, you can likewise use negative numbers to represent these layers.

ⓘ Daytime and nighttime images

For all elements that take a texture, you can specify distinct daytime and nighttime textures. Depending on the lighting conditions and additional route instructions, OpenBVE will display any intermediate blend between the daytime and nighttime textures. If no nighttime textures are used, the daytime images will be darkened to simulate corresponding nighttime images.

➟ See also the quick reference for the panel2.cfg...

ⓘ Overlay and Lighting

The cab is rendered as an overlay. This means that the cab will always appear in front of scenery objects. This is intentional, because this way, rain, walls and other obstructing objects cannot be accidentally rendered inside the cab. Furthermore, lighting in the cab is different than in the scenery. While the ambient brightness is reflected in the cab, the ambient color is not, and the cab always appears as if reflecting white light.

■ 2. Syntax

---

Each line in the file can be empty (or solely consist of white spaces) and will be ignored, can mark the beginning of a new section or contain key-value pairs inside a section. All key-value pairs relate to the last section opened.

A new section is opened by starting the line with an opening bracket (U+005B) and ending it with a closing bracket (U+005D). The text in-between the brackets indicates the name of the section and is case-insensitive. White spaces at the beginning and the end of the line are ignored, as well as at the beginning and the end of the name of the section. Thus, the beginning of the section has the following form:

[NameOfTheSection]

A key-value pair is indicated by giving the key, an equals sign (U+003D) and then the value. The key is case-insensitive. White spaces at the beginning and the end of the line are ignored, as well as in front and after the equals sign. Alternatively, white spaces surrounding the key and the value are ignored. Thus, a key-value pair as the following form:

NameOfTheKey = Value

Some values are further split into multiple parts, separated by commas (U+002C).

You can use comments anywhere at the end of a line. A comment is started by a semicolon (U+003B). Comments, if present, are stripped away from all lines before these are processed.


■ 3. The This section

---

The This section defines the background image to use for the panel and which resolution the panel has. Only one This section may be used within the file.

[This]

This starts the section.

Resolution = Value

Value: A floating-point number representing the width measured on the panel background image that corresponds to the width of the screen for the default camera position, alignment and zoom.

Left = Value

Value: A floating-point representing which x-coordinate in the panel background corresponds to the farthest point to which can be scrolled left. The point is not required to lie within the bounds of the background image.

Right = Value

Value: A floating-point representing which x-coordinate in the panel background corresponds to the farthest point to which can be scrolled right. The point is not required to lie within the bounds of the background image.

Top = Value

Value: A floating-point representing which y-coordinate in the panel background corresponds to the farthest point to which can be scrolled up. The point is not required to lie within the bounds of the background image.

Bottom = Value

Value: A floating-point representing which y-coordinate in the panel background corresponds to the farthest point to which can be scrolled down. The point is not required to lie within the bounds of the background image.

DaytimeImage = FileName

FileName: The image file to use as the daytime version of the panel background image, relative to the train folder. If not specified, no background image will be shown.

NighttimeImage = FileName

FileName: The image file to use as the nighttime version of the panel background image, relative to the train folder. If specified, the daytime version must also be specified. Otherwise, no nighttime version will be available.

TransparentColor = HexColor

HexColor: A hexcolor representing the exact color in both the DaytimeImage and NighttimeImage files which corresponds to a transparent pixel. The default value is #0000FF.

Center = X, Y

X: A floating-point number representing the x-coordinate of the panel background image that corresponds to the center of the screen. Y: A floating-point number representing the y-coordinate of the panel background image that corresponds to the center of the screen.

Defines which pixel in the background image corresponds to the center of the screen for the default camera position. The relation between Center and Origin influences the yaw and pitch of the cab alignment.

Origin = X, Y

X: A floating-point number representing the x-coordinate of the panel background image that corresponds to the vanishing point. Y: A floating-point number representing the y-coordinate of the panel background image that corresponds to the vanishing point.

Defines which pixel in the background image corresponds to the vanishing point for the default camera position. This is the point to which the two rails converge at the horizon on a straight piece of track. The relation between Center and Origin influences the yaw and pitch of the cab alignment.

ⓘ When camera restriction affects the default camera setup

Camera restriction is the built-in functionality to limit the camera view inside cabs created by the panel2.cfg to the rectangle as specified via Left, Right, Top and Bottom. If your setup of Center and Resolution would force the camera to show parts that are outside of that specified region even with the default camera settings, the camera position will be altered to guarantee that the view stays inside the cab region. In order to verify that your Center and Origin setup is unaffected by this, disable camera restriction by hitting the CAMERA_RESTRICTION key (default: CTRL+R) and then reset the camera by hitting the CAMERA_RESET key (default: num 5). The Center and Origin values will now be exactly as scripted, thereby revealing possible problems in the relations of Resolution, Left, Right, Top, Bottom, Center and Origin.

■ 4. The PilotLamp section

---

The PilotLamp section creates an indicator that can be made visible or invisible. You can use as many of these sections as required.

The DaytimeImage is required to be specified if you make use of the PilotLamp section. The Subject used needs to return 1 if the PilotLamp is to be made visible, otherwise it will be invisible.

[PilotLamp]

This starts the section.

Subject = Subject

Subject: One of the available subjects. The default subject is true.

Location = Left, Top

Left: A floating-point number representing the x-coordinate at which the left of the image is inserted. The default value is 0. Top: A floating-point number representing the y-coordinate at which the top of the image is inserted. The default value is 0.

DaytimeImage = FileName

FileName: The image file to use as the daytime version of the indicator image, relative to the train folder. Is required to be specified.

NighttimeImage = FileName

FileName: The image file to use as the nighttime version of the indicator image, relative to the train folder. If not specified, no nighttime version will be available.

TransparentColor = HexColor

HexColor: A hexcolor representing the exact color in both the DaytimeImage and NighttimeImage files which corresponds to a transparent pixel. The default value is #0000FF.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 5. The Needle section

---

The Needle section creates a rotating element, or needle. You can use as many of these sections as required.

The image used for the Needle, defined by DaytimeImage (required) or NighttimeImage (optional), will be rotated around a defined Origin and optionally scaled if Radius is used. The needle depicted in the image should be pointing up.

[Needle]

This starts the section.

Subject = Subject

Subject: One of the available subjects. The default subject is true.

Location = CenterX, CenterY

CenterX: A floating-point number representing the x-coordinate of the center of rotation in terms of the background image. The default value is 0. CenterY: A floating-point number representing the y-coordinate of the center of rotation in terms of the background image. The default value is 0.

Radius = ValueInPixels

ValueInPixels: A non-zero floating-point number that redefines the radius of the element in pixels relative to the background image. The default value is Y from the Origin key-value pair.

The Y value in the Origin key-value pair defines the vertical point of rotation, but also defines the actual radius of the element in the bitmap's own pixel coordinates. If ValueInPixels is set to a different value than this actual radius, the image will be scaled by a factor of Radius / Y, while preserving the Origin-Center relation. If you do not want to scale the image, set ValueInPixels to the same value as Y in the Origin key-value pair, or omit Radius altogether.

DaytimeImage = FileName

FileName: The image file to use as the daytime version of the needle image, relative to the train folder. Is required to be specified.

NighttimeImage = FileName

FileName: The image file to use as the nighttime version of the needle image, relative to the train folder. If not specified, no nighttime version will be available.

Color = HexColor

HexColor: A hexcolor representing the color by which the images are multiplied with. The default value is #FFFFFF.

Multiplies the images by the color specified by HexColor. Setting HexColor to #FFFFFF (white) preserves the original color of the images, while setting HexColor to #000000 (black) produces black images. Pixels defined as being transparent via TransparentColor are not affected.

TransparentColor = HexColor

HexColor: A hexcolor representing the exact color in both the DaytimeImage and NighttimeImage files which corresponds to a transparent pixel. The default value is #0000FF.

Origin = X, Y

X: A floating-point number representing the x-coordinate that corresponds to the image's center of rotation. The default value is half the image width. Y: A floating-point number representing the y-coordinate that corresponds to the image's center of rotation. The default value is half the image height.

InitialAngle = ValueInDegrees

ValueInDegrees: A floating-point number representing the angle in degrees that corresponds to the Minimum value. The angle is measured clock-wise from the 12 o'clock position. The default value is -120.

LastAngle = ValueInDegrees

ValueInDegrees: A floating-point number representing the angle in degrees that corresponds to the Maximum value. The angle is measured clock-wise from the 12 o'clock position. The default value is 120.

Minimum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use that should be linked to the InitialAngle. The default value is 0.

Maximum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use that should be linked to the LastAngle. The default value is 1000.

NaturalFreq = Value

Value: A non-negative floating-point number representing the natural frequency of an assumed undamped oscillatory system. If not specified, damping will not be performed.

Defines the natural frequency. In an undamped oscillatory system, this is the angular frequency in radians per second. As soon as damping is performed, the frequency will decrease with convergence of the oscillator. A natural frequency of 0 will not allow any rotation to be performed. Higher values roughly correspond to radians per second. If specified, DampingRatio should also be specified.

DampingRatio = Value

Value: A non-negative floating-point number representing the damping ratio. If not specified, damping will not be performed.

Defines the damping ratio for the oscillatory system. Values between 0 and 1 represent under-damping, 1 represents critical damping and values above 1 represent over-damping. Compare the following illustration in which the angle of rotation changes from 0 to 1 over time:

If specified, NaturalFreq should also be specified.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 6. The DigitalNumber section

---

The DigitalNumber section creates an indicator that can switch between multiple states, useful to build up a display of decimal digits. You can use as many of these sections as required.

The image used for the DigitalNumber, defined by DaytimeImage (required) and NighttimeImage (optional), is comprised of the individual states, which are stacked vertically, anchored at the top of the image. The width of a single state is equal to the width of the image, while the height of a single state is defined by Interval (required). The Subject used needs to return an integer from 0 (first element) to n-1 (last element), where n is the number of elements. If a value outside of that range is returned by Subject, the DigitalNumber will be made invisible.

[DigitalNumber]

This starts the section.

Subject = Subject

Subject: One of the available subjects. The default subject is true.

Location = Left, Top

Left: A floating-point number representing the x-coordinate at which the left of the image is inserted. The default value is 0. Top: A floating-point number representing the y-coordinate at which the top of the image is inserted. The default value is 0.

DaytimeImage = FileName

FileName: The image file to use as the daytime version of the DigitalNumber image, relative to the train folder. Is required to be specified.

NighttimeImage = FileName

FileName: The image file to use as the nighttime version of the DigitalNumber image, relative to the train folder. If not specified, no nighttime version will be available.

TransparentColor = HexColor

HexColor: A hexcolor representing the exact color in both the DaytimeImage and NighttimeImage files which corresponds to a transparent pixel. The default value is #0000FF.

Interval = Height

Height: The height of a single state in the images in pixels. Is required to be specified.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 7. The DigitalGauge section

---

The DigitalGauge section creates a solid-color square of which only a radial section is shown at a time. You can use as many of these sections as required.

There are three important angles to consider. The InitialAngle defines which angle corresponds to the Minimum value, while LastAngle defines which angle corresponds to the Maximum value. The current value at a given time corresponds to the current angle. The solid-color square will only show the part that is between the current angle and the LastAngle. If InitialAngle is less than LastAngle, the solid-color square will wind clockwise. If InitialAngle is greater than LastAngle, the solid-color square will wind counter-clockwise.

The subject needs to return a value that meaningfully works together with the Minimum and Maximum settings.

[DigitalGauge]

This starts the section.

Subject = Subject

Subject: One of the available subjects. The default subject is true.

Location = CenterX, CenterY

CenterX: A floating-point number representing the x-coordinate at which the left of the image is inserted. The default value is 0. CenterY: A floating-point number representing the y-coordinate at which the top of the image is inserted. The default value is 0.

Radius = ValueInPixels

ValueInPixels: A non-zero floating-point number representing half the edge length of the solid-color square in pixels. Is required to be specified.

If Radius is negative, it is treated as if it was positive, but the entire LED is rotated by 180 degrees.

Color = HexColor

HexColor: A hexcolor representing the color of the solid-color square. The default value is #FFFFFF.

InitialAngle = ValueInDegrees

ValueInDegrees: A floating-point number representing the angle in degrees that corresponds to the Minimum value. The angle is measured clock-wise from the 12 o'clock position. The default value is -120.

⚠

The absolute difference between InitialAngle and LastAngle may not exceed 360 degrees.

LastAngle = ValueInDegrees

ValueInDegrees: A floating-point number representing the angle in degrees that corresponds to the Maximum value. The angle is measured clock-wise from the 12 o'clock position. The default value is 120.

⚠

The absolute difference between InitialAngle and LastAngle may not exceed 360 degrees.

Minimum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use that should be linked to the InitialAngle. The default value is 0.

Maximum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use that should be linked to the LastAngle. The default value is 1000.

Step = Value

Value: A floating-point value representing the step in which values on the solid-color square can increase. The value to be displayed via the solid-color square will be rounded down to the next integer multiple of Value. If Value is negative, values will be rounded up to the absolute value of Value instead. If Value is 0, increases will be smooth. The default value is 0.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 8. The LinearGauge section

---

The LinearGauge section creates a panel layer, which uses texture shifting to create a sliding linear gauge. You can use as many of these sections as required.

Consider a standard OpenBVE face:



As you can see, the horizontal texture-coordinates upon this face are 0 at the right and 1 at the left.
Thus, the value given by Minimum represents 0 Maximum, represents 1, and the current value may then be calculated as a simple percentage.

Further, the direction of the texture shift may be changed from horizontal to vertical (or both) by using the Direction parameter.

[LinearGauge]

This starts the section.

Subject = Subject

Subject: One of the available subjects. The default subject is true.

Location = CenterX, CenterY

CenterX: A floating-point number representing the x-coordinate at which the left of the image is inserted. The default value is 0. CenterY: A floating-point number representing the y-coordinate at which the top of the image is inserted. The default value is 0.

Minimum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use. The default value is 0.

Maximum = Value

Value: A floating-point value corresponding to the value returned by the Subject in use. The default value is 1000.

Direction = XDirection, YDirection

XDirection: -1: Translates from right to left 0: No translation is performed 1: Translates from left to right. The default value is 0. YDirection: -1: Translates from top to bottom 0: No translation is performed 1: Translates from bottom to top. The default value is 0.

Width = NeedleWidth

NeedleWidth: An integer which defines the width in pixels of the needle, from the edge of the texture- Translation of the texture will stop when this reaches this number of pixels from the end, in order to avoid wrapping around. The default value is 0.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 9. The Timetable section

---

The Timetable section defines where to place custom timetables. The actual images are loaded via the route file. Only one Timetable section may be used within the file.

[Timetable]

This starts the section.

Location = Left, Top

Left: A floating-point number representing the x-coordinate at which the left of the image is inserted. The default value is 0. Top: A floating-point number representing the y-coordinate at which the top of the image is inserted. The default value is 0.

Width = ValueInPixels

ValueInPixels: A positive floating-point number representing the width of the timetable measured in terms of the background image. Is required to be specified.

Height = ValueInPixels

ValueInPixels: A positive floating-point number representing the height of the timetable measured in terms of the background image. Is required to be specified.

TransparentColor = HexColor

HexColor: A hexcolor representing the exact color in both the daytime and nighttime versions of the timetable which corresponds to a transparent pixel. The default value is #0000FF.

Layer = LayerIndex

LayerIndex: An integer which uniquely defines this element among overlapping elements. Lower numbers represent the background and higher numbers the foreground. Elements may use the same LayerIndex as long as they do not overlap. The default value is 0.

■ 10. Available subjects

---

A subject is composed of a base subject and an optional subject suffix. The subject controls what information is fed to the element that uses the subject. For example, a Needle can use the subject kmph to be fed with the current speed of the train in kilometers per hour, or with the mr subject to show the main reservoir pressure.

● Base subjects

Base subject	Description
acc	Returns the (signed) acceleration of the train in meters per second squared (m/s²).
atc	Equivalent to ats271.
atsi	Returns the state of the ith plugin variable, depending on the plugin used. This is the same as pluginState[i] in animated objects. For the built-in safety systems ATS and ATC, see below.
locobrakecylinder	Returns the pressure of the brake cylinder on the driver's car in kPa (1000 Pa).
bc	Returns the pressure of the brake cylinder in kPa (1000 Pa).
locobrakepipe	Returns the pressure of the brake pipe on the driver's car in kPa (1000 Pa).
bp	Returns the pressure of the brake pipe in kPa (1000 Pa).
brake	Returns the currently selected brake notch. For trains with automatic air brakes, 0 represents RELEASE, 1 represents LAP, 2 represents SERVICE and 3 represents the emergency brake. For trains without a hold brake device, 0 represents released brakes, i represents brake notch i and n+1 represents the emergency brake, where n is the number of brake notches the train has. For trains with a hold brake device, 0 represents released brakes, 1 represents the hold brake, i+1 represents brake notch i, and n+2 represents the emergency brakes, where n is the number of brake notches the train has.
locobrake	Returns the currently selected Loco Brake notch.
csc	Returns 1 if the const speed system is currently active and 0 otherwise.
door	Returns a value between 0 (open doors) and 1 (closed doors).
doorli	Returns a value between 0 (open) and 1 (closed) for the left doors of car i, or 2 if the car does not exist. Car index 0 represents the first car in the train, and n-1 the last car, where n is the number of cars in the train.
doorri	Returns a value between 0 (open) and 1 (closed) for the right doors of car i, or 2 if the car does not exist. Car index 0 represents the first car in the train, and n-1 the last car, where n is the number of cars in the train.
doorbuttonl	Returns 1 if the left door button is currently pressed, 0 otherwise.
doorbuttonr	Returns 1 if the right door button is currently pressed, 0 otherwise.
er	Returns the pressure of the equalizing reservoir in kPa (1000 Pa).
hour	Returns the integer part of the current hour.
kmph	Returns the absolute speed of the train in kilometers per hour (km/h).
min	Returns the integer part of the current minute.
motor	Returns the acceleration which the motor of the first motor car currently generates in m/s².
mph	Returns the absolute speed of the train in international miles per hour (mph).
mr	Returns the pressure of the main reservoir in kPa (1000 Pa).
ms	Returns the absolute speed of the train in meters per second (m/s).
power	Returns the currently selected power notch. This is an integer between 0 and n, where n is the number of power notches the train has.
rev	Returns the currently selected reverser position. 0 represents backward, 1 represents neutral and 2 represents forward.
sap	Returns the pressure of the straight air pipe in kPa (1000 Pa).
sec	Returns the integer part of the current second.
true	Always returns 1. This is useful for the PilotLamp element in order to always show the associated bitmap.
Klaxon	Returns the currently playing horn (if any) as follows: (0) No horns are playing (1) The primary horn is playing (2) The secondary horn is playing (3) The music horn is playing. Note If multiple horns are playing, the lowest value will be returned.
PrimaryKlaxon	Returns 1 if the primary horn is currently playing, 0 otherwise.
SecondaryKlaxon	Returns 1 if the secondary horn is currently playing, 0 otherwise.
MusicKlaxon	Returns 1 if the music horn is currently playing, 0 otherwise.

If atsi is used with the built-in safety systems ATS and ATC, the following mapping for i applies:

i	English	日本語	Return values		ats271	Meaning
256	ATS	ATS	0 (unlit) or 1 (lit)		0	ATC not available
257	ATS RUN	ATS 作動	0 (unlit), 1 (lit) or 2 (flashing)		1	0 km/h
258	ATS RUN	ATS 作動	0 (unlit / non-flashing), 1 (lit / flashing)		2	15 km/h
259	P POWER	P 電源	0 (unlit) or 1 (lit)		3	25 km/h
260	PTN APPROACH	パターン接近	0 (unlit) or 1 (lit)		4	45 km/h
261	BRAKE RELEASE	ブレーキ開放	0 (unlit) or 1 (lit)		5	55 km/h
262	BRAKE APPLY	ブレーキ動作	0 (unlit) or 1 (lit)		6	65 km/h
263	ATS P	ATS-P	0 (unlit) or 1 (lit)		7	75 km/h
264	FAILURE	故障	0 (unlit) or 1 (lit)		8	90 km/h
265	ATC	ATC	0 (unlit) or 1 (lit)		9	100 km/h
266	ATC POWER	ATC 電源	0 (unlit) or 1 (lit)		10	110 km/h
267	ATC SRV	ATC 常用	0 (unlit) or 1 (lit)		11	120 km/h
268	ATC EMG	ATC 非常	0 (unlit) or 1 (lit)		12	ATS is active
269	CONST SPEED	定速	0 (unlit) or 1 (lit)
270	EB	EB	0 (unlit) or 1 (lit)
271	ATC speed indicator		0 - 12, see table on the right

● Suffixes

Subject suffix	Description
di	With d0 for the ones, d1 for the tens, d2 for the hundreds, etc., this suffix returns a value between 0 and 9 corresponding to the respective digit of the underlying subject, but only if the value of the subject is less than 10 for d1, less than 100 for d2, etc., otherwise this suffix returns 10.

Example: kmphd1 can be used to feed a DigitalNumber with the tens of the current speed of the train in kilometers per hour. The image used by the DigitalNumber will thus need to be composed of images from 0 to 10 in order to show all possible states kmphd1 can return, where images 0 through 9 correspond to the digits, and 10 corresponds to an image shown at the tens when the speed is below 10 km/h (e.g. another 0-digit, or blank space).