UKSPt.dll.20.05 - release notes


by Simon Gathercole
issued 20/05/05

Contents

  1. Contents
  2. Summary
  3. Starting states
  4. Configuration
  5. Master Switch
  6. AWS/TPWS
  7. Vigilance
  8. Interlocks
  9. Engine
  10. Guard
  11. Door Release Indicators
  12. Rain and Windscreen Wipers
  13. Head and Tail Lights
  14. Horn Lever Animation

Summary

UKSpt.dll is an ats plugin for BVE4 designed to represent a variety of modern UK diesel multiple units and specifically the BR 'Sprinter' series, classes 150 to 158.

The plugin has been completely redesigned since the last release (UKMUt.18.01) and includes many new features, which are summarised below and described in detail in the rest of this document:

Starting states

Two starting states are available:

The desired starting state is selected in the route file, where
If the driver uses the BVE restart or  jump to features, the following starting states are automatically selected:

Note for drivers on using jump to

Following a jump to, the driver should ensure that the controls are resynchronised with the plugin by
  1. returning the reverser to NEUTRAL
  2. returning the power handle to OFF
  3. applying full service brakes

Note on Beacons

During a jumpto operation, BVE sends all the beacons passed by the train to the plugin, which can result in unexpected behaviour - particularly if the jump is backwards to an earlier station!  To avoid this, the plugin currently ignores all beacons received immediately following a start/restart.

In the current version this imposes the following limitations:
It may be possible to remove these limitations by more sophisticated processing of beacons and this will be considered for future releases.

Configuration

The configuration file is named UKSpt.cfg and resides in the same folder as the plugin.

All configuration statements have the form:

classId.attributeId=value or
classId.attributeId=value1,value2,value3,...
where
classId
identifies the feature, e.g. "wiper" for rain and windscreen wiper
attributeId
identifies a configurable attribute, e.g. "holdPosition" for the wiper parking position

Note that the configuration statements must be entered exactly as shown above, without any whitespace.  Details of configuration for individual features are given in the sections below.

Master Switch

Panel variables

ats0 = 1 when Master switch is OFF
ats1
= 1 when Master switch is ON

When the starting state is OFF, the master switch must be turned on before the train can be driven - this is done by moving the reverser from 'neutral' to forward and returning it to neutral (this is as close as BVE allows to a four position reverser/master switch).  The following should then occur:
Instrument illumination is faked using masks to represent the unilluminated instruments, controlled as [Pilotlamps] from ats0.

AWS/TPWS

Panel variables

ats6 = 1 when AWS display is Black
ats7
= 1 when AWS display is Sunflower
ats8
= 1 when AWS reset button is pressed
ats9
= 1 when TPWS Brake Demand lamp is on
ats10
= 1 when TPWS Isolation lamp is on
ats11
= 1 when TPWS TSS override lamp is on

Sound variables

ats0 AWS bell
ats1
AWS startup test bell (reduced sounding time)
ats2
AWS horn

Keys

ats key A1
[Insert]
AWS reset
ats key C1
[Page Up]
TPWS TSS override
ats key C2
[Page Down]
AWS, TPWS, vigilance isolate

New Features for TPWS fitted trains:

Self Test

A more detailed representation of the AWS/TPWS self test is included.  It is  initiated by turning the Master switch on and proceeds as follows:
  1. AWS display turns from black to sunflower and back to black
  2. The TPWS lamps are illuminated
  3. The brakes are applied
  4. The AWS horn sounds
  5. Pressing the AWS reset button cancels the AWS horn, sounds the AWS bell briefly, turns off the TPWS lamps and allows the brakes to be released.
Note: the reduced AWS bell sound at the end of the test is deliberate, suggested by prototype notes.

AWS Brake Demand

(Thanks to Paul Cooper for information on this feature.)

Safety System Isolation

Pressing [Page Down] fully isolates the safety system (AWS/TPWS and VIGILANCE device) and illuminates the TPWS isolation lamp.  This feature is not completely prototypical but is provided as a route development/learning aid.

Vigilance

Configurable features (classId = "vigilance")

type
0, 1, 2 (default 2)
as below

The type of vigilance device fittted to the train is configurable using the type attribute, with values:

0
no vigilance device
1
standard vigilance device with 60 second cycle time
2 (default)
Sprinter-type vigilance device with cycle time reduced to 45 seconds in notches 6 and 7

Interlocks

New Features:

Reverser Interlocks

Brakes are now held on

Door Interlocks

Brakes are held on when the doors are released,  unless the reverser is in NEUTRAL.

BVE Interlocks

The following non-prototypical  interlocks have been added to conform with the  behaviour of BVE:

