Framing, Look At and Focus

Framing modifiers decide where things appear on screen. Composition keeps the view's subject at a chosen screen point and, when a second subject is added, moves the camera so both land on their points. Look At and Lock-On supply that second subject. Look Hint gently turns the camera toward nearby points of interest, and Focus keeps the depth of field on whatever matters. All of them run in the framing stage, before any effect modifier (see The Modifier Stack).

Screen coordinates

Framing works in screen coordinates from -1 to 1 on both axes, with 0 at the center and +Y up. The rule-of-thirds lines sit at ±1/3. Zone sizes are half-sizes in these units, so a dead zone of 0.12 × 0.10 covers 12% of the screen width and 10% of its height.

          amber: anchors · white: dead zone · blue: soft zone  

Anchors are the nine thirds points (Upper Left, Upper Center, Upper Right, Middle Left, Center, Middle Right, Lower Left, Lower Center, Lower Right) or a Custom point. Cameras.Debug 2 draws the same guides over the game view while Composition runs.

Composition

plCameraCompositionModifier places the view's subject on screen. Its default scope is Third Person, Fixed and Rail views.

One subject

Alone, the subject sits at the SoloPoint, and Composition only rotates the camera:

• Inside the dead zone around the anchor, the camera does not turn.
• In the soft zone, the camera turns toward the subject, smoothed by Damping.
• The subject never leaves the soft zone: past its edge the correction is immediate.

A camera jump of more than 3 m is treated as a cut, and the subject is framed again from scratch.

Assist while the player steers

On first- and third-person views, which the player steers, Composition only assists. In frames where the player turns the camera, the soft-zone correction is off. In other frames it is scaled by the player's assist setting: Camera.MouseAssist (default 0) with keyboard and mouse, Camera.GamepadAssist (default 1) otherwise. The soft-zone edge always holds. See Player Look Settings. Fixed and Rail views have no player look input, so Composition owns their aim fully.

Several subjects

A second subject can come from three places, checked in this order: a Look At in progress, a Lock-On target, or the first usable entry of the Subjects list (its object exists and its Weight is above 0). One extra subject is framed at a time. With a second subject, Composition moves the camera as well as turning it, using Balanced Framing (below). The view's subject goes to the layout's player anchor and the second subject to the layout's target anchor.

Layout	Player anchor	Target anchor
Thirds Diagonal	Lower Left	Upper Right
Thirds Horizontal	Middle Left	Middle Right
Over The Shoulder	Lower Left	Middle Right
Custom	Center	The subject entry's own Anchor (Subjects list only)

With Mirror set to Auto, the layout is flipped left to right when the target is on the other side of the player, which needs less camera travel. The decision is made once, when the second subject appears, and kept for as long as it is framed. When framing starts or ends, the camera position and the player's screen point both slide between the solo and the two-subject framing, so neither end pops.

Composition properties

Property	Default	Description
Views	Third Person, Fixed, Rail	View kinds this modifier applies to.
SoloPoint	Center	Center, Left Third, Right Third, or Leading Room: the third behind the subject's direction of travel, so it has room to move into. Leading Room switches sides only on clear sideways movement (above 0.35 m/s) and eases across.
DeadZone	(0.12, 0.10)	Half-size of the dead zone, in screen units (0–0.9).
SoftZone	0.55	Half-size of the soft zone, in screen units, the same on both axes (0.05–0.95).
Damping	0.35 s	Time constant for turning while the subject is in the soft zone.
Several Subjects
Layout	Thirds Diagonal	Layout for subjects from the Subjects list.
Mirror	Auto	Auto or Off, for subjects from the Subjects list.
Subjects	empty	Extra subjects to frame with the view's subject (see below).
MinDistance	2.5	Closest the camera may be to the player while framing two subjects, in meters.
MaxDistance	10	Farthest the camera may be from the player while framing two subjects, in meters.
MaxFieldOfView	0	When the two subjects cannot be framed exactly, the field of view may widen up to this many degrees if that gets closer. 0 never widens.
CollisionLayer	0	Physics collision layer for the collision sweep.

Each entry of the Subjects list has these properties:

Property	Default	Description
Object	empty	Object path or name, searched relative to the view's object.
Offset	(0, 0, 0)	Point to frame, in the object's space.
Anchor	Upper Right	Screen anchor for this subject. Used with the Custom layout, as other layouts use their own anchors.
CustomAnchor	(0, 0)	Screen point when Anchor is Custom.
Weight	1	0 skips the entry. Any value above 0 frames it.
MustKeep	off	Stored with the entry. The current solver does not use it.

Balanced Framing

Balanced Framing is how Composition places the camera for two subjects. In plain words:

