Bevy All-in-One Documentation

A powerful 3D/2.5D game controller plugin for Bevy Engine.

Project maintained by yaskhan Hosted on GitHub Pages — Theme by mattgraham

Stealth System - Comprehensive Documentation

Overview
Core Components
System Architecture
Hide States
- State Types
- State Transitions
Cover System
Visibility & Detection
Camera System
Advanced Features
AI Integration
Setup and Usage
Performance Considerations
Customization Guide

Overview

The Stealth System provides comprehensive mechanics for hiding, cover-based gameplay, and detection avoidance. It enables players to hide from enemies, take cover behind objects, peek around corners, and manage their visibility through multiple states and mechanics. The system seamlessly integrates with the Character Controller, AI System, and Camera System to create immersive stealth gameplay experiences.

Key Features

Multiple Hide States: Crouch hiding, prone hiding, peeking, corner leaning, and fixed-place hiding
Cover Detection: Advanced raycasting system to detect and utilize cover objects
Visibility System: Dynamic visibility meter tracking detection levels, sound, and light exposure
Camera Controls: Specialized camera controls for peeking, looking around while hidden, and zooming
AI Detection: Real-time line-of-sight checks with AI enemies and gradual detection mechanics
Spring Camera: Optional auto-return camera behavior for intuitive controls
Sound Management: Footstep noise levels affecting detection risk
Flexible Configuration: Extensive customization options for all stealth mechanics

Design Philosophy

The Stealth System follows a state-based approach where the player transitions between various hide states based on input, cover availability, and detection status. Each state has unique camera behaviors, movement restrictions, and detection properties, allowing for varied stealth gameplay styles from static hiding to dynamic cover-to-cover movement.

Core Components

StealthController

The main configuration component that defines stealth behavior and capabilities:

Cover Detection Settings:

| Field | Type | Default | Description | |——-|——|———|————-| | cover_detection_distance | f32 | 2.0 | Maximum distance for cover detection raycasts | | cover_detection_angle | f32 | 90.0 | Field of view angle for cover detection (degrees) | | cover_layer | u32 | 256 | Physics layer mask for cover objects (layer 8) | Hide Requirements:

StealthState

Runtime state component tracking the current stealth status:

Hide State:

| Field | Type | Description | |——-|——|————-| | last_time_spring_rotation | f32 | Timestamp for spring rotation timer | | last_time_spring_movement | f32 | Timestamp for spring movement timer |

CoverDetection

Component managing cover detection and current cover status:

Low - Waist-high cover (height < 0.5)
Medium - Chest-high cover (0.5 <= height < 1.5)
High - Full cover (height >= 1.5)
Corner - Corner cover for leaning
Full - Complete concealment

VisibilityMeter

Component tracking player visibility and detection status:

| Field | Type | Default | Description | |——-|——|———|————-| | current_visibility | f32 | 0.0 | Current visibility level (0.0 = hidden, 1.0 = visible) | | detection_level | f32 | 0.0 | Detection progress (0.0 = undetected, 1.0 = detected) | | sound_level | f32 | 0.0 | Current noise level (0.0 = silent, 1.0 = loud) | | light_level | f32 | 0.0 | Current light exposure (0.0 = dark, 1.0 = bright) | | visibility_decay_rate | f32 | 0.5 | Speed of detection decay per second | | detection_increase_rate | f32 | 0.3 | Speed of detection increase per second | | sound_decay_rate | f32 | 0.2 | Speed of sound decay per second | | is_visible_to_ai | bool | false | Whether AI can see character | | is_detected_by_ai | bool | false | Whether AI has detected character |

System Architecture

The Stealth System uses a dual-timestep approach with systems running in both Update and FixedUpdate:

Update Systems (Frame-rate dependent)

System Execution Chain:

handle_stealth_input - Processes player input for hide, peek, lean, zoom, and camera controls
update_stealth_state - Updates camera rotation, movement, zoom, and spring behaviors
update_visibility_meter - Updates visibility, detection, and sound levels

FixedUpdate Systems (Physics timestep)

System Execution:

