Format de fitxer train.xml

NOTE:

This page is still under construction.

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:

<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 </SpringType>
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 </SpringType>
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.

<HeadlightStates> NumberOfStates </HeadlightStates>

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.

■ 3.4. The Sanders section

The <Sanders> section specifies the properties of the sanders fitted to this car, and supports the following properties:

Type Type
Type: The type of sanders fitted to this car (if any).
<NormalPressure> Pressure </NormalPressure>
NotFitted: No sanding mechanism is fitted.
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.
Rate SandingRate
SandingRate: The rate at which sand is applied per second.
SandLevel Level
Level: The initial starting level of sand, if not in shot mode.
NumberOfShots Shots
Shots: The number of sand shots available.
ApplicationTime Time
Time: When in shots mode, sets the duration of a sand shot in seconds.
ActivationTime Time
Time: When in automatic mode, the amount of time before the system reacts and applies sand.

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

*NumberOfDrops Drops
Drops: The total number of drops on the windscreen.
*WipeSpeed Speed
Speed: The time in seconds for the wipers to make a single sweep of the windscreen.
*HoldTime Time
Time: The time in seconds for the wipers to hold at the hold position during a sweep.
*DropLife Life
Life: The life in seconds before a drop is eligible to be recycled when all drops are visible.
*RestPosition Position
Position: The rest position for the wipers.

▸ Available options for Position:

Left: The wipers rest at the left of the screen when off.
Right: The wipers rest at the right of the screen when off.
*HoldPosition Position
Position: The hold position for the wipers.

▸ Available options for Position:

Left: The wipers hold on the left of the screen for HoldTime during their sweep.
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:

<Minimum> Distance </Distance>

Distance sets the minimum distance between the two cars.

<Maximum> Distance </Maximum>

Distance sets the maximum distance between the two cars.

This defines the acceleration curves and the power handle fitted to the car, and supports the following child nodes:

3.1.1. Acceleration Curves

☀ Note

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

<CanUncouple> Boolean </CanUncouple>

Boolean should be a boolean true / false value, determining whether this coupler may be uncoupled by the player.

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

<HeadlightStates> NumberOfStates </HeadlightStates>

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.