Skip to Content
DocsVoicereactGetting Started

Getting Started

This guide walks you through creating your first voice-reactive enemy that hunts the player when they make noise.

What You’ll Build

An enemy that:

  • Hears the player when they speak
  • Knows the player’s position when heard
  • Reacts differently to whispers vs shouts
  • Loses the player when they go silent

Step 1: Scene Setup

First, set up VoiceReact in your scene:

// Use the Quick Setup menu:
// Tools > VoiceReact > Quick Setup Scene

This automatically adds:

  • VoiceReact Manager - Required coordinator
  • VoiceReactController - Voice detection on player

Manual Setup Alternative:

  1. Create empty GameObject named “VoiceReact Manager”
  2. Add VoiceReactManager component
  3. Add VoiceReactController to your player GameObject

Step 2: Add Voice Listener to Enemy

Make your enemy able to hear the player:

  1. Select your enemy GameObject
  2. Add Component > VoiceListener
  3. Configure in Inspector:
    • Base Hearing Range: 10 (meters)
    • Require Line Of Sight: false (can hear through walls)

The VoiceListener will automatically find the player’s VoiceReactController.

Step 3: Create Enemy AI Script

Create a new script VoiceReactiveEnemy.cs:

using UnityEngine;
using UnityEngine.AI;
using Peek.VoiceReact;
 
public class VoiceReactiveEnemy : MonoBehaviour
{
    [Header("References")]
    [SerializeField] private NavMeshAgent agent;
 
    [Header("Behavior")]
    [SerializeField] private float investigationDuration = 5f;
 
    private VoiceListener voiceListener;
    private Vector3 lastKnownPosition;
    private bool isInvestigating;
    private float investigationTimer;
 
    void Start()
    {
        voiceListener = GetComponent<VoiceListener>();
 
        // Hook up event handlers
        voiceListener.OnPlayerHeard.AddListener(OnHeardPlayer);
        voiceListener.OnPlayerLost.AddListener(OnLostPlayer);
    }
 
    void Update()
    {
        // Continue investigating if we heard the player recently
        if (isInvestigating)
        {
            investigationTimer -= Time.deltaTime;
 
            if (investigationTimer <= 0)
            {
                isInvestigating = false;
                ReturnToPatrol();
            }
        }
    }
 
    void OnHeardPlayer(Vector3 position, float decibelLevel)
    {
        Debug.Log($"Enemy heard player at {position} with volume {decibelLevel} dB");
 
        // Save where we heard the player
        lastKnownPosition = position;
 
        // Start investigating
        isInvestigating = true;
        investigationTimer = investigationDuration;
 
        // Move to player's position
        agent.SetDestination(lastKnownPosition);
 
        // React based on volume
        if (decibelLevel > -15f)
        {
            // Loud noise (shout) - run to position
            agent.speed = 6f;
        }
        else
        {
            // Quiet noise (whisper/normal) - walk to position
            agent.speed = 3.5f;
        }
    }
 
    void OnLostPlayer()
    {
        Debug.Log("Enemy lost the player (they went silent)");
        // Player is no longer making noise, but keep investigating last known position
    }
 
    void ReturnToPatrol()
    {
        Debug.Log("Enemy stopped investigating");
        agent.speed = 2f;
        // Return to patrol behavior
    }
}

Step 4: Configure Enemy

  1. Attach VoiceReactiveEnemy.cs to your enemy
  2. Assign references in Inspector:
    • Agent: Your NavMeshAgent component
  3. Adjust Investigation Duration (how long to search after hearing player)

Step 5: Test It

Enter Play mode and test:

  1. Whisper into your microphone → Enemy walks to your position
  2. Shout into your microphone → Enemy runs to your position
  3. Stay silent → Enemy stops hearing you after a moment

Understanding the System

Detection Flow

  1. Player speaks into microphone
  2. VoiceReactController detects voice and measures volume
  3. VoiceReactManager updates all VoiceListeners (30 times/sec)
  4. Each VoiceListener checks if player is in hearing range
  5. OnPlayerHeard event fires with position and volume
  6. Your AI script reacts to the event

Hearing Ranges

VoiceListener uses volume-based ranges:

// Example with baseHearingRange = 10 meters:
// Whisper (-40 dB): 2 meters  (10 * 0.2 whisperMultiplier)
// Normal  (-25 dB): 5 meters  (10 * 0.5 normalMultiplier)
// Loud    (-15 dB): 10 meters (10 * 1.0 loudMultiplier)
// Shout   (0 dB):   20 meters (10 * 2.0 shoutMultiplier)

Louder speech = larger hearing range.

Common Patterns

React to Current Hearing State

Check if enemy can currently hear player:

void Update()
{
    if (voiceListener.CanHearPlayer)
    {
        // Currently hearing player - stay alert
        alertMeter += Time.deltaTime;
    }
    else
    {
        // Not hearing player - calm down
        alertMeter -= Time.deltaTime;
    }
}

Distance-Based Reactions

Get distance to player:

void OnHeardPlayer(Vector3 position, float decibelLevel)
{
    float distance = voiceListener.DistanceToPlayer;
 
    if (distance < 3f)
    {
        // Very close - attack immediately
        Attack();
    }
    else if (distance < 10f)
    {
        // Medium range - investigate
        Investigate(position);
    }
    else
    {
        // Far away - just become alert
        BecomeAlert();
    }
}

Multiple Listeners Coordination

Get all enemies that can hear the player:

// From any script with access to VoiceReactManager:
var hearingEnemies = VoiceReactManager.Instance.GetListenersWhoCanHear();
 
foreach (var listener in hearingEnemies)
{
    Debug.Log($"{listener.gameObject.name} can hear the player!");
}

Next Steps

Now that you have basic voice detection working:

Troubleshooting

Enemy Never Hears Player

Check:

  • VoiceReactManager exists in scene
  • VoiceReactController is on player
  • Microphone permissions are granted
  • Speaking loud enough (try shouting)
  • Enemy’s hearing range is large enough

Hearing Range Seems Wrong

The effective range depends on:

  • baseHearingRange setting
  • Volume multipliers (whisper/normal/loud/shout)
  • Current player volume (dB level)

Enable debug gizmos on VoiceListener to see ranges in Scene view.

Events Not Firing

Ensure:

  • Event listener is added in Start(), not Awake()
  • VoiceListener component exists on GameObject
  • GameObject is active and enabled
Last updated on
EventsInstallation