Camera Scripting Wizard

by GPA

Contents

1) What's this stuff?

2) How it works?

3) What do you have to do?
     a) Basic commands
     b) setup cameras
     c) advanced camera command
         - Rotate camera
         - Using reserved keyword "PARAM"
         - Using reserved keyword "GET"
         - Effects
     d) working with setup.sqs

4) Appendix
     a) Reserved variables
     b) Error messages

5) History

1) What's this stuff?

The cutscene wizard is a group of scripts that allow you to control all cutscenes within your missions and/or all your intro/outros. Basically these routines are based on a parser that searches your mission for certain markers to figure out where cameras will be placed, what the target will be etc.

Your cameras can also be grouped in separate functional units that can be started separately in your mission or when a particular condition becomes true.

The wizard comes with 7 scripts:

- setup.sqs : is the only one you must edit if you want to run the wizard with full features.

- deploy.sqs : the main script you call within your missions.

- play.sqs : the core script that contains the parser.

- parser.sqs : the parser played by the PLAY modality. (without any controls)

- test.sqs : if you run the wizard in TEST mode this script displays some information on the screen about your cameras.

- errorhandler.sqs : in both advanced mode (TEST and PLAY) displays on screen error messages that apply to the setup of your cameras.

- messages.sqs : displays on screen messages involved in TEST and SEARCH functions.

2) How it works?

The wizard works in 4 different modalities:

- AUTO mode: this is for newbie's of camera editing or for fast test cutscenes. This mode disallows you the use of multiple "scenes". All that you have to do is deploy a marker wherever you want to run a camera, naming it "c(n)" where (n) is a number between 1 and (n). So the first camera will be named "c1" and so on. For each camera you must deploy another marker naming it "t(n)" with (n) equal to the number of the camera. The only available kind of camera in this modality is "STAY" camera.

- PLAY mode: Is the fully functional modality. You can use multiple scenes, markers or units as target for cameras, and markers or a units position setup your cameras. You can also use any kind of camera (see below), set effects and include custom scripts. No tests are invoked, so it is a little bit faster than TEST mode.

- TEST mode: like the PLAY mode, but with some useful information about the camera actually running displayed on the screen. The error handler is also on, so if you've made some mistakes in programming cameras, you'll notice useful advice on how to fix them.

- SEARCH mode : Fast search the specified camera to fast test it without looking at the whole cutscene.

3) What you have to do

a) Basic

The first thing you have to do is to call the wizard at the start of your mission. This can be done with an init trigger, within an init script, or in the init field of your player.

The call to the camera wizard script has following syntax:

["MODE", parX, parY] exec "deploy.sqs"

Valid keywords for MODE are:

"AUTO" : Tells the parser to search only for cameras deployed with markers. The setup.sqs scripts is not involved in the process at all. To run properly the parser must be able to find camera markers named from "c1" to "c(n)" and related targets from "t1" and "t(n)".

    parX : in AUTO mode is default height value for all cameras.
    parY : in AUTO mode is default time value for all cameras.

"PLAY" : Tell the parser to search in setup.sqs for the programming code for cameras.

"TEST" : Runs the wizard in PLAY mode, but in addition tells the parser to display on screen info about cameras. If you've done a wrong camera setup in the setup.sqs script the errorhandler routine also will notice for you and display information on how to fix that.

    parX : in both TEST and PLAY mode this is number of scene from which the parser starts to play cutscenes. WARNING : In this release this parameter MUST set to 1 (first cutscene).
    parY : in both TEST and PLAY mode this is the number of scenes to play.

"SEARCH" : allows you to make a fast search for a specified camera and play it, to find out if it works well. This is a kind of like the FF key on a videorecorder.
    parX : is the number of the camera in a scene to search for.
    parY : is the number of the scene in which to search for the specified camera.

When your mission executes the camera wizard nothing happens. Why?

The wizard is waiting for the statement that will tell it to start playing the first scene. This is done by setting the reserved global variable CUTSCENE to true. You can do that in an 'on activation' field of a dedicated trigger, or maybe in same field of a waypoint.

When cutscene ends, the control returns back to player until a new statement CUTSCENE = true is found by the parser. In this case the parser starts to play the second cutscene and so on for all the scenes that you have inserted in your mission.

