Vehicle Files

Creating Vehicles for Virtual Sailor

Virtual Sailor supports many types of vehicles, all types are made of the following parts :

Vehicle configuration file
3D mesh file and attached textures
Optional instrument panel
Optional weapons
Optional lights
Optional smokes
Optional flames
Optional effects
Optional sound files
Optional elements
Optional components

Vehicles can be made standard or customized, the standard vehicles are created by the program using a simple vehicle configuration file, this file defines only the basic properties of the vehicle, and not the actual part breakdown, and properties of each part.

Before going in depth into vehicle design please see this tutorial.

When you define elements or components for the vehicle, the vehicle becomes customized and allows you to define each part in great detail, the following sections explain the basic vehicle types and the ways to customize them and make your vehicle highly accurate.

The Vehicle Configuration File

The vehicle configuration file defines the basic vehicle properties, for each vehicle type there are basic properties you can set using this file, the program reads this file and stores all the parameters read, for the missing parameters the program uses default values.

This is the list of all properties and their meanings:

[type] – type of vehicle

hang_glider – hang glider
para_glider – para glider
ultra_light – ultra light ( light plane )
glider – glider ( plane without engine )
airplane – airplane ( fixed wing airplanes )
trike – microlight ( powered hang glider mounted on wheels )
paraplane – paraplane ( powered paraglider mounted on wheels )
autogyro – auto gyro ( free rotatiing rotor with after propeller )
helicopter – helicopter ( powered main rotor with tail rotor )
automobile – car or land vehicle
boat – boat ( powered boat without sails )
submarine – submarine ( submersible without sails )
balloon – hot air balloons and dirigibles

[mass] – mass of vehicle (kg)
[crew_mass] – mass of boat crew (kg ) moves with point of view and effects boats weight and balance.
[has_catamaran] – boat is catamaran or not ( 1 or 0 )

[pilot_name] – name of animated pilot to use
[eject_name] – name of ejection parachute to use

[wing_sur] – wing area (m^2)
[wing_span] – wing span (m)

[wing_dihedral] – wing dihedral angle (rd)
[wing_height] – wing height above cg (m) – [hang glider, trike]

[wing_al0] – wing install angle (rd)
[wing_alm] – wing stall angle (rd)

[wing_cla] – wing lift line slope (cl/rd)
[wing_cd0] – wing zero incidence drag coefficient
[wing_cdi] – wing induced drag coefficient

[cd_flaps] – added drag coefficient with flaps fully extended
[al_flaps] – added AOA with flaps fully extended

[cd_spoilers] – added drag coefficient with spoilers fully extended
[al_spoilers] – added AOA with spoilers fully extended

[cd_gear] – added drag coefficient with gear fully extended

[body_area] – body cross section area (m^2) – [gyro, helicopter, car, boat]
[body_cd] – body drag coefficient – [gyro, helicopter, car, boat]

[cockpit_size] – size of shadow area around cockpit (m)
[scale_factor] – scale factor – use 0.3048 to convert model from ft to m
[auto_pilot_gain] – auto pilot gain factor of control ( 0 to 1 ) to reduce turn rates use smaller values.

[boat_length] – boat waterline length (m)
[boat_alt] – boat draft, height of waterline above keel, (m)
[boat_cgy] – height of boat CG above waterline (m)

[hydro_cruise] – cruise speed of boat with hydrofoils (kt) use 0 for boats without hydrofoils.
[hydro_angle] – angle of pitch for boat with hydrofoils (rd ) use 0 for flat planning.
[hydro_alt] – height of waterline above keel for boat at cruise speed (m)

[clmax_sailb] – maximum lift coefficient allowed for main sail of boat ( 0 – 5 ) for square rigger use small values.
[clmax_sails] – maximum lift coefficient allowed for jib sail of boat ( 0 – 5 ) for square rigger use small values.

[has_sails] – boat has sails or not (1 or 0)

[sur_sailb] – area of main sail of boat (m^2)
[sur_sails] – area of jib sail of boat (m^2)
[sur_spin] – area of spinnaker of boat (m^2)

[pilot_x] – pilot x position on body (m)
[pilot_y] – pilot y position on body (m)
[pilot_z] – pilot z position on body (m)

[main_gear_x] – main gear x position on body (m)
[main_gear_y] – main gear y position on body (m)
[main_gear_z] – main gear z position on body (m)

