Camera Tug Configurations

Step-by-step recipes for tug-field cinematic pulls — vista pull, doorway glance, and decoupled source / destination patterns.

Tug Fields pull the camera’s pose toward a designated point while a proxy entity is inside a defined PhysX trigger volume. Each recipe below assumes the PhysX layer setup (TugProxy ↔ TugField collision-group pair) is already configured for your project.

For the concept, the three-component model, and the PhysX layer setup walkthrough, see The Basics: Tug Fields. For the per-tick algorithm and per-field reference, see Tug Fields (Framework API).

Before starting any recipe: Confirm the PhysX layer setup. If TugProxy and TugField aren’t paired (and only paired) in your collision-group preset, nothing will fire — that is the single biggest authoring failure for this system.

Recipe: Vista Pull
Recipe: Doorway Glance
Recipe: Decoupled Source and Destination
See Also

Recipe: Vista Pull

Pull the cam’s gaze toward a vista point when the player approaches a railing.

Entities

Entity	Components
Player root (or a child entity)	`TugFieldProxyComponent` + PhysX trigger collider (small sphere or capsule) on the `TugProxy` layer.
“Vista trigger” (level entity, placed at the railing)	`CameraTugVolumeComponent` + PhysX trigger collider (a box covering the railing approach) on the `TugField` layer.
(Source on the same entity as the volume — default)	`CameraTugSourceComponent` configured with the vista point as the destination.

Configuration

On the volume’s CameraTugSourceComponent:

Field	Set to
`Tug Point Offset`	Local offset to the proximity-reference point (default `(0,0,0)` works if the volume is centered on the railing).
`Destination Entity`	(leave empty — destination = source for the simple case)
`Inner Radius`	`1.0` m — within this radius, full pull.
`Outer Radius`	`4.0` m — beyond this, no pull.
`Inner Weight`	`1.0`
`Outer Weight`	`0.0`
`Falloff Curve`	`EaseInOutQuadratic`

On the cam:

Add a TugAimListener to the m_additives list.
Channels → leave empty (matches any).
Blend Halflife → 0.4 (slow engagement / disengagement).
Strength → 1.0.

The cam’s gaze now drifts toward the vista as the player approaches the railing, full at deadzone, none outside the outer radius.

Recipe: Doorway Glance

The cam glances through a doorway as the player walks past, then returns. Body stays put; only aim engages.

Same shape as the vista pull, but:

The volume’s trigger collider is a flat slab across the doorway approach.
The cam uses only TugAimListener (not body). The cam continues to follow the player normally; aim drifts toward what’s beyond the doorway.
Configure a short halflife (0.2) on the listener so the glance is responsive — engage as the player enters, release as the player exits.

Recipe: Decoupled Source and Destination

You want the volume to fire at one location but the cam to be pulled toward a different location. Common case: the player crosses a threshold, but the cam should look 10 m past it.

Setup

Place the volume entity with CameraTugVolumeComponent at the threshold.
Place a separate “destination entity” with TransformComponent only (no CameraTugSourceComponent!) at the vista point.
Place a separate source entity with CameraTugSourceComponent somewhere convenient (often on the volume entity itself, or as a child of it). Configure:
- Destination Entity → point at the destination entity from step 2.
- Destination Offset → local offset from that entity (default (0,0,0) works).
On the volume’s m_sourceEntity field, point at the source from step 3.

Now proximity is measured around the threshold (where the volume is), but the cam is pulled toward the vista point (the destination entity).

If you leave Destination Entity unset on the source component, destination falls back to source. The decoupled setup is only needed when they should differ.