-- define a list to put our wheels in, or rather to enable us to detect when a wheel entity 
-- has been assigned to our vehicle.  For performance reasons and to hide this variable
-- so it doesn't clash with any other scripts we define it as 'local'

local wheels = {}

-- the init function in this case simply scales the wheel slightly as I think it looks better
-- than the default the modeller chose (which is 200, from the fpe file)
function wr_wheel_init(e)
    Scale(e, 260)
end

-- the main script, 'e' is the 'entity' id, not to be confused with the 'object' id, basically 
-- every entity has an 'object' id but 'active' objects also have an entity id.

function wr_wheel_main(e)

-- first Lua'ism, this does NOT, as you may be forgiven for thinking, create a new variable
-- which is a 'copy' of the list entry.  It IS the list entry, i.e. think of it as a 'pointer' to the 
-- actual list entry
-- when the main script is first executed the list entry for this entity will not exist yet so
-- wheel will be 'nil' if it isn't nil then we have assigned this wheel already.

    local wheel = wheels[e]
	
-- this code is checking that the function 'WhackyRacerAddWheel' actually exists.  
-- this script may get executed BEFORE the script that defines the function!
  
    if wheel == nil and WhackyRacerAddWheel ~= nil then

-- we know at this point that this wheel is not already assigned to a vehicle and 
-- that the vehicle script is known about so call the function that assigns the wheel.

        wheels[e] = WhackyRacerAddWheel(e)

-- as we have finished return immediately, in this case it doesn.t really matter much
-- but in really big or complex scripts returning as soon as you can is a good habit
-- to get into

        return
    end	
end

local hammers = {}

function wr_hammer_init(e)
end

function wr_hammer_main(e)
    local hammer = hammers[e]
	
    if hammer == nil and WhackyRacerAddHammer ~= nil then
        hammers[e] = WhackyRacerAddHammer(e)
        return
    end	
end

-- first up we define a list to store details of each vehicle

local whackyRacer = {}

-- the definition is 'local' to avoid clashes with other scripts (iow this enables multiple
-- different whacky racer scripts to co-exist, maybe one for the hammer weaponed one
-- and another for the 'sweeper' etc.

-- another Lua'ism.  Here we create a reference to our quaternion library.   Even  though
-- many scripts may have this line in them the library will only be loaded once but every
-- script using it will be able to access it's functions with a local 'pointer' (I find it easier
-- to think of them as pointers)

local Q = require "scriptbank\\quatlib"

-- the string part tells Lua where to look for the script.

-- this is not strictly necessary but it improves both readability and more importantly
-- performance.  Every time a 'global' is accessed Lua has to look it up in the global
-- namespace, by creating local 'pointers' to globals we avoid the look up which speeds
-- up the execution of the code

local sin  = math.sin
local cos  = math.cos 
local rad  = math.rad
local deg  = math.deg
local asin = math.asin
local atan = math.atan2

-- the init function in this case contains an 'include' which is purely here so that the
-- standalone creation will copy the quaternion library.

function whacky_racer_walkthru_init( e )
    Include( "quatlib.lua" )
end

function whacky_racer_walkthru_main( e )

-- first get a local 'pointer' to our vehicle list

    local vehicle = whackyRacer[e]

-- if this is 'nil' then we haven't set it up yet
    
    if vehicle == nil then

-- another example of creating a 'local' reference to a global list, if you are going
-- to access a global more than once in your script then this is a good habit to 
-- get into

        local Ent = g_Entity[e]

-- now we  set up our vehicle list entry, i.e. create the starting values for 'this'
-- vehicle instance
        
        whackyRacer[e] = 
            { state = 'init',
              wheels = {}, hammer = nil, fireHammer = false,
              x = Ent.x, y = Ent.y + 50, z = Ent.z,
              quat = Q.FromEuler( rad( GetEntityAngleX( e ) ), 
                                  rad( GetEntityAngleY( e ) ), 
                                  rad( GetEntityAngleZ( e ) ) ),
              vmAng = 0, rotAng = 0, turnAng = 0,
              speed = 0
            }
        return
    end

-- the 'quat' line simply sets up a quaternion (i.e. magical container) for the rotational
-- specification of this vehicle

-- next time this routine is called we will execute the following:
-- the GotEnts function will return 'true' when all wheels and the weapon has been
-- assigned for this vehicle
    
    if vehicle.state == 'init' and GotEnts( e, vehicle ) then

        vehicle.state = 'idle'
    end

-- once all ents are assigned we can carry on
    
    if vehicle.state == 'idle' then

-- firstly we use the quaternion to get the Euler angles for this vehicle:
	
        local xA, yA, zA = Q.ToEuler( vehicle.quat )

-- define a couple of local variables

        local roll, pitch

-- another Lua'ism.  Functions in Lua can be passed many parameters and can
-- also return many results!
        
        vehicle.y, pitch, roll = GetWheelHeights( vehicle, xA, yA, zA )

-- GetWheelHeights does quite a bit so I'll  describe it later.  Basically at this
--  point we have determined the height of the vehicle entity and the angles
-- of it needed to position it wrt to the terrain

-- this bit is magic!  /:-]        
-- basically if you take a quaternion defining the rotational characteristics
-- of an entity and multiply it by another quaternion defining a rotation the
-- resulting quaternion is the new rotation it needs to be in.  

        vehicle.quat = Q.Mul( vehicle.quat, Q.FromEuler( pitch, 0, roll ) )
        
-- now convert the result into Euler angles

        xA, yA, zA = Q.ToEuler( vehicle.quat )

-- which we pass into a bunch of functions to position all the entities assigned
-- to this vehicle as well as the vehicle entity itself:
         
        PositionVehicle( e, vehicle, xA, yA, zA )

        PositionWheels( vehicle, xA, yA, zA )

        AttachPlayer( vehicle, xA, yA, zA )
        
        MoveVehicle( vehicle, xA, yA, zA )

-- now we need to figure out what the player wants the vehicle to do
        PlayerControl( vehicle )
        
-- and finally if the  vehicle has a weapon, in this case a hammer, position
-- it wrt to the vehicle
        if vehicle.hammer ~= nil then
            PositionHammer( vehicle, xA, yA, zA )
        end            
    end
end

-- these functions are 'global', iow they can be called by other scripts to interact with the main script
-- the first will add wheels to our vehicle

function WhackyRacerAddWheel( e )

-- this is the recommended method for iterating though a list
-- it simply visits every entry in the specified list and returns the key and value 'pair'
-- for each entry

    for k, v in pairs( whackyRacer ) do

-- first we check if our vehicle already has 4 wheels assigned, the # is
-- a special operator that returns the number of enties in a list

        if #v.wheels < 4 then

-- as we don't have 4 wheels yet we assign the entity passed in to our
-- wheel list.
-- here I find my first bug .... this function is supposed to return k!

            v.wheels[#v.wheels + 1] = { Ent = e }
            return
        end
    end    
end

-- this function assigns a weapon to our vehicle and initialises the angle
-- of it to a sensible value.  Again the same bug, should be returning k

function WhackyRacerAddHammer( e )
    for k, v in pairs( whackyRacer ) do
        if v.hammer == nil then
            v.hammer = { Ent = e, angle = -20 }
            return
        end
    end    
end

local function GotEnts( e, v )

-- check we have 4 wheels, if not stick a Prompt on screen so we know what went wrong

    if #v.wheels ~= 4 then
        PromptLocal( e, "Not enough wheel entities!" )
        return false
    end

-- check if we have a hammer

    if v.hammer == nil then
        PromptLocal( e, "No weapon entity!" )
        return false
    end
	
    return true
end

local function Rotate3D ( x, y, z, xrot, yrot, zrot ) 

-- I'm not going to delve into the math here, I pretty much just copied it from a big
-- book on 3d graphics, but what it does is take a vector defined by x,y,z amounts
-- and rotate it by a given set of Euler angles when return the transformed vector

    function RotatePoint2D ( x, y, Ang )  -- Ang in radians
        local Sa, Ca = sin( Ang ), cos( Ang )
        return x * Ca - y * Sa, x * Sa + y * Ca
    end
 
    local NX, NY, NZ = x, y, z

    -- X
    NZ, NY = RotatePoint2D ( NZ, NY, -xrot )
    
    -- Y
    NX, NZ = RotatePoint2D ( NX, NZ, -yrot )
    
    -- Z
    NY, NX = RotatePoint2D ( NY, NX, -zrot )

-- here we see the cool way in which Lua can return multiple results

    return NX, NY, NZ
end

-- this is a Lua list, or more accurately a list of lists

local wheelOffsets = 
        {{ x = -62.7, y = -3.7, z = 136.4 },  -- left front
         { x = -62.7, y = -3.7, z =   0.6 },  -- left rear
         { x =  62.7, y = -3.7, z = 136.4 },  -- right front
         { x =  62.7, y = -3.7, z =   0.6 }   -- right rear
        }

-- here we have four lists with no specified key, each list contains key/value pairs.  
-- it works like a two dimensional array so wheelOffset[2].x would be -62.7 which 
-- in this case is the x offset from the entity origin  of the left rear wheel.

-- So what is this for?  Simply a way of defining the positional offsets for each wheel,
-- 4 of them in this case, so we know where to position them at run time.
-- You may be wondering how I calculate these, well attached to this post is a useful
-- little script that does just that.  Attach the script to a couple of entities and hit 
-- the rocket, in the test game you will see the offsets from the origin point of one
-- entity to the origin point of the other!

-- we will use this list to store the wheel heights for each wheel

local wheelHeights = {}

-- and this function simply works out the angle between two heights a specified 
--distance apart

local function calcAngle( h1, h2, l )
    return asin( ( h2 - h1 ) / l )
end

 local function GetWheelHeights( v, xA, yA, zA )

-- first we declare some working variables
    local xo, yo, zo
    local avgHeight, avgRoll, avgPitch = 0, 0, 0
    
-- next we loop through the 4 wheels and calculate the appropriate
-- terrain cooridinates for each one
    for i = 1, 4 do
        local wo = wheelOffsets[i]
    
        xo, yo, zo = Rotate3D( wo.x, wo.y, wo.z, xA, yA, zA )

-- '24' just happens to be a number chosen to make the effect look good, it
-- should represent the distance between the wheel centre and the ground
-- but rather than calculate it I just took a guess and then tweaked it till it 
-- looked right.
        wheelHeights[i] = GetTerrainHeight( v.x + xo, v.z + zo ) + 24
        
        avgHeight = avgHeight + wheelHeights[i]
        
        wheelHeights[i] = ( v.y + yo ) - wheelHeights[i] 
    end

-- we now have an array of 4 wheel heights so we calculate the average of them
    
    avgHeight = avgHeight / 4
    
-- workout the angle for the front axle
    local ax1 = calcAngle( wheelHeights[1], wheelHeights[3],
	                       wheelOffsets[3].x - wheelOffsets[1].x );
							   
-- and the rear angle
    local ax2 = calcAngle( wheelHeights[2], wheelHeights[4],
	                       wheelOffsets[4].x - wheelOffsets[2].x );

-- calculate the average angle
    avgRoll = ( ax1 + ax2 ) / 2

-- do the same for pitch, i.e. front-to-back angle    
    local p1 = calcAngle( wheelHeights[1], wheelHeights[2],
	                      wheelOffsets[1].z + wheelOffsets[2].z );
						  
    local p2 = calcAngle( wheelHeights[3], wheelHeights[4],
	                      wheelOffsets[3].z + wheelOffsets[4].z );
    
    avgPitch = ( p1 + p2 ) / 2

-- and return the results, the '3' here is another tweakable value, it just
-- alters the ride height of the vehicle a bit to make the wheel position
-- look right
    return avgHeight + 3, avgPitch, avgRoll
end

local function PositionWheels( v, xA, yA, zA )
    for i = 1, 4 do
        PositionWheel( i, v, xA, yA, zA )
    end
end

-- don't think this needs much explanation!

-- first a little list to help simplify the code a bit, for a given wheel number this simply 
-- indicates whether it is a front or rear wheel
local turnDir = { 'F', 'R', 'F', 'R' }

-- couple of quats for working with
local rotQuat = nil
local finQuat = nil

local function PositionWheel( num, v, xA, yA, zA )

-- we need our wheel offsets again, this time we use the passed in index 
-- to get the appropriate list for the wheel we are working on
    local wo = wheelOffsets[num]
    
-- more rotational geometry, we calculated these before so could have stored 
-- them for future use but that would overcomplicate the code
    local xo, yo, zo = Rotate3D( wo.x, wo.y, wo.z, xA, yA, zA )

-- we did store the individual wheel height though ao now we use it to work out
-- how high or low (within sensible limits) to put the wheel     
    local suspensionOffset = wheelHeights[num]
    
    if suspensionOffset >  4 then suspensionOffset =  4 end
    if suspensionOffset < -4 then suspensionOffset = -4 end

-- now we  can position the individual wheel on it's axle
    ResetPosition( v.wheels[num].Ent, v.x + xo, 
                                      v.y + yo - suspensionOffset, 
                                      v.z + zo );

-- and depending on whether the wheel is a front left or front
-- right turn the wheel to match the turn angle
-- also we need to flip the wheel over so the hub is on the outside         
    if turnDir[num] == 'F' then
        if num == 1 then
            finQuat = Q.FromEuler( 0, rad( v.turnAng ), 0 )
        else
            finQuat = Q.FromEuler( 0, rad( -v.turnAng ), rad( 180 ) )
        end
    else
-- rear wheel don't turn but we still need to flip one of them
        if num == 2 then
            finQuat = Q.FromEuler( 0, 0, 0 )
        else
            finQuat = Q.FromEuler( 0, 0, rad( 180 ) )
        end
    end

-- at this point the quaternion we have calculated, finQuat,
-- represents the angles needed to turn and flip the wheel 
-- entity so now we need to give a bit of tilt relative to the 
-- suspension travel, again within reasonable limits

    if num < 3 then suspensionOffset = -suspensionOffset end
    
-- now multiply the quaternion representing the direction of
-- travel of the vehicle with 'finQuat' to work out the anmgles
-- at which to put the wheel in 'world' terms 
-- (note that the order of multiplication matters!)
    finQuat = Q.Mul( v.quat, finQuat )
    
-- phew, all we have to do now is rotate the wheel!  rotAng 
-- represents how far around the axis to rotate
    if num > 2 then
        rotQuat = Q.FromEuler( rad( -v.rotAng ), 0, rad( suspensionOffset * 2 ) )
    else
        rotQuat = Q.FromEuler( rad( v.rotAng ), 0, rad( suspensionOffset * 2 ) )
    end

-- note that the wheels on one side of the car rotate in the opposite
-- direction from the ones on the other side and we factor in the tilt
-- amount at  the same time

-- update the rotation abgle for next time, this is a simple calculation,
-- no wheel spin I'm afraid (well not yet anyhow)
    v.rotAng = v.rotAng - v.speed / 10

    if v.rotAng < -180 then 
        v.rotAng = v.rotAng + 360
    elseif v.rotAng > 180 then
        v.rotAng = v.rotAng - 360
    end
    
-- now multiply with our earlier quaternion to give the final
-- representation
    finQuat = Q.Mul( finQuat, rotQuat )

-- and convert back to Euler angles so we can tell GG
    local xA, yA, zA = Q.ToEuler( finQuat )
    
    ResetRotation( v.wheels[num].Ent, deg( xA ), deg( yA ), deg( zA ) )
end

local function PositionVehicle( e, v, xA, yA, zA )
    
    ResetPosition( e, v.x, v.y, v.z )
    ResetRotation( e, deg( xA ), deg( yA ), deg( zA ) )

end
-- see, told ya it was boring.
-- couple of things to watch out for, the angle values being passed around are
-- radians, GG wants degrees so don't forget to convert them.

-- first another list to hold the posityional offsets of the hammer entity
local ho = { x = 0, y = 55.5, z = 129.3 }

local function PositionHammer( v, xA, yA, zA )

-- which we transform using the angles
    local xo, yo, zo = Rotate3D( ho.x, ho.y, ho.z, xA, yA, zA )
    
-- and use to position the entity    
    ResetPosition( v.hammer.Ent, v.x + xo, v.y + yo, v.z + zo )
    
-- but we also want to be able to biff people with it so here
-- we calculate a quaternion on the fly and multiply with the
-- vehicle quat and convert back to Euler all in one statement!
    xA, yA, zA = Q.ToEuler( Q.Mul( v.quat, Q.FromEuler( rad( v.hammer.angle ), 0 ,0 ) ) )

-- and final tell GG to rotate the hammer 
    ResetRotation( v.hammer.Ent, deg( xA ), deg( yA ), deg( zA ) )

-- this bit recalculates the hammer angle for next frame and
-- limits the travel all based on whether the hammer is being
-- fiored or not    
    if v.fireHammer then
        if v.hammer.angle > -170 then
            v.hammer.angle = v.hammer.angle - 17
        else
            v.fireHammer = false
        end
    elseif v.hammer.angle < -20 then
        v.hammer.angle = v.hammer.angle + 5
    else
        v.hammer.angle = -20
    end
end

-- first a couple of 'constants'  note that there is no actual way of defining
--  real constants in Lua, you just have to use a bit of discipline to stop 
-- yourself from changing them
local maxSpeed      = 20
local acceleration  = 0.03

-- as I said this aint pretty but it works!
local function PlayerControl( v )
-- handle accelerate and decelerate, can't really call it braking
-- as it is too gentle
    if v.speed < maxSpeed and g_KeyPressW == 1 then
        v.speed = v.speed + acceleration
    end
    if v.speed > 0 and g_KeyPressS == 1 then
        v.speed = v.speed - acceleration * 2
    end

-- then turning, simply adjusts the turn angle when the keys are 
-- pressed and if they aren't gradually return the wheels to 
-- strainght ahead
    if g_KeyPressR == 1 then
        if v.turnAng < 30 then
            v.turnAng = v.turnAng + 0.3
        end
    elseif v.turnAng > 0 then
        v.turnAng = v.turnAng - 0.1
    end
    if g_KeyPressE == 1 then
        if v.turnAng > -30 then
            v.turnAng = v.turnAng - 0.3
        end
    elseif v.turnAng < 0 then
        v.turnAng = v.turnAng + 0.1
    end

-- finally use mouse key to fire the hammer
    if not v.fireHammer and 
       v.hammer.angle > -60 and g_MouseClick == 1 then
        v.fireHammer = true
    end
end

local function MoveVehicle( v, xA, yA, zA )

-- first a sanity check to see if we need to move     
    if v.speed > 0 then

-- next we calculate the movement vector (go back to the earlier post explaining this)
        local mX, mY, mZ = Rotate3D( 0, 0, v.speed, xA, yA, zA )
    
-- then simply apply the vector
        v.x, v.y, v.z = v.x + mX, v.y + mY, v.z + mZ

-- oh and calculate the 'world' angle for later use
        v.vmAng = deg( atan( mX, mZ ) )
    
-- finally rotate the entity slightly in the direction of  the turn angle
        v.quat = Q.Mul( v.quat, Q.FromEuler( 0, rad( v.turnAng / 20 ),0 ) )
    end
end   

local function AttachPlayer( v, xA, yA, zA )
        
-- firstly lets work out a position relative to the vehicle to place the player
-- -300 units behind it in this case
    local xo, yo, zo = Rotate3D( 0, 0, -300, xA, yA, zA )

-- now work out where the ground is (we don't want the player to be viewing
-- things from inside the terrain!) at that point
    local y = GetTerrainHeight( v.x + xo, v.z + zo )
    
-- now position the player at a set height, 200 chosen at random, above the
-- terrain
    SetFreezePosition( v.x + xo, y + 200, v.z + zo )

-- and finally rotate the player to face the vehicle, this is where we use the 
-- angle we calculated earlier
    SetFreezeAngle( 20, v.vmAng, 0 )
    TransportToFreezePosition()
end