Camera Zoom in Torque

Hello there. These are the results of my first attempt to modify the Torque engine and add something that I thought was quite necessary for my game
style. This is targeted toward the beginner, and I hope my comments will make what is going on quite clear.

Structure:
In the code snippets, anything in bold is new, and you need to add it yourself. Ignore the ..., as they are there for brevity.

Introduction:
To begin with, the Torque scripts already contain a value which "zooms in and out". The problem with this value, is that it is only checked once,
upon game startup, and any changes to that value after a game commences is meaningless. That value can be found here:

player.cs

datablock PlayerData(LightMaleHumanArmor)
{
  ... 
  cameraMaxDist = 3;
  ...
}

Remember the location of this line, because it will be your easy way to tweak the zoom once we place all the code. If we follow the path that
cameraMaxDist takes upon game startup, we end up in the engine code, specifically in:

shapeBase.cc

void ShapeBase::getCameraTransform(F32* pos,MatrixF* mat)
{
  ...
  vp.y = -(max - min) * *pos;
  ...
}

The value in max you see above is taken from the cameraMaxDist=3 that was specified in the previous player.cs file. I felt it would be too big
of an undertaking to mess with changing this variable, so I took a different route. To conclude the intro, I know what I wanted to do was press
'Home' to zoom in, and press 'End' to zoom out. I knew that adjusting the line in shapeBase.cc like the following would work:

vp.y = -(max +5 - min) * *pos;
//Zoom out by 5
vp.y = -(max -4 - min) * *pos;
//Zoom in by 4

------------------------------------------
The following are changes I made to the Engine
------------------------------------------
shapeBase.h

class ShapeBase : public GameBase
{
   typedef GameBase Parent;
   friend class ShapeBaseConvex;
   friend void physicalZoneFind(SceneObject*, S32);

   public:

[b]static S32 cameraZoomValue;  // Static Signed Int - Zoom Value that all derived classes will take
virtual void setZoomValue(S32); // Set value, this function should update the cameraZoomValue by the amount we request,
 //and since cameraZoomValue is public, there is no need for a get function[/b]

   enum PublicConstants 
  {
   ...
   ...
  }
}

The most important portion of the code above is the fact that cameraZoomValue is static. Since this variable is in the ShapeBase class, it is automatically
derived by sub-classes of ShapeBase, such as Camera. If this were not made static, there could(and would) be several instances of setZoomValue.
When we try to update the value through the script for the Camera Zoom, the fact that we're updating the Camera::setZoomValue means absolutly
nothing to the ShapeBase::setZoomValue. That's a big problem since our function which actually zooms in and out is a
Member function of ShapeBase, not Camera.

shapeBase.cc (most of our work)

ShapeBase::~ShapeBase()
{
...
}

[b]S32 ShapeBase::cameraZoomValue = 4;  // Init the static cameraZoomValue to 4[/b]

...

void ShapeBase::getCameraTransform(F32* pos,MatrixF* mat)
{
  ...
  [b]vp.y = -(max + cameraZoomValue - min) * *pos;[/b] // Make sure you replace the old line with this new one
  ...
}

...

static void cSetupInvincibleEffect(SimObject* obj, S32, const char** argv)
{
   ShapeBase* shape = static_cast<ShapeBase*>(obj);
   shape->setupInvincibleEffect(dAtof(argv[2]), dAtof(argv[3]));
}

[b]static void cSetZoomValue(SimObject *ptr, S32, const char **argv)
{
   ShapeBase* obj = static_cast<ShapeBase*>(ptr); // The script gives us a zoom value, such as "1", we need to turn it into
   obj->setZoomValue(dAtof(argv[2]));             // an integer, then call the update function setZoomValue(S32)
}[/b]

...
[b]
void ShapeBase::setZoomValue(S32 increment)
{
	S32 temp = cameraZoomValue + increment;  
	if (temp > -5 && temp < 20)
	    cameraZoomValue += increment; // Static / Public Data
	                                  // Zoom will carry over to any derived class
	// The zoom function actually moves the camera, so we dont want them to wander
	// really far off into the sky, so lets limit the zoom to be between -5 <--> 20
	// The -5 is necessary because the zoom is initilized to 4.  So, this lets us have
	// a max zoomin of -1, and max zoomout of 24
}
[/b]


