NOTE:
This page is still under construction.
- 1. Overview
- 2. The Train section
- 3. The Car section
- 3.1. The Power section
- 3.2. The Brake section
- 3.3. The Doors section
- 3.4. The Sanders section
- 3.4. The Windscreen section
- 4. The Coupler section
- 5. Miscellaneous Properties
■ 1. Overview
The train.xml format is the native format for newer versions of OpenBVE, and is intended to replace the older train.dat format. It allows setting of many more properties, and is extensible.
It may either be constructed as a single file containing the properties of the entire train, or as a single consist definition, along with child car files.
Positions Within Cars:
In the train.xml format, all positions are measured relative to the center of the car, which is assumed to be at 0,0,0 Whilst this is a change for some parameters from the legacy BVE formats, it means that all positions should be consistant.
■ 2. The Train section
Whether using child car files, or a single file, the first node in each train.xml file must be the <Train> node.
This supports the following properties:
This defines a car within the train.
CarProperties may either be a set of child nodes (if using the single file format) or a relative on-disk path to a child car file.
Car must be a positive integer less than or equal to the number of cars in the train, setting the driver car.
This overrides the in-game UI notch descriptions displayed.
Notch may be one or more child-nodes, with one of the following subjects: Power, Brake, LocoBrake or Reverser
A child-node must be of the following format:
Descriptions should be a comma or semi-colon separated list, equal to the number of notches the train has for the subject.
The entries for this list must be placed in order from low to high.
For an example brake or locomotive brake handle with EB, hold brake and 8 notches, the following would be used:
| Example Brake Handle NotchDescriptions: | |
| ƒ | <NotchDescriptions>EB,HLD,N,1,2,3,4,5,6,7,8</NotchDescriptions> |
A train using the automatic air-brake has a total of three notches, e.g:
| Example Brake Handle NotchDescriptions: | |
| ƒ | <NotchDescriptions>EB,REL,LAP,SRV</NotchDescriptions> |
For an example power handle with 8 notches, the following would be used:
| Example Power Handle NotchDescriptions: | |
| ƒ | <NotchDescriptions>N,1,2,3,4,5,6,7,8</NotchDescriptions> |
The reverser must be in the order Neutral, Forwards, Reverse:
| Example Reverser Handle NotchDescriptions: | |
| ƒ | <NotchDescriptions>N,F,R</NotchDescriptions> |
■ 3. The Car section
When using child car files, the <Car> node should be the first node in the file. All other details remain the same.
The
This supports the following properties:
This sets any camera restrictions within the cab (Generally used for 3D cabs).
Restrictions may be one or more child-nodes, with one of the following subjects: Backwards, Forwards, Left, Right, Down or Up
A child-node must be of the following format:
Distance should be a distance in meters from the origin point 0,0,0 at the center of the cab object.
LengthInMeters should be the length of the car in meters.
WidthInMeters should be the width of the car in meters.
HeightInMeters should be the length of the car in meters.
CenterOfGravityInMeters should be the height above the rails in meters at which the center of mass is located.
Area should be a positive floating-point number measured in square meters (m²) indicating the frontal area of a car when it is fully exposed to resisting air, for example when the car is the front car in the current nominal direction of travel.
Area should be a positive floating-point number measured in square meters (m²) indicating the frontal area of a car when it is fully not exposed to resisting air, namely any car in the train other than the front car.
EmptyMass should be the mass of an empty (unloaded) car in kilograms.
IsMotorCar sets whether the car is a motor car- If true, this car is set as a motor car.
Position should be the position in meters of the axle from the center of the car.
Position should be the position in meters of the axle from the center of the car.
ObjectFile should be a relative on-disk path to the exterior 3D object to use.
IsReversed sets whether the 3D exterior object is reversed. If true, the object is reversed.
ObjectFile should be a relative on-disk path to the interior 3D object to use.
IsVisible controls whether the exterior object(s) for this car are visible from the interior of other cars. If true, objects will be visible.
Sways sets whether loading sway affects this specific car. If true, then whilst passengers are boarding at a station, the loading sway animation is used.
Position should contain a comma-separated 3D vector, defining the position of the driver’s eyes within the car, relative to 0,0,0
CargoType defines the type of cargo which this car carries. The following load types are available:
None: This car carries no load (e.g. a locomotive, brake van or similar). It’s weight is not affected by the loading given at stations.
■ 3.1. The Power section
Motor cars may specifiy a <Power> node.
This defines the acceleration curves and the power handle fitted to the car, and supports the following child nodes:
3.1.1. Acceleration Curves
In the train.dat acceleration curve figures are given for the train as a whole, and an internal calculation is performed to produce the per-car acceleration figures.
However, in train.xml acceleration curve figures apply to the current car only.
The <AccelerationCurves> child node should contain a list of acceleration curve nodes. These must be in ascending order, and should correspond to the number of power notches the train has.
Currently, the only supported acceleration curve node is the <OpenBVE> node, supporting the following properties (as per a train.dat acceleration curve):
Acceleration should be a positive floating-point number representing the acceleration at a speed of 0 km/h expressed in km/h/s.
Acceleration should be a positive floating-point number representing the acceleration at a speed of n km/h expressed in km/h/s.
Speed should be a positive floating-point number representing the reference speed for StageOneAcceleration
Exponent should be a positive floating-point number representing the exponent used in the stage two speed calculation.
Speed should be a positive floating-point number representing the reference speed for StageTwoExponent
Number should be a positive floating-point number representing the blended output of the motor car to the train’s acceleration. The default value is 1.0
This figure is only meaningful for trains using BVE acceleration numbers converted via CarXMLConvertor, and should be omitted if setting acceleration outputs on a per-car basis.
Thus:
If the speed of the train is 0 km/h, a0 indicates the acceleration output.
If the speed of the train is between 0 km/h and v1, the acceleration output is determined via the following formula:
| Acceleration between 0 km/h and v1, where x is the current speed of the train in km/h: | |
| ƒ | a0 + (a1 - a0) * x / v1 |
If the speed of the train is v1, the acceleration output is indicated by a1.
If the speed of the train is between v1 and v2, the acceleration output is determined via the following formula:
| Acceleration between v1 and v2, where x is the current speed of the train in km/h: | |
| ƒ | v1 * a1 / x |
If the speed of the train is greater than v2, the acceleration output is determined via the following formula (for version 2.0 exponents):
| Acceleration above v2, where x is the current speed of the train in km/h: | |
| ƒ | v1 * a1 * v2e-1 / xe |
3.1.2. Power Handles
Driver and non-driver cars:
The properties within this node will only be interpreted if the car is specified as the driver car.
The <Handle> node specifies properties for the power handle, and supports the folowing properties:
NumberOfNotches should be a positive integer, setting the number of power notches.
▸ Available options for Type:
Single: The spring return mechanism is reset when this handle is operated.
AnyHandle: The spring return mechanism is reset when any power or brake handle is operated. AnyKey: The spring return mechanism is reset when any keyboard key or joystick control is operated.
■ 3.2. The Brake section
The <Brake> section specifies properties for the braking system of the car, and consists of the following child nodes, each corresponding the a component of the twin-pipe standard air-brake system:
Air compressor
An optional <Compressor> node, supporting the following properties:
CompressionRate should be a positive number, representing the compression rate in Pa/s.
Main Reservoir
The <MainReservoir> node, supporting the following properties:
Pressure should be a positive number, representing the minimum pressure in the main reservoir in Pa.
Pressure should be a positive number, representing the maximum achievable pressure in the main reservoir in Pa.
Auxiliary Reservoir
The <AuxiliaryReservoir> node, supporting the following properties:
Rate should be a positive number, representing the charge rate of the auxiliary reservoir from the main reservoir in Pa/s.
Equalizing Reservoir
The <EqualizingReservoir> node, supporting the following properties:
Pressure should be a positive number, representing the normal pressure of this reservoir in Pa.
Brake Pipe
The <BrakePipe> node, supporting the following properties:
Pressure should be a positive number, representing the normal nominal pressure of the brake pipe in Pa.
Rate should be a positive number, representing the normal charge rate in Pa/s.
Rate should be a positive number, representing the charge rate in Pa/s when making a service brake application.
Rate should be a positive number, representing the charge rate in Pa/s when making an emergency brake application.
Straight Air Pipe
The <StraightAirPipe> node, supporting the following properties:
Rate should be a positive number, representing the charge rate in Pa/s when making a service brake application.
Rate should be a positive number, representing the charge rate in Pa/s when making an emergency brake application.
Rate should be a positive number, representing the charge rate in Pa/s when releasing a brake application.
Brake Cylinder
The <BrakeCylinder> node, supporting the following properties:
Pressure should be a positive number, representing the maximum pressure in Pa when making a full service brake application.
Pressure should be a positive number, representing the maximum pressure in Pa when making a full emergency brake application.
Rate should be a positive number, representing the release rate in Pa/s during a full emergency brake application.
Rate should be a positive number, representing the charge rate in Pa/s when releasing the brakes.
3.2.2. Brake Handles
Driver and non-driver cars:
The properties within this node will only be interpreted if the car is specified as the driver car.
The <Handle> node specifies properties for the brake handle, and supports the folowing properties:
NumberOfNotches should be a positive integer, setting the number of power notches.
▸ Available options for Type:
Single: The spring return mechanism is reset when this handle is operated.
AnyHandle: The spring return mechanism is reset when any power or brake handle is operated. AnyKey: The spring return mechanism is reset when any keyboard key or joystick control is operated.
■ 3.3. The Doors section
The <Doors> section specifies the properties of the passenger doors fitted to this car, and supports the following properties:
Speed should be a positive number, setting the time taken for the doors to open in seconds.
Speed should be a positive number, setting the time taken for the doors to close in seconds.
If the opening or closing speed is not set, this will be calculated using the duration of the open / close sounds.
See the sound.cfg documentation for further details.
DoorWidth should be a positive number, setting the width of the door opening in meters.
DoorTolerance should be a positive number, setting a tolerance in meters before the door is considered to be closed.
■ 3.4. The Sanders section
The <Sanders> section specifies the properties of the sanders fitted to this car, and supports the following properties:
▸ Available options for Type:
PressAndHold: The sanders are applied whilst the Sanders key is held and sufficient sand is available.
Toggle: The Sanders key toggles the sanders on and off. NumberOfShots: N shots of sand are available, which are applied when the Sanders key is pressed. Automatic: The sanders are automatically activated when wheelslip is detected and sufficient sand is present.
■ 3.5. The Windscreen section
The <Windscreen> section specifies the properties of the windscreen, and should be used if you wish to animated a windscreen on a 3D cab using the inbuilt functionality. It supports the following properties:
▸ Available options for Position:
Right: The wipers rest at the right of the screen when off.
▸ Available options for Position:
Right: The wipers hold on the right of the screen for HoldTime during their sweep.
■ 4. The Coupler section
Car nodes (or child file references) may optionally be separated by a <Coupler> node.
This defines the coupler between the two cars, and supports the following properties:
Distance sets the minimum distance between the two cars.
Distance sets the maximum distance between the two cars.
ObjectFile should be a relative on-disk path to the exterior 3D object to use.
The coupler object is not deformed when the coupler stretches / compresses.
Boolean should be a boolean true / false value, determining whether this coupler may be uncoupled by the player.
■ 5. Miscellaneous Properties
PluginFile should contain the relative path to the security plugin DLL to load.
Text should contain the textual description for the train to display in the main menu.
NumberOfStates should be the total number of states that the train headlight posesses.
Note: Headlight effects must be implemented by the train developer, using animation / panel properties.