Focus system

What the focus system does

PBADOF finds a focus distance by casting physics raycasts from the camera, filtering the results, and selecting the most suitable target.

How focus acquisition works

The centre ray has the highest priority. When the centre ray reaches its maximum distance without finding a valid target, the solver can use surrounding rays instead. This allows focus to move smoothly from a centre target to the floor or an object composed at the side of the frame, rather than losing focus immediately.

Focus modes

Smart Subject mode

PBADOF offers two focus-selection solvers via the FocusSelectionMode enum. Legacy (0) is the original depth-cluster solver that groups ray hits by distance. SmartSubject (1) groups ray hits by semantic target, producing more stable focus on characters, vehicles, and other multi-collider subjects.

AutoDepthOfFieldFocusTarget

The AutoDepthOfFieldFocusTarget MonoBehaviour marks a GameObject and its children as one stable semantic subject. In Smart Subject mode, colliders on the target and its descendants are grouped together rather than treated as individual hits. Add it from the component menu: HIBIKI Entertainment / Depth Of Field / Auto Depth Of Field Focus Target.

Subject scoring

ResolveSmartSubject() sorts accepted candidates by optical depth, groups them by their parent AutoDepthOfFieldFocusTarget, and uses GetBestSubjectCluster() to find the strongest depth cluster per target. The score is:

cluster ray weight × target.Priority × focus-hint influence

Depth cluster tolerance is max(0.25, 5% of the nearer depth). The winning subject's cluster produces a weighted median focus distance via SelectSubjectMedian(), which avoids focusing on an arbitrary first collider when a subject has multiple visible parts.

Focus hints

A focus hint is a soft preference — not an unconditional override. Call SetFocusHint(target, strength) to bias the solver towards a specific AutoDepthOfFieldFocusTarget. The hinted target must still be hit by a valid ray and pass all occlusion, tag, glass, layer, and distance filters. A focus hint can trigger FocusSwitchReason.CueAcquisition.

Call ClearFocusHint() to remove the active hint.

Temporal subject tracking

The solver maintains a locked subject and a challenger. The current subject is not replaced the moment another scores higher, a challenger must satisfy both conditions:

• Score at least ChallengerAdvantage times the locked subject's score (default 1.25, clamped to a minimum of 1.0).
• Remain stronger for SwitchConfirmationTime (default 0.20 s).

If the locked subject disappears, LostSubjectGraceTime (default 0.30 s) holds focus before the solver considers new candidates. The snapshot reports FocusSwitchReason.LostSubjectGrace during this interval.

FocusSwitchReason values: None, InitialAcquisition, ChallengerConfirmed, CueAcquisition, LockedSubjectVisible, LostSubjectGrace, HoldLastFocus, TrackingReset.

API methods

// Set a soft preference for a specific focus target
autoFocus.SetFocusHint(target, strength: 4f);

// Clear the current focus hint
autoFocus.ClearFocusHint();

// Reset temporal tracking (lock state, challenger, grace timers)
autoFocus.ResetFocusTracking(preserveLensPosition: true);

Accuracy and sampling

Accuracy is a multiplier that controls how many rays fill the designated sampling area. At accuracy 1, Multi-ray mode uses 9 focus points. This is the recommended setting when you want the lowest physics cost available in Multi-ray mode.

FOV Multiplier controls how much of the camera frustum the rays cover. The sampling area is related to the camera's focal length, so it adjusts with the camera's lens configuration. Increase the multiplier when targets near the edges of the intended composition should contribute to focus.

Higher accuracy produces denser sampling and increases the number of physics queries. Keep Accuracy at 1 unless the scene requires more coverage or more stable results on small targets.

Tag filtering

Tag filtering narrows the set of colliders that can receive focus after interaction layer filtering. Choose the mode that matches whether tags are optional, required, or used as a preference.

Focus exclusion

Use focus exclusions when objects near the camera should never become focus targets.

