# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gaming.skillfulai.io/unity-gaming-sdk/services/smart-npcs/service-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.