So, you want to build a train for BVE4?


Ok, by now your train is starting to come together.  You've got the images and the physics sorted, so now we can start to tie it all together.  To do this we need config files, which you can easily distinguish because they have filetype .cfg, and if you look in a typical train directory you'll find four of them:

I'm going to refer to the class 323 for BVE4 as an example this time.

1. ats.cfg  - this tells BVE4 which plugin the train is using to control ATS functions, and just contains just one line - the name of the plugin file, in this case UKMUt.dll, for example.
2. one for the plugin:  in this case, it's called UKMUt.dll.  This contains the specifications for things controlled by the plugin.  In the case of the 323, it reads like this:

blower.startDelay=-1890
blower.endDelay=1890
door.openDelay=3848
door.closeDelay=7094
pickup.panUpDelay=4050
pickup.position=30.0;
pickup.pArcDry=10;
pickup.pFailArc=40;
pickup.pResetFail=25;
wiper.sweepTimes=1000,500
wiper.holdTimes=0,0

These settings vary from plugin to plugin and will be covered in detail later.  As with most of BVE trainbuilding, you can often find out how things work by studying other trains and the config files for them.

3. panel2.cfg - this is the big one, which has almost everything in it, barring the sounds.  In particular this is the one that controls all the graphics, so we'll look into it in some detail.

Here's the beginning of the file:

Version 1.0

;CLASS 323 PANEL BVE4.1
;(c) S.Green 2004,2005
;
; Modified (c) S.Gathercole 2004,2005
; Modified AWS, added DRA, TPWS, Wiper, Switches

[This]
Resolution = 1024
Left = 0
Top = 0
Right = 1280
Bottom = 790
DaytimeImage = d3d\panel2.bmp
NighttimeImage = d3d\panel2_n.bmp
TransparentColor = #0000FF
Center = 500, 275
Origin = 540, 230 


Note the bits near the top with semi-colons as the first character of the line, these are comments - any line with a ; at the beginning is ignored when the game is run.  The next bit is the definition of the panel image.  The lines in [square brackets] identify the item being defined.  Normally, BVE4 trains use Resolution = 1024.  The next 4 lines are the size of the (virtual) screen or viewport.  Notice that the width is defined as 1280, whereas your panel image is likely 1024x1024.  There's a reason for that - in this case, there's a 256x1024 graphic with the simple operating instructions for the trin in it, which is displayed on the extreme right.  On a 1024-wide monitor or window, you can scroll over to it, then scroll back and hide it from view.
Notice also that the "Bottom = " line isn't 1024.  This is limiting the view - chances are, that on this train the cab image is not 1024 deep, and so the author decided to limit the depth of the viewport, so that you don't see the filler at the bottom of the screen when you zoom out.  If you look at other trains, you'll find a variety of viewport sizes.
The next 2 lines define the image file to be used.  As you can see, the images in this case are in a "d3d" subdirectory.  Make sure you get them right, or the images won't display.
The next line defines the transparent colour, our old friend #0000FF.  Note that you can use other colours, like black (#000000) but this is not a good idea as then anything in the image that's black will come out transparent, which is why convention favours blue.
The last 2 lines in this bit are "Center" and "Origin".  "Center defines the position of the centre of the panel, in X-Y co-odrinates measured from left and top.  All the co=ordinates work this way.  I think Origin defines where the view is centred when you start BVE, on most trains it's either in the same place as the centre or nearby.

Now, we'll start looking at the rest of the items.  These fall into several categories, and I'll show an example of each.  The first category is items which have a single image - most of these are illuminated lamps which are "off" on the panel image and "on" by overlaying a "lit" image.  Here's an example: the "door closed" light.

[PilotLamp]
Subject = ats14
Location = 818, 516
DaytimeImage = d3d\doorcls.bmp
NighttimeImage=d3d\Doorcls.bmp
TransparentColor = #0000FF
Layer = 5

All this class of items are identified by [PilotLamp].  This item is typical of the class. 
Subject = ats14 - defines the trigger condition which causes the lamp to light.  In this case, it's a plugin function but some functions are part of BVE itself.
Location = X,Y - The location you want the image to display.  This location defines the top left of the image, so you have to take that into account when deciding where to locate it.  The way I do this is to open the panel image in PSP10, then copy and paste the item image as a new selection.  I don't actually drop the selection, just move it to the right place and note the co-ordinates, then cancel the operation.  Make sure, if you do this, that you don't save ANY image files.  When you run BVE you'll undoubtedly find that some of your items are not in the right places, and you'll have to fine-tune the locations.
The next 2 lines are obvious: location of the image files for day and night images.
TransparentColor this time is the one that applies to the image you're turning "on", not the panel image, if it's different.
The last line is "Layer = 5"  There are up to 15 layers.  The panel itself is on layer 0, so anything with a higher number overlays it. Normally, it's not really important which layer things are on, but if you have 2 overlays which overlap you need to get them in the right order.  An example might be a switch which moves and illuminates - it could be done in one layer or you could have one layer for the switch and one for the illumination.  Another thing which is a PilotLamp is the instuction panel, as shown below: this is always on, so the trigger is "Subject = true"

[PilotLamp]
Subject = true
Location = 1024, 0
DaytimeImage = d3d\keys.bmp
NighttimeImage = d3d\keys.bmp
Layer = 1

The next class of item we'll study is the multi-position controls.  These are a class called [DigitalNumber] and the code looks like this:

[DigitalNumber]
Subject = brake
Location = 5, 700
DaytimeImage = d3d/Brake.bmp
NighttimeImage = d3d/Brake_n.bmp
TransparentColor = #0000FF
Layer = 1
Interval = 93

