Occlusion

Occlusion

How occlusion works and why it muffles audio.

What Is Occlusion?

Occlusion muffles audio when obstacles (walls, buildings, other players) are between the listener and the speaker. This creates realistic audio — voices sound quieter when someone is behind a wall.

How It Works

The system uses raycasting from the listener's head toward the emitter's head (hits are not ordered by distance). Hits along the ray determine how much audio is muffled.

Raycast Logic

Hits	Meaning	Result
0	Clear line of sight	Full clarity (1.0)
1	One obstacle hit	Check distance — if > 1m from emitter, full clarity; otherwise apply obstacle/player clarity
2	Two obstacles hit	If both are players → player clarity; otherwise → AudioObstacle clarity on environment hit (or global fallback)

Note: Player occlusion only activates when the UI layer is included in playerOcclusionMask. Without it, only environment obstacles are detected.

Environment vs Player Occlusion

• Environment occlusion: walls, buildings, floors — uses AudioObstacle clarity or global fallback
• Player occlusion: other players standing between listener and emitter — uses playerClarity setting
• Environment dominates: when any environment hit exists, player occlusion is ignored

This means a wall always takes precedence over a player blocking the sound path.

Occlusion Strategies

Strategy	Behavior
DefaultPlayerOcclusion	Raycast-based, supports AudioObstacle per-obstacle clarity
NullPlayerOcclusion	No occlusion (passthrough) — useful for testing or worlds that don't need occlusion

See Also

• AudioObstacle — per-obstacle configuration
• How to Set Up Occlusion — step-by-step setup guide
• DefaultPlayerOcclusion — raycast strategy details