1. The player is pinned exactly. Whatever happens, the view's subject lands on its anchor.
2. The camera moves on its orbit. For two screen points and a field of view, the two subjects must appear a fixed angle apart. Every camera position that sees them that far apart lies on one surface around them. The solver stays at the distance from the player closest to where the camera is now, within MinDistance and MaxDistance, and searches around that surface for the position nearest the current camera where the target lands on its anchor. The horizon stays level.
3. The camera stays at a usable height. Positions more than 25° below or 70° above the player are not used, because from there the camera would look almost straight up or down.
4. It relaxes when it cannot fit. If no position frames both exactly (the subjects are too far apart, too close, or only fit from straight above), the closest framing is used: the player stays pinned and the target drifts off its anchor. If MaxFieldOfView is set and a wider lens gets closer, the field of view widens.
5. Collision. A 0.2 m sphere is swept from the player to the solved position against static geometry. If it hits, the camera is pulled in along that line (never closer than 0.3 m), which keeps the player pinned and lets the target relax.
6. Continuity. The camera eases toward each new solution over about a quarter of a second, so a subject crossing behind the player does not make it jump.

The debug overlay reports balanced when both subjects are framed exactly, balanced (relaxed) otherwise, and the target's distance from its anchor in screen units.

Look At

plCameraLookAtModifier is "press F to look at". When its Action is pressed, it frames the best point of interest in range. Its default scope is First and Third Person views.

Choosing the point

While not framing, Look At checks every active point of interest each frame. A point is eligible when:

• the player (the view's subject) is within its ActivationRadius and inside its ViewCone,
• its frame point is in front of the camera (within roughly 78° of the view direction), and
• if RequireLineOfSight is on, nothing static blocks a ray from the camera to it.

Among eligible points the highest Priority wins, then the one nearest the player. Whenever the best point changes, Look At sends plMsgCameraPointOfInterestChanged as an event message to the player object, where the first handler on it or its parents receives it. The message carries the point's component handle (invalid when nothing is in range) and its DisplayName, so game UI can show or hide its prompt. C++ code can also ask the director with GetBestPointOfInterest().

Framing it

Look At starts on a key press while a point is eligible, on the director's LookAtObject, or by itself the first time an AutoTrigger point becomes eligible. It then ramps in over BlendIn:

• Balanced framing hands the point to Composition as a second subject, laid out by Layout, so the camera moves to show the player and the point together. This needs a Composition modifier whose scope includes the active view.
• Aim framing, or Balanced framing without a Composition in scope, turns the camera to the point and blends the field of view to the zoom field of view. In first person this is what happens with the default scopes, since Composition does not include first-person views.

It ends when:

• Hold is For Duration and BlendIn plus the hold time has passed (the point's HoldTime if set, otherwise Duration),
• Hold is While Held and the key is released after the blend-in,
• BreakOnInput is on and the player turns the camera (after the first 0.2 s), or
• the point is removed.

Then it ramps out, and Release decides where the view looks. Keep Direction hands the camera's final direction to the view, so nothing snaps back. Return hands back the direction from before the look started. Views that keep their own look direction (Third Person and First Person) take it over, while Fixed and Rail views ignore it.

note

A First Person View with YawFromEyeObject on takes its yaw from the character again on the next frame, so after a look only the pitch is kept.

Property	Default	Description
Views	First Person, Third Person	View kinds this modifier applies to.
Action	LookAtInterest	Input action that starts a look.
Framing	Balanced	Balanced (player and point together, through Composition) or Aim (turn to the point and zoom).
Layout	Thirds Diagonal	Two-subject layout for Balanced framing. Custom falls back to Thirds Diagonal.
Mirror	Auto	Auto flips the layout when the point is on the player's other side, decided when the look starts. Off never flips.
BlendIn	0.6 s	Ramp-in time. The ramp out takes 80% of it.
Hold	For Duration	For Duration or While Held.
Duration	3 s	Hold time after the blend-in, unless the point sets its own.
ZoomFieldOfView	45	Field of view for Aim framing (1–170), unless the point sets its own.
Release	Keep Direction	Keep Direction or Return.
BreakOnInput	on	Player look input ends the look early.

Camera Point Of Interest

plCameraPointOfInterestComponent marks something worth looking at. It does nothing on its own, and Look At and Look Hint read it. The editor draws its activation radius in gold with a manipulator and, when selected, the edges of its view cone, a line to the frame point and a cross at the frame point.

Property	Default	Description
DisplayName	empty	Name for the game's prompt, for example "Shrine of Ash".
ActivationRadius	15	The player must be within this distance of the object, in meters.
ViewCone	360°	Full angle around the object's +X axis in which the player must stand (1–360°). 360° means any side.
RequireLineOfSight	on	The frame point must be visible from the camera (static geometry only).
Priority	0	Higher priorities win over nearer points.
FrameOffset	(0, 0, 0)	The point the camera frames, in the object's space, for example the top of a statue.
ZoomFieldOfView	0	Field of view for Aim framing. 0 uses the modifier's.
HoldTime	0 s	How long to hold. 0 uses the modifier's Duration.
AutoTrigger	off	Frames itself once, without a key press, the first time it becomes eligible after play starts. For scripted story beats.

Look Hint

plCameraLookHintModifier is a slow, weak pull toward the nearest point of interest in range, while the player is not steering. After the player has not turned the camera for IdleTime, it turns the view's heading toward the nearest point whose radius and view cone contain the player, at most Speed per second. It changes the view's own look direction, so the player takes over without a jump. It never takes control: any look input resets the idle timer, and it waits while Look At or Lock-On is framing. Line of sight and priority are not checked.

Property	Default	Description
Views	Third Person	View kinds this modifier applies to.
Speed	8°	Turn speed toward the point, in degrees per second.
IdleTime	1.5 s	Time without look input before the hint starts.

Focus

plCameraFocusModifier keeps the depth of field on what matters and pulls focus smoothly over PullTime. It picks the first of:

1. the Look At or Lock-On target, while one is more than halfway blended in,
2. with Target set to Subject, the view's subject,
3. with Target set to Crosshair, whatever a ray along the view direction hits (static and dynamic shapes), up to MaxDistance, or
4. otherwise MaxDistance.

The director writes the result to its camera when its WriteFocus is on, and switches the camera's focus mode to Manual. Views that set their own focus distance (Fixed, Rail, Top-Down) are blended toward Focus's value by its weight. In standalone mode no focus is written.

Property	Default	Description
Views	all	View kinds this modifier applies to.
Target	Subject	Subject or Crosshair.
PullTime	0.4 s	Time constant for focus pulls.
MaxDistance	200	Crosshair ray length, and the focus distance when nothing else applies (1–100000).

Lock-On

plCameraLockOnModifier locks onto a target and keeps it framed with the player through Composition. Targets are objects carrying the tag in TargetTag (default LockOnTarget) that have render bounds (a mesh or other rendered component), lie within MaxDistance of the player and are in front of the camera (within roughly 72° of the view direction).

• Action toggles the lock with Toggle on, or holds it while pressed with Toggle off. The first target is the one nearest the screen center.
• SwitchAction picks the next target to the right, wrapping around.
• A target farther than 1.2 × MaxDistance is lost. The modifier then picks a new one, or releases the lock when there is none.
• While Look At frames something, Look At wins.

note

Lock-On does not turn the camera itself. It needs a Composition modifier whose scope includes the active view.

Property	Default	Description
Views	Third Person	View kinds this modifier applies to.
Action	LockOn	Input action that locks on.
SwitchAction	empty	Input action that switches to the next target.
Toggle	on	On: a press toggles the lock. Off: the lock holds while the action is held.
TargetTag	LockOnTarget	Tag that marks lock-on targets.
MaxDistance	25	Search radius around the player, in meters (1–1000).
TargetOffset	(0, 0, 1.2)	World-space offset added to the target's position, for example to aim at the chest.
Layout	Over The Shoulder	Two-subject layout. Custom falls back to Over The Shoulder.
Mirror	Auto	Auto or Off, decided when a target is picked.
BlendIn	0.4 s	Ramp time in and out.

Press F to look at a shrine

1. In the project's input action map, add an action named LookAtInterest and bind it to F and a gamepad button. Make sure the player has a plInputComponent that uses the map.
2. Set up a third-person camera with a Camera Director.
3. In the director's Modifiers list, add Composition, Look At and Focus. Leave Composition's SoloPoint at Center.
4. Select the shrine object and add a Camera Point Of Interest. Set DisplayName to "Shrine of Ash", ActivationRadius to 12, and FrameOffset to the top of the statue, for example (0, 0, 2.5). If the shrine should only be offered from the front, set ViewCone to 120° and turn the object so its +X axis faces the approach.
5. On the player, add a script or component that handles plMsgCameraPointOfInterestChanged: show "F Look at" plus DisplayName when the handle is valid, and hide the prompt when it is invalid.
6. Play, walk up to the shrine and press F. The camera moves so the player sits lower left and the statue upper right, holds for three seconds, then keeps the new direction. Turn the camera to break out early.
7. Run Cameras.Debug 2 to see the thirds grid and where the statue lands. To show the shrine in a cutscene-like beat without a key press, turn on AutoTrigger, or call LookAtObject("Shrine") on the director.

Troubleshooting

Symptom	Likely cause
The prompt never appears	The player is outside ActivationRadius or the view cone, the frame point is behind the camera, or static geometry blocks the line of sight. Look At's debug line reads point in range when a point is eligible.
Pressing F turns the camera but does not show the player	No Composition modifier applies to the active view, or Framing is Aim. In first person this is the default.
The target misses its thirds point	The two subjects cannot be framed within MinDistance/MaxDistance and the elevation limits, or collision pulled the camera in. The overlay shows balanced (relaxed). Raise MaxDistance or set MaxFieldOfView.
Composition fights the mouse	With Camera.MouseAssist at 0 (the default), only the soft-zone edge corrects the camera. If the edge is reached while turning, widen SoftZone. If a gamepad player feels it, lower Camera.GamepadAssist.
Lock-On finds nothing	Targets lack the TargetTag tag, have no render bounds, are farther than MaxDistance, or are behind the camera.
Focus never changes	The director's WriteFocus is off, or the camera runs in standalone mode.

Reference: the two-subject camera surface follows Lino & Christie, "Intuitive and Efficient Camera Control with the Toric Space", ACM SIGGRAPH 2015.

See also: Gameplay Cameras · The Modifier Stack · Camera Director · Player Look Settings · Camera Views