> ## Documentation Index
> Fetch the complete documentation index at: https://docs.npcbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unity Plugin

> Install the NPC Builder SDK and chat with NPCs in Unity

<Info>
  The NPC Builder Unity package lets you import a single <code>.unitypackage</code>, configure API credentials, then script AI-powered NPC conversations with one component.
</Info>

## Prerequisites

* Unity **2020.3 LTS** or higher (2019.4 works but examples use the new Input System).
* NPC Builder account with an **active plan** and project.
* Client ID / Client Secret (or Bearer token) generated in **Developers → API Keys**.
* Basic familiarity with C# scripting in Unity.

## 1 · Installation

<Steps>
  <Step title="Download package">
    Get the <strong>NPC Builder</strong> `.unitypackage` from the Asset Store (or company download link).
  </Step>

  <Step title="Import into Unity">
    In the Unity Editor choose\
    **Assets → Import Package → Custom Package** and select the downloaded file.\
    Click <em>Import</em> when Unity shows the file list.
  </Step>
</Steps>

## 2 · Configure credentials

A ready-made <code>config.json</code> lives at <code>Assets/NPCBuilder/config.json</code>. Edit the placeholders:

<img src="https://mintcdn.com/npcbuilder/gDWYaAGXxhL_iGnr/integrations/media/unity-1.png?fit=max&auto=format&n=gDWYaAGXxhL_iGnr&q=85&s=c7afc91baaa9b2ae7c6721db9ae75430" alt="unity-1" width="1920" height="1080" data-path="integrations/media/unity-1.png" />

<Note>
  For credentials management refer to: <a href="/api-reference/authentication">authentication</a>
</Note>

```json theme={null}
{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "bearerToken": "YOUR_BEARER_TOKEN"
}
```

* Client ID + Secret is the preferred long-term auth.
* Bearer token is an alternative for quick tests.
* If both are present the plugin prioritizes the secret.

<Callout type="warning">
  Keep credentials out of public repos. Use Unity’s **Secrets Manager** or CI variables for production builds.
</Callout>

## 3 · Attach the component

Drag your NPC prefab into the scene and add **NPCBuilderInteractions** via the Inspector.\
Fill <code>Game ID</code>, <code>World ID</code>, and <code>character\_id</code>—all visible in the dashboard context tree.

<img src="https://mintcdn.com/npcbuilder/GsOKyk9tvehbw9t1/integrations/media/unity-2.png?fit=max&auto=format&n=GsOKyk9tvehbw9t1&q=85&s=6cc066401345102e7fc6ea864e6fc0ed" alt="unity-2" width="696" height="760" data-path="integrations/media/unity-2.png" />

## 4 · Minimal chat script

```csharp theme={null}
using UnityEngine;
using NPCBuilder;

public class ChatStarter : MonoBehaviour
{
    NPCBuilderInteractions npc;

    void Awake()
    {
        npc = GetComponent<NPCBuilderInteractions>();
        npc.OnMessageReceived += OnReply;
        npc.StartInteraction(ConversationRole.User, "Hello NPC!");
    }

    void OnReply(System.Collections.Generic.List<Message> convo)
    {
        Debug.Log(npc.GetConversationString());
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.V))
            npc.StartInteraction(ConversationRole.User, "How are you?");
        if (Input.GetKeyDown(KeyCode.C))
            npc.ClearConversation();
    }
}
```

The component queues calls asynchronously, so gameplay never blocks.

## 5 · Working with events & items

<Note>
  To understand with more details events & items explore <a href="/essentials/events-and-items">Events and Items</a>
</Note>

NPC replies can include <code>character\_events</code> or <code>user\_events</code>.\
Create **Action** or **Item** events in the dashboard (globally or per character), then reference them exactly in Unity:

```csharp theme={null}
// Map item events to GameObjects
npc.getGameObjectAssociatedToEvent += go =>
{
    if (go != null)
        Debug.Log($"Event item prefab set to {go.name}");
};
```

| Event Type | Purpose            | Example.                                             |
| ---------- | ------------------ | ---------------------------------------------------- |
| Action     | No item; pure verb | <code>wave</code>, <code>bow</code>                  |
| Item       | Includes an item   | <code>give\_sword</code>, <code>trade\_potion</code> |

<Note>
  Need more endpoints? Explore <a href="/api-reference/introduction">OpenAPI</a> or see <a href="/context-api-reference">Context API</a> for UID details.
</Note>