Important: Many different cameras can be created or removed, but there are three cameras created by HeroBlade which should never be removed: GAME, FLY, and OVERHEAD.
- GAME is the camera that moves with a character.
- FLY is the free-moving camera associated with the various selection tools
- OVERHEAD is the top-down camera that is toggled with the CTRL-O Hotkey
The default camera and mouse movement settings we include with the Clean Engine are there as placeholders so that your team can begin working on day one, but you'll want to put more time into crafting these systems to better fit your game:
Camera and Mouse Movement
There are many ways you can modify the way the camera behaves in response to input (such as mouse input).
The easiest (but least correct) way to smooth mouse-look is to adjust the client side $INPUT system node's "_InputGameMouseSensitivity" field to a value like '0.1'. You'll notice that the intervals the camera rotates are now condensed by a factor of 10 (giving the appearance of 'smooth' mouse-look).
The harder (but far more correct) way to smooth mouse-look would be to set up either a linear or spline interpolation over time such that mouse movement adjusts the 'target' camera destination but does not immediately 'snap' the camera to the new rotation. Then - each frame - smoothly adjust the rotation and position of the camera to match the target such that you get a smooth transition. You can see on line 65 of the client-side script '_Input_Camera' that an immediate snap is the default behavior. This is where you'd want to look to begin adjusting the way camera rotation behaves. Follow this link to an example implementation of a linear interpolated camera to smooth out camera movement Example Advanced Camera
Nearly everything in HeroEngine - including interactivity between mouse input and camera control - is override'able and extendable. Whether that means tweaking a variable like '_InputGameMouseSensitivity' to tweak camera rotation calculations or completely overriding the way cameras work in general, a few script and class changes are usually all you need.
A few useful wiki articles you might want to take a look at as you design any changes to the way things work:
- Adapting Clean Engine
- Per frame callback
- Interpolation curves
- Example Advanced Camera
- The camera functions listed in the remainder of this page.
Cameras have two possible modes:
- LookAt mode
- FreeLook mode
When a camera is created, it is in FreeLook mode by default.
- The following exposed functions are all client-side only; the server has no knowledge of them.
- Anywhere that a camera function takes the name of a camera, you can use "*" to indicate the currently active camera.
Adding, removing, and finding cameras
AddCamera(name as string) as noderef
This function is used to do two things: create a camera and return a generic reference to it; and return a generic reference to an existing camera.
myCam as NodeRef = AddCamera(name)
TestCamera(name as String) as BooleanIf TRUE, the camera exists.
Get All Cameras
GetAllCameras() as List of NodeRefReturns a list of noderef, which contains a list of all of the cameras that currently exist on the client.
RemoveCamera(name as string)This function is used to remove a client's knowledge of a specified camera. It has no return value, but it will throw a script error if the specified camera was not found. The three default cameras should never be removed.
ActivateCamera(name as string)This function tells the client to use the specified camera as the point of view for the viewport. It has no return values, but it will throw a script error if the specified camera was not found.
Get Active Camera
GetActiveCamera() as noderefThis function returns a generic reference to the client's currently active camera.
myCam as NodeRef = GetActiveCamera()
Camera Look Modes
LookAt(cameraName as String, target as noderef of class hbnode, offset as vector3)This function tells the specified camera to enter LookAt mode. This will either cause the camera to look at and lock onto the specified target node, using the specified offset; or if the target is an empty reference, to use the offset as a point in world space to look at and lock onto.
LookAt("NAME", target, offset)
FreeLook(cameraName as string, steady as boolean)
This function tells the specified camera to enter FreeLook mode. If the second parameter is set to true, the camera's rotation property will be set to its current LookAt rotation; if set to false, the camera will snap from its LookAt rotation back to its rotation property.
Is Camera Free
IsCameraFree() as booleanReturns true if the camera is in "Free Look" mode (which it is by default)
Look at Next
LookAtNext(cameraName as string, target as noderef of class hbnode, offset as vector3, time as float, curve as string)
This function works like LookAt(), but also specifies a time over which to turn towards the new target. Additionally, the last parameter specifies the manner in which the turning should be executed.
The way to visualize this is to think of a camera inside of a moving object, like a cameraman inside of a moving car on a highway, who is focusing in on different telephone poles as they whiz past. The cameraman could stay focused on one pole, and then snap to focus on the next one, or they could do a slow pan from the last pole to the next one, or they could start turning slowly from the last pole, and then speed up as they approach the focus point on the new one. In HeroBlade, the car would then be the path follower, and the cameraman would be the camera that's associated with the follower, pointing at each waypoint as the follower moves along the path.
- LINEAR specifies that the camera should turn by the same amount each frame.
- SMOOTH combines EASE_IN and EASE_OUT so that the camera speeds up initially, then slows down near the end of the turn.
- EASE_IN specifies that the camera should turn slowly at first, and speed up during the early portion of the turn, then stop suddenly when the turn is complete.
- EASE_OUT specifies that the camera should turn quickly at first, and decelerate the rate of rotation near the end of the turn.
- TWIST is sort of an inverse of smooth: a lot of change at first, then very little in the middle, then a lot again towards the end, so it almost appears to hold halfway between the targets.
- HOLD specifies that the camera should stay on the old target the whole time period, then go to the next target at the very end.
LookAtNext("NAME", target, offset, 1.0, "SMOOTH")
Is Camera Free
IsCameraFree(cameraName as string) as booleanThis function returns TRUE if the specified camera is in FreeLook mode, or FALSE if it is in LookAt mode.
On Camera Look At Next Done
OnCameraLookAtNextDone()When a camera is done performing a LookAtNext(), if its script field is set and this callback function exists in the specified script, it will be called with me set to the camera. Subsequent calls to LookAtNext() that happen before a previous call has had time to finish, will interrupt the operation, and the previous call will not trigger this callback.
Zooming and panning
Zoom(cameraName as string, amount as float, time as float, curve as string)This function tells the camera to zoom forward or backward in local space, the distance specified by 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 in LookAtNext().
Zoom("NAME", 0.5, 1.0, "SMOOTH")
GetZoom(name as string) as floatReturns the amount of zoom.
Pan(cameraName as string, amount as vector3, time as float, local as boolean, curve as string)This function tells the specified camera to rotate over time, causing to pan, tilt, and/or roll. Again, the manner of motion can be controlled with the same curve parameters as used in LookAt(). By default, the rotation takes place in world space, but you can specify that the rotation take place in local space by passing the local parameter as true. Since the amount parameter is a Vector3, it has 3 subfields: amount.x controls the tilt of the camera; amount.y controls the pan of the camera; and amount.z controls the roll of the camera.
Pan("NAME", amount, 1.0, true, "SMOOTH")
PanTo(cameraName as string, orientation as vector3, time as float, curve as string)Similar to the Pan function, but the "orientation" parameter is the desired camera orientation at the end of the specified time, rather than the amount by which the camera is panned.
On Camera Zoom Done
When a camera is done performing a Zoom(), if its script field is set and this callback function exists in the specified script, it will be called with me set to the camera. Subsequent calls to Zoom() that happen before a previous call has had time to finish, will interrupt the operation, and the previous call will not trigger this callback.
On Camera Pan Done
OnCameraPanDone()When a camera is done performing a Pan() or PanTo(), if its script field is set and this callback function exists in the specified script, it will be called with me set to the camera. Subsequent calls to Pan() or PanTo() that happen before a previous call has had time to finish, will interrupt the operation, and the previous call will not trigger this callback.
Camera position and offsets
Get Camera Position
GetCameraPosition(name as string) as Vector3The above function returns the actual position of the camera, which takes into account aspects such as zoom and offset.
Align Flight Camera
Sets the Fly camera to the current position and rotation of the Game camera
Camera Move To
CameraMoveTo(name as string, position as Vector3, time as float, curve as string)
Moves the specified camera to the target position, taking as much time as is specified, using Interpolation curve specified.
Get Game Camera Rotational Offset
GetGameCameraRotationalOffset() as floatGets the rotational offset from the Game Camera, as the heading that is the offset from looking directly forward.
Set Game Camera Rotational Offset
SetGameCameraRotationalOffset(offset as float)Sets the rotational offset for the Game Camera, as the heading that is the offset from looking directly forward. In other words, an offset of 90 would mean setting the camera to look at the player from over the player's left shoulder.
Clear Game Camera Rotational Offset
ClearGameCameraRotationalOffset()Clears the rotational offset from the Game Camera, for example when looking at a character from the side. It "snaps" back to a no-rotation position.
Get Camera Follow
GetCameraFollow(name as string) as noderef
For the specified camera, if it is set to follow a character, this returns a noderef to the character (or other node) that is being followed. If it is not set to follow a character, it returns a NULL noderef.
Get Camera Follow Offset
GetCameraFollowOffset(name as string) as vector3Returns the specified camera's "follow" offset, meaning the position that the camera is attached to the character (such as the back of the head, or whichever point on the character the camera goes to if it zooms in all the way). For example, the "position" of the character is the position where the character's feet are, and the offset would be the vector3 from the feet to the head.
Get Camera Offset
GetCameraOffset(name as string) as floatFor the specified camera, the offset is the distance that the camera stays away from the node that it is following (in other words, the amount of zoom)
Jolt Active Camera
JoltActiveCamera(joltVector as vector3, time as float, oscillationRate as float)Starts shaking the camera according to the parameters. The camera will continue to shake until told to stop, or it runs out of time as specified. The oscillationRate is the frequency that it will shake back and forth, in cycles per second. joltVector is the direction that the camera will start moving. A very fast jolt might be .2 for the time, and 650 for the oscillation rate, with a random joltVector in a small range.
Stop Jolting Active Camera
StopJoltingActiveCamera()Stops the jolting immediately.
Set Camera Follow
SetCameraFollow(name as string, target as noderef)Sets the specified camera to follow the specified node.
Set Camera Follow Offset
SetCameraFollowOffset(name as string, offset as vector3)Sets the follow offset on the specified camera, meaning the position that the camera is attached to the character (such as the back of the head, or whichever point on the character the camera goes to if it zooms in all the way). For example, the "position" of the character is the position where the character's feet are, and the offset would be the vector3 from the feet to the head.
Set Camera Offset
SetCameraOffset(name as string, offset as float)Sets the distance from the target node, that the camera will follow.
Set Horizontal Center Offset
SetHorizontalCenterOffset(name as string, offset as float)Sets the horizontal center offset, which offsets the screen in relation to where the camera is looking (to allow for a separate interface which may be taking up screen real estate on one side or the other. An offset of .5 makes the center of the screen move to the right, from the viewer's perspective.