[nose_gear_y] – nose gear y position on body (m)
[nose_gear_z] – nose gear z position on body (m)

[gear_min_kf] – minimal gear friction coefficient
[gear_max_kf] – maximal gear friction coefficient

[has_skids] – vehicle has skids instead of wheels (0 or 1)
[has_floats] – vehicle has floats instead of wheels (0 or 1)

[camera_x] – camera x position on pilot [ hang glider, paraglider ] or on body (m)
[camera_y] – camera y position on pilot [ hang glider, paraglider ] or on body (m)
[camera_z] – camera z position on pilot [ hang glider, paraglider ] or on body (m)

[wing_x] – wing x position on body (m) – [ paraglider ]
[wing_y] – wing y position on body (m) – [ paraglider ]
[wing_z] – wing z position on body (m) – [ paraglider ]

[cable_x] – cable attachment point x position on body (m)
[cable_y] – cable attachment point y position on body (m)
[cable_z] – cable attachment point z position on body (m)

[hook_x] – hook attachment point x position on body (m)
[hook_y] – hook attachment point y position on body (m)
[hook_z] – hook attachment point z position on body (m)

[vario_climb] – variometer climb threshold (m/s)
[vario_sink] – variometer sink threshold (m/s)

[sink_max] – maximum sink rate (m/s)
[max_tilt] – maximum heel allowed for boat (rd)

[max_g] – maximum g load (g)
[min_g] – minimum g load (g)

[has_engine] – vehicle has engine ( 0 or 1 )
[engine_type] – type of engine

prop – constant pitch propeller
vpitch – variable pitch propeller
jet – turbo jet
jetab – turbo jet with after burner
rocket – rocket engine
car – car engine
boat – boat engine
amphib – amphibian engine

[fuel_time] – fuel time at max_rpm (sec)
[rpm_max] – maximal rpm at full throttle (rpm)
[rpm_min] – minimal rpm at idle (rpm)

[motor_hp] – engine effective power (hp) – per engine
[prop_diam] – propeller diameter (m) – per engine
[max_thrust] – maximum thrust (newton) – per engine
[max_altitude] – altitude limit for air breating engine (m)

[num_props] – number of engines [hang glider, trike, paraglider, paraplane, plane, gyro]
[ccw_left] – left propellers rotate counter clockwise ( 0 or 1 )
[ccw_right] – right propellers rotate counter clockwise ( 0 or 1 )
[ccw_rotor] – helicopter rotor rotates counter clockwise ( 0 or 1 )

[has_gear] – vehicle has landing gear [ also when loading gear.x ]
[has_flaps] – vehicle has flaps [ also when found in model ]
[has_brakes] – vehicle has spoilers [ also when found in model ]
[has_rcs] – vehicle has reaction control system [ plane out of atmosphere ]
[has_vector] – vehicle motor has thrust vectoring ( 0 or 1 )

[panel_name] – name of panel

[panel_x] – panel x position on body (m)
[panel_y] – panel y position on body (m)
[panel_z] – panel z position on body (m)

[panel_scale] – panel scale
[panel_alfa] – panel pitch angle
[panel_beta] – panel yaw angle
[panel_gama] – panel roll angle

[num_blades] – main rotor blades count [autogyro, helicopter ]

[rotor_radius] – main rotor radius (m) [autogyro, helicopter ]
[rotor_chord] – main rotor chord (m) [autogyro, helicopter ]

[rotor_height] – main rotor height above cg (m) [autogyro, helicopter ]
[rotor_tilt] – main rotor control tilt angle (rd) [autogyro, helicopter ]

[rotor_mass] – main rotor mass (kg) [autogyro, helicopter ]
[spool_rpm] – main rotor spool rpm [ autogyro ]

[rotor_cla] – main rotor lift line slope (cl/rd) [autogyro, helicopter ]
[rotor_cd0] – main rotor zero incidence drag coefficient [autogyro, helicopter ]
[rotor_cdi] – main rotor induced drag coefficient [autogyro, helicopter ]
[rotor_al0] – main rotor install angle (rd) [autogyro, helicopter ]
[rotor_alm] – main rotor stall angle (rd) [autogyro, helicopter ]

[has_deck] – vehicle has deck ( landable by other vehicles ) [ boat ]
[deck_alt] – deck height above cg (m) [ boat ]
[hide_water] – hide water in cabin [boat] at [deck_alt] level