b) Set up cameras in setup.sqs script

The statement that allows you to program a camera is as follows:

setcam(n) = [name,"type",zoom,z_axis,target,zt_axis,time,"effect",("script"/[ADDON])]

Parameters in round brackets are optional, parameters put in quotation marks must be given as strings.

Name is the name of the marker that shows where the camera will be placed. In this case the name must be in quotation marks. You can also give here the name of a unit (i.e. aP) as indicator for camera’s position. If you do that, you done have to include the name in quotation marks. Use of a unit’s name as indicator is forced when the effect "FOLLOWCAM" is set for this camera.

Type is a keyword that selects which kind of camera will be played. Available types at present are:

"STAY" : the camera stays in place for "time" (in seconds).

"MOVE" : the camera(n) starts to move, by getting the position set by the "name" marker (or name unit) and moving to the position shown by camera(n+1), moving over "time" seconds.

"STOP" : this is not a camera command in usual meaning of the word. This allows you to close a chain of MOVE cameras without committing any changes in the last camera’s parameter (so maintaining the same target) and stop the camera watching target for "time" seconds.

"CUSTOM" : this camera behaves like a STAY camera, but allows you to run a custom script AFTER deployment of the camera. Changes are committed before the script starts. The script name is set by the "script" parameter, including the extension (.sqs) and full path if you use some kind of general directories for your scripts. By default, the full setup string for the camera is passed by value to the script, with scene, camnum and target (in the case of "GET" target) in this order.

"SCRIPT" : This is not a camera. This allows you to synchronize external scripts with your cutscene. No changes are committed to a camera, so if in the script you call for no changes to be made the previous camera still runs for TIME seconds. Parameters are set and passed as for a CUSTOM camera.

"ROTATE" : The most powerful kind of camera available. This allows you to move a camera in a along circular path around a target (can also be a moving target). Being an advanced camera, see how to use it in the "Advanced settings" section.

Zoom is the zoom value for this camera.

Z_axis is the height of the camera from the ground. If camera is given by a unit name, this value will be added to the height value for that unit.

Target is the name of the marker that sets where the camera will watch. In this case the name must be in quotation marks. You can also give the name of a unit (i.e. aP) as indicator for camera’s target. If you do that, you don't have to include the name in quotation marks. Use of unit’s name as indicator is forced when an effect "FOLLOWTARGET" is set for this camera.

Zt_axis is the height of the target from the ground. If target is given by a unit name, this value will be overrun.
Time is the time in seconds for the camera to stay in place (STAY, STOP and CUSTOM) or the time the camera takes to get next waypoint (MOVE).

Effect see "Advanced command" for a description. If no effect is set for a camera you must set this parameter at an empty string "".

Script is the name of custom script running with CUSTOM camera. See also "Advanced command" for other uses of this field as ADDON field.

c) Advanced camera command

USE of reserved variable CHOICESCENE

This variable allows you to play optional scenes. An optional scene is a scene that will be played only if certain conditions will be flipped to true part way through a mission. For example, if into the mission you’ve set four scenes (1 to 4), those will be played one by one when the parser runs into the statement CUTSCENE = true. But in this mission you may or may ot nif you want a little cutscene to do a shot of the helys take-off, for example. LSo what you do is setup a 5th SCENE in your setup.sqs script, programming cameras for this optional scene; Call the parser at the start mission with the statement:

["PLAY",1,4] EXEC "deploy.sqs"

(note 3rd parameter : 4 scenes in this mission)

Then, deploy a trigger that will be triggered by your air covering call (i.e. radio trigger) and in its "on activation" field put these statements:

CHOICESCENE = 5;CUTSCENE = true

You’ve finished. This 5th scene will be played optionally. The parser is not affected by this optional call.

Rotate camera

This kind of camera needs some additional parameters to properly run. With these parameters you can command camera's path, framerate and other useful variables making this camera type very versatile :)

Parameters must be set in the ADDON field and have the following syntax:

[alpha_rate, spiral_rate, Z_rate, framerate]

- alpha_rate: Is the angle increment value. Negative value for anti-clockwise rotation. The framerate value effects the behaviour of the camera's shot: the camera's movement on its path is faster with bigger values of alpha_rate.

