Smart NPCs Service Reference

This reference guide covers the essential components and usage patterns of the Smart NPCs service, focusing on practical implementation details.

Core Components

SmartNPC Component

The primary component for adding voice capabilities to your game objects. This component handles:

• Voice selection and management

• Speech generation and playback

• Audio queue management

• Voice parameter customization

Implementation Patterns

Basic NPC Pattern

Simplest implementation for a speaking character:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class BasicNPC : MonoBehaviour
{
    private SmartNPC npc;

    void Start()
    {
        // Basic setup
        npc = gameObject.AddComponent<SmartNPC>();
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Male);
        npc.audioSource = gameObject.AddComponent<AudioSource>();
    }

    public void Speak(string text)
    {
        npc.Speak(text);
    }
}

Intelligent Speaking NPC Pattern

Combining Smart NPCs with Skillful Agents:

using SkillfulAI.Agents;
using SkillfulAI.SmartNPCs;
using UnityEngine;

public class IntelligentNPC : MonoBehaviour
{
    private SmartNPC npc;
    private SkillfulAgent agent;
    private bool isSpeaking = false;

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

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

    public void Interact(string playerInput)
    {
        if (!isSpeaking)
        {
            isSpeaking = true;
            agent.SendMessage(playerInput, response => {
                npc.Speak(response);
                isSpeaking = false;
            });
        }
    }
}

Multi-Voice Manager Pattern

For managing multiple NPCs with different voices:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class NPCManager : MonoBehaviour
{
    private Dictionary<string, SmartNPC> npcs = new Dictionary<string, SmartNPC>();

    void Start()
    {
        CreateNPC("Merchant", VoiceCategories.American);
        CreateNPC("Guard", VoiceCategories.British);
        CreateNPC("Guide", VoiceCategories.Female);
    }

    private void CreateNPC(string role, VoiceCategories category)
    {
        GameObject npcObj = new GameObject($"{role}NPC");
        SmartNPC npc = npcObj.AddComponent<SmartNPC>();
        VoiceSelector.SetVoiceByCategory(npc, category);
        npcs[role] = npc;
    }

    public void MakeNPCSpeak(string role, string text)
    {
        if (npcs.TryGetValue(role, out SmartNPC npc))
        {
            npc.Speak(text);
        }
    }
}

Dialogue System Pattern

For handling complex dialogue sequences:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class DialogueSystem : MonoBehaviour
{
    private SmartNPC npc;
    private Queue<string> dialogueLines = new Queue<string>();
    private bool isPlaying = false;

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

    public void QueueDialogue(string[] lines)
    {
        foreach (string line in lines)
        {
            dialogueLines.Enqueue(line);
        }

        if (!isPlaying)
        {
            PlayNextLine();
        }
    }

    private void PlayNextLine()
    {
        if (dialogueLines.Count == 0)
        {
            isPlaying = false;
            return;
        }

        isPlaying = true;
        string line = dialogueLines.Dequeue();
        npc.Speak(line);
    }
}

Interactive Tutorial Pattern

For creating voiced tutorials:

using SkillfulAI.SmartNPCs;
using UnityEngine;

public class TutorialGuide : MonoBehaviour
{
    private SmartNPC npc;
    private Dictionary<string, string> tutorialLines = new Dictionary<string, string>();

    void Start()
    {
        // Setup NPC
        npc = gameObject.AddComponent<SmartNPC>();
        VoiceSelector.SetVoiceByCategory(npc, VoiceCategories.Female);

        // Setup tutorial content
        InitializeTutorialContent();
    }

    private void InitializeTutorialContent()
    {
        tutorialLines.Add("movement", "Use WASD keys to move around.");
        tutorialLines.Add("jump", "Press Space to jump.");
        tutorialLines.Add("interact", "Press E to interact with objects.");
    }

    public void ExplainMechanic(string mechanicId)
    {
        if (tutorialLines.TryGetValue(mechanicId, out string explanation))
        {
            npc.Speak(explanation);
        }
    }

    public void OnPlayerAction(string action)
    {
        switch (action)
        {
            case "first_move":
                npc.Speak("Great! You've taken your first step!");
                break;
            case "first_jump":
                npc.Speak("Excellent jump! You're getting the hang of it!");
                break;
        }
    }
}

Best Practices

1. Voice Selection

   • Choose appropriate voices for character types

   • Keep voice settings consistent for each character

   • Consider using voice categories for consistency

2. Speech Management

   • Don't overlap speech from the same NPC

   • Implement proper queue management

   • Consider adding speech cooldowns

3. Performance

   • Reuse SmartNPC components

   • Manage audio resources properly

   • Implement proper cleanup.

If you're stuck or need help, don't hesitate to reach out in our Discord Community