detect_cover_objects - Performs raycasts to detect nearby cover objects
check_line_of_sight - Checks AI line-of-sight and updates detection status
update_hide_states - Validates hide state requirements and enforces rules

System Dependencies

The Stealth System integrates with:

Character Controller: For movement state (crouching, sprinting) and pose management
AI System: For enemy detection ranges and line-of-sight checks
Input System: For capturing hide, peek, lean, and camera control inputs
Camera System: For applying camera transformations during hiding
Physics System (Avian3D): For raycasting and spatial queries

Hide States

State Types

The system supports five distinct hide states, each with unique behaviors:

HideState Enum:

Visible         - Default state, not hiding
CrouchHide      - Hiding while crouched
ProneHide       - Hiding while prone
Peek            - Peeking from cover
CornerLean      - Leaning around corner
FixedPlaceHide  - Hiding at fixed location

State Characteristics:

State Transitions

Transition Rules:

Visible → CrouchHide
  - Press Hide action
  - character_need_to_crouch must be true
  - Not currently detected
  - Can be hidden is true
CrouchHide → Peek
  - Press Peek action while hiding
  - In cover
  
CrouchHide → CornerLean
  - Press Corner Lean action while hiding
  - At corner cover
Peek/CornerLean → CrouchHide
  - Release Peek/Corner Lean action
Any Hidden State → Visible
  - Press Hide action (toggle off)
  - Detected by AI
  - Move too much (if character_cant_move is true)
  - Stand up (if character_need_to_crouch is true)
  - Hide time limit exceeded (if hidden_for_a_time is true)

State Transition Diagram:

┌─────────┐
│ Visible │
└────┬────┘
     │ Hide pressed
     ▼
┌──────────────┐
│ CrouchHide   │◄────────┐
└──┬───────┬───┘         │
   │       │             │
   │ Peek  │ Corner Lean │ Release/Detected
   │       │             │
   ▼       ▼             │
┌──────┐ ┌──────────────┐│
│ Peek │ │ CornerLean   ││
└──────┘ └──────────────┘│
   │           │         │
   └───────────┴─────────┘

Cover System

Cover Detection

The cover detection system uses raycasting to identify nearby cover objects:

Detection Process:

Raycast forward from character position
Maximum distance: cover_detection_distance
Filter by physics layer: cover_layer
Calculate angle between character forward and hit direction
Accept if angle <= cover_detection_angle
Classify cover type based on height
Update cover information in CoverDetection component

Raycast Configuration:

Origin: Character’s world position
Direction: Character’s forward vector
Max Distance: Configurable (default 2.0 units)
Layer Mask: Cover-specific physics layer
Collision Type: First hit only

Cover Types

Cover is automatically classified based on height relative to character:

Height-Based Classification:

Each cover type provides different gameplay characteristics:

Low Cover:

Requires crouching
Allows peeking over top
Moderate protection
Easy to spot from elevated positions

Medium Cover:

Can hide standing
Allows peeking over top
Good protection
Balanced visibility/protection

High Cover:

Full standing protection
Requires corner leaning to see
Maximum protection
Limited visibility

Corner Cover:

Special lean mechanics
Directional exposure
Tactical positioning
Quick peek capability

Cover Mechanics

Entering Cover:

Character approaches cover object
System detects cover via raycast
is_in_cover flag set to true
Cover information stored in CoverDetection
Character can activate hiding

Using Cover:

While in cover and hidden:
- Camera controls enabled
- Movement restricted based on settings
- Detection risk reduced
- Peek and lean actions available

Leaving Cover:

Move away from cover object
Stand up (if crouching required)
Distance exceeds detection range
Cover object destroyed/moved

Cover-Based Detection:

Being in cover doesn’t guarantee safety
AI can detect if:
- Character moves too much
- Character peeks/leans
- AI flanks to different position
- Line of sight is established

Visibility & Detection

Line of Sight

The system performs real-time line-of-sight checks between player and AI enemies:

Line of Sight Algorithm:

For each AI enemy:
  1. Calculate distance between character and AI
  2. Check if distance <= AI detection range
  3. Calculate direction vector from character to AI
  4. Perform raycast from character to AI
  5. If raycast hits nothing (clear path):
     - Character is visible to AI
     - Set detection flag
     - Start detection timer
  6. If raycast hits obstacle:
     - Character has cover
     - No detection from this AI

Detection Validation:

Must be within AI’s detection range
Must have clear line of sight (no obstacles)
Hide state affects detection probability
Cover type influences visibility

Multiple AI Handling:

Checks against all AI entities
Any single AI can trigger detection
Detection is global (one AI detecting alerts others)
System exits early on first detection for performance

Detection Levels

The visibility meter tracks gradual detection using multiple factors:

Detection Calculation:

Visibility Level (0.0 - 1.0):

0.0 - Fully hidden, invisible to AI
1.0 - Fully visible, easily detected
Updated based on hide state

Detection Progress (0.0 - 1.0):

0.0 - Undetected, safe
1.0 - Fully detected, AI alerted
Increases at detection_increase_rate when visible
Decreases at visibility_decay_rate when hidden

Detection States:

The system considers multiple factors for detection:

Visibility: Current hide state
Sound: Movement noise level
Light: Environmental lighting (placeholder)
Distance: Proximity to AI
Cover: Cover type and quality

Sound System

Movement generates noise that affects detection:

Sound Level Calculation:

Sound level decreases over time
Decay rate: sound_decay_rate per second (default 0.2)
Gradual reduction simulates sound dissipation
AI may investigate last known sound location

Sound-Based Detection:

High sound levels increase AI awareness
AI may enter suspicious state from sound alone
Combined with visibility for total detection risk
Movement noise persists briefly after stopping

Camera System

Camera Controls

While hidden, the camera enters a specialized free-look mode:

Free-Look Activation:

Triggered when entering hide state
Camera detaches from normal character follow
Mouse/controller input controls camera directly
Character body remains stationary

Camera Rotation:

Horizontal Rotation (Yaw):

Input: Mouse X-axis or right stick X
Speed: rotation_speed multiplier
Range: range_angle_y (min, max degrees)
Smooth: smooth_camera_rotation_speed

Vertical Rotation (Pitch):

Input: Mouse Y-axis or right stick Y
Speed: rotation_speed multiplier
Range: range_angle_x (min, max degrees)
Smooth: smooth_camera_rotation_speed

Rotation Implementation:

Horizontal angle += mouse_x * rotation_speed
Vertical angle -= mouse_y * rotation_speed
Horizontal clamped to [range_angle_y.min, range_angle_y.max]
Vertical clamped to [range_angle_x.min, range_angle_x.max]
Camera rotation = Quat from Euler angles (vertical, 0, 0)
Pivot rotation = Quat from Euler angles (0, horizontal, 0)

Camera Translation:

Horizontal Movement:

Input: WASD or left stick
Speed: move_camera_speed multiplier
Range: move_camera_limits_x (min, max units)

Vertical Movement:

Input: WASD or left stick
Speed: move_camera_speed multiplier
Range: move_camera_limits_y (min, max units)

Camera Reset:

Manual reset via input action
Returns camera to neutral position
Resets rotation and translation
Immediate or smooth transition

Peek Mechanics

Peeking allows limited exposure to gain visibility:

Peek Activation:

Must be in hide state
Press Peek action
State transitions to HideState::Peek
Camera behavior changes

Peek Camera Behavior:

More restrictive rotation limits
Reduced movement range
Over-shoulder view perspective
Character slightly emerges from cover

Peek Detection Risk:

Higher visibility than full hide
Reduced compared to being fully visible
AI can detect if looking directly
Brief peeks minimize risk

Peek Duration:

Can peek indefinitely
Detection risk accumulates over time
Best used for quick glances
Release to return to full hide

Zoom System

Optional zoom functionality for enhanced visibility:

Zoom Controls:

Zoom In: Decrease FOV
Zoom Out: Increase FOV
Input: Mouse wheel or shoulder buttons

Zoom Parameters:

Max Zoom: Minimum FOV (default 10°)
Min Zoom: Maximum FOV (default 90°)
Zoom Speed: FOV change rate (default 10°/sec)

