Camera commands
Issuing Camera Commands from Waypoint Data
Also see:
Overview
This is a system usable by GameMasters to set up a path and waypoints, and then send a camera along that path. For example, this could be used to choose a path for making a demo videotape of the game.
Setup and execution
The first thing required, is to set up an Area with which to use the MasterCamera script. For a tutorial, please see: Area Creation.
Next, various commands are issued via the CLI. These commands can control the camera.
Setup
- call mastercamera setup;<path name>
where <path name> is the path that the camera will follow. Setting up an area will need to be redone each time that you reload it.
Check if an area is setup for use with the camera
You can check if an area is set up from the CLI, by typing:
- call mastercamera check
Start the camera moving
Once set up, start the camera moving along the path with:
- call mastercamera start
This will move the follower to the first waypoint on the path, unpause the follower, create the camera and attach it to the path follower, activate it, and execute the first waypoint's commands.
Pause and unpause the camera
Once started, you can pause the camera's motion with:
call mastercamera pause
which pauses the path follower, aligns the fly camera with the cinema camera, then activates it. This allows you to study the scene from that perspective, and fly around without disrupting the cameras progression. When ready, use:
call mastercamera unpause
to re-activate the cinema camera and release the path follower. Alternately you can reset the fly camera to the cinema camera's position and rotation with:
call mastercamera resetfly
End the session
When you wish to end the whole process:
call mastercamera stop
This will pause the path follower, activate the fly camera wherever it was last at, and remove the cinema camera. (Removing the cinema camera isn't really necessary, but is done to exercise the function.)
All of these functions also exist as waypoint commands of the same name, except for areasetup and checkarea. None require any parameters.
Using Waypoint Data Commands
Commands are text strings in the waypoint data box, which is in the properties section of the Paths Panel in HeroBlade.
The string consists of the command, followed by zero or more parameters that are separated by semi-colons. For example:
lookat;181591;0,0,0
where lookat is the command, 181591 is the first parameter, and 0,0,0 is the second parameter.
Each command must be on its own line, without any blank lines in the data. Long commands that wrap in the waypoint data box are okay, they will be read as individual commands. However blank lines, including a terminating blank line, will cause a script error as the script interprets that line as an invalid command. Any number of commands can be executed from a waypoint, and they will be executed in the order they are listed.
The Commands
Autoroll
autoroll;<speed as float>
This sets the AutoRoll property on the path follower.
Freelook
freelook;<boolean>
This tells the camera to stop looking at its focus and enter FreeLook mode. When <boolean> is true, the camera retains its current rotation, and when false it reverts to its last non-lookat rotation.
Lookat
lookat;<target as id>;<offset as vector3 string>
This tells the camera to look at and lock onto the specified target or point in space. If a target id is specified, then offset is used as a local space offset to that target. If the target is specified as zero, then offset is used as a point in world space to use as the target. This command causes the camera to snap to its lookat rotation.
Lookatnext
lookatnext; <target as id>;<offset as vector3 string>;<time as float>;<curve as string>
This tells the camera to look at and lock onto the specified target or point in space in the same fashion as the lookat command. However, rather than snapping to its new rotation, the camera will rotate over time in the manner specified by the curve attribute. For more deals on curve attributes available, see Interpolation curves.
Lookbackward
lookbackward
This command has no parameters. It causes the camera to LookAtNext the previous waypoint on the path.
Lookforward
lookforward
This command has no parameters. It causes the camera to LookAtNext the next waypoint on the path.
Pan left
panleft; <amount as float>
This command tells the camera to pan to the left by the specified number of degrees. Note that this does nothing visually while the camera is in LookAt mode. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree pan). Note that this does nothing visually while the camera is in LookAt mode.
Pan right
panright; <amount as float>
This command tells the camera to pan to the right by the specified number of degrees. Note that this does nothing visually while the camera is in LookAt mode. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree pan). Note that this does nothing visually while the camera is in LookAt mode.
Pause
pause
This command functions exactly like executing the CLI pause command described earlier.
Pause post lookatnext
pausepostlookatnext
This command has no parameters. It tells the camera that the next time it is done with a lookatnext command, it should execute a pause command.
Pause post pan
pausepostpan
This command has no parameters. It tells the camera that the next time it is done with a pan command, it should execute a pause command.
Pause post zoom
pausepostzoom
This command has no parameters. It tells the camera that the next time it is done with a zoom command, it should execute a pause command.
Reset Fly
resetfly
This command has no parameters. It causes the fly camera to be positioned and rotated to view the scene from the same place and angle as the cinema camera.
Roll left
rollleft;<amount as float>
This command causes the camera to roll left the specified number of degrees. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree roll. This command works regardless of mode.
Roll right
rollright;<amount as float>
This command causes the camera to roll right the specified number of degrees. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree roll. This command works regardless of mode.
Script
script;<scriptname as string>
This command will cause the MasterCamera script to call the specified script at the shared function: ReachedWaypoint(path as Node Ref of Class hbpath, wp as ID), where wp is the waypoint that the command was issued from, and path is that waypoint's path.
Set rotation
setrotation;<offset as vector3 string>
This command will cause the camera's rotation to snap to the specified angle. Note that this does nothing visually while the camera is in LookAt mode.
Set slowing
setslowing;<value as float>
This command will set the path follower's SlowdownWhenTurning property.
Set speed
setspeed;<speed as float>
This command will set the path follower's speed property.
Set tolerance
settolerance;<value as float>
This command will set the path follower's tolerance property.
Set turnrate
setturnrate;<value as float>
This command will set the path follower's turn rate property.
Snap backward
snapbackward
This command has no parameters. This command will cause the camera to enter FreeLook mode and look directly backward with respect to the path follower's rotation.
Snap forward
snapforward
This command has no parameters. This command will cause the camera to enter FreeLook mode and look directly forward with respect to the path follower's rotation.
Start
start
This command functions exactly like executing the CLI start command described earlier.
Stop
stop
This command functions exactly like executing the CLI stop command described earlier.
Tilt down
tiltdown;<amount as float>
This command tells the camera to tilt down by the specified number of degrees. Note that this does nothing visually while the camera is in LookAt mode. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree tilt). Note that this does nothing visually while the camera is in LookAt mode.
Tilt up
tiltup;<amount as float>
This command tells the camera to tilt up by the specified number of degrees. Note that this does nothing visually while the camera is in LookAt mode. It does this at a rate of .017 seconds per degree of rotation (just over 3 seconds for a 180 degree tilt). Note that this does nothing visually while the camera is in LookAt mode.
Unpause
unpause
This command functions exactly like executing the CLI unpause command described earlier.
Zoom
zoom;<amount as float>;<time as float>;<curve as string>
This command tells the camera to zoom forward or backward in local space, the distance specified by the amount. Forward motion is accomplished with a positive amount, while backward motion is accomplished with a negative amount. While this changes the camera's perspective, it does not actually change the camera's position property. The camera will zoom in or out over the specified period of time, using the same curve parameters as used with lookatnext. For more information on various curve parameters, see Interpolation Curves.
Zoom in
zoomin;<amount as float>
This command requires that the camera be in LookAt mode. It tells the camera to zoom forward the specified decimal percentage distance between the camera's current location and the LookAt location (so amount must be between 0 and 1; bigger is closer to the LookAt location). The zoom occurs over a 2 second period.
Zoom out
zoomout;<amount as float>
This command requires that the camera be in LookAt mode. It tells the camera to zoom backward the specified decimal percentage distance between the camera's current location and the LookAt location (so amount can be any positive value; bigger is farther away from the LookAt location). The zoom occurs over a 2 second period.
Zoom reset
zoomreset
This command causes the camera to zoom back to normal view over a 2 second period.
