Skip to main content
The NPC Builder Unity package lets you import a single .unitypackage, configure API credentials, then script AI-powered NPC conversations with one component.

​
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

1

Download package

Get the NPC Builder .unitypackage from the Asset Store (or company download link).
2

Import into Unity

In the Unity Editor choose
Assets → Import Package → Custom Package and select the downloaded file.
Click Import when Unity shows the file list.

​
2 · Configure credentials

A ready-made config.json lives at Assets/NPCBuilder/config.json. Edit the placeholders: unity-1
For credentials management refer to: authentication
{
  "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.
Keep credentials out of public repos. Use Unity’s Secrets Manager or CI variables for production builds.

​
3 · Attach the component

Drag your NPC prefab into the scene and add NPCBuilderInteractions via the Inspector.
Fill Game ID, World ID, and character_id—all visible in the dashboard context tree. unity-2

​
4 · Minimal chat script

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

To understand with more details events & items explore Events and Items
NPC replies can include character_events or user_events.
Create Action or Item events in the dashboard (globally or per character), then reference them exactly in Unity: 
// Map item events to GameObjects
npc.getGameObjectAssociatedToEvent += go =>
{
    if (go != null)
        Debug.Log($"Event item prefab set to {go.name}");
};
Event TypePurposeExample.
ActionNo item; pure verbwave, bow
ItemIncludes an itemgive_sword, trade_potion
Need more endpoints? Explore OpenAPI or see Context API for UID details.
⌘I