Anti-Wallhack Visibility System

The ObserverManager is the central coordinator of the visibility system. It manages the registration and unregistration of observers and players, controls visibility state changes, dispatches visibility events, and provides global access to visibility-related operations.

Key fields and methods:

• Instance (singleton)
• OnVisibilityChanged (event)
• RegisterObserver / RegisterPlayer / UnregisterPlayer
• ChangeVisibility / IsPlayerVisibleToObserver / GetAllPlayersExcept

Call Rate Mode

The ObserverManager includes a configurable call rate system that controls how often visibility updates are executed. This allows developers to balance detection responsiveness and CPU usage according to the needs of the project.

• Unlimited: Visibility is updated every frame
• Limited: Fixed update rate

When using Limited, you can define how many visibility updates are executed per second. Lower update rates reduce CPU usage and improve scalability, while higher update rates provide faster visibility response and greater accuracy.

The PlayerObserver represents the player's vision in the system. It is responsible for determining which targets should be evaluated for visibility.

Observer Mode

Defines how the observer searches for visible targets.

• 180°: Uses camera direction, FOV, aspect ratio, and precise frustum validation
• 360°: Uses distance-based detection in all directions around the observer

Camera & Detection Settings

• maxObserverAngle → Defines the detection mode: 180° or 360°
• cameraFOVAngle → Base vertical FOV used for visibility detection
• broadPhaseFOVMultiplier → Expands the broad-phase FOV check before precise validation
• viewDistance → Maximum detection distance
• aspectFormat → Aspect ratio used to calculate horizontal FOV
• detectionMode → Defines how the target is tested during observer filtering
• smoothSpeed → Controls smoothing speed for dynamic FOV transitions

Aspect Ratio

The observer uses the selected aspect ratio to calculate horizontal FOV from the configured camera FOV. This helps match visibility detection with the player's real screen format.

• 4:3
• 16:9
• 16:10
• 21:9
• 32:9

Detection Mode

• ClosestPoint: Faster, uses the closest collider point and optional cached shadow point
• BoundsCorners: More precise, tests collider boundary points and optional cached shadow point

Broad Phase Optimization

Broad Phase Optimization is an early filtering step used before expensive visibility checks. Instead of running detailed physics and sampling validation against every player, the observer first performs a lightweight distance and FOV approximation.

This reduces unnecessary calculations by quickly rejecting targets that are clearly outside the observer's possible visibility area.

• Performs a fast distance check before detailed validation
• Uses an expanded FOV approximation to reduce false negatives
• Prevents unnecessary line sampling against distant or invalid targets
• Improves scalability when many players are active

Broad Phase FOV Multiplier

The broadPhaseFOVMultiplier controls how much the initial FOV check is expanded before precise frustum validation. Higher values are more tolerant, while lower values are stricter and more performance-focused.

• Lower values: Better performance, but may reject targets too early
• Higher values: Safer detection, but allows more targets into detailed checks

FOV Compensation PRO

FOV Compensation dynamically expands the observer's field of view to reduce visibility loss caused by fast camera rotation and network latency.

• Disabled: Uses the configured FOV without compensation
• Rotation: Expands FOV based on camera rotation speed
• RotationAndLatency: Combines camera rotation and ping compensation

FOV Compensation Parameters

• minAngularSpeed → Minimum camera rotation speed required before compensation starts
• maxAngularSpeed → Rotation speed where maximum compensation is reached
• maxPingFOVExpansion → Maximum FOV expansion caused by network latency
• maxRotationFOVExpansion → Maximum FOV expansion caused by camera rotation
• maxPingForFullCompensation → Ping value where latency compensation reaches full strength

Observer Prediction PRO

Observer Prediction offsets the virtual observer position to compensate for player movement and latency. This improves visibility consistency when players move quickly or peek around corners.

• Disabled: No positional prediction
• Velocity: Uses player movement velocity to offset the virtual observer
• VelocityAndLatency: Scales velocity prediction using network latency

Prediction Parameters

• maxPredictionDistance → Maximum virtual observer offset distance
• velocityPredictionScale → Scales how strongly velocity affects prediction
• latencyExpansionMultiplier → Caps latency-based prediction growth
• predictionAxisMode → Selects lateral, frontal, or combined prediction
• lateralWeight → Weight applied to side movement prediction
• frontalWeight → Weight applied to forward movement prediction

Prediction Axis Mode

• Lateral: Compensates side movement, useful for corner peeking
• Frontal: Compensates forward and backward movement
• LateralAndFrontal: Combines both axes for more complete prediction