[is_hot_air] – type of balloon ( 1 – hot air 0 – dirigible )
[input_rate] – heating rate (kelvin/sec) or fill rate (m^3/sec)
[output_rate] – cooling rate (kelvin/sec) or drain rate (m^3/sec)
[volume] – volume of gas (m^3)

[doors_angle] – angle of swing doors rotation (rd)
[doors_move] – range of sliding doors movement (m)
[sweeps_angle] – angle of swepts wings rotation (rd)

[thrust_angle] – angle of thrust vectoring for boats with outboard engines ( attach_props = 1)
[steer_angle] – angle of steering for nose wheels and fronts wheels of cars (rd)

The X Files

Virtual Sailor uses the DirectX format for 3D model files, typically these files are generated by 3D modeling software and saved in the very popular 3DS format, from this format they can be converted to DirectX files using a converter created by Microsoft called Conv3ds, conv3ds can be downloaded here.

Conv3ds and scenery tools

Some modeling software have their own X Files exporters, for example if you are using the excellent 3D Studio Max download this plugin.

Panda Exporter for 3D Studio 9

The vehicle mesh file – vehicle.x

This file contains the 3D model of the vehicle itself, including its moving parts, any moving part you wish to have, should be named according to the following list of tags, the parts should have their axes defined according to actual rotation axis for this part.

The program seeks also other names of files for compatibility, possible names are plane.x, boats.x, body.x.

The program supports also one optional LOD file which is used when the vehicle is far from the observer, this file is called simple.x.

The program supports also one optional DAMAGE file which is used when the vehicle is broken, this file is called broken.x.

The program supports also one optional LIGHTS file which is used for glowing parts at night, this file is called lights.x.

The program supports also one optional ANIMATED file which is used for animated parts, this file is called anim.x.

The program supports also one optional GEAR file which is used for landing gear, this file is called gear.x.

For paragliders only the program loads also an animated mesh file called wing.x.

The vehicle mesh files are searched for moving parts, part names are identified accoring to name tags, each name is asscociated with a moving part and a specific function, the following table shows the possible name tags and their functions.

This file contains the 3D model of the vehicle including moving parts, each moving part should be named according to a specific list of tags, the parts should have their axes defined according to the rotation axis for this part, as seen in the image below.

The Boat model should be placed pointing to the Y axis, and its center is along the keel at middle of ship.

The Plane model should be placed pointing to the Y axis, and its center of gravity used as origin.

elevonl – left elevon
elevonr – right elevon

stickl – left stick
stickr – right stick

wheell – left control wheel
wheelr – right control wheel

stwheel – left steering wheel
stwheer – right steering wheel

spropl – left prop
spropr – right prop

fpropl – fast left prop
fpropr – fast right prop

doorl – left swinging door
pdoorl – left sliding door

doorr – right swinging door
pdoorr – right sliding door

sweepl – left swept wing
sweepr – right swept wing

lightsl – lit/unlit part
lightsr – lit/unlit part
lightsm – lit/unlit part
lightst – lit/unlit part

srotorl – left main rotor
frotorl – fast left rotor

strotorl – left tail rotor
ftrotorl – fast left tail rotor

srotor – main rotor
frotor – fast main rotor

srotorr – right main rotor
frotorr – fast right rotor

strotor – tail rotor
ftrotor – fast tail rotor

strotorr – right tail rotor
ftrotorr – fast right tail rotor

strotorl – left tail rotor
ftrotorl – fast left tail rotor

pedalr – right pedal
pedall – left pedal

pedaltr – right pedal
pedaltl – left pedal

thrott – trottle handle
throt1 – trottle handle
throt2 – trottle handle
pthrot – throttle push handle

sproptl – tip left prop
fproptl – fast tip left prop

sproptr – tip right prop
fproptr – fast tip right prop

flexwing – a hang glider type wing
parawing – a paraglider type wing

handlel – left paraplane handle
handler – right paraplane handle

brakel – left airbrake
braker – right airbrake

brakeh – brake handle
cableh – cable release handle
pcable – cable release pull handle

flapl – left flap
flapr – right flap
flaptl – right flap
flaptr – left flap

spoill – left spoiler
spoilr – right spoiler

spoiltl – left spoiler
spoiltr – right spoiler

string – yaw string

radarl – rotating radar
radarr – rotating radar

vtaill – left V tail
vtailr – right V tail
collect – collective handle

