*******************************************************************************
*                                                                             *
* VEHICLE DYNAMICS                                                            *
*                                                                             *
* This is a demonstration of the MathEngine Dynamics toolkit being used in a  *
* vehicle dynamics application. Each vehicle is constructed from 5 rigid      *
* bodies. 1 for the chassis and 1 for each wheel. Each wheel is jointed to    *
* the chassis with a simple suspension joint constraint that behaves similarly*
* to a conventional spring/damper system with hard travel limits. The engine  *
* is a simple torque motor applied to the rear wheels. The collision detection*
* for each vehicle consists of an aligned bounding box for the chassis and a  *
* sphere for each wheel. Detection against the landscape ties in with the     *
* RenderWare sphere-to-BSP function to generate a list of polygons to check   *
* against. The 'Tyre model' is implemented in the form of a callback from the *
* collision detection. For every contact between the wheels and the world,    *
* the callback sets up the constraint friction parameters. Polygon texture is *
* used to discriminate between on or off the track. Each vehicle is modelled  *
* in the same way although their individual data may be different. The        *
* computer controlled vehicles endeavour to follow a preset course around the *
* track.                                                                      *
*                                                                             *
* The following is an explanation of all the various keywords used in the     *
* script files for car.exe . Try changing some of the data parameters to see  *
* the effects on handling. This is NOT a definitive set of vehicle parameters *
* and are specific to this application only. They do not have any predefined  *
* relationship to the dynamics toolkit itself. Other MathEngine vehicle demos *
* may have different input parameters. There is also very little error        *
* checking on the script files so it is recommended that backup copies are    *
* saved for reference.                                                        *
*                                                                             *
*******************************************************************************

*******************************************************************************
Configuration file script keywords 
*******************************************************************************

Keyword:  PC_VIDEOMODE 
Parameters: Horizontal res, Vertical res, Colour depth
Description:On PC you can set the default screen video mode which is displayed 
    in the video mode selection box. If the video mode isn't available,
    the selection box will default to its usual settings.

Keyword:  SHAPE_DIR
Parameters: Shape directory path relative to executable
Description:This is the path to the world .BSP file.

Keyword:  TEXTURE_DIR 
Parameters: Texture directory path relative to executable
Description:This is the path to all textures used in the world BSP

Keyword:  WORLD_BSP
Parameters: World BSP filename
Description:Specify the world .BSP file

Keyword:  LIGHTS_FILE 
Parameters: Dynamic lighting filename
Description:Add additional lighting to the world at run time.

Keyword:  TRACKS_FILE
Parameters: Track filename
Description:Specify routes around the track that can be assigned to drivers

Keyword:  REAR_VIEW_MIRROR 
Parameters: X pos,Y pos,W width ,H height as fractions of screen resolution
Description:Experimental rear view mirror. Only works properly on PC.

Keyword:  DRIVER 
Parameters: Vehicle description file, Track, Start point
Description:Use multiple entries to create a list of cars. They can share .veh 
    files or each have a unique one. Assign a route with a label that 
    corresponds to a track defined in the tracks file. Specify a start
    point on the track. If you specify the same startpoint for more 
    than one driver then the vehicles will start on top of each other.

Keyword:  PLAYER_CAR 
Parameters: Driver ID that player is initialized to 
Description:An ID of 1 indicates the first car on the list will be given to the
    player.An ID of 0 will not initially allocate any car to the player.
    Player control of a vehicle can still be achieved in the game by using
    the 'M' key.

*******************************************************************************
Vehicle description file keywords
*******************************************************************************

Keyword:  SHAPE_DIR
Parameters: Shape directory path relative to executable
Description:This sets the current path the .DFF files. If shapes are stored in
    multiple locations then a SHAPE_DIR entry will be required for each
    location.

Keyword:  TEXTURE_DIR 
Parameters: Texture directory path relative to executable
Description:This sets the current path to all textures. If there are multiple 
    texture locations then a TEXTURE_DIR entry will be required for each 
    location.

Keyword:  CMPT_SHAPES
Parameters: Front Right, front left, rear right, rear left, chassis (.DFF files)
Description:Add the shape files for the vehicle components in the above order

Keyword:  INTERNAL_SHAPE 
Parameters: Internal vehicle shape file
Description:If required, a separate shape can be used for the internal F6 view

Keyword:  EXTERNAL_TEXTURE
Parameters: External texture map file
Description:Change the colours of vehicles to help identify them

Keyword:  STEERING_GAINS 
Parameters: Control gain values - Proportional input, Time compensated prop input,
    Ang. vel. input,  Slip input 
Description:Proportional input is based on the error in heading
    Time comp. prop. input is scaled by the current frame time
    Ang. Vel. Input is based on the turn rate of the car and scaled by
    the current frame time.
    Slip input is based on the lateral slip velocity of the chassis 

Keyword:  THROTTLE_GAINS
Parameters: Throttle control gain - Proportional input
Description:Proportional input is based on the speed error

Keyword:  CAR_DATA_FILE
Parameters: Data file of car parameters
Description:Cars can share the same data or each have unique files

*******************************************************************************
Vehicle data file keywords
*******************************************************************************

Keyword:  WHEEL_BASE  
Parameters: Wheel base
Description:Distance between front and rear axles

Keyword:  WHEEL_TRACK 
Parameters: Front track, rear track
Description:Distance between the two front wheels & the two rear wheels

Keyword:  WHEEL_RADIUS
Parameters: Front wheel radius, rear wheel radius
Description:Enter the wheel radii - Graphical representation only

Keyword:  WHEEL_MASS  
Parameters: Wheel mass
Description:At the moment all wheels are assumed to have the same mass. Moments 
    of Inertia based on front wheel radius.