Grace Prediction PRO

Grace Prediction smooths latency-aware prediction when a target was recently visible. This helps reduce flickering when players rapidly move in and out of cover.

• useGracePrediction → Enables prediction smoothing after recent visibility
• gracePingStart → Ping where grace prediction begins to take effect
• gracePingMax → Ping where grace prediction reaches full strength
• minGraceScale → Minimum prediction scale when grace is fully active

Configuration Examples

180° Mode — Precision Setup

          Max Observer Angle = 180
          Camera FOV Angle = 60
          Broad Phase FOV Multiplier = 1.7
          View Distance = 250
          Aspect Format = 16:9
          Detection Mode = BoundsCorners
          FOV Compensation Mode = RotationAndLatency
          Observer Prediction Mode = VelocityAndLatency
          

360° Mode — Distance-Based Setup

          Max Observer Angle = 360
          View Distance = 250
          Detection Mode = ClosestPoint
          FOV Compensation Mode = Disabled
          Observer Prediction Mode = Velocity
          

Gizmos

• showGizmos — Enables visualization in Scene view

Responsible for performing visibility validation using line sampling, collider geometry, physics-based checks, and optional environment-based detection. This component works together with PlayerObserver and is automatically added when using NetworkPlayerVisibilityDetector.

Collider Settings

• Free: Uses PlayerBox (box-based detection)
• Pro: Supports PlayerCylinder for more realistic player shape
• Collider can be placed on root or child GameObject

Line Sampling

• Fixed Lines → constant visibility checks
• Dynamic Lines → sweeping lines for better precision
• Adjustable density and speed

// Key parameters
verticalFixedLineCount
horizontalFixedLineCount
dynamicLineSpacing
dynamicLineSpeed 

Grid Subdivision

Defines how the collider is subdivided for sampling.

• Vertical lines (rows)
• Horizontal columns

Alignment Filtering

• alignmentThreshold → Minimum valid angle
• targetAlignmentThreshold → Refined target validation

Environment Detection PRO

Environment Detection extends the regular line-of-sight validation by allowing the system to detect players through indirect visual information, such as projected shadows and reflections. This makes visibility checks more realistic in scenarios where the player body is hidden, but environmental clues are still visible.

• Disabled: Uses only direct line-of-sight validation
• Shadow: Enables indirect detection through projected shadows
• Reflection: Enables indirect detection through reflective surfaces

Shadow Detection Settings PRO

When Environment Detection is set to Shadow, the detector uses registered ShadowLight sources to evaluate whether a player's shadow is visible to the observer.

• Light Sources → List of ShadowLight components used for shadow visibility checks
• Min Shadow Vertical Angle → Minimum vertical angle required for a shadow to be considered valid
• Shadow Line Count → Number of lines used to sample the projected shadow
• Shadow Light Refresh Rate → How often the detector refreshes nearby or assigned shadow lights
• Enable Shadow Ground Projection → Projects shadow samples onto the environment for improved accuracy

Reflection Detection Settings PRO

When Environment Detection includes Reflection, the detector uses every enabled ReflectionSurface in the scene to evaluate whether a player is visible through its reflection. Environment Detection is a flags field, so Shadow and Reflection can be enabled together.

• Show Reflection Lines → Draws the observer → surface → player path in the Scene view
• Obstacles Mask → Also used for the two reflection linecasts (observer to surface, surface to player)

Size Compensation

• Free: Velocity-based expansion
• Pro: Velocity + Animation + Latency

Animation Compensation PRO

Animation Compensation dynamically adjusts the visibility sampling area according to the current animation pose. This helps prevent situations where important body parts move outside the base collider and become incorrectly ignored by visibility checks.

• Detects animation pose overflow outside the player collider
• Supports head, hands, and feet compensation
• Improves visibility accuracy during running, crouching, jumping, leaning, and attack animations
• Requires a Humanoid Animator, and Always Animate culling on a dedicated server
• Works together with velocity and latency compensation systems

Advanced PRO

• Cylinder angular sweep control
• Latency-based expansion scaling
• Animation-based collider adjustment
• Double wall optimization check
• Shadow-based environment detection
• Reflection-based environment detection

Performance & Stability

• stateStabilizeTime prevents flickering
• Layer masks control raycast cost
• Smoothing reduces abrupt changes
• Shadow light refresh rate helps control environment detection cost

Defines the bounding box used for player visibility detection. It is responsible for providing the geometric base used by line sampling and alignment checks.

Core Settings