Engine

Panel variables

ats3 = 1 when the engine is running
ats4 engine start pushbutton with integral indicator lamp (display using [DigitalNumber])

starter inactive
starter active
button unpressed
0
2
button pressed 1
3
ats5
engine stop pushbutton with integral indicator lamp (display using [DigitalNumber])

engine stopped
engine running
button unpressed
0
2
button pressed
1
3

Sound variables

Engine start sounds
ats7
starter motor switching on
ats8
starter motor loop
ats9
starter motor running down
ats10 engine start
ats11
engine stall on start

ats12
engine idle
ats13
engine revving up
ats14
engine revving down
ats15
engine stopping

Keys

ats key D
[2]
Start engine
ats key E [3]
Stop engine

Configurable features (classId = "engine")

General
starterType
0, 1 (default 0)
0=simple start model; 1=complex start model
runDownDelay
>0 (default 4000)
length in ms of the revving down sound (ats14)
Simple start model
startDelay
>0 (default 4000)
length in ms of the engine start sound (ats10)
Complex start model
startDelay >0 (default 4000) length in ms of the engine start sound (ats10)
motorStartDelay
>0 (default 250)
length in ms of motor switch on sound (ats7)
stallDelay
>0 (default 1000)
length in ms of engine stall sound (ats11)
fireProbability
0-1000
simulation features - see below
stallProbability
0-1000

minFireProbability
0-1000 (default 10)

maxStallProbability
0-1000 (default 400)

New Features:

Interlocks

Starting

Two models of engine starting are available:

Simple start model

A single sound file is required, covering the entire startup procedure.  It must be aliased to ats10 in sound.cfg

On pressing the engine start button:

Complex start model

Five sound files are required, as listed above.  To start the engine, the start button must be pressed and held until the engine fires after a random number of BVE frames.  To add even more excitement, the engine randomly stalls after firing.  The ease of starting and likelihood of stalling can both be configured.

On pressing the starting button:

If interlocks prevent starting (see above):
If starting is allowed:
During the engine start loop
On engine firing:

Randomising Start Performance

With the complex start model, performance can be further randomised by specifying:

fireProbability = 0
stallProbability = 1000

In this case random values are assigned as follows:

fireProbability a value between minFireProbability and 1000
stallProbability a value between 0 and maxStallProbability

Revving up/down sounds

These sounds are played whenever the power handle is moved away from/to the OFF position.  In addition, the revving down sound is correctly played if the power is tripped by an interlock.

Notes

  1. There is a slight but noticeable delay on shutting off power before the revving down sound is played, due to the way BVE handles plugin sound variables.   If this is unacceptable, increase the power down delay in the train.dat file.
  2. Because it is not possible with BVE 4.1 to fade plugin sounds out, stopping the idle loop when the power handle is opened produces an unrealistic sudden change in the engine sound. To avoid this, the idle loop is played continuously, regardless of power setting.

Engine shutdown

On pressing the engine shutdown button:
Note that there are no interlocks preventing the engine stop button being active while the train is in motion.

Guard

Sound variables

ats5 Draw forward signal
ats6
Set back signal

Beacons

23 Door release side
24
Station limits

New Features:

In a suitably beaconed route, the Guard will play the correct buzzer signal if the train stops outside the permitted zone at a station.  The route must be equipped as follows:
The Guard will not play a buzzer signal if the train stops outside station limits, so that signal stops will not be affected.

Door Release Indicators

Panel variables

ats14 = 1 when the doors are closed
ats15
= 1 when the left hand doors are released
ats16
= 1 when the right hand doors are released

Keys

ats key J
[8]
release doors (left)
ats key K
[9]
close doors
ats key L
[0]
release doors (right)

New Features:

This is a stub which controls door interlocks and allows for more detailed models of specific door types in future. It is, however, able to drive door release indicators on routes correctly equipped with .beacon 23.  The keys allow the correct indication to be selected manually on startup or after a restart.

Rain and Windscreen Wipers

Panel variables

ats198 wiper switch position, =0 (OFF), 1, 2... up to the number of wiper settings
ats199
wiper position
ats200-255
raindrop animation = 1 when raindrop is visible

Sound variables

ats16 switch sound
ats17
single sweep of wipers on wet windscreen
ats18
single sweep of wipers on dry windscreen
ats19-23
raindrop sounds

Keys

ats key B1
[Home]
wiper on/speed up
ats key B2
[End]
wiper off/speed down

Configurable features (classId = "wiper")

holdPosition
0 or 100 (values >0 are treated as 100; default 0)
parking position of wiper
sweepTimes
time1,time2..., values >0  (default single value of 1000)
time in ms for a single sweep of the wiper
holdTimes
time1,time2..., values >250 (default single value of 250)
corresponding hold times in ms
nDrops
0-50 (default 50)
number of raindrops to use
nDropSounds
0-5 (default 5)
number of drop sounds to use
vFactor
Rain simulation features - see below

lockout


wipeFactor


dryLimit


Beacons

21 optional data from 0-100 gives rain intensity

Features:

Modelling of rain and windscreen wipers is based on code designed and written by O.Saarekas and is used with permission.  However, a number of enhancements and new features have been added:

Wiper speeds and hold times

Wiper speed is configurable up to a maximum of four settings, plus OFF.  Speeds are entered in the configuration file under the attribute sweepTimes as a list of values, each representing the time in milliseconds for a single sweep of the wiper across the screen. The default is a single setting with a sweep time of 1000ms.

For each speed, a hold time is configurable using the attribute holdTimes to create intermittent wiper modes.  Note that even in continuous modes, the minimum hold time is 250ms (see Wiper Animation below).  If more hold times are entered than sweep times, superfluous hold times are ignored; if there are fewer hold times than sweep times, the default hold time of 250ms is used.

Wiper Animation

For better visual effect a minimum pause of 250ms at each end of the wiper's sweep has been introduced: this ensures that the wiper appears to reach the end of its travel on every sweep.  Previously, the wiper could sometimes reverse direction within a BVE frame and appear to miss out the end of its sweep.

Wiper Sounds

Two wiper sounds are supported, one representing the wiper on a wet windscreen, the other the scrape of a wiper on a dry windscreen.  Changeover is controlled by rain simulation variables (see below).

Raindrops

From 0 to 50 (the default) raindrops can be configured using the attribute nDrops: the same drop placement algorithm is used as in OS_ATS_1.3.

Up to five (the default) drop sound channels can be configured using the attribute nDropSounds- they can be aliased to the same or different sound files in the sound.cfg file.  It is strongly recommended that the full five channels be used, otherwise sound may not play correctly at higher rain intensities.

New Rain Simulation Features

A number of the variables used in simulating rain are configurable in this release, to allow us to find the most effective values for them.  It is likely that they will be fixed in future releases.

Speed Dependence

Rain intensity i now increases with speed as:

i = i0 × (1 + vFactor × speed)

where vFactor is a configurable attribute  The default value is 0.05

Raindrop 'lockout'

At high rain intensities, the rain algorithm could reuse a raindrop almost immediately after it had been removed by the wiper, with two undesirable results:
  1. It looked as though the wiper had missed the drop;
  2. The difference in effectiveness between different wiper speeds did not show up well.
To avoid this phenomenon, drops are now locked out of use for a configurable time after being wiped.  The time can be entered in milliseconds under the attribute lockout (default value 1000).

Wiper Sounds

To decide which wiper sound to use, the 'wetness' of the windscreen is modelled, increasing by 1.0 for each drop that falls and being reduced for every sweep of the wiper as

wetnessn+1 = wetnessn × 1/wipeFactor

where wipeFactor is a configurable attribute (default value 2.5).

The value of wetness at which the sound changes from 'wet' to 'dry' is configurable using the attribute dryLimit (default value 2.0).

The intention is that at low rates of rain, the driver will be forced to switch between wiper modes in order to avoid annoying wiper-scrape, introducing an extra level of distraction into the simulation :-)

To help with configuring this feature, an Excel spreadsheet Rain.xls is supplied.  Given a starting value of wetness and the number of drops falling on each sweep of the wipers (a measure of rain intensity and approximately 1 at an intensity of  5), this calculates and displays on a graph:
It can also show the value of dryLimit for easy comparison.

Head and Tail Lights

Panel variables

ats20 Headlights [ = 0 (off), 1 (day), 2 (marker only), 3 (night) ]
ats21
Taillights [ = 1 when on]

Sound variables

ats24 Generic panel switch sound

Keys

ats key F
[4]
Toggle taillights
ats key G
[5]
Cycle headlights (works as a rotary switch)

Starting states for the Head and Tail lights:

Starting state OFF

Starting State NEUTRAL


Horn Lever Animation

Panel variables

ats24 = 0 (forward), 1 (off, centred), 2 (back)

Configurable features (classId = "horn")

tForward
(default 1500)
time lever remains forward before automatically recentering
tBack
(default 1500)
time lever remains back before automatically recentering

Features:

The horn lever moves when either of the BVE horn keys is pressed and returns to its off position automatically after a time which can be separately configured to suit the horn sounds used with the train.



This document © Simon Gathercole 2005
Date of issue 20/05/05