Unity Integration – Plugin

Welcome to the NPC Builder Plugin for Unity, designed to streamline the integration and interaction of non-playable characters (NPCs) within your Unity projects. This guide will walk you through setting up and using the plugin from start to finish.

Prerequisites #
  • Unity 5.3 or higher. (Unity 2020.2 to use example – because, Input System use).
  • Basic understanding of Unity and C# scripting.
Installation #
  1. Download the NPC Builder Plugin package the from Unity Asset Store (currently under publishing process).
  2. In Unity, go to Assets -> Import Package -> Custom Package and select the downloaded file.
  3. Ensure all the files are selected and click ‘Import’.
Configuring Credentials #

Before using the plugin, you need to configure your authentication credentials. A config.json file is already provided at the root of the NPC Builder Plugin package within your Unity project’s Assets folder.

Navigate to the config.json file located in the root of the NPC Builder package within your Unity project’s Assets folder.

Open the config.json file and update it with your actual credentials:

{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "bearerToken": "YOUR_BEARER_TOKEN"
}

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and YOUR_BEARER_TOKEN with the actual credentials provided by the NPC Builder platform.

Please note:

  • The clientId and clientSecret are required for the initial setup and authentication with the NPC Builder API.
  • The bearerToken is an alternative method of authentication. If you have a clientSecret, you may not need to use the bearerToken. However, if you prefer to use a token-based authentication for API calls, you can replace the bearerToken field with your actual token.
  • If both clientSecret and bearerToken are provided, the plugin will prioritize the usage of the clientSecret for authentication.
  • Ensure that your credentials are kept secure and not exposed in shared or public code repositories.
Using the Plugin #

Attach the NPCBuilderInteractions component to your NPC object in the scene.

Note: Get the id values from the platform.

EXAMPLE: Interacting with NPCs #

Use the following example script to initiate interactions with your NPCs:

using System.Collections.Generic;
using NPCBuilder; // Namespace specific to the NPC Builder system.
using UnityEngine;
using UnityEngine.InputSystem;
using static NPCBuilder.NPCBuilderInteractions; // Imports static definitions from NPCBuilderInteractions for easier access.

public class ApiInteractionsExample : MonoBehaviour
{
    // Declares a private variable to hold a reference to the NPCBuilderInteractions component.
    private NPCBuilderInteractions npcBuilderInteractions;

    void Awake()
    {
        // Retrieves the NPCBuilderInteractions component attached to the same GameObject.
        npcBuilderInteractions = GetComponent<NPCBuilderInteractions>();

        // Subscribes to the OnMessageReceived event. This means OnNPCMessageReceived will be called each time a new message is received.
        npcBuilderInteractions.OnMessageReceived += OnNPCMessageReceived;

        // Starts an interaction with the NPC by sending the initial message "Hola Robot".
        npcBuilderInteractions.StartInteraction(ConversationRole.User, "Hola Robot");
    }

    // This method is called every time a new message is received from the NPC.
    private void OnNPCMessageReceived(List<Message> conversation)
    {
        // Converts the current conversation (a list of messages) into a string.
        string conversationString = npcBuilderInteractions.GetConversationString();

        // Prints the current conversation in the Unity console for debugging.
        Debug.Log(conversationString);

        // Iterate through each message in the conversation
        foreach (var message in conversation)
        {
            // Check if the role of the current message equals the 'Assistant' role
            // The ToRoleString() method is invoked to get the corresponding string value of the enum
            if (message.role == ConversationRole.Assistant.ToRoleString())
            {
                // If the message is from the assistant, its content is logged
                Debug.Log(" Assistant message: " + message.content);
            }
        }
    }

    void Update()
    {
        // Checks if the 'C' key was pressed.
        if (Keyboard.current.cKey.wasPressedThisFrame)
        {
            // If the 'C' key was pressed, initiates a new interaction with the NPCBuilder Api, sending the message".
            npcBuilderInteractions.StartInteraction(ConversationRole.User, "Que quieres?");
        }
    }
}

As we can see in the image below, the conversation returned by the NPC Builder API is displayed.