Zoom Implementation:

If increase_zoom:
    current_fov -= delta_time * zoom_speed
If decrease_zoom:
    current_fov += delta_time * zoom_speed
current_fov clamped to [max_zoom, min_zoom]

Zoom Features:

Smooth transitions
Configurable speed
Input debouncing (0.1s)
FOV override option for hide state

Advanced Features

Corner Leaning

Corner leaning provides tactical positioning at corners:

Lean Activation:

Must be in hide state
Must be at corner cover
Press Corner Lean action
State transitions to HideState::CornerLean

Lean Mechanics:

Character shifts laterally
Partial body exposure
Maintains cover protection
Camera adjusts to lean direction

Lean Types:

Left Lean: Expose left side
Right Lean: Expose right side
High Lean: Peek over top
Low Lean: Peek around bottom

Tactical Advantages:

Minimal exposure
Quick return to cover
Precise positioning
Fire from cover capability

Spring Camera

Automatic camera return for intuitive controls:

Spring Rotation:

After spring_rotation_delay seconds of no input
Camera automatically returns to neutral rotation
Smooth interpolation
Can be disabled

Spring Movement:

After spring_movement_delay seconds of no input
Camera automatically returns to neutral position
Smooth interpolation
Can be disabled

Spring Behavior:

If no rotation input for > spring_rotation_delay:
    Interpolate camera rotation to identity
    Interpolate pivot rotation to identity
    
If no movement input for > spring_movement_delay:
    Interpolate camera position to zero offset

Use Cases:

Casual exploration
Reduces player fatigue
Natural camera behavior
Optional feature for hardcore mode

Fixed Place Hide

Specialized hiding at designated locations:

Concept:

Predefined hide spots in level
Character enters specific animation/pose
Fixed camera perspective
Complete hiding functionality

Implementation:

Hide spot entities marked with components
Character snaps to hide position
Custom camera settings per hide spot
Exit triggers return to normal gameplay

Examples:

Closets
Under tables
In vents
Behind curtains
In haystacks

Benefits:

Guaranteed hiding
Cinematic presentation
Level design opportunities
Clear player feedback

AI Integration

The Stealth System tightly integrates with the AI System:

AI Detection Range:

Queries AI detection_range field
Only checks AI within range
Distance-based detection probability
Gradual awareness system

AI Behavior Triggers:

Hidden state → AI ignores player
Detected state → AI enters alert
Sound events → AI investigates
Line of sight breaks → AI searches

Faction Integration:

Checks faction relations
Only hostile factions trigger detection
Neutral/friendly AI ignore stealth state
Dynamic faction changes supported

Alert System:

Detection alerts nearby AI
Alert radius configurable
Faction-wide awareness
Coordinated search patterns

AI State Changes on Detection:

Player Detected:
    AI State: Idle/Patrol → Suspect → Chase
    AI Speed: patrol_speed → chase_speed
    AI Behavior: Passive → Aggressive
    AI Memory: Stores last known position

Stealth Recovery:

After time_delay_to_hide_again_if_discovered
Player can attempt hiding again
AI may remain in search mode
Requires breaking line of sight

Setup and Usage

Basic Stealth Setup

Minimal Configuration:

use bevy::prelude::*;
use bevy_allinone::prelude::*;
fn spawn_stealth_character(mut commands: Commands, position: Vec3) -> Entity {
    commands.spawn((
        Name::new("Stealth Character"),
        
        // Stealth components
        StealthController::default(),
        StealthState::default(),
        CoverDetection::default(),
        VisibilityMeter::default(),
        
        // Character controller
        CharacterController::default(),
        CharacterMovementState::default(),
        
        // Input
        InputState::default(),
        
        // Transform
        Transform::from_translation(position),
        GlobalTransform::default(),
        
        // Physics
        RigidBody::Dynamic,
        Collider::capsule(0.4, 1.0),
        LockedAxes::ROTATION_LOCKED,
    ))
    .id()
}

Custom Stealth Configuration

Advanced Setup:

fn spawn_custom_stealth_character(mut commands: Commands) -> Entity {
    commands.spawn((
        Name::new("Custom Stealth Character"),
        
        StealthController {
            // Cover detection
            cover_detection_distance: 3.0,
            cover_detection_angle: 120.0,
            
            // Hide requirements
            character_need_to_crouch: true,
            character_cant_move: true,
            max_move_amount: 0.05,
            
            // Detection
            check_if_detected_while_hidden: true,
            time_delay_to_hide_again_if_discovered: 3.0,
            
            // Camera rotation
            camera_can_rotate: true,
            rotation_speed: 15.0,
            range_angle_x: Vec2::new(-60.0, 60.0),
            range_angle_y: Vec2::new(-90.0, 90.0),
            use_spring_rotation: true,
            spring_rotation_delay: 2.0,
            
            // Camera movement
            camera_can_move: true,
            move_camera_speed: 8.0,
            move_camera_limits_x: Vec2::new(-1.5, 1.5),
            move_camera_limits_y: Vec2::new(-1.5, 1.5),
            use_spring_movement: true,
            spring_movement_delay: 2.0,
            
            // Zoom
            zoom_enabled: true,
            zoom_speed: 20.0,
            max_zoom: 15.0,
            min_zoom: 75.0,
            
            // UI
            use_character_state_icon: true,
            use_message_when_unable_to_hide: true,
            unable_to_hide_message: "Cannot hide while being watched!".to_string(),
            
            ..default()
        },
        
        StealthState::default(),
        CoverDetection::default(),
        
        VisibilityMeter {
            visibility_decay_rate: 0.8,
            detection_increase_rate: 0.5,
            sound_decay_rate: 0.3,
            ..default()
        },
        
        // ... other components
    ))
    .id()
}

Cover Object Setup

Creating Cover Objects:

fn spawn_cover_object(
    mut commands: Commands,
    position: Vec3,
    cover_type: CoverType,
) -> Entity {
    let height = match cover_type {
        CoverType::Low => 0.5,
        CoverType::Medium => 1.0,
        CoverType::High => 2.0,
        _ => 1.0,
    };
    
    commands.spawn((
        Name::new(format!("{:?} Cover", cover_type)),
        Transform::from_translation(position),
        GlobalTransform::default(),
        
        // Physics - make sure it's on the cover layer
        RigidBody::Static,
        Collider::cuboid(1.0, height, 1.0),
        CollisionLayers::new([Layer::Cover], [Layer::All]),
    ))
    .id()
}

Input Actions

Required Input Actions:

The stealth system requires the following input actions to be mapped:

InputAction::Hide - Toggle hiding
InputAction::Peek - Toggle peeking
InputAction::CornerLean - Toggle corner leaning
InputAction::ResetCamera - Reset camera to neutral
InputAction::ZoomIn - Zoom in (decrease FOV)
InputAction::ZoomOut - Zoom out (increase FOV)

Example Input Mapping:

// This is typically configured in your input system
let input_mappings = vec![
    (InputAction::Hide, KeyCode::C),
    (InputAction::Peek, KeyCode::Q),
    (InputAction::CornerLean, KeyCode::E),
    (InputAction::ResetCamera, KeyCode::R),
    (InputAction::ZoomIn, MouseScrollUp),
    (InputAction::ZoomOut, MouseScrollDown),
];

Performance Considerations

Optimization Techniques

Raycast Optimization:

Raycasts only fire when hidden
Limited to cover_detection_distance
Single raycast per character per frame
Early exit on first hit

Line of Sight Optimization:

Only checks when check_if_detected_while_hidden enabled
Distance culling against AI detection range
Early exit on first detecting AI
Spatial partitioning for AI queries

Update Frequency:

Cover detection runs in FixedUpdate (physics timestep)
Camera updates run in Update (frame-rate)
Visibility meter updates run in Update
State validation runs in FixedUpdate

Component Organization:

Data organized for cache efficiency
Minimal state duplication
Optional components for unused features
Separate systems for independent features

Performance Tips

