Smart NPCs Quick Start Guide

Let's get started with adding voice to your game characters. This guide will show you how to implement Smart NPCs in your Unity project.

Adding Your First Smart NPC

You have two ways to implement a Smart NPC:

Method 1: Through Code

Create a new script (e.g., ExampleSmartNPC.cs) with this basic implementation:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class ExampleSmartNPC : MonoBehaviour
{
    private void Start()
    {
        // Add the Smart NPC component
        SmartNPC myNpc = gameObject.AddComponent<SmartNPC>();

        // Set a voice by category
        VoiceSelector.SetVoiceByCategory(myNpc, VoiceCategories.Female);

        // Set the output audio source for the NPC. 
        myNpc.audioSource = gameObject.AddComponent<AudioSource>();

        // Make the NPC speak!
        myNpc.Speak("Hello! I'm your first Smart NPC!");
    }
}

Method 2: Using the Unity Inspector

1. Create an empty GameObject

2. Add the SmartNPC component

1. Add an AudioSource component (required for speech playback)

2. Create a script to interact with it:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class NPCController : MonoBehaviour
{
    private SmartNPC npc;

    private void Start()
    {
        // Get reference to existing SmartNPC component
        npc = GetComponent<SmartNPC>();
        
        // Select a voice and speak
        VoiceSelector.SetVoiceByName(npc, "YourVoiceNameHere");
        npc.Speak("Hello, I'm ready to talk!");
    }
}

Voice Selection Options

Smart NPCs offers several ways to select voices:

public class VoiceExample : MonoBehaviour
{
    private SmartNPC npc;

    void Start()
    {
        npc = gameObject.AddComponent<SmartNPC>();

        // Option 1: Select by category
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Male);

        // Option 2: Select by specific voice name
        VoiceSelector.SetVoiceByName(npc, "VoiceName");

        // Option 3: Select a random voice
        VoiceSelector.SetRandomVoice(npc);
    }
}

Customizing Voice Settings

Fine-tune your NPC's voice characteristics:

public class VoiceCustomization : MonoBehaviour
{
    private SmartNPC npc;

    void Start()
    {
        npc = gameObject.AddComponent<SmartNPC>();

        // Customize voice settings
        npc.voiceSettings = new VoiceSettings
        {
            stability = 0.5f,            // Voice consistency
            similarity_boost = 0.5f,      // Similarity to original
            use_speaker_boost = true     // Enhanced clarity
        };

        // Test the customized voice
        npc.Speak("This voice has been customized!");
    }
}

Integrating with Skillful Agents

Create an NPC that can think and speak:

public class TalkingNPC : MonoBehaviour
{
    private SkillfulAgent agent;
    private SmartNPC npc;

    void Start()
    {
        // Setup both components
        agent = gameObject.AddComponent<SkillfulAgent>();
        npc = gameObject.AddComponent<SmartNPC>();

        // Configure them
        agent.SelectAgentByName("YourAgentName");
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Female);

        // Start a voiced conversation
        agent.SendMessage("Introduce yourself", response => {
            npc.Speak(response);
        });
    }
}

Managing Speech Queue

Handle multiple speech requests:

public class QueuedSpeechManager : MonoBehaviour
{
    private SmartNPC npc;

    void Start()
    {
        npc = gameObject.AddComponent<SmartNPC>();
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Male);

        // Queue multiple speeches
        npc.Speak("First message");
        npc.Speak("Second message");
        npc.Speak("Third message");
        
        // Messages will play in order automatically
    }

    public void StopTalking()
    {
        npc.StopSpeaking(); // Clears queue and stops current speech
    }
}

Creating a Basic Dialogue System

Implement a simple dialogue system:

public class DialogueNPC : MonoBehaviour
{
    private SmartNPC npc;
    private SkillfulAgent agent;
    private Queue<string> dialogueQueue = new Queue<string>();

    void Start()
    {
        // Setup components
        npc = gameObject.AddComponent<SmartNPC>();
        agent = gameObject.AddComponent<SkillfulAgent>();

        // Configure
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Female);
        agent.SelectAgentByName("DialogueAgent");
    }

    public void StartDialogue()
    {
        agent.SendMessage("Greet the player", response => {
            npc.Speak(response);
        });
    }

    public void PlayerResponse(string input)
    {
        agent.SendMessage(input, response => {
            npc.Speak(response);
        });
    }
}

Next Steps

Now that you have your Smart NPC working, consider:

1. Experimenting with different voices and settings

2. Creating more complex dialogue systems

3. Implementing voice-based tutorials

4. Adding ambient NPC chatter

5. Creating voiced cutscenes

Check out the Service Reference for more detailed implementation options and advanced features.