"Script.txt"  A tour through the Move_Car 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 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 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".
______________________________________________________________
MOVE_CAR.WDL

The Move_Car.wdl file should be in the same project folder as the game, or simulation.
The easiest way to get the Player_Car action to perform, is to "attach" the action
to the 3D player model in the WED properties box, under the "behavior" tab.  
However, the Player_Car action can also be attached to the player model through 
additional C-Script programming.  This extra programming (not included) can cause
the script to switch the 3D model between modes provided by the standard templates, 
(such as walking, running, wading, swimming, etc.), and the vehicle motion actions 
provided by the Player_Car "Action" in the Move_Car.wdl C-Script file.

For learning purposes, we will assume the action has been attached through WED, 
and the main script function is just the default script provided by 3DGS WED, when 
a new level is built.

Since the Move_Car.wdl file is listed in the "Include" list at the beginning of the 
main (default) script, all of the variables in the Move_Car file will be defined, 
and intial values will be assigned to those variables.  Other definitions, such as 
"panel", "view", etc., will also be active, and will be visible on the screen.
The "Car_Cam.wdl" file is automatically "Included" by an instruction at the end
of the "Move_Car.wdl" file.  Do NOT manually include the "Car_Cam.wdl" file.

The initial variable definitions may be found in lines 0000 through 0158.  All variables
are defined within this block of script.  While it is not required, but only a personal
preference of mine, I usually always set ALL variables to some value, even if it is only
zero.  The variables which are identified as "(calculated)", should never use the intial
value given to the variable.  Instead, once some calculation is finished, it will put 
an initial value in the variable.  The "zero" value is there just in case a "bug" 
causes the script to read the variable, before we have done the proper calculation.  
(This technique sometimes helps to eliminate unpredictable behaviors in the
programming.)

Part of the variable definitions is called the "Table Enty Area". (Lines 25 through 49)
These are the variables that are designed to be set by the Player, to adjust vehicle 
characteristics, such as Horsepower, number of gears, squealing, leaning, rock back, etc.
This is important, since the Move_Car script does not use "Skills" or "Flags".

Following the variable definitions are the function prototypes.  I believe all functions
used in Move_Car.wdl are listed here, along with comments for each of them.
(Lines 159 - 196)

The next group includes both functions and definitions for "panels", "views", etc.
(Remember the panels and views will be active, right from the start.)  
The "functions" will be called from the main part of the Player_Car "Action"
C-Script, so let's start with how the Player_Car C-Script executes.

When the level is "Run", two things happen:
1.  The "Main" function in the default script starts executing, and
2.  The "Action" assigned in WED will automatically start executing soon.

Conitec requires the display of a "splash screen" with the A5 logo, for one second.
You may want to follow the logo splash screen with one of your own, which 
could include panels, buttons, game settings, etc.
However, the on-screen displays in the Player_Car action are already active,
and will display on the screen.  We want to block that, until we are ready to see
those displays on the screen.  (Especially if our main script starts in "Walking" 
mode first, and later switches to the Player_Car action, to drive a vehicle.)

To block the display of the on-screen HUDs (Heads Up Displays), such as the 
speedometer, tachometer, rear-view mirror, etc., we need to put one line of script
in the main function:
              [    screen_hold = 1;   ]
The variable "screen_hold" has already been defined in the Move_Car script.  It 
should not be defined again in the main (default) script.  We put this line near the 
end of the default script's main function, at line number 140.  By the time we get 
to line 140, the splash screen should have already displayed, and been turned off.
____________________
The Player_Car action, in the Move_Car.wdl script file, starts at line 663:
      [ action Player_Car  ]
This is the real entry point for the Move_Car script.  It is the start, or beginning, 
of the "Action" instructions we are going to execute.