Keyword:  CHASSIS_HEIGHT_OFF_GROUND
Parameters: Equilibruim chassis position above ground plane
Description:This is the vertical position of the centre of the chassis shape

Keyword:  CHASSIS_X_POS   
Parameters: Chassis position from midpoint between front and rear axles
Description:This is the X position of the centre of the chassis shape

Keyword:  CHASSIS_MASS    
Parameters: Chassis mass
Description:Chassis mass, surprisingly enough!

Keyword:  CHASSIS_COM_UP_OFFSET 
Parameters: Chassis c.g. vertical offset
Description:This is the vertical offset of the chassis centre of mass relative 
    to the centre of the chassis shape.

Keyword:  CHASSIS_COM_FWD_OFFSET    
Parameters: Chassis c.g. forward offset
Description:This is the X direction offset of the chassis centre og mass relative
    to the centre of the chassis shape.

Keyword:  CHASSIS_COLL_BOX
Parameters: Length, Width, Height of the chassis collision box
Description:The box is centred on the centre of the chassis shape. The wheel
    spheres use to wheel radius for their dimension.

Keyword:  SUSP_TRAVEL       
Parameters: Front suspension travel, rear suspension travel
Description:This is the total travel between the upper and lower limits of the
    suspension.

Keyword:  SUSP_LEVEL_TWEAK      
Parameters: Chassis equilibrium level adjustment
Description:Use this parameter to adjust the forward / back angle of the chassis 
    if necessary.

Keyword:  SUSP_DAMPING    
Parameters: Front suspension damping, rear suspension damping
Description:A value of 1 represents critical damping. 0 is not quite undamped due 
    to enegry losses within the integration.

Keyword:  SUSP_EQUILIBRIUM    
Parameters: Front suspension equilibrium position, rear suspension equilibrium 
    position
Description:This is equilibrium position of the joint as a fraction of the 
    travel, measured from the bottom.

Keyword:  SUSP_Z_TO_S     
Parameters: Front Z_to_S, rear Z_to_S
Description:This value is the fraction of suspension travel required to generate 
    twice the equilibrium load. This is effectively the suspension
    stiffness.

Keyword:  SUSP_SOFT
Parameters: front suspension softness, rear suspension softness
Description:This is the softness of the suspension end stops. 

Keyword:  MAX_STEERING_ANGLE  
Parameters: Maximum steering angle of front wheels
Description:The is the maximum slow speed angle that the wheels can be steered 
    to. The maximum value is reduced as the speed qoes up.

Keyword:  TORQUE_MULT       
Parameters: Engine torque multiplier
Description:This affects both the acceleration and top speed of the vehicle.

Keyword:  BRAKE_MULT        
Parameters: Brake multiplier
Description:Heavier vehicles will require more braking force

Keyword:  TYRE_TRACK_PROPS  15000 0.1 0.0 0.5 0.02 0.02 0.0001 0.0001
Parameters: Maximum limiting friction force,
    Camber zone over which max. force applies (cos(angle))
    Minimum limiting friction force at cutoff
    Camber angle at which min. force is reached (cos(angle))
    Max. lateral slip velocity
    Max. rolling slip velocity
    Min. slip velocity
    Rate at which slip increases with wheel tangential speed
Description:These parameters apply to the contact constraint generated between 
    the wheels and the track textures. The first 4 control the maximum
    limiting friction force and it's variation with camber. The second
    4 control the slip parameter and it's dependence with wheel rpm.

Keyword:  TYRE_GRASS_PROPS  
Parameters: See TYRE_TRACK_PROPS 
Description:Same as TYRE_TRACK_PROPS but apply to everything except track 
    textures.

*******************************************************************************
Tracks File keywords 
*******************************************************************************

Keyword:  TRACK
Parameters: Track name label
Description:The label is used the .cfg file to assign a track to a driver. Max 
    label length is 50 characters. Max 10 track definitions per file. 
    Max 50 points per track

Keyword:  POINT
Parameters: Point id, Next point id, X position, Y position, speed, 
    Outer tolerance, Inner Tolerance.
Description:The first point should be the next point id for laast point to make
    a loop circuit. The speed is the approximate speed desired at each 
    point. To pass a point, the vehicle must be either a) inside the 
    inner tolerance for that point or b) inside the outer tolerance and
    have a significant velocity component directed towards the next 
    point.

Keyword:  END_TRACK
Parameters: NONE
Description:End the track description and Initialise the course

*******************************************************************************
Lighting File keywords - included for completeness but purely asthetic
*******************************************************************************

Keyword:  Light
Parameters: None
Description:Starts a new light description

Keyword:  Type  
Parameters: AMBIENT, DIRECTIONAL, SPOT, POINT or SPOTSOFT
Description:Defines the type of light this is.

Keyword:  Position
Parameters: world X,Y,Z position
Description:Position of light in world

Keyword:  Direction
Parameters: Light direction in degrees
Description:Not applicable to all light types

Keyword:  Pitch 
Parameters: Light pitch in degrees
Description:Not applicable to all light types

Keyword:  RGB  
Parameters: Light RGB values
Description:These values are relative and not limited to 255

Keyword:  Alpha   
Parameters: Light colour alpha value
Description:I don't know if this has any effect

Keyword:  Radius  
Parameters: Light radius
Description:Distance to which lights effect is felt

Keyword:  Cone    
Parameters: Angle in degrees
Description:Light cone angle

Keyword:  World   
Parameters: 1 or 0 
Description:Apply this light to the world BSP (TRUE/FALSE)

Keyword:  Atomics 
Parameters: 1 or 0
Description:Apply this light to the individual shapes (TRUE/FALSE)

Keyword:  EndLight
Parameters: None
Description:Finish light definition and actually create light  