- Spiral_rate: If set = 0 the camera should follow a circular path. A positive value makes the camera follow an external spiral path with a rate of radius increment equal to Spiral_rate each frame (done by framerate).

- Z_rate: If set = 0 the camera's path lies down on a level surface (const height from the ground). Any other value places camera's path on a cylindrical surface if spire_rate = 0, or on a cone-shaped surface with a negative value for spiral_rate (inverse conical surface for positive value for spiral_rate). The path can be ascending from or descending to the ground (positive or negative value respectively).

- framerate : Is obiousvly the framerate for the camera. Default value is 40 frame/sec (framerate = 0.025). A higher value gives a flickering effect to the shot. A lower one may heavily affect your CPU usage.

NOTE: There are many tricky ways to use alpha_rate with frame_rate. I.e., by setting alpha_rate to 45 (in degrees) and framerate to 8.00 (sec) You'll manage to have multiple stay cameras watching the same target for 8 sec each, from multiple positions deployed along a circular path. Look at this following setup:

["tvcam", "ROTATE", 0.7, 10.00, target, 0.00, 32.00, "TVSET", [90,0,0,8.00]]

With only one setup command line you are able to simulate a perimetrical control camera facilities from 4 towers 10 mt high.. amazing, uh?

- USE of reserved keyword "PARAM"

Instead of putting cameras and/or target names with units or markers names, you can use the reserved keyword "PARAM". If the parser runs into that keyword it will point at the global variable PARAM_C and PARAM_T searching for cameras and target positions respectively. You can set these two variables in your own scripts or in any "on activation" or "on deactivation" field (wherever you want in short).
Have a look at the following example:

["none", "SCRIPT", 0.7, 0.00, target, 0.00, 0.50, "", "myscript.sqs"]
[ myguy, "STAY", 0.7, 1.80, "PARAM", 0.50, 10.00, "BINOCULAR"]


For example, into the mission the unit target might die. Now, at this moment myguy must watch the dead guy with binocular view. In "myscript.sqs" you can test if the target is still alive: if he is, then set PARAM_T = target, else set PARAM_T = anotherguy (or PARAM_T = "newmarker"). In the next statement tell the parser to search the target for that camera in the PARAM_T variable.

- USE of reserved keyword "GET"

Sometimes you may need to join two camera movements. This can be done with a chain of MOVE cameras, but what about joining a camera with FOLLOCAM or FOLLOWTARGET effect with next camera? You don’t know really where the first camera stops its shot. In this case you need the reserved keyword "GET". If the name field is set to "GET" this camera gets the starting point from the last point reached by the previous one. Pretty simple. This is a little example:

[ aguy, "STAY", 0.7, 0.00, aguy, 0.00, 10.50, "FOLLOWTARGET",[0,0,1.8,0]]
[ "GET", "STAY", 0.7, 1.80, aguy, 0.50, 10.00, ""]


Effects

Effects are parameters that allow you to do some pleasant things with your cameras. Some of these effects require the camera or/and target to be set by unit name rather than markers. In addition some effects will require additional parameters to properly work. All effects can work with any kind of camera, but with a "MOVE" camera you can appreciate funny (and if you know them, very useful) behaviours.

The following effects are at present available:

Slowmotion :Self explanatory. The camera will play with a slow motion shot. The speed that time moves at is set by default to 1/5 of normal speed. You can change this parameter for each scene by setting the reserved variable SLOWMOTION.

Binocular : Puts this overlay resource on the screen. The camera plays with a binocular view.

Tvset : Puts this overlay object on the screen.

Followcam :The camera stays near the unit that represents its starting position while it moves. It's target may be a unit or a marker. This effect needs 4 additional parameters that give the offsets( pos or neg) for the 3 axis coordinates in relation to that unit, and the camera rate, setting by default at 40 frames/sec (rate = 0.025). Max rate is 100 frames/sec (rate = 0.01).

You can set these by stating the following parameters array in addon field:

[Xoffset, Yoffset, Zoffset, rate]

Followtarget : This effect runs as previous, but the camera stays near its target. The Name parameter in the setup statement is in this case overrun.

Shake : Allows you to shake the camera (thanks to DRAK for the idea). Very useful for cameras placed in the middle of explosions or maybe near to a tank column moving at full speed. This effect needs 4 additional parameters. You can sets these by stating the following parameter array in addon field:

[shakerate, topeffecttime, fulleffecttime, camerarate]

- shakerate : is max offeset for all 3 axis for shake the camera. You must try out a little with this.

- Topeffecttime : is elapsed time before the effect reach the maximum range of shake. (Do you know Gaussian graphic? )

- Fulleffecttime : is the "plateau" of the effect. Throughout this time the effect works at full range.

- Camerarate : is the flickering of the camera playing the shaking effect. This also effects the increment/decrement of the effect throughout the camera time.

d) Working with setup.sqs script

We have seen above that the statement to program a camera is:

setcam(n) = [name,"type",zoom,z_axis,target,zt_axis,time,("effect"),("script"/[ADDON])]

For each scene you must write this line for all cameras within this scene.

The scene is set a label named #SCENE(n) with (n) = number of scene.

At the end you must collect all camera setups in a global array named DATACAM and then goto the end of script with the statement GOTO "END". Within setup of scenes you can also set some global parameters like SLOWMOTION.

Here is an example:

#SCENE1
SLOMOTION = 0.25
_setcam1 = ["c1" , "STAY" , 0.7, 2.00, "t1" , 1.00, 10 , ""]
_setcam2 = [unit1, "MOVE" , 0.5, 1.00, "t2" , 2,00, 7.5, ""]
_setcam3 = ["c3" , "STAY" , 0.3, 0.50, unit1, 0.00, 10 , "SLOWMOTION"]
_setcam4 = [unit2,"CUSTOM", 0.1, 1.00, unit1, 0.00, 8 , "", "myscript.sqs"]
_setcam5 = [unit1, "STAY" , 0.7, 0.00, unit1, 0.00, 10 , "FOLLOWTARGET",[0,0,1.8,0]]

DATACAM = [_setcam1, _setcam2, _setcam3, _setcam4, _setcam5]

Goto "END"

#SCENE2
......
......
Goto "END"

4) Appendix

a) Reserved Variables

Read only:
         CALLALLOWED[]
         EFFECTALLOWED[]
         CAMALLOWED[]
         SCENE
         CAMERAS
         TESTFLAG
         SEARCHING
         MOTIONRATE
         TIME

Read/Write
         CUTSCENE
         CHOICESCENE
         SLOWMOTION
         PARAM_T
         PARAM_C
         _time

b) Error Messages

        01 : Main command not found.
        02 : Can't find any camera setup for requested scene (s).
        03 : Camera(n) is not deployed.
        04: This kind of camera does not exists.
        05 : Mode SEARCH: Camera not found.
        06 : Effect not allowed or syntax error in effect called for camera(n).
        07 : Target of Camera (n) in scene (s) not found.
        08 : N/A
        09 : N/A
        10 : The parser has found no camera in AUTO mode.
        11 : No target found for camera(n) in AUTO mode.
        12 : Not enough additional parameter sets for effect(type) in camera(n) Scene(s).
        13 : N/A
        14 : Wrong additional parameter sets for effect(type) in camera(n) Scene(s).
        15 : N/A
        16 : Not enough additional parameters sets for camera(n) Scene (s).

5) History

ver 1.4
     added support for Optional Scene
     added reserved keyword GET.
     improved SEARCH mode.
     Fixed AUTO mode bug.
     Fixed inverse angle position on Rotate Camera.

ver 1.3
    added SEARCH mode
    added ROTATE camera.
    Added SCRIPT camera.
    added SHAKE effect (tks to DRAK for idea)
    improved effect FOLLOWCAM and FOLLOWTARGET
    added reserved keyword PARAM
    Fixed sinchronisation with CPU speed.
    some minor bugs fixed

ver 1.2 (first full running version)
    added effects
    more interactive error handler
    supports for multiple camera with single camera marker

ver. 1.1 b
    added support for scenes
    added modality for newbye (AUTO)
    added modality for test (TEST)
    added error handler (TEST)

ver 1.0 b
    supports STAY, MOVE, STOP and CUSTOM camera
    supports marker and units targets
    no effect yet

This tutorial comes with a mission example. Soon available also will be a tips’n tricks mission and a mission tutorial.

Have fun with this wizard. Any suggestion or bug report are appreciated.

Download the example mission.