Camera Views

A camera view is a component that works out where a camera should be for one frame: its position, rotation, field of view, focus distance and near plane. With a Camera Director in the world, the director asks the active view for its pose, blends it and writes it to its own camera. Without a director, each view writes its pose to its own object (standalone mode). All views share a set of common properties and can carry their own modifier list.

Common view properties

Every view derives from plCameraViewComponent and shows these properties in its View and Modifiers groups.

Property	Default	Description
FieldOfView	0	Field of view in degrees (0–170), in whatever axis the camera component's mode fixes. 0 keeps the camera's own field of view: the camera component's value, read once when play starts. A non-zero value replaces it while this view is shown. The player's field-of-view offset and modifiers such as FOV Kick and Zoom apply on top in both cases.
Priority	50	Stored with the view. In this version every request names its own priority (a volume's Priority, the Priority argument of ActivateView, or the request message), so this value does not affect which view is shown.
BlendTime	0 s	Blend used when this view becomes active and the request does not set one. 0 uses the director's BlendTime.
BlendCurve	Ease In Out	Curve for this view's blend: Cut, Linear, Ease In, Ease Out or Ease In Out. Only used when BlendTime is above 0.
Modifiers	empty	Modifiers that only apply while this view is active. They run before the director's modifiers in each stage. See The Modifier Stack.

The subject

Most views have a subject: the object they follow or look at, usually the player. Framing modifiers aim at the subject point, effect modifiers read its speed and ground state, and camera volumes test where it is. Grounded, airborne and crouching states are read from any component on the subject object that exposes the script functions IsStandingOnGround, IsInAir and IsCrouching, which the character controllers do.

View	Subject object	Subject point
Third Person	Target Object	Halfway between Target Offset Low and High, in the target's space.
First Person	The topmost ancestor of the eye object (the character root)	The eye point.
Fixed, Rail	Target	The target's position plus Target Offset.
Top-Down	Target	The target's position.

Object references

Reference properties such as Target, Spline and EyeObject are picked in the editor like any other object reference. At runtime, a reference set from script is treated as an object path or name, searched relative to the view's object. The Third Person View's TargetObject is always a path or name (default .., the parent).

Looking through a view in the editor

Selecting an object with a view draws its rig in the viewport: a frustum at the view's last pose, plus the view-specific drawing described below. While playing, Cameras.Debug 2 draws the active view's rig.

Third Person View

plThirdPersonViewComponent puts the camera on an arm behind a target. The arm hangs from a pivot point between TargetOffsetLow and TargetOffsetHigh, picked by how far the arm is raised, and pitches between MinUpRotation and MaxUpRotation. A positive up rotation raises the arm, so the camera sits above the target and looks down. The arm is kept below CeilingHeight and above FloorHeight, both measured from the target's origin. A sphere of radius SweepWidth is swept along the arm. When it hits, the camera is pulled in at ZoomInSpeed and let back out at ZoomOutSpeed, never closer than MinDistance.

Version-1 compatible defaults

With its default settings the view behaves as it did in Game Components 1.x: it follows the target's yaw, pitches only through the RotateUp script function, and its sweep hits static shapes only. Scenes saved with version 1 of the component load their original properties, and every property added in version 2 starts at a value that keeps that behaviour: no look input, Follow Target yaw, no shoulder offset, no lag, no recentering, no dynamic-shape hits and no look-ahead. The common view data loads with its defaults, so FieldOfView 0 leaves the camera's field of view as authored.

The version-2 properties are all opt-in:

• Look input (LookInput): the view turns from input actions by itself. See Look input.
• Yaw mode (YawMode): Follow Target keeps the camera behind the target and adds look input as an offset, while Free orbits independently of the target's rotation.
• Shoulder offset and shoulder swap: shift camera and aim point sideways together.
• Position lag: the aim point trails the target.
• Auto recenter: swings the camera back behind a moving target after the player stops steering.
• Hit Dynamic Shapes: dynamic bodies also pull the arm in. Characters never do.
• Look-ahead: the camera aims ahead of a moving target.

Properties

Property	Default	Description
Rig
TargetObject	..	Path or name of the object to follow, searched relative to the view's object. .. is the parent.
TargetOffsetHigh	(0, 0, 0)	Pivot in the target's space when the arm is fully raised.
TargetOffsetLow	(0, 0, 0)	Pivot in the target's space when the arm is fully lowered. Level arms use the point halfway between the two.
MinDistance	0.25	Closest the sweep may pull the camera to the pivot, in meters (0.05–10).
MaxDistance	3	Arm length when nothing is in the way, in meters (0.5–100).
MinUpRotation	-70°	Lowest arm angle (camera below the pivot, looking up). Range -85° to 70°.
MaxUpRotation	80°	Highest arm angle (camera above the pivot, looking down). Range -70° to 85°.
CeilingHeight	4	The camera stays below this height above the target's origin while the arm is raised.
FloorHeight	0	The camera stays above this height above the target's origin while the arm is lowered.
CollisionLayer	0	Physics collision layer the arm sweep tests against.
SweepWidth	0.2	Radius of the sphere swept along the arm, in meters (0.05–2).
ZoomInSpeed	10	How fast the camera moves in when the arm gets shorter. Higher is faster.
ZoomOutSpeed	1	How fast the camera moves back out when the arm gets longer. Higher is faster.
HitDynamicShapes	off	Off: only static shapes pull the arm in. On: dynamic bodies do too.
Control
LookInput	no actions	Input actions that turn the view. Horizontal input changes the yaw, vertical input raises or lowers the arm. See Look input.
YawMode	Follow Target	Follow Target stays behind the target, and look input and Orbit add an offset. Free orbits on its own, starting from the target's facing when play starts.
ShoulderOffset	0	Sideways offset of camera and aim point in meters, positive to the right (-3 to 3). Changes ease in over a fraction of a second.
ShoulderSwapAction	empty	Input action that moves the camera to the other shoulder when pressed.
PositionLag	0 s	How far the aim point trails the target, as a time constant (0–2 s). 0 follows exactly.
AutoRecenter	off	Follow Target mode only: swings the camera back behind the target after the player has not steered for RecenterDelay, but only while the target moves (above about 0.5 m/s).
RecenterDelay	2 s	Time without steering before recentering starts.
RecenterSpeed	90°	Recentering speed, in degrees per second.
LookAhead	0	How far ahead of a moving target the camera aims, in meters (0–10). The full distance is reached at 6 m/s.

Script functions

Function	Description
RotateUp(angle)	Raises the arm by the angle (negative lowers it), clamped to the up rotation limits.
Orbit(angle)	Turns the camera around the target. Positive turns left.
SwapShoulder()	Moves the camera to the other shoulder.

Editor drawing

When the object is selected, the view draws the line between the two target offsets, the arm to the current camera position and its continuation to MaxDistance, the sweep sphere (amber when blocked), the ceiling and floor as squares around the target, and the camera frustum. In edit mode the drawing uses the view's own maths with a level arm, so you can tune distances and offsets without playing.

Setting up a third-person camera

1. Open the character prefab. Make sure the root has a plInputComponent using the project's input action map if the camera should read look input.
2. Add a child object named CameraView and add a Third Person View to it. Leave TargetObject at ...
3. Set TargetOffsetLow to about chest height, for example (0, 0, 1.2), and TargetOffsetHigh to about head height, for example (0, 0, 1.7). Select the object and check the drawn rig.
4. Set MaxDistance to the arm length you want, for example 3.5, and CollisionLayer to the layer your level geometry uses.
5. In the Control group, open LookInput and set LookAction to the action that reports mouse or stick movement (or set the four turn and look actions). Set YawMode to Free if the camera should orbit independently of the character's facing.
6. Optional: set ShoulderOffset to 0.5 for an over-the-shoulder camera, assign a ShoulderSwapAction, and turn on HitDynamicShapes if crates and doors should push the camera in.
7. In the scene, create a Camera object with a Camera component (Usage Hint Main View) and a Camera Director. Set the director's DefaultView to the CameraView object of the placed character.
8. Play and turn the camera. Run Cameras.Debug 2 to see the rig while playing.

note

Without a director, put the Camera component on CameraView instead. The view then moves that object itself, which is how scenes made with Game Components 1.x work.

First Person View

plFirstPersonViewComponent puts the camera at a character's eyes. The position follows the eye object plus EyeOffset. Only the height is smoothed, over EyeHeightSmoothing, so crouching eases while walking stays exact. With YawFromEyeObject on, the yaw comes from the eye object, so a character controller that turns itself also turns the view. Pitch comes from look input or script and is clamped to MaxPitch. In a headset (camera mode Stereo) the view adds no pitch, and the director writes only position and yaw, because the headset owns the rest.

Property	Default	Description
EyeObject	empty	The object at the eyes, usually the character's head object. Empty uses the view object's parent.
EyeOffset	(0, 0, 0)	Offset of the eye point in the eye object's space.
EyeHeightSmoothing	0.12 s	Time constant for height changes such as crouching (0–2 s). 0 follows exactly.
MaxPitch	85°	Pitch limit up and down (0–89°).
YawFromEyeObject	on	On: yaw follows the eye object's facing, and horizontal look input is ignored. Off: horizontal look input turns the view by itself.
LookInput	no actions	Input actions that pitch (and, with YawFromEyeObject off, turn) the view. See Look input.
NearPlane	0	Near clip distance while this view is shown, in meters (0–1). 0 leaves the camera's own setting.

Function	Description
SetVerticalRotation(Radians)	Sets the pitch, clamped to MaxPitch.
ChangeVerticalRotation(Radians)	Adds to the pitch, clamped to MaxPitch.

The two script functions have the same names and arguments as the Head Bone component's, so scripts written for Head Bone drive the First Person View unchanged.

Setting up a first-person camera on a character with a head object

1. Open the character prefab. The character controller sits on the root and has a head object as a child (the object it raises and lowers when crouching).
2. Under the head object, create a child object named FirstPersonView and add a First Person View. Leave EyeObject empty, so it uses the head object.
3. If the eyes are not at the head object's origin, set EyeOffset.
4. For pitch, either set LookInput → LookUpAction and LookDownAction (or a vector LookAction), or keep the script that called Head Bone's ChangeVerticalRotation and point it at this component instead. Leave YawFromEyeObject on so the character controller keeps turning the player.
5. If the player's own arms or weapon clip into nearby walls, set NearPlane, for example to 0.05.
6. In the scene, set the Camera Director's DefaultView to the FirstPersonView object, or put the Camera component on FirstPersonView for standalone mode.
7. Add Head Bob, Landing and Recoil modifiers to the director or to the view's own Modifiers list. Head Bob is scoped to first-person views by default.

note

If the head object still has a Head Bone component, remove it or stop calling it. Both would pitch the camera.

Fixed View

plFixedViewComponent stays where it is placed: a security camera or a fixed-angle shot. Without a target it uses its object's rotation. With a Target it turns to keep looking at it, smoothed by TrackingSmoothing, and sets the focus distance to the target. With FrameTarget on it also narrows the field of view so an area FrameSize meters tall around the target fills the screen height. The result is never below 5° and never wider than FieldOfView, or 90° when FieldOfView is 0.

Property	Default	Description
Target	empty	Object to look at.
TargetOffset	(0, 0, 1)	World-space offset added to the target's position.
TrackingSmoothing	0.15 s	Time constant for turning toward the target (0–2 s). 0 turns instantly.
FrameTarget	off	Narrows the field of view to frame the target.
FrameSize	3	Height in meters of the area framed around the target (0.1–100).

Rail View

plRailViewComponent rides along a spline like a camera on a dolly track and looks at a target. The spline is a plSplineComponent, and you edit its nodes with the Spline Edit Mode. Positions on the spline are evaluated in global space. In Closest To Target mode the camera sits at the point of the spline nearest the target, shifted by KeyOffset. In Scripted mode a script moves it with SetRailKey. Movement along the spline is smoothed by RailSmoothing. Without a target the camera looks along the spline.

Property	Default	Description
Spline	empty	Object with the plSplineComponent. Empty uses the view's own object.
Target	empty	Object to look at and, in Closest To Target mode, to follow along the spline.
TargetOffset	(0, 0, 1)	World-space offset added to the target's position.
Mode	Closest To Target	Closest To Target or Scripted.
KeyOffset	0	Added to the spline key, so the camera can lead or trail the target along the track.
RailSmoothing	0.3 s	Time constant for movement along the spline (0–5 s). 0 follows exactly.

Function	Description
SetRailKey(Key)	Sets the spline key the camera moves to in Scripted mode. The key is the spline's own parameter.

warning

In standalone mode the view moves its own object. Keep the spline on a separate object in that case, otherwise the spline moves with the camera.

Top-Down View

plTopDownViewComponent places the camera high above a target at a fixed pitch, for top-down, isometric and strategy games. The camera looks at the target plus any pan offset from the current zoom distance, at Pitch below the horizon and Yaw around it. Zoom steps, rotation steps and panning come from input actions or script, and zoom and rotation changes ease in. With GroundFollow on, the focus point drops onto the static ground under it.

Property	Default	Description
Target	empty	Object to follow. Without one, the view's own position is the focus point.
Pitch	55°	Angle below the horizon (5–89°).
Yaw	45°	Starting heading around the focus point.
Control
RotateStep	90°	How far one rotate step turns.
RotateLeftAction	empty	Input action that rotates one step left when pressed.
RotateRightAction	empty	Input action that rotates one step right when pressed.
Zoom
ZoomDistances	8, 14, 22	Camera distances for each zoom level, nearest first. An empty list uses 14.
StartZoom	1	Index of the zoom level when play starts.
ZoomInAction	empty	Input action that moves one level closer when pressed.
ZoomOutAction	empty	Input action that moves one level further when pressed.
Pan
PanAction	empty	Vector input action: y pans away from the camera, x to its right.
PanSpeed	12	Pan speed in meters per second at zoom distance 14, scaled with the current distance (0–500).
MaxPan	30	Farthest the pan may move from the target, in meters.
EdgeScroll	off	Pans while the mouse is within 2% of a screen edge.
Follow
FollowLag	0.2 s	Time constant for following the focus point (0–3 s). 0 follows exactly.
GroundFollow	off	Moves the focus point down onto static ground (a ray cast from 50 m above it, 100 m long).

Function	Description
ZoomIn()	One zoom level closer.
ZoomOut()	One zoom level further.
RotateStep(Steps)	Rotates by RotateStep times the number of steps. Positive turns left.
ResetPan()	Moves the focus back onto the target.

warning

Give the Top-Down View a Target when it runs in standalone mode. Without one it uses its own position as the focus point while also moving its own object, so the camera keeps sliding away.

Troubleshooting

Symptom	Likely cause
The camera does not move at all	The view has no target (Third Person: TargetObject does not resolve, First Person: no eye object and no parent, Rail: no spline), or the world has a director that shows a different view.
Look input does nothing	No LookInput actions are set, or no active plInputComponent is found on the subject, its parents, the view's object or its parents.
First-person view does not turn left and right from look input	YawFromEyeObject is on, so yaw comes from the character. Turn the character, or switch the option off.
Third-person camera passes through crates and doors	HitDynamicShapes is off, or the bodies are on a layer that CollisionLayer does not collide with.
The field of view changes when a view becomes active	That view has a non-zero FieldOfView. Set it to 0 to keep the camera's own field of view.
Camera slides out from close up when play starts	The arm starts short and lengthens at ZoomOutSpeed. Raise ZoomOutSpeed for a faster start.

See also: Gameplay Cameras · Camera Director · The Modifier Stack · Framing, Look At and Focus · Player Look Settings