Disable Unused Features:
- Set check_if_detected_while_hidden to false if not needed
- Disable zoom if not required
- Disable spring camera if not desired
Adjust Detection Frequency:
- Increase check_if_character_can_be_hidden_again_rate
- Reduce update frequency for background characters
Optimize Cover Layer:
- Use dedicated physics layer for cover
- Minimize objects on cover layer
- Use simple collision shapes
Limit AI Count:
- Reduce active AI entities
- Use frustum culling for distant AI
- Implement AI LOD system
Spatial Partitioning:
- Use Bevy’s spatial queries efficiently
- Implement chunking for large worlds
- Cull checks outside relevant zones

Customization Guide

Creating Custom Hide States

Extending HideState Enum:

// Add new state to enum
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Reflect)]
pub enum HideState {
    // ... existing states ...
    Crawling,        // New: crawling hide state
    VentHiding,      // New: hiding in vents
    WaterHiding,     // New: hiding underwater
}

Implementing Custom State Logic:

fn update_custom_hide_states(
    mut query: Query
) {
    for (stealth, mut state, transform) in query.iter_mut() {
        match state.hide_state {
            HideState::Crawling => {
                // Custom crawling logic
                state.camera_is_free = false;
                // Implement crawling movement restrictions
            }
            HideState::VentHiding => {
                // Custom vent hiding logic
                state.camera_is_free = true;
                // Implement vent-specific mechanics
            }
            HideState::WaterHiding => {
                // Custom water hiding logic
                // Implement oxygen system, bubble detection, etc.
            }
            _ => {}
        }
    }
}

Custom Cover Types

Adding Specialized Cover:

// Extend CoverType enum
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Reflect)]
pub enum CoverType {
    // ... existing types ...
    Foliage,         // Bushes, grass
    Water,           // Puddles, ponds
    Crowd,           // Blend into groups
    Shadow,          // Dark areas
    Dynamic,         // Moving cover (vehicles, etc.)
}

Custom Cover Detection:

fn detect_custom_cover_types(
    mut query: Query,
    foliage_query: Query>,
) {
    for (stealth, mut cover, transform) in query.iter_mut() {
        // Check proximity to foliage
        for foliage_transform in foliage_query.iter() {
            let distance = (foliage_transform.translation - transform.translation).length();
            
            if distance < 1.0 {
                cover.is_in_cover = true;
                cover.cover_type = CoverType::Foliage;
                cover.cover_height = foliage_transform.scale.y;
                break;
            }
        }
    }
}

Custom Detection Factors

Environmental Detection Modifiers:

#[derive(Component)]
pub struct EnvironmentalDetection {
    pub weather_modifier: f32,      // Rain/fog reduces detection
    pub time_of_day_modifier: f32,  // Night reduces detection
    pub noise_level: f32,           // Ambient noise masks footsteps
}
fn update_environmental_detection(
    mut query: Query,
    environment: Res,
) {
    for (mut visibility, env_detection, transform) in query.iter_mut() {
        // Weather modifier
        let weather_factor = match environment.weather {
            Weather::Rain | Weather::Fog => 0.5,
            Weather::Clear => 1.0,
            _ => 0.8,
        };
        
        // Time of day modifier
        let time_factor = if environment.is_night() { 0.3 } else { 1.0 };
        
        // Calculate final detection modifier
        let total_modifier = weather_factor * time_factor * env_detection.noise_level;
        
        // Apply to visibility
        visibility.current_visibility *= total_modifier;
    }
}

Custom Camera Behaviors

Implementing New Camera Modes:

#[derive(Component)]
pub struct CustomCameraMode {
    pub mode: CameraMode,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CameraMode {
    OverShoulder,
    FirstPerson,
    TopDown,
    Isometric,
}
fn update_custom_camera_modes(
    mut query: Query,
    camera_query: Query, Without)>,
) {
    for (state, camera_mode, character_transform) in query.iter() {
        if !state.is_hidden {
            continue;
        }
        
        for mut camera_transform in camera_query.iter_mut() {
            match camera_mode.mode {
                CameraMode::OverShoulder => {
                    // Implement over-shoulder camera
                    let offset = Vec3::new(0.5, 0.5, -2.0);
                    camera_transform.translation = character_transform.translation + offset;
                }
                CameraMode::FirstPerson => {
                    // Implement first-person camera
                    let offset = Vec3::new(0.0, 1.7, 0.0);
                    camera_transform.translation = character_transform.translation + offset;
                }
                CameraMode::TopDown => {
                    // Implement top-down camera
                    let offset = Vec3::new(0.0, 10.0, 0.0);
                    camera_transform.translation = character_transform.translation + offset;
                    camera_transform.rotation = Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2);
                }
                _ => {}
            }
        }
    }
}