flamel – left burner or jet flame
flamer – right burner or jet flame
flamem – middle burner or jet flame
flameu – upper flame
flamed – lower flame

burnerh – gas burner handle
canopyh – canopy gas release value

flapsh – flaps extraction handle
gearh – gear extraction handle
trimh – trim adjustment handle

pitch – propeller pitch handle
ppitch – propeller pitch push handle

mixt – fuel mixture handle
pmixt – fuel mixture push handle

steer – plane wheel steering
steer1 – car wheel steering
steer2 – car wheel steering
steer3 – car wheel steering

wheel1 – plane or car wheel
wheel2 – plane or car wheel
wheel3 – plane or car wheel
wheel4 – plane or car wheel

wheel5 – plane or car wheel
wheel6 – plane or car wheel
wheel7 – plane or car wheel
wheel8 – plane or car wheel

sailb – main sail
sailbl – mail sail on the left
sailbr – main sail on the right
sailbf – main sail folded

sailb2 – main sail
sailbl2 – mail sail on the left
sailbr2 – main sail on the right
sailbf2 – main sail folded

sailb3 – main sail
sailbl3 – mail sail on the left
sailbr3 – main sail on the right
sailbf3 – main sail folded

sails – jib sail
sailsl – jib sail on the left
sailsr – jib sail on the right
sailsf – jib sail folded

sails2 – jib sail
sailsl2 – jib sail on the left
sailsr2 – jib sail on the right
sailsf2 – jib sail folded

sails3 – jib sail
sailsl3 – jib sail on the left
sailsr3 – jib sail on the right
sailsf3 – jib sail folded

spin – skinnaker sail

Box 0.25 0.1 bump.jpg
Loft 0.25 0.1 bump.jpg
rudder 0.25 0.1 bump.jpg
pedal 0.25 0.5 bump.jpg
elevator 0.25 0.1 bump.jpg
aileron 0.25 0.1 bump.jpg
flap 0.25 0.1 bump.jpg
Sphere 0.25 0.1 bump.jpg
Mesh 0.25 0.1 bump.jpg
Cylinder 0.5 0.0 bump.jpg

// Effect file structure

number of parts

part name reflection bump bump_texture
part name reflection bump bump_texture
…

Each line contains a name of part to be searched in the mesh file or weapons and the reflection scale and bump scale to be applied on this part, the part name can be a partial name, for example the name Box will be applied to Box01, Box02 etc..

The reflection scale gives a value between 0 and 1 where 0 is not reflective and 1 is fully reflective ( mirror ), the bump scale gives the bumpiness factor where 0 means smooth and 1 means rough.

The bump texture name gives the name of bump texture to load for this part, customized bump textures should exist inside the vehicle directory, or inside the graphics directory.

You can use a custom bump texture for each part of the vehicle giving it a very detailed appearance with less polygons, a good example of effects can be seen in the image below.

The Lights file

The lights filelights.cfgcontains the position, size and type of lights defined for the vehicle when lights are turned on, a typical example of this file is seen below.

4 [lights_num]

