"Changes.txt"  Ideas for making changes to table entries, or the C-Script. Version 1.1  April 21, 2002 
=======================================================================
Line numbers are given to help locate areas of the script.  They will not be exact,
due to script changes from debugging, etc.  The whole Move_Car.wdl script file
is approximately 1,088 lines long.
Any time a line of script is displayed here, it will be enclosed in brackets, such as:
     [  This is the line of script you would see;   ]
The brackets do not exist in the actual script.  They are used here only to identify 
the line as having come directly from the C_Script file.
============================================================
The Move_Car package contains two C-Script wdl files:
"Move_Car.wdl"  and "Car_Cam.wdl"

The Move_Car.wdl file contains all C-Script instructions for the Player_Car action.
The Move_Car.wdl C-Script is explained in the documentation file, "Script.txt".

The Car_Cam.wdl file contains all C-Script intructions for the camera views.  
The Car_Cam C-Script is explained in the documentation file, "Cam_Script.txt".
______________________________________________________________
TABLE ENTRIES

The "table entries" are all located near the front of the "Move_Car.wdl" file.  (lines 21 -57)
Each table entry has a comment to help explain it's purpose, and how to use it.
Later in the script, you will find variable definitions with comments that end with
"(calculated)".  This means the value for that variable will be calculated later by the 
script, and the result of the calculation will be stored in that variable.  You shouldn't 
try to make any changes to these variables, since your numbers will be overwritten 
when the calculation is done.  However, you can always "read" this information 
and use those values for other purposes.

Usually,  you will want to use the Move_Car package and script for vehicle movement, 
but you might want to change how the vehicle behaves, or even the type of vehicle.
(For tips on using other vehicles, please take a look at the two documentation files, 
"Other_Models.txt" and "Other_Models2.txt".)

Let's first take a look at what makes the vehicle move forward:

ENGINE => GEARs => DIFFERENTIAL => AXLE => WHEELS => ROAD

Changing the horsepower of the engine will make the vehicle accelerate quicker, 
and go faster.  But not as much as you might think!  Other factors work against 
the engine, and reduce it's effective power.  Those things are:

Air Resistance (Drag), Rolling Resistance (friction), Braking (pedal and hand brake),
Engine friction, how much power the engine is actually producing according to the 
accelerator and engine RPMs, gear efficiency, vehicle weight, climbing hills, and 
some power loss when you are turning the vehicle.

All of those factors, working together, affect how fast you can accelerate, how fast
you go, and how quickly you can slow down, or stop.  All of those factors are calculated
in the "Car_Physics" function (line 792), and all of them can be adjusted just by changing
numbers in the "Table Entry Area", or by moving the throttle, or by applying the brakes.

Not all of the physics that affects vehicle motion has been simulated.  For example, the
script does not consider the inertia of the wheels.  It does not simulate the traction or 
"grip" of the wheels with different kinds of road surfaces, or whether the road is dry,
wet, or snowy and icy.  It does not simulate the sideways (lateral) forces on the 
vehicle for skids, or spins.  It treats the vehicle as a "box" and does not calculate
the forces on each of the individual wheels, or their rotation or movement.

The script tries to achieve a balance between a mathematically accurate physics 
simulation, and lower cpu and memory demands, for a more enjoyable experience.  
Some people will want more accuracy and detailed simulation; others will want less
demands on their computer, and higher frame rates.  So please consider this script 
as a "starting point" you can modify, to go in either direction.
__________________________________________________________
What happens when table entries get changed?  What do I need to know when I start
changing things?

Let's take a real example, and change quite a few things!
The Move_Car package comes with settings and table entries that are very close
to that of a Corvette, with a four speed transmission.  If we go to the General Motors
Chevrolet web site, we can get engineering specifications for the performance version
(model 206) of the 2002 Corvette.  So let's plug those numbers in, and see what happens.

Take a look at the Table Entry Area in Move_Car.wdl, which starts at line 25.

(Remember, the brackets "[" and "]" just show what the actual script looks like.)
Example:    [  this is the actual script here;  ]   
The brackets do not actually exist in the C-Script.

We see the following:

   [  var Brake_Torque = 100000;   // Stopping force (arbitrary number)  ]
Let's leave this one alone - it only affects how powerful the brakes are.

    [  var Car_Weight = 3600;       // Total car weight, in pounds  ]
The performance version of the Corvette is about this same weight, so we 
don't have to change this table entry.

   [  var differential_ratio=2.73; // Ratio of the differential gear  ]
The specs show the "axle" is at 3.42, so let's change the differential ratio to this:
   [   var differential_ratio=3.42; // Ratio of the differential gear  ]

   [  var Drag = 0.29;             // Air friction (A Corvettte is 0.29)  ]
The engineering specs for the performance (206) 'vette say 0.31 for drag, so:
   [    var Drag = 0.31;             // Air friction (A Corvettte is 0.29)  ]

   [  var gear_efficiency = 0.8;   // Overall gear efficiency  ]
They don't give any information on gear efficiency, so we will leave this one alone.

   [  var Horse_power = 400;       // Rated enigne horsepower - will be converted to Max_Torq  ]
The horsepower shown is 405@6000 RPM, so let's change Horse_power:
   [  var Horse_power = 405;       // Rated enigne horsepower - will be converted to Max_Torq  ]

   [  var num_gears = 4;           // Number of forward gears (at least 1, but no more than 6) ]
The performance 'vette has 6 forward, so let's change this to 6:
   [   var num_gears = 6;           // Number of forward gears (at least 1, but no more than 6) ]

   [   // Specify actual gear ratios in the Car_Init() function (near the end of this script)  ]
Now we need to jump to line 1050 in function "car_init()" and enter the gear ratios:
The old values were:

   [  gear_ratio[0] = 2.29;     // Reverse gear  ]
   [  gear_ratio[1] = 3.06;     // First gear        ]
   [  gear_ratio[2] = 1.62;     // Second gear   ]
   [  gear_ratio[3] = 1.0;      // Third gear       ]
   [  gear_ratio[4] = 0.8;      // Fourth gear     ]
   [  gear_ratio[5] = 0.0;      // Fifth gear        ]
   [  gear_ratio[6] = 0.0;      // Sixth gear       ]

Now change those values to the ones given by the Chevrolet web site:

   [ gear_ratio[0] = 3.28;     // Reverse gear  ]
   [ gear_ratio[1] = 2.97;     // First gear        ]
   [ gear_ratio[2] = 2.07;     // Second gear    ]
   [ gear_ratio[3] = 1.43;      // Third gear      ]
   [ gear_ratio[4] = 1.00;      // Fourth gear    ]
   [ gear_ratio[5] = 0.84;      // Fifth gear       ]
   [ gear_ratio[6] = 0.56;      // Sixth gear       ]

Make sure you set BOTH "num_gears" and "gear_ratio" when you change the number
of the gears!

Now, let's go back to the "Table Entry Area" and see what else we might want to change.

(line 33)
   [ var wheel_radius_inch = 15.0; // Wheel radius, in inches  ]
Looks like the wheels are still 15 inch tires, so we don't have to change that.
_______________________________
Let's try running the action, and see what kind of results we get.....
_______________________________
Wow!   Not too bad!  On a long straightaway, I buried the speedometer to what looked
like about 165 MPH!  (Don't forget you will lose power and speed if you turn the vehicle.)
The web site says the 2002 Chevrolet Corvette, model 206, has a top speed of 171 MPH.
Maybe with a longer, straighter run, we would have made that top speed...

One problem though, the red line for the 'vette is supposed to be 6,500 RPM.  And we are
pushing that...  Take a look at line 49:
   [ var UpShift = 6000; // Specify RPM to shift to higher gear (+500 if accelerator floored) ]
It looks like it is set a little low. We could change that.  But - we also (in the script) add
500 RPM if the accelerator is "floored".   That is, the throttle is over 90%.  Assuming you 
are trying to get maximum performance, the shift point is actually at about the right place.
_____________________
Next, let's look at line 44:
   [ var Max_RPM = 7000;     // Maximum allowed engine speed  ]
The script will stop the engine from going any faster, if we reach this RPM.  It will also stop
the vehicle from accelerating if the engine is "maxed out".  NOTE:  This does not determine
the top speed of the vehicle, only the top speed of the engine.
If you want, we could change this to 6,500 RPM, to keep the engine from going above the
rated "red line".      Or, we can leave it at 7,000 RPM and let the driver overspeed when 
the forced downshift is activated.  And, we could also then start subtracting engine 
"health points" (or reduce available engine power buy lowering the value in "Max_Torq") 
because the engine was forced to overspeed.   
But, that's your choice!

There now are two things wrong, that we can't fix within the script:
1.  The speedometer for our vehicle only goes to 140 MPH.  The speedometer on a real
     Corvette goes to 200 MPH.
2.  Our tachometer has the "red line" in the wrong place, at 6,000 RPM, instead of 6,500.

The only way we can fix this, is with a "paint" program, and change the graphics.
You can open "tach.pcx" in your paint program, and "move" the red line.  This will
change the display for 1024x768.  If you want the tachometer to display properly in 
other screen resolutions, you will have to change the graphics for those displays as well.
    "tach640.pcx" is for 640x480 screen resolution.
    "tach800.pcx" is for 800x600 screen resolution.

You can make the same changes for the speedometer:
    "speedo.pcx" is for 1024x768 screen resolution.
    "speedo640.pcx" is for 640x480 screen resolution.
    "speedo800.pcx" is for 800x600 screen resolution.

However, if you change the speedometer graphic, so the last number on the speedometer 
is at the same place as 140 MPH, the speedometer needle will have to rotate less, for the 
same speed as it did before.   Let's take a look at the lines of script  that controls the 
rotation of the speedometer needle, starting at line 550, "function sneedle_roll()".  We want 
to adjust the line that determines how far the needle rotates:  (line 552)
   [  sneang = (car_speed-70)*(286/140);  // 286 degrees / 140 mph  ]
The "Speedometer NEedle ANGle" (sneang) is controlled by this one line of script.

The center of the speedometer is at the top.  If the speedometer now goes from 
0 to 200, the center of that rotation is not 70 (as shown in the calculation above), but
the middle will now be 100.  (This is just the way the calculation and the graphic was 
set up, with no rotation of the needle being at the top of the dial.)  So the first part of 
the calculation should read (car_speed-100) to make the needle rotate counter-clockwise 
to where we show zero MPH, when we have zero car_speed.

The speedometer rotates through a total of 286 degrees, from zero to the top speed.
(Again, that is just the way the graphic was drawn.  But that's why the 286 is there.)
But now, the top speed is 200, and not 140.  So if we change the last part of the 
calculation to (286/200), the needle will rotate the correct number of degrees, for each
Mile Per Hour.   So line 552 should now look like this:
     [  sneang = (car_speed-100)*(286/200);  // 286 degrees / 200 mph  ]
Remember - this will only look and work correctly if you have changed the speedometer
graphic to put the top speed (200 mph) where the old 140 mph used to be.  Otherwise, 
the needle will rotate the right amount, but the numbers will be wrong.  
____________________________________________________________
But how about acceleration?
The 'vette web site says the car will do 116 MPH in a quarter mile.  Great!  But I don't
have a quarter mile marked in my level.  
However, the web site also says this model 'vette will do zero to sixty in 3.9 seconds.
That we can check!   Let's run it again, and time it.
________________________________________
Hmmmm.  That wasn't too good.  It looked to me like it took nearly six seconds to get
from 0 to 60 MPH.  So, if the other numbers are correct, how do we fix that?

Our C-Script has a built in "Fudge factor".  This is necessary, since we aren't 
simulating all of the variables that affect acceleration, such as traction, wheel 
inertia, etc.  So we have this variable called "Accel_Val" or "Acceleration Value".
You can find it in the second table entry area, at line 38:
   [  var Acel_Val = 6;   // Acceleration value - increase to accelerate slower  ]
If we make this number smaller, the vehicle will accelerate faster.  (But you can't make
it smaller than "1".)  Let's try changing it to, say, 4.5.  We now have:
   [  var Acel_Val = 4.5;  // Acceleration value - increase to accelerate slower  ]
Let's give that a try....
___________________________
Still looks a little slow.  Let's try 3.0 for "Accel_Val".
___________________________
Hey - that looked pretty good!  I don't have a stop watch handy, and don't know if 
we found the best number, or not.  You may want to play with "Accel_Val" until
you get the acceleration to work the way you want the vehicle to perform.

What else could we have adjusted?
______________________________
DRAG and ROLLING RESISTANCE

Well, one thing would be (Air) Drag, or Rolling Friction.  Rolling Friction has more
effect at slower speeds, and (Air) Drag has more effect at higher speeds.
Air Friction, or "Drag" is set at line 28.  We calculate Rolling Friction as a ratio
of Drag.  You can change this calculation at line 1072.
   [  Resistance = Drag * 60; // Rolling resistance, based on air Drag (calculated) ]
This calculation is not included in the "Table Entry Area" since it is not usually one
of the things you would normally change.  Don't forget that Rolling Resistance also
affects how quickly the vehicle slows down at slower speeds, when you reduce 
the throttle.  (Air) Drag slows you down more quickly at higher speeds.
___________________
GEAR EFFICIENCY

Since we don't really know how efficient the gear train is, we could have also 
adjusted "gear_efficiency", at line 29:
   [  var gear_efficiency = 0.8;   // Overall gear efficiency  ]
Setting "gear_efficiency" to 1.0 means the gears are 100% efficient.
(You can even make this more efficient than 1.0 !)
________________________
TORQUE LOOK-UP TABLE

Another thing we could have adjusted is the RPM torque "look-up" table.
As an engine goes faster, it developes more horsepower.  Our default is to give
the engine about 80% of it's power, and keep increasing this as the engine goes faster.
(This adjustment is also not in the "Table Entry Area", since it is not an adjustment
that most people will want to make, unless they have engine performance curves
for a specific engine.)

This calculation is done in the "Car_Physics" function, at line 819:
   [  // Vary engine torque depending on RPM   Ranges from .8 to 1.0+  ]
   [   lookup_torque = 0.8 + (rpm /30000);   ]
At 6,000 RPM, we are adding 0.2 (or 20%) more power.   (6,000/30,000 = 0.2)
Therefore, at 6,000 RPM, the engine has 100% of it's power available.
Since we can go above 6,000 RPM, it would be more realistic to make this calculation
look like this:
    [   lookup_torque = 0.8 + (rpm /35000);   ]
Now the engine won't develop 100% of it's power until we reach 7,000 RPM.
______________________
ENGINE RESISTANCE

Another variable that would affect performance and acceleration, is "T_Eng_Resis".
This variable represents the amount is engine is slowed, by it's own internal friction.
The effect of engine resistance, or engine braking, is felt through the entire drive train.
So we have to take into consideration the force multipliers of the gears we are using.
(To be more accurate, we should also consider gear_efficiency and the ratio of the 
differential.  We don't.  Instead we use an arbitrary number to compensate for those 
additional calculations.)

This calculation is done in the "Car_Physics" function, at line 838:
  [ T_Eng_Resis = (-Max_Torq) * (RPM / 18000)* gear_ratio[Use_Gear]; // Engine resistance ]
At zero RPM, there is no engine resistance.
As the engine goes faster, it's resistance gets larger.  We are dividing the RPM by 18,000
to give us a steadily increasing amount of engine "drag", or power loss, due to internal
engine friction.  If we reduce the throttle, engine braking will be greater at higher RPMs,
than at lower RPMs.  (That's why when we "down shift", (which increases engine RPM), 
we get more engine braking.)
To be more precise with this variable, we really need the engine performance curves
for the specific engine and drive train we are trying to simulate.  (Which is why
it's not included in the "Table Entry Area".  Most people should be fairly happy with 
the default calculation.  But it would be interesting to play around with this variable, 
just to see what happens!
______________________________
FORCED DOWNSHIFT

Finally, to help our vehicle accelerate faster, we could have simply activated the forced
down shift.  Pressing the "forced down shift" buttons will keep the automatic
transmission from upshifting to a higher gear.  When the engine is at a higher RPM, 
it develops more horsepower.  (Until we reach "Max_Rpm".)  See the explanation
above, about the "torque look-up table".
_______________________________
UPSHIFT and DNSHIFT

The automatic transmission will "up shift" to a higher gear, and will "down shift" to 
a lower gear, based on engine RPM.  You can get more horsepower by delaying when
the upshift happens (raise the upshift RPM).  You can get more acceleration at slower 
speeds, by raising the RPM at which the transmission will downshift to a lower gear.  
(Down shifts sooner, and gets more acceleration from the lower gear ratio.)

These two shift points are specified in the "Table Entry Area", lines 42 and 49:
   [  var DnShift = 3500;  // Specify RPM to automaticaly down shift to a lower gear  ]
   [  var UpShift = 6000;  // Specify RPM to shift to higher gear (+500 if accelerator floored) ]
Notice that the UpShift will automatically be delayed by 500 RPM (by the C-Script) if
the accelerator is more than 90%.  This calculation is done in the function "car_gear()"
at line 305.
   [  if((calc_rpm>UpShift+500) && (Accelerator >= 0.9)){gear += 1;} // Delay if floored ]
You can change this one line, to change that characteristic.  Or, comment this one line
out, to completely eliminate the delayed upshift.

One thing to be careful with, is setting the two shift points too close together, which will
cause problems when you force a down shift.  The only suggestion I can give you, is to
try some RPM shift points for your particular number of gears and gear ratios, and 
then test it out.  (Increase speed gradually, and force a down shift at various points 
within the RPM range of each gear.)
If the UpShift and DownShift are fighting with each other, you will need to experiment
with different RPM values for the shift points.
__________________________________________________________________
OTHER TABLE ENTRY SETTINGS

You can change various other things, such as when the tires squeal, how much the 
vehicle leans in turns, how much power loss you have in turns, how much rock back 
you have, etc.,  just by changing the values in other "Table Entry Area" variables.  
You can find these setting at line 35, in "Other table values you can adjust".
The comments with each of them explain how the settings work.

Take a look at the documentation files, "Other_Models.txt" and "Other_Models2.txt".  
Most of these settings are explained, in detail, in those two documentation files.
