> For the complete documentation index, see [llms.txt](https://docs.gaming.skillfulai.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaming.skillfulai.io/unity-gaming-sdk/services/smart-npcs/service-reference.md).

# Service Reference

## `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:

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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:

```csharp
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.

{% hint style="info" %}
If you're stuck or need help, don't hesitate to reach out in our [Discord Community](https://discord.gg/WhAYqkXYkg)
{% endhint %}