Red [light_name]
0.1 [light_scale]
-4.0 [lig
0.4 [light_y]
0.2 [light_z]

Green [light_name]
0.1 [light_scale]
4.0 [light_x]
0.4 [light_y]
0.2 [light_z]

Strobe [light_name]
0.2 [light_scale]
0.0 [light_x]
1.25 [light_y]
-2.7 [light_z]

White [light_name]
0.2 [light_scale]
0.0 [light_x]
-0.7 [light_y]
2.0 [light_z]

The first line of the file contains the number of lights to have, the other lines contain data about each light, up to 64 lights can be defined for a vehicle.

The types of lights available are;Red, Green, White, Yellow, Blue,each light type has a visibility sector typical to navigation lights, these sectors are used for boats and aircraft, light names can have a combination of the type and a modifier, the modifier types areStrobe, Beam, Brakes, Blinker, Reverse, Omni, Flat, Fore, Back.( for example ForeWhite, BackWhite, FlatWhite, etc.. )

The other parameters for each light include; scale, x, y, z position.

The sectors used for these lights are:

Red – portside
Green – starboard side
White – fore or aft
Yello – yellow light
Blue – blue light
Strobe – blinking light
Beam – light beam with cone
Brakes – car red brake lights
Blinker – car orange blinker
Reverse – car white reverse
Fore – forward
Back – backwards
Omni – omni directional
Flat – forward or aft flat

A typical view of navigation lights can be seen in this image.

note: You can measure the position you wish to set your lights using the views dialog,
this dialog contains three sliders and x,y,z coordinate display.

The Smokes file

The smokes filesmokes.cfgcontains the position, size and color of smokes defined for the vehicle when the engine is turned on, a typical example of this file is seen below.

2 [smokes_num]

0.5 [smoke_x]
-0.6 [smoke_y]
-6.5 [smoke_z]
225 [smoke_r]
225 [smoke_g]
225 [smoke_b]
0.8 [smoke_s]

-0.5 [smoke_x]
-0.6 [smoke_y]
-6.5 [smoke_z]
225 [smoke_r]
225 [smoke_g]
225 [smoke_b]
0.8 [smoke_s]

The first line of this file gives the number of smoke sources, up to 12 smoke sources can be defined for a vehicle.

The color of the smoke is given in red, green, blue values, the size is given in meters.

A typical view of vehicle with smoke source can be seen in the following image.

The Flames file

The flames fileflames.cfgcontains the position, size and color of flames defined for the vehicle when the engine is turned on, a typical example of this file is seen below.

3 [flames_num]

-1.52 [flame_x]
0.6 [flame_y]
-9.0 [flame_z]
3.0 [diameter]
2500 [temperature]
1 [has_smoke]

1.52 [flame_x]
0.6 [flame_y]
-9.0 [flame_z]
3.0 [diameter]
2500 [temperature]
1 [has_smoke]

0.0 [flame_x]
3.53 [flame_y]
-8.5 [flame_z]
3.0 [diameter]
2500 [temperature]
1 [has_smoke]

The first line of this file gives the number of flames, up to 12 flames can be defined for a vehicle.

The color of the flame is given by its temperature in Kelvin, the size is given in meters, the flame can have also a smoke source which gives a lengthy trail instead of smoke particles.

A typical view of vehicle with flames can be seen in the following image.

The Trails file

The trails filetrails.cfgcontains the position and size of contrails emitted from the vehicle when flying in fog, a typical example of this file is seen below.

2 [trails_num]

-5.95 [trail_x]
-0.35 [trail_y]
-3.26 [trail_z]
0.2 [diameter]

5.95 [trail_x]
-0.35 [trail_y]
-3.26 [trail_z]
0.2 [diameter]

The first line of this file gives the number of trails, up to 12 trails can be defined for a vehicle, next comes the position and diameter of the trail to be emitted.

Normally these trails should be emitted from wing tips and flaps when extended.

Vehicle Sound Files

The default sounds are located inside the sounds directory of the program, however, each vehicle can have custom sounds and should have custom sounds whenever possible, these sounds should be places inside the vehicle directory itself.

Sound files should be mono sounds, 22 kHz, 16 bit sounds, other formats can be loaded as well.

The following sound files are loaded for each vehicle:

wind.wav – normal wind sound of vehicle in air.
wave.wav – normal water sound of vehicle in water.
engine.wav – normal engine sound when engine in nominal rpm.
start.wav – sound of engine start.
stop.wav – sound of engine shutdown.
rotor.wav – sound of rotary craft in flight.
flow.wav – airplanes afterburner,
thrust.wav – RCS thrusters, boat bow or aft thrusters, balloons and subs filling or dumping gas.
thruster.wav – sound of bow or stern thrusters.
walk.wav – walking sound of hang glider or paraglider pilot.
stall.wav – stall warning sound.
break.wav – breaking sound of vehicle when crashing.
skid.wav – tires skidding on ground.
bounce.wav – wheels bouncing on ground.
splash.wav – vehicle splashing into water.
bwave.wav – wave splashing upon the bow of a ship.
bang.wav – vehicle collision with other vehicle or object.
explode.wav – explosion sound for vehicle being hit or exploding.
beep.wav – variometer sound, or instrument beep sound.
turf.wav – sound of wheels rolling on ground.
stress.wav – vehicle in critical stress, close to breaking.
buzzer.wav – variometer sink warning.
chute.wav – ejection seat sound.
chuter.wav – parachute release sound.
flutter.wav – sound of sails fluttering.
winch.wav – sound of winches for sails manipulation.
horn.wav – sound of horn.
inside.wav – optional ambient sound inside vehicle.
outside.wav – optional ambient sound outside vehicle.

The following sections explain the details of the panels, weapons and vehicle customization.