Format de fitxer train.xml

NOTE:

This page is still under construction.

■ 1. Descripció

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

This supports the following properties:

<Car> CarProperties </Car>

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.

<DriverCar> Car </DriverCar>

Car must be a positive integer less than or equal to the number of cars in the train, setting the driver car.

<NotchDescriptions> Notch </NotchDescriptions>

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:

<Subject> Descriptions </Subject>

Descriptions should be a comma-separated list, equal to the number of notches the train has for the subject.

■ 3. The Car section

Note

When using child car files, the <Car> node should be the first node in the file. All other details remain the same.

The node contains the properties for each induvidual train car.

This supports the following properties:

<CameraRestriction> Restrictions </CameraRestriction>

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:

<Subject> Distance </Subject>

Distance should be a distance in meters from the origin point 0,0,0 at the center of the cab object.

<Length> LengthInMeters </Length>

LengthInMeters should be the length of the car in meters.

<Width> WidthInMeters </Width>

WidthInMeters should be the width of the car in meters.

<Height> HeightInMeters </Height>

HeightInMeters should be the length of the car in meters.

<Mass> EmptyMass </EmptyMass>

EmptyMass should be the mass of an empty (unloaded) car in kilograms.

<MotorCar> IsMotorCar </MotorCar>

IsMotorCar sets whether the car is a motor car- If true, this car is set as a motor car.

<FrontAxle> Position </FrontAxle>

Position should be the position in meters of the axle from the center of the car.

<RearAxle> Position </RearAxle>

Position should be the position in meters of the axle from the center of the car.

<Object> ObjectFile </Object>

ObjectFile should be a relative on-disk path to the exterior 3D object to use.

<Reversed> IsReversed </IsReversed>

IsReversed sets whether the 3D exterior object is reversed. If true, the object is reversed.

<InteriorView> ObjectFile </InteriorView>

ObjectFile should be a relative on-disk path to the interior 3D object to use.

<VisibleFromInterior> IsVisible </VisibleFromInterior>

IsVisible controls whether the exterior object(s) for this car are visible from the interior of other cars. If true, objects will be visible.

<LoadingSway> Sways </LoadingSway>

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.

<DriverPosition> Position </DriverPosition>

Position should contain a comma-separated 3D vector, defining the position of the driver’s eyes within the car, relative to 0,0,0

<Cargo> CargoType </Cargo>

CargoType defines the type of cargo which this car carries. The following load types are available:

Passenger: This car carries passengers. Its overall weight is affected by the loading given at stations, and passenger discomfort is scored. Freight: This car carries freight. Its overall weight is affected by the loading given at stations.
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

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

<StageZeroAcceleration> Acceleration </StageZeroAcceleration>

Acceleration should be a positive floating-point number representing the acceleration at a speed of 0 km/h expressed in km/h/s.

<StageOneAcceleration> Acceleration </StageOneAcceleration>

Acceleration should be a positive floating-point number representing the acceleration at a speed of n km/h expressed in km/h/s.

<StageOneSpeed> Speed </StageOneSpeed>

Speed should be a positive floating-point number representing the reference speed for StageOneAcceleration

<StageTwoExponent> Exponent </StageTwoExponent>

Exponent should be a positive floating-point number representing the exponent used in the stage two speed calculation.

<StageTwoSpeed> Speed </StageTwoSpeed>

Speed should be a positive floating-point number representing the reference speed for StageTwoExponent

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:

<Notches> NumberOfNotches </Notches>

NumberOfNotches should be a positive integer, setting the number of power notches.

SpringType Type
Type: The type of spring return fitted to this handle (if any).

▸ Available options for Type:

None: No spring return mechanism is fitted.
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:

<Rate> CompressionRate </Rate>

CompressionRate should be a positive number, representing the compression rate in Pa/s.

Main Reservoir

The <MainReservoir> node, supporting the following properties:

<MinimumPressure> Pressure </MinimumPressure>

Pressure should be a positive number, representing the minimum pressure in the main reservoir in Pa.

<MaximumPressure> Pressure </MaximumPressure>

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:

<ChargeRate> Rate </ChargeRate>

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:

<NormalPressure> Pressure </NormalPressure>

Pressure should be a positive number, representing the normal pressure of this reservoir in Pa.

Brake Pipe

The <BrakePipe> node, supporting the following properties:

<NormalPressure> Pressure </NormalPressure>

Pressure should be a positive number, representing the normal nominal pressure of the brake pipe in Pa.

<ChargeRate> Rate </ChargeRate>

Rate should be a positive number, representing the normal charge rate in Pa/s.

<ServiceRate> Rate </ServiceRate>

Rate should be a positive number, representing the charge rate in Pa/s when making a service brake application.

<EmergencyRate> Rate </EmergencyRate>

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:

<ServiceRate> Rate </ServiceRate>

Rate should be a positive number, representing the charge rate in Pa/s when making a service brake application.

<EmergencyRate> Rate </EmergencyRate>

Rate should be a positive number, representing the charge rate in Pa/s when making an emergency brake application.

<ReleaseRate> Rate </ReleaseRate>

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:

<ServiceMaximumPressure> Pressure </ServiceMaximumPressure>

Pressure should be a positive number, representing the maximum pressure in Pa when making a full service brake application.

<EmergencyMaximumPressure> Pressure </EmergencyMaximumPressure>

Pressure should be a positive number, representing the maximum pressure in Pa when making a full emergency brake application.

<EmergencyRate> Rate </EmergencyRate>

Rate should be a positive number, representing the release rate in Pa/s during a full emergency brake application.

<ReleaseRate> Rate </ReleaseRate>

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:

<Notches> NumberOfNotches </Notches>

NumberOfNotches should be a positive integer, setting the number of power notches.

SpringType Type
Type: The type of spring return fitted to this handle (if any).

▸ Available options for Type:

None: No spring return mechanism is fitted.
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:

<OpenSpeed> Speed </OpenSpeed>

Speed should be a positive number, setting the time taken for the doors to open in seconds.

<CloseSpeed> Speed </CloseSpeed>

Speed should be a positive number, setting the time taken for the doors to close in seconds.

Note

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.

<Width> DoorWidth </Width>

DoorWidth should be a positive number, setting the width of the door opening in meters.

<Tolerance> DoorTolerance </Tolerance>

DoorTolerance should be a positive number, setting a tolerance in meters before the door is considered to be closed.

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

<Minimum> Distance </Distance>

Distance sets the minimum distance between the two cars.

<Maximum> Distance </Maximum>

Distance sets the maximum distance between the two cars.

<Object> ObjectFile </Object>

ObjectFile should be a relative on-disk path to the exterior 3D object to use.

Note

The coupler object is not deformed when the coupler stretches / compresses.

■ 5. Miscellaneous Properties

<Plugin> PluginFile </Plugin>

PluginFile should contain the relative path to the security plugin DLL to load.

<Description> Text </Description>

Text should contain the textual description for the train to display in the main menu.