Panel2.cfg

From BVEStation Wiki
Jump to: navigation, search

The panel2.cfg file format


■ 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.

File:Illustration center origin.png

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:
File:300px-2nd Order Damping Ratios.svg.png
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.

File:Illustration digitalgauge 1.png

File:Illustration digitalgauge 2.png

[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 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.



■ 9. 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.
bc Returns the pressure of the brake cylinder 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.
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.
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.


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).