• skinWidth → Adds a small margin to avoid precision issues
• boxExpansionAxisAdjustment → Controls how expansion applies per axis
• enableColliderWallClamping → Prevents detection through walls

Gizmos (Basic)

• Toggle visualization
• Basic collider color display

The Pro version extends PlayerBox with advanced debugging, visualization tools, and an enhanced wall clamping system, allowing detailed inspection of visibility behavior in real time while improving collision accuracy and reliability.

Advanced Wall Clamping

• Improved collision detection around complex geometry
• More accurate handling of corners and thin walls
• Better stability in fast-paced scenarios

Advanced Gizmos

• Per-player color visualization
• Base vs Expanded collider comparison
• Line clamp visualization
• Debug line points rendering

        // Examples
        showBaseSize
        showExpandedSize
        showLineClamp
        linePointRadius
            

The PlayerCylinder provides a more accurate geometric representation of the player using a cylindrical shape. This improves visibility detection in scenarios where box-based colliders are not precise enough, especially around corners and curved movement paths.

Geometry Settings

• radius → Defines player width
• height → Defines player height
• center → Adjusts collider offset

Expansion & Compensation

• expansionFactor → Global size multiplier for safety margin
• expansionAxis → Controls which axes are expanded (X, Y, Z or all)
• cylinderExpansionAxisAdjustment → Fine-tunes radius and height expansion
• SkinWidth → Prevents precision issues in collision checks

Advanced Wall Clamping

• Rotating scan system around the cylinder
• Continuous obstacle detection
• Handles thin walls and corner exposure

• speedLineClamp → Rotation speed of the scan
• raysClampPerFrame → Number of rays processed per frame
• enableColliderWallClamping → Enables collision safety system

Performance Considerations

• Adjust scan speed for performance vs accuracy
• Reduce rays per frame on large-scale matches
• Use only when high precision is required

Gizmos

• Real-time cylinder visualization
• Expansion preview
• Line clamp debug rendering

ShadowLight represents a light source capable of generating shadow visibility information for the Environment Detection system.

Supported Light Types

• Directional: Infinite directional light (sunlight)
• Point: Radial light source
• Spot: Cone-based light source

Shadow Modes

• Simple: Fast single-line shadow evaluation
• Accurate: Multi-line shadow sampling for improved precision

Light Settings

• Light Type → Defines the light source type
• Range → Maximum shadow influence distance
• Spot Angle → Cone angle used by Spot lights
• Near Horizontal Angle → Controls shadow projection spread
• Sync With Unity Light → Automatically synchronizes settings with a Unity Light component

Performance Recommendations

• Use Simple mode for large-scale matches
• Use Accurate mode only when shadow precision is required
• Reduce Shadow Light Refresh Rate for better performance
• Limit the number of active ShadowLights in large maps

ReflectionSurface marks a mirror, window or any reflective plane that the Environment Detection system can use to validate whether a player is visible through its reflection.

Surface Orientation

The reflection plane is defined by the transform position and its local +Z axis (blue arrow), which must point away from the reflective face. The yellow gizmo line shows the current normal direction.

Reflection Modes

• Simple: Reflects a single main player point — fastest option
• Accurate: Reflects multiple collider bounds points for better precision near the surface edges

Surface Settings

• Size → Width and height of the reflective area
• Edge Tolerance → Extra margin around the surface, preventing visibility from dropping abruptly near the edges

Detection Settings

• Max Distance → Maximum distance at which observers can detect reflections
• Reflection Surface FOV → Minimum viewing angle required before reflection checks run
• Reflection Mode → Simple or Accurate sampling
• Obstacle Mask → Layers that block the line between the observer and the surface itself

How Detection Works

• The observer first runs a cheap surface check: distance, then viewing angle, then a linecast to the surface center using the surface Obstacle Mask
• Only surfaces that pass are evaluated for that tick
• The observer position is mirrored across the reflection plane, and the point where the mirrored line crosses the plane becomes the reflection point
• The reflection point must land inside the surface area, including Edge Tolerance
• Two final linecasts validate the path: observer → reflection point and reflection point → player, both using the detector Obstacles Mask

Performance Recommendations

• Use Simple mode when edge precision is not critical
• Keep Max Distance and Reflection Surface FOV as tight as the map allows, since both reject surfaces before any reflection math runs
• Restrict Obstacle Mask to layers that can realistically block a reflection
• Limit the number of active reflection surfaces in large maps

Relays visibility events to a UnityEvent for easy editor configuration. Requires PlayerVisibilityDetector on the same GameObject.