Best Practices

Design Guidelines

Cover Placement:
- Place cover at strategic locations
- Provide multiple cover options
- Create cover-to-cover paths
- Balance risk and reward
Detection Tuning:
- Start with generous detection times
- Test with real players
- Balance challenge with fairness
- Provide clear feedback
Camera Feel:
- Smooth camera transitions
- Comfortable rotation speeds
- Reasonable angle limits
- Optional spring camera for accessibility
Level Design:
- Design with stealth in mind
- Provide sightline breaks
- Create hiding opportunities
- Support multiple playstyles

Common Patterns

Stealth Sequences:

// Patrol guards → Find cover → Wait → Move to next cover → Reach objective

Detection Escalation:

// Suspicious → Investigating → Alert → Combat → Search → Return to patrol

Cover Progression:

// Safe area → Open space with cover → Guarded area → Objective

Debugging Tips

Visualization:

Enable debug gizmos for cover detection
Draw detection ranges
Show line-of-sight rays
Display state information

Logging:

Log state transitions
Track detection events
Monitor visibility levels
Record AI awareness

Testing:

Test all hide states
Verify cover detection
Check AI integration
Validate edge cases

Troubleshooting

Common Issues

Character Can’t Hide:

Check can_be_hidden flag
Verify crouch requirement met
Ensure not detected
Check cooldown timer

Cover Not Detected:

Verify cover object on correct physics layer
Check cover_detection_distance
Ensure cover object has collider
Verify cover_layer mask

Camera Not Moving:

Check camera_can_rotate flag
Verify camera_is_free is true
Ensure in hide state
Check input mapping

AI Detects Through Walls:

Verify wall colliders exist
Check raycast layer masks
Ensure obstacles on correct layers
Test line-of-sight algorithm

Spring Camera Not Working:

Enable use_spring_rotation/use_spring_movement
Check delay timers
Verify last input timestamps
Test with longer delays

Performance Issues

High Raycast Cost:

Reduce cover detection distance
Increase FixedUpdate timestep
Limit active stealth characters
Optimize cover object count

AI Detection Lag:

Reduce AI query range
Implement spatial partitioning
Limit active AI count
Use frustum culling

Advanced Topics

Multiplayer Stealth

Considerations for networked stealth gameplay:

Client-Server Architecture:

Server authoritative detection
Client prediction for hiding
Reconciliation for state mismatches
Bandwidth optimization

Synchronization:

Replicate hide state
Sync visibility meter
Network camera transforms
Handle latency compensation

Animation Integration

Connecting stealth to animation system:

Animation States:

Idle hidden animation
Peek animation
Corner lean animations
Transition animations

Animation Blending:

Blend between states
Layer animations for peeking
IK for wall contact
Procedural lean adjustments

AI Cooperation

Advanced AI behaviors for stealth:

Alert Sharing:

Nearby AI alerted on detection
Radio communication simulation
Investigation patterns
Search coordination

Smart Searching:

Last known position tracking
Predicted player position
Cover checking
Systematic area search

Future Enhancements

Potential areas for expansion:

Light & Shadow System: Dynamic lighting affecting detection
Noise Propagation: Realistic sound travel through environment
Disguise System: Blending in with NPCs
Environmental Kills: Takedowns from hiding
Distraction Items: Throwable objects to divert attention
Smell Detection: AI tracking via scent
Crowd Blending: Hiding in plain sight
Dynamic Cover: Destructible and movable cover
Awareness Indicators: Show AI suspicion levels
Stealth Rating: Score player’s stealth performance