This is a simple little function which allows you to tell the player and/or his camera to instantly turn to face a target object. It's main use is as part of the GestaltCameraTrack function, but you can use it by itself. Here's an example -

#include "in_g_cutscene"
void main()
{
    object oPC = GetFirstPC();
    object oTarget = GetObjectByTag("target");

    GestaltCameraFaceTarget (oTarget
                            5.0, 50.0,
                            oPC,
                            0, 0);
}

1. Target - The first thing you have to do is tell the function which object you want the camera to face.

   
   

2. Camera position - Next we set the distance between the camera and the player and the camera's vertical tilt, measured as the number of degrees from vertical. If you set either of these to -1.0 that part of the camera's position won't change when the function is called.

   
   

3. Player selection - The next thing you have to tell the function is which player you want to move the camera of. You can set up an object to contain this information, or you can simply put a function such as GetFirstPC(), GetPCSpeaker() or GetLastPlayerDied() directly in the GestaltCameraMove line of your script.

   
   

4. Options - The last two numbers are integers which control various options in the function. The first option (iFace) sets whether the PC (2), their camera (0) or both (1) will rotate to face the object you are tracking. The second option (iParty) is for multiplayer modules only, and tells the function whether to move the camera of only the specified player (0), all the players in their party (1), or all the players on the server (2). Both of these options default to 0.

This means that the example script above is turning the selected player's camera to face a target object with the imaginative tag "target", simultaneously zooming the camera in close-up to the player and down close to the ground (50 degrees from the vertical).

Here are a couple more sample scripts to get your teeth into -

#include "in_g_cutscene"
void main()
{
    object oPC = GetFirstPC();
    object oTarget = GetObjectByTag("target");

    GestaltCameraFaceTarget (oTarget
                            -1.0, 50.0,
                            oPC,
                            1);
}

This is exactly the same as the first target script, except that this time we are leaving the camera's distance from the player untouched. However far away the player had the camera at the time the function was called, it will stay there - only the tilt and direction of the camera will be changed. Also note that we've set iFace to 1, which means that the player and his camera will be turned together so that they both face the target object.

One last thing. Because we want to leave the last option (iParty) at its default value of 0 in this example, we don't atually have to include that parameter in the list when we call the function - the game will fill in the blank for us.

#include "in_g_cutscene"
void main()
{
    object oPC = GetFirstPC();
    object oTarget = GetObjectByTag("target");

    GestaltCameraFaceTarget (oTarget
                            -1.0, -1.0,
                            oPC,
                            2, 1);
}

And finally here's an example of a script that will turn only the player's character but not his camera, by setting the final number to 2. As we're not moving the camera at all, we've left both of the camera controls at -1.0. We've also set iParty to 1, which means that all of the other players in the selected player's party will turn to face the object as well.


NOTE - GestaltCameraFaceTarget includes one more parameter - iCamID - which defaults to 0 and should NEVER be used in your own scripts. This is for internal use by other functions in the include file only.