Focus exclusion roots identify Transform roots whose entire hierarchies should be excluded from focus consideration. This is useful for excluding the player character, a weapon hierarchy, or other objects attached to the camera.

Character-controller exclusion automatically excludes the character controller from focus raycasts. Enable it when the player's own body or controller collider is interfering with autofocus.

Glass traversal

Glass traversal allows the camera to look through tagged colliders, such as windows, doors, or display cases, and focus on an object behind them. The solver can apply a correction to compensate for the glass surface when calculating the final focus distance.

Assign the Glass tag to a collider to enable glass traversal for that object. Configure the following settings to control when traversal activates and how many colliders the solver can cross.

Glass focus correction can also be overridden in the volume system. This lets you use different correction levels in different areas of a scene.

Ground Assist

When normal autofocus finds no valid subject, PBADOF can fall back to Ground Assist instead of leaving the focus plane at an arbitrary distance. Ground Assist fires a real forward ray — it does not project a flat ground plane.

Ground Assist becomes eligible when the camera looks downward past the Downward Activation Angle (formerly Camera Pitch Limit, default 35 degrees, range 1-90 degrees). The ray must hit a collider on the configured Ground Layers.

Ground Assist rejects hits that are behind the camera, too far away, on too-steep surfaces, on the camera or character hierarchy, or on ignored colliders. It does not extrapolate ground past a ledge, it uses only the real hit point.

When the camera looks upward or beyond an edge, the solver holds the current focus rather than snapping to an inferred ground position.

On startup with legacy data, MigrateLegacyGroundFallback() copies interaction layers to Ground Layers and sets MaximumGroundSlope to 60 degrees.

The solver sets FocusSolveStatus.GroundAssist when Ground Assist provides the focus distance. The older PitchFallback enum value is an obsolete alias for GroundAssist.

Diagnostics

Use focus diagnostics to determine why a ray was accepted or rejected and to inspect the confidence of the latest focus solve.

FocusDebugSnapshot contains detailed information about the latest solve, including accepted rays, rejected rays, and confidence data. Access the snapshot through AutoDepthOfField.CurrentFocusSnapshot.

The readiness panel in the Inspector reports pipeline, camera, and output status. Use it to identify setup problems such as missing render-pipeline camera data, an invalid camera configuration, or another enabled AutoDepthOfField component owning the output.

Enable the component's debug gizmos to view ray travel lines at runtime. Programmatic tools can read AutoDepthOfField.CurrentReadiness to inspect the component's readiness state.

// Access the latest focus solve diagnostics
if (AutoDepthOfField.TryGetCurrent(out var dof))
{
    var snapshot = dof.CurrentFocusSnapshot;
    var readiness = dof.CurrentReadiness;

    // Force a diagnostic refresh
    dof.UpdateDiagnosticsNow();
}

In Smart Subject mode, FocusDebugSnapshot also exposes temporal tracking properties. These are most useful when tuning ChallengerAdvantage, SwitchConfirmationTime, and LostSubjectGraceTime, or diagnosing why focus switched subjects unexpectedly.

// Smart Subject tracking diagnostics
snapshot.LockedSubject                // AutoDepthOfFieldFocusTarget — currently locked subject
snapshot.ChallengerSubject            // AutoDepthOfFieldFocusTarget — challenger subject
snapshot.LockedSubjectScore           // float — score of the locked subject
snapshot.ChallengerScore              // float — score of the challenger
snapshot.FocusHint                    // AutoDepthOfFieldFocusTarget — current hint target (if any)
snapshot.FocusHintStrength            // float — current hint strength
snapshot.SwitchConfirmationProgress   // float (0–1) — challenger confirmation timer
snapshot.LostSubjectGraceProgress     // float (0–1) — grace timer after subject loss
snapshot.SwitchReason                 // FocusSwitchReason — reason for the most recent focus decision
snapshot.GroundAssistSurface          // string — description of the ground surface hit (or null)

Next steps

Learn about the Physical lens model and presets to control the depth-of-field look, or explore Override volumes to blend focus settings across your scene.