In this case, the subject is a main BVE function, i.e. brake.  Note that this is a single-lever control train, and thus there isn't a separate "power" lever.
Once again, the location is the top left of the image.  The other lines are the same but there's an additional line, which is "Interval = 93".  This is the vertcial repeat interval of the image in the file - the first part of the image goes from 0 to 92, then the next from 93 onwards.  The value of the trigger "brake" defines how many intervals the program counts down to find the correct image to display.  If the file doesn't repeat at exact intervals, or the Interval = is set wrongly, the image will display wrong in BVE.

Before we do needles, theres one other special item in BVE4 and that's the timetable:

[Timetable]
Location = 624,0
Width = 400
Height = 400
TransparentColor = #000000
Layer = 15

This tends to be put on layer 15 to make sure it overlays everything else on the screen.  Choice of where you put it is rather up to you, but it's better to have it in view withotu needing to scroll, so at the top of the screen is a good plan.  In this case, it's placed so as to be in the top right of a 1024-wide window.

The last kind of item in panel2.cfg is  needles.  These are all the animated needles on your train including the wipers, which are treated as a needle by BVE, driven from the plugin.  A typical bit of needle code, again from the 323, is shown below:

[Needle]
Subject = kmph
Location = 508, 583
DaytimeImage = d3d\speed.bmp
NighttimeImage = d3d\speed_n.bmp
TransparentColor = #000000
Origin = 16, 225
Layer = 9
Radius = 37
InitialAngle = -120
LastAngle = 120
Minimum = 0
Maximum = 160
NaturalFreq = 21.3
DampingRatio = 0.6

This is the speeedo needle, as you've probably guessed.  In the case of needles, the co-ordinates are for the centre of the dial.  Needles are often drawn on a black background, as in this case, hence the TransparentColor value.  If your needles are on a blue background, then obviously the TransparentColor is blue, not black.  There are several parameters for needles:
Origin = X,Y - the position of the pivot point in the needle graphic.
Radius = N - the radius of the dial - effecitvely, a scaling factor for the needle to make it fit the scale.  Note that you may need a few goes to get this right as the needle doesn't necessarily fill its image.
InitialAngle and LastAngle = DDD - limits on the needle in degrees; 0 is vertical and negative angles are anti-clockwise.  You can define a needle that goes anticlockwise or clockwise by selecting suitable angles.  Lastangle is not a stop, it's the position that corresponds to Maximum value.
Minium and Maximum = NNN - the values for the Initial and Last angles.  In this case, at 160km/h the needle will point to 120 degrees, but if "kmph" goes higher, so will the needle.
NaturalFreq and DampingRatio define the manner in which the needle responds.  Setting DampingRatio higher will make the needle move more slowly.  Experiment with these to get the kind of behaviour you want, or, if you prefer, copy the values others have used!

All the gauge needles work much the same.  Remember, if you have a dual-needle gauge with concentric needles, then one will be on top of the other.  Make sure you adjust "layer" accordingly.

The special case in needles is the winscreen wipers.  The 323 has a pantographic wiper, which is to say that the wiper blade is arranged to stay more or less vertical throught the sweep.  Wipers vary, some are simple pivoted blades and others are on pantographs.  If we look at the wiper code, we'll see how this works:

;; Wiper & rain
;;
[Needle]
Subject = Ats199
Location = 522, -8160
DaytimeImage = d3d\wiper.bmp
NighttimeImage = d3d\wipern.bmp
TransparentColor = #0000FF
Origin = 16, 5000
Layer = -2
Radius = 8600
InitialAngle = 177.7
LastAngle = 182.3
Minimum = 0
Maximum = 100
NaturalFreq = 22
DampingRatio = 0.8

[Needle]
Subject = Ats199
Location = 522, 480
DaytimeImage = d3d\wiper1.bmp
NighttimeImage = d3d\wiper1n.bmp
TransparentColor = #0000FF
Origin = 8, 512
Layer = -3
Radius = -455
InitialAngle = 225
LastAngle = 130
Minimum = 0
Maximum = 100
NaturalFreq = 22
DampingRatio = 0.8

As with the other needles, the location is that of the pivot point.  The second part is the pivoted arm, and this is placed on layer -3, i.e. behind the main panel image - that way, it appears to be mounted outside the cab, as it should.  In this case, the wiper starts on the right and sweeps to the left.  Minimum and Maximum for wipers (for this plugin, anyway) are 0 and 100.  Note that the wiper speed is controlled in the pluginconfig file, not in panel2.cfg.  I'm not sure, in this case, why the angles and radius are the other way about - I suspect that using
Radius = 455
InitialAngle = 45,
LastAngle = -50,
would work just the same.
The other part of the wiper is the blade, and this, as you can see, is pivoted off in the distance somewhere.  Note, too, that the origin is not within the image.  The blade doesn't actually stay completely vertical, as you can see, it varies by about 4.5 degress.  Note also that, as it should be, it's one layer nearer to the driver.  If you watch this one it's not bad; but in fact, it really should be in 3 parts, if you're aiming for ultra-realistic - the 2 pantograph arms should pivot separately, and the short link at the top should stay attached to the blade.  However, it's not really noticeable when the train's in motion.

Right, that's it for panel2.cfg, except for raindrops.  Raindrops are a complicated issue, as they need to be timed to match the wiper, and they will be done later.

There are 2 more config files to do, sound.cfg and the one for the plugin, and these will be dealt with in part 9.