void ShapeBase::initPersistFields()
{
...
}

void ShapeBase::consoleInit()
{
   Con::addVariable("SB::DFDec", TypeF32, &sDamageFlashDec);
   ...
   Con::addCommand("ShapeBase", "setDamageVector", cSetDamageVector, "obj.setDamageVector(vec)", 3, 3);
[b]   Con::addCommand("ShapeBase", "setZoomValue", cSetZoomValue, "obj.setZoomValue(value)", 3, 3);[/b]
}

Breakdown:
Con::addCommand("Class Type(ShapeBase), Function Name, Function to actually Call,
Script way to call the function we want, min parameters, max parameters);

When we actually call the equivilent of obj.setZoomValue(3) in the script, we're going to find this line. It knows to expect 1 parameter
{because there's always a minimum of 2, so to pass a function with no parameters we would do, 2, 2); We want 1 parameter so we do, 3, 3);}
When we find this line we call cSetZoomValue("3"). The script passes every parameter as a string,
and it's up to us to decide what to do with it once the code receives it. We decide to turn it back into an integer in the cSetZoomValue,
and toss it over to setZoomValue(3). Once setZoomValue has the int 3, it checks to
make sure we're not trying to zoom out too far. If everything is ok, it applies the number
and we zoom out!

----------------------------------------------
The following are changes I made in the script
----------------------------------------------

commands.cs

function serverCmdZoomInCamera(%client)
{
    %client.getControlObject().setZoomValue("-1");
}

function serverCmdZoomOutCamera(%client)
{
     %client.getControlObject().setZoomValue(1);
}

We create 2 server commands. It's necessary to do this so we know who's client is asking to zoom in. We use getControlObject()
to find out what the %client is actually controlling. Is it a person, a camera, a car?

default.bind.cs

//------------------------------------------------------------------------------
// Camera & View functions
//------------------------------------------------------------------------------
[b]
//Camera Zoom in and out, 3rd person view - Keyboard
function zoomIn(%val)
{
  if (%val)
     commandToServer('ZoomInCamera');
}

function zoomOut(%val)
{
  if (%val)
     commandToServer('ZoomOutCamera');
}


MoveMap.bind(keyboard, "home", zoomIn);
MoveMap.bind(keyboard, "end", zoomOut);

//Camera Zoom in and out, 3rd person view - Mouse Wheel
function handleMouseWheel(%val)
{
   // Check if the wheel scrolled up or down
   if( %val > 0 )
         commandToServer( 'ZoomInCamera' ); //Mwheel Up
   else
         commandToServer( 'ZoomOutCamera' );//Mwheel Down

}

moveMap.bind(mouse, "zaxis", handleMouseWheel );
[/b]

The first portion binds the zoom in and out to the Home and End keys on the keyboard. The 2nd part binds
it to the mouse wheel up and down. If you use mouse wheel for something else, I dont suggest adding this part.


config.cs

[b]
//Added Zoom In / Out
moveMap.bind(keyboard, "home", zoomIn);
moveMap.bind(keyboard, "end", zoomOut);
[/b]
moveMap.bind(mouse0, "xaxis", yaw);
moveMap.bind(mouse0, "yaxis", pitch);
[b]moveMap.bind(mouse0, "zaxis", handleMouseWheel);[/b]
moveMap.bind(mouse0, "button0", mouseFire);

This is everything you need to get camera zoom working. I hope my documentation was thorough and you understood everything I tried to say here.
In closing, I guess I'll make mention of a few points:

-I didnt add the Home/End/MouseWheel to the Options Dialog GUI screen.
-You can adjust the intialzoomed out amount through the maxZoomDist in the player.cs file
-There's another way to add console commands to the engine, but it is used for regular
functions, not member functions. Do a search for ConsoleFunction in your source code
-The camera code in general needs to be optimized. Currently the engine checks the camera position in a constant loop. If
you're sitting still and staring at the same spot for 10 minutes, then the camera position gets checked hundreds of thousands of times. Is this necessary?
Cant we just have it check for a new position when we make a move? Probably. Maybe I'll try to knock that one out too, eventually.

Hope you enjoyed it, any questions or comments are welcome.
-Jared