The first thing we will find, is the instruction that checks to see if "screen_hold" 
has been set to "1".  (line 665)
   [ while (screen_hold = = 0) {wait (1);}  // Wait for splash screens to finish  ]
The Player_Car action will not go any further, until "screen_hold" gets set to "1"
in the default script's Main function.  Therefore, you can delay the start of the 
Player_Car action, by waiting to set "screen_hold" until you have finished your
own splash screens, button selections, Player switch, etc.

Once we get the OK to proceed, and "screen_hold" has been set to "1", (or we
commented out line 665 because we didn't want to wait!), we then set some 
default values for things such as: Move mode, scale factors, and hiding the 
mouse cursor.   (Lines 667 - 680)
________________________________________________________
We then call our first function:   (line 681)
   [   car_init();  //  Initialize variables  ]
That causes us to  jump to the "car_init()" function, at line 1049.  
(Last function in the Move_Car.wdl file.)

The variable definitions at the beginning of the C-Script file created
"place holders" for us, to store values.  But during the definitions, 
we couldn't perform any calculations to set initial values.  Here we can, 
because now we are actually executing C-Script instructions.
Line 1052 through line 1078 sets some additional initial values, which we 
can now calculate.  

For example, here we convert "Horsepower" to "Max_Torq", which is 
the number we will use for maximum engine power.  Horsepower is a 
"table entry" number, that is designed to be set by the player for 
different types of vehicles.  But once we do the conversion to "Max_Torq",
we won't do that calculation again.  (Unless we stop, and restart the 
Player_Car Action.)  This now gives us the ability to modify the 
maximum engine power, (Max_Torq), in case of damage, or "health" problems.  
However, in case the player is reset, or "re-born", we can do the 
Horsepower conversion again (in your own script) to get back to the 
original number we used for maximum engine power.

We also use this area to set some limits on variables, such as "Acel_Val", and 
"Turn_Effect", so we won't divide by zero, even if a "zero" was entered in the 
table entry area.

Finally, lines 1080 - 1086 are called "Housekeeping".  This is where we
actually "turn on" the sounds, panel displays, and views.  We also check to
see if the player set those to "off" (zero) in the table entry area.
Lines 52 through 56 are table entry values to turn off certain features:
  [ // Features you can turn off - Set to zero for OFF, non-zero (1) for ON ]

The "Housekeeping" area starts the engine sound, and calls several functions
that will turn on the sounds, or "show" the on-screen displays.  You may want to 
take a look at those functions.  The "Adjust_Screen()" function is the most 
complicated, since this is where we adjust the displays for the screen 
resolution that was set in the default script.
line 227   {Car_Horn();}           // Start looking for horn button
line 248   {Car_Squeal();}        // Start looking for tire squeals
line 486   {rear_view.visible = ON;} // Show Rear_View Mirror
line 568   {Show_Hud();           // Shows the on-screen displays
line 583   Adjust_Screen();       // Adjust on-screen display if 800x600 or 640x480

We have finished the "Car_Init()" function, and won't be coming this
way again.  We now return to where we came from, which is line 682.
_____________________________________________________
At line 683, we find a "while" loop, that ends with a wait (1) instruction.
This while loop will repeat forever (or until we end the Player_Car Action).
There are only two instructions within the repeating "while" loop:
[   player_car_move();   // Execute the functions in the action  ]
[   update_views();        // Update rear view mirror  ]

The "update_views()" function will keep our rear-view mirror image
updated and current.  You may want to take a look at that function. (line 212)

The "player_car_move()" function is really the heart of the Player_Car action.
Remember, the previous "while" loop will keep us repeating the 
"player_car_move()" function, over and over.  So let's go there next....(line 692)
_____________________________________________________
Once in player_car_move(), we make sure some of the intial variables are
still set properly, such as "Me", trigger, my._TYPE, etc.  We also make
sure straffing is turned off (no side stepping!).

What follows is only 15 lines long, and controls everything that happens
in the Player_Car Action.  This is a "menu" list (or "cook book") of functions
which handle each of the different areas of the Action.

The first six function calls, (lines 714 - 719) handle the control inputs, the
tilt and roll of the vehicle, the physics calculations, the steering, the actual
movement of the vehicle, and updates for the main camera view.  (The 
updating of the main camera view is done in the Car_Cam.wdl script.  Look
there for the "car_view()" function.)

Here are the major control functions:

line 731  [  car_player_intentions();   //  Get Player Input  ]
line 868  [  car_scan_floor();   // find ground below (set tilt, roll, my_height, my_floornormal) ]
line 792  [  car_physics();           //  Calculate car vectors, torque, acceleration, etc.  ]
line 987  [  car_steering();          //  Calculate car steering  ]
line 956  [  car_move_gravity(); // Move the car  ]
line 104 - Car_Cam.wdl     [  car_view();   // Update the main camera view (Car Cam)  ]

Each function represents one major area of control.  Together, they control all of 
the major vehicle movements, of the Player_Car Action.  Follow each of these 
functions, to understand the workings of the major parts of the "Action".
_____________________________________________________
There are also some "Helper" functions. (Lines 722 through 728)
Most of these helper functions control the sounds, and the "eye-candy" (displays).  
They tune the engine sound, rotate the speedometer and tachometer needles, 
move the throttle "thermometer" arrow, and toggle the input devices and the
on-screen text displays.  They also shift the gears, and check whether the car
is going forward, braking, or going backwards.  
Additional functions, such as model animations, the ability to fly, etc,. could be 
inserted in this list, or in the above list of major functions, depending on your needs.   
Take a look at each of these functions:

line 411  tune_esound();    // Set engine sound according to RPM 
line 548  sneedle_roll();     // Sets the angle of the speedometer needle 
line 555  tneedle_roll();     // Sets the angle of the tachometer needle     	
line 562  Throttle_Arrow();  // Move arrow up and down the throttle thermometer
line 273  car_motion();     // Check if moving forward, braking or backing-up
line 288  car_gear();        // Shift gears when needed, including reverse
line 1008 car_toggle();     // Check toggles for steering and throttle input types
________________________________________________________
Remember, the "While" loop we saw earlier, will keep us looping through
the "player_car_move()" function, so all of the above control functions will
keep executing, over and over, until we stop the Player_Car Action..
________________________________________________________
Well, that's it!  You should now be able to find each of the different pieces, and
see them in small enough areas to understand them, one function at a time.
_________________________________________________________
To understand the workings of the Car_Cam camera views, take a look 
at the documentation file, "Cam_Script.txt".
__________________________________________________________
Bill McGonigal  (Willy)
April 21, 2002