The Modifier Stack and Effect Modifiers

Modifiers adjust the camera pose after the view has computed it and the director has blended it. Framing modifiers aim the camera, and effect modifiers add motion on top of the framed pose. Each modifier is an entry in an ordered Modifiers list, either on the Camera Director (applied to every view) or on a view (applied only while that view is active). This page covers how the stack runs and every effect modifier. The framing modifiers are described in Framing, Look At and Focus.

How the stack runs

Each frame, after blending:

1. Prepare. Every enabled modifier gets a chance to exchange information, the active view's first, then the director's. This is how Look At hands a second subject to Composition.
2. Framing stage. Framing modifiers of the active view, in list order, then those of the director.
3. Effects stage. Effect modifiers of the active view, in list order, then those of the director.

Each modifier always runs in its own stage, wherever it sits in the list. Order only matters within a stage. A Composition modifier listed after a Shake modifier still runs first, so it never sees shake as subject movement and cancels it.

In standalone mode (no director in the world) only the view's own list runs, in the same two stages.

note

Order within the effects stage changes the result. For example, Zoom multiplies the field of view and FOV Kick adds degrees: Zoom before FOV Kick adds the full kick to the zoomed field of view, while FOV Kick before Zoom scales the kick down with the zoom.

Common modifier properties

Property	Default	Description
Name	empty	Optional. Lets scripts address the modifier through SetModifierEnabled and SetModifierWeight on the director.
Enabled	on	Off: the modifier still runs with weight 0, so springs and timers settle instead of resuming mid-effect later. Disabled modifiers do not receive impulses.
Weight	1	How strongly the modifier applies (0–1).
Views	per modifier	The kinds of view the modifier applies to: First Person, Third Person, Fixed, Rail, Top Down, Other. With the active view outside the scope, the weight is 0.
AllowInXR	off	Only on modifiers that rotate or shake the camera (Shake, Recoil, Head Bob, Lean, Landing). These sit out while the camera is in Stereo mode, because they cause discomfort in a headset, unless this is on.

In Stereo mode the director writes only position and yaw to the camera, since the headset owns the rest.

Impulses

One-shot events reach the modifiers through plMsgCameraImpulse (see Messages) or the director's AddTrauma and AddRecoil. Shake reacts to Shake impulses, Recoil to Recoil impulses and Landing to Landing impulses. Impulses go to the enabled modifiers of the active view and of the director.

Effect modifiers at a glance

Modifier	Default Views	Driven by	Effect
Shake	all	Trauma from impulses and shake volumes	Smooth noise on yaw, pitch, roll and optionally position.
FOV Kick	First, Third Person	Subject speed	Widens the field of view when moving fast.
Zoom	all	Input action or SetZoomed	Narrows the field of view, pulls a third-person camera in, slows look input.
Recoil	First, Third Person	Recoil impulses	Spring-driven pitch and yaw kick.
Head Bob	First Person	Subject speed and ground state	Walking bob and nod.
Lean	First Person	Input actions or SetLean	Sideways offset and roll, plus an optional constant dutch angle.
Landing	First, Third Person	Subject landing or Landing impulses	Spring-driven dip and pitch.
Damping	all	Always	Smooths position and rotation.

Shake

plCameraShakeModifier shakes the camera with smooth noise on yaw, pitch and roll, and optionally on position. The amount is driven by trauma (0–1). Shake impulses and AddTrauma add trauma, which then decays by TraumaDecay per second. Camera shake volumes at the camera's position provide a second trauma value, and the larger of the two is used. The shake scales with trauma squared, so small amounts stay subtle and large ones get violent.

A Shake impulse with a Radius above 0 falls off linearly from its Position to zero at that distance, measured from the camera.

Property	Default	Description
MaxYaw	4°	Yaw at full trauma.
MaxPitch	4°	Pitch at full trauma.
MaxRoll	6°	Roll at full trauma.
MaxOffset	0	Sideways and vertical position shake at full trauma, in meters (0–2).
Frequency	9	Speed of the noise (0.1–60). Higher is faster.
TraumaDecay	0.9	Trauma removed per second (0–10).
UseShakeVolumes	on	Also shakes from camera shake volumes at the camera's position.

Camera Shake Volume Sphere

plCameraShakeVolumeSphereComponent defines a sphere in which the camera shakes. Its strength is highest at the center and falls off linearly to zero at Radius. Where volumes overlap, the strongest one counts. Shake modifiers with UseShakeVolumes on and the legacy Camera Shake component both read these volumes. It is listed under Cameras/Shake.

Property	Default	Description
Strength	0	Strength at the center, usually between 0 and 1.
BurstDuration	0 s	Above 0: after this time from play start the volume deactivates and runs OnFinishedAction. 0 shakes constantly.
OnFinishedAction	None	What happens when a burst ends, for example deleting the object.
Radius	1	Radius of the sphere (at least 0.1).

FOV Kick

plCameraFovKickModifier widens the field of view as the subject's horizontal speed rises past SpeedThreshold, reaching MaxKick at FullSpeed. The kick eases in over InTime and out over OutTime.

Property	Default	Description
SpeedThreshold	4.5	Speed in m/s where the kick starts.
FullSpeed	7	Speed in m/s where the full kick is reached.
MaxKick	10	Degrees added at full speed (-60 to 60). Negative values narrow the view.
InTime	0.25 s	Time constant while the kick grows.
OutTime	0.4 s	Time constant while the kick shrinks.

Zoom

plCameraZoomModifier zooms while its Action is held or while the director's SetZoomed(true) is in effect. It multiplies the field of view by FovScale, moves a third-person camera toward its subject point by ArmPull, and multiplies look input by LookScale from the next frame on, so aiming is slower while zoomed.

Property	Default	Description
Action	Aim	Input action that zooms while held.
FovScale	0.6	Field-of-view multiplier when fully zoomed (0.05–2).
ArmPull	0.4	Third-person views only: fraction of the way from the camera to the subject point the camera moves when fully zoomed (0–0.95).
LookScale	0.5	Look input multiplier when fully zoomed (0–2).
BlendTime	0.15 s	Time constant for zooming in and out.

Recoil

plCameraRecoilModifier kicks the aim on every Recoil impulse (AddRecoil or plMsgCameraImpulse with Type Recoil) and a damped spring brings it back. The impulse's pitch and yaw are the kick, and RandomYaw adds a random sideways part. With the default Stiffness and Damping, the kick peaks at about the requested angle (a 3° recoil peaks at about 3°). A much stiffer or softer spring peaks lower or higher.

Property	Default	Description
Stiffness	140	Spring stiffness (1–2000). Higher returns faster.
Damping	18	Spring damping (0–200). Higher overshoots less.
RandomYaw	1.2°	Largest random sideways kick added to each impulse.

Head Bob

plCameraHeadBobModifier adds a walking bob: the camera dips at every footfall and sways sideways over two steps, with a small downward nod. It scales with the subject's horizontal speed up to FullSpeed and fades out while the subject is in the air.

Property	Default	Description
VerticalAmplitude	0.04	Vertical bob in meters (0–0.5).
LateralAmplitude	0.03	Sideways sway in meters (0–0.5).
StepsPerMeter	0.6	Footfalls per meter travelled (0.05–5).
PitchNod	0.4°	Downward nod at each footfall.
FullSpeed	5	Speed in m/s at which the bob reaches full size.

Lean

plCameraLeanModifier leans the camera sideways while LeanLeftAction or LeanRightAction is held, or by the director's SetLean (added to the actions). It moves the camera up to SideOffset to the side and rolls it by up to MaxRoll. A 0.15 m sphere is swept to the side first, against static and dynamic shapes, so the camera never leans through a wall. DutchAngle adds a constant roll on top.

Property	Default	Description
LeanLeftAction	LeanLeft	Input action that leans left.
LeanRightAction	LeanRight	Input action that leans right.
MaxRoll	12°	Roll at full lean.
SideOffset	0.35	Sideways offset at full lean, in meters (0–2).
BlendTime	0.15 s	Time constant for leaning in and out.
DutchAngle	0°	Constant roll, scaled by the weight.
CollisionLayer	0	Physics collision layer for the side sweep.

Landing

plCameraLandingModifier dips the camera when the subject lands and springs back. A landing is detected when the subject goes from airborne to grounded, and the fall speed just before decides the dip. A Landing impulse does the same with its Strength as the fall speed in m/s. Falls slower than MinSpeed do nothing. The dip is (fall speed - MinSpeed) × DipPerSpeed + 0.02 meters, at most MaxDip, and the camera pitches down by PitchPerMeter per meter of dip. With the default spring the dip bottoms out at about that depth.

Property	Default	Description
MinSpeed	3	Slowest fall in m/s that causes a dip.
DipPerSpeed	0.03	Meters of dip per m/s above MinSpeed (0–1).
MaxDip	0.35	Deepest dip in meters (0–2).
PitchPerMeter	12°	Pitch per meter of dip.
Stiffness	120	Spring stiffness (1–2000).
Damping	14	Spring damping (0–200).

note

Automatic landing detection and Head Bob's airborne check need a component on the subject that exposes IsInAir or IsStandingOnGround, as the character controllers do. Without one, the subject always counts as grounded, so send Landing impulses from gameplay code instead.

Damping

plCameraDampingModifier smooths position and rotation for views that have no lag of their own. Each half-life is the time the camera takes to cover half the remaining distance to the pose. A jump of more than 25 m is treated as a cut and followed at once.

Property	Default	Description
PositionHalfLife	0.08 s	Position smoothing. 0 follows exactly.
RotationHalfLife	0.05 s	Rotation smoothing. 0 follows exactly.

note

Damping is an effect modifier, so it smooths everything listed before it in the effects stage. Put it first in the list so shake and recoil listed after it keep their full sharpness.

Adding weapon feedback to a first-person camera

1. Select the Camera Director and open its Modifiers list.
2. Add a Damping modifier if the view feels jittery, then a Recoil, a Shake, a Zoom and a Head Bob modifier, in that order.
3. Name the Shake modifier Shake so scripts can turn it down with SetModifierWeight("Shake", 0.5).
4. From the weapon script, call AddRecoil(3, 0) on the director for each shot. For explosions, send a plMsgCameraImpulse with Type Shake, the explosion's Position, a Radius and a Strength, or call AddTrauma.
5. Bind the Aim action in the input action map to the aim button.
6. Play with Cameras.Debug 1 to watch each modifier's contribution.

Troubleshooting

Symptom	Likely cause
A modifier does nothing	The active view's kind is not in its Views scope (Head Bob and Lean default to First Person only), it is disabled, or its weight is 0. Cameras.Debug 1 lists it with its contribution.
No shake, recoil or bob in a headset	Rotational effects sit out in Stereo mode. Turn on AllowInXR for the ones you want.
Recoil feels muted	A Damping modifier listed after Recoil smooths the kick. Move Damping to the top of the list.
Lean or Zoom ignores the keys	The action names do not match the input action map, or no active plInputComponent is found on the subject, the view's object or their parents.
Shake volumes do not shake the camera	UseShakeVolumes is off, the volume's Strength is 0, or the camera is outside the radius.

See also: Gameplay Cameras · Framing, Look At and Focus · Camera Director · Camera Views