Skip to Content
Loremind Unity SDKLoreMindNPC

LoreMindNPC Component

The LoreMindNPC component gives any GameObject conversational AI. Add it to your NPC and start talking.

Quick Start

var npc = GetComponent<LoreMindNPC>();
var response = await npc.RespondAsync("Hello!");
Debug.Log(response.response);

Required: Select an Entity Mind from the dropdown in the Inspector.

Required vs Optional Settings

SettingRequired?What it does
Entity MindYesThe NPC’s personality and knowledge
LocationNo, but recommendedWhere the conversation happens
Time of DayNoAffects NPC responses (“It’s getting late…”)
Everything elseNoAdvanced features you can add later

Start simple. Just set the Entity Mind and start talking.

Talking to Your NPC

Async/Await Pattern

using UnityEngine;
using Peek.LoreMind;
 
public class NPCDialogue : MonoBehaviour
{
    [SerializeField] private LoreMindNPC npc;
 
    public async void OnPlayerInteract(string playerMessage)
    {
        var response = await npc.RespondAsync(playerMessage);
 
        if (response != null && response.success)
        {
            ShowDialogue(response.response);
        }
        else
        {
            HandleError(response);
        }
    }
 
    void ShowDialogue(string text)
    {
        // Display in your dialogue UI
        dialogueUI.ShowText(text);
    }
 
    void HandleError(NPCResponse response)
    {
        string error = response?.error ?? "unknown";
 
        switch (error)
        {
            case "INSUFFICIENT_CREDITS":
                Debug.LogError("Out of credits! Add more at loremind.peekgames.dev");
                break;
 
            case "RATE_LIMITED":
                Debug.LogWarning($"Too many requests. Wait {response.retryAfter}s.");
                break;
 
            default:
                Debug.LogError($"NPC error: {response?.message}");
                break;
        }
    }
}

Event Pattern

Don’t want async/await? Use Unity Events:

void Start()
{
    npc.OnResponseReceived.AddListener(OnNPCResponse);
    npc.OnError.AddListener(OnNPCError);
}
 
void OnPlayerSpeaks(string text)
{
    npc.Respond(text); // Fire and forget
}
 
void OnNPCResponse(string npcText)
{
    dialogueUI.ShowText(npcText);
}
 
void OnNPCError(string error)
{
    Debug.LogError($"NPC Error: {error}");
}

Wire up events in the Inspector too - no code needed.

Checking If NPC Is Busy

The component won’t send a new request while one is in progress:

if (npc.IsProcessing)
{
    Debug.Log("NPC is thinking...");
    return;
}
 
await npc.RespondAsync(playerInput);

Adding Context

NPCs give better responses when they know where they are.

Location

npc.SetLocation("The Rusty Anvil Tavern", "Crowded, late evening");
 
var response = await npc.RespondAsync("Is it always this busy?");
// "Aye, especially on market days! Though it's usually quieter by midnight."

Time and Weather

npc.Context.timeOfDay = "midnight";
npc.Context.weather = "stormy";
 
var response = await npc.RespondAsync("Should I head out?");
// "In this storm? At this hour? I wouldn't recommend it, friend."

Custom Context

Add any game-specific context:

npc.SetCustomContext("player_reputation", "respected");
npc.SetCustomContext("active_quest", "Find the missing merchant");
 
var response = await npc.RespondAsync("Need any help around here?");
// NPC references the quest and treats the player accordingly

Multi-Turn Conversations

The NPC automatically remembers what you talked about:

await npc.RespondAsync("What's your name?");
// "I'm Garrick, innkeeper here for twenty years."
 
await npc.RespondAsync("Twenty years? That's impressive!");
// NPC remembers what they just said

Clear history when conversation ends:

void OnPlayerLeave()
{
    npc.ClearConversationHistory();
}

Otherwise the next conversation continues from where you left off.

Response Configuration

Response settings like verbosity, temperature, and topK are configured per Entity Mind in the LoreMind dashboard . The dashboard is the single source of truth — no SDK-side overrides needed.

SettingDashboard LocationEffect
VerbosityEntity Mind → Response ConfigTerse (1-2 sentences), Balanced (2-4), or Verbose
TemperatureEntity Mind → Response ConfigCreativity level (0.0–1.0)
TopKProject-level defaultNumber of lore chunks retrieved (1–10)

Active Knowledge Tags

Restrict which lore an NPC can reference at runtime — useful for gating knowledge behind quest progression or story beats.

Setting Tags at Runtime

// Early game: NPC only knows about blacksmithing
npc.ActiveKnowledgeTags = new[] { "blacksmithing" };
 
// After player completes a quest, unlock more knowledge
void OnQuestComplete(string questId)
{
    if (questId == "discover-ruins")
    {
        npc.ActiveKnowledgeTags = new[] { "blacksmithing", "ancient-ruins" };
    }
}
 
// Clear to restore full Entity Mind knowledge
npc.ActiveKnowledgeTags = null;

Active tags can only narrow the Entity Mind’s configured tags — they cannot grant access to tags the NPC doesn’t already have in the dashboard.

Inspector

The Knowledge Gating foldout in the Inspector lets you set default active tags without code. Tags set in the Inspector are used unless overridden at runtime.

See Entity Minds — Active Knowledge Tags for the platform-level overview.

Context Awareness (Advanced)

Auto-Sense Nearby Entities

NPCs can automatically detect nearby characters and objects with ContextTag components:

npc.AutoSenseNearby = true;
npc.SenseRadius = 10f; // Adjust based on your game's scale
 
// NPC now knows about nearby tagged entities
var response = await npc.RespondAsync("Who else is here?");
// "Besides us, there's a suspicious merchant near that altar."

Sync Global Context

Automatically sync time/weather from GlobalContextManager:

npc.SyncGlobalContext = true;
 
// When you update global time, all synced NPCs know
GlobalContextManager.Instance.SetTimeOfDay("dusk");

See Context System for details.

Long-Term Memory

Make NPCs remember players across play sessions:

npc.EnableMemoryRetrieval = true; // Remember past conversations
npc.EnableMemoryStorage = true;   // Save new memories

Requires: Production setup with playerId provided in requests. See Long-Term Memory and Backend Integration.

Custom Transport (Advanced)

For advanced scenarios, you can override how requests are sent using custom transports.

SetTransport

Inject a custom transport implementation:

// Use a custom transport for this NPC
npc.SetTransport(myCustomTransport);

Transport Property

Access the current transport for debugging or logging:

var currentTransport = npc.Transport;
Debug.Log($"Using transport: {currentTransport.GetType().Name}");

Transport Events

Monitor request/response flow for debugging:

npc.OnRequestSending.AddListener(request =>
{
    Debug.Log($"Sending request: {request.text}");
});
 
npc.OnResponseReceived.AddListener(response =>
{
    Debug.Log($"Received response: {response.response}");
});
 
npc.OnTransportError.AddListener(error =>
{
    Debug.LogError($"Transport error: {error}");
});

Most developers won’t need custom transports. The SDK automatically handles:

  • Editor testing - Uses your Server API Key stored locally
  • Production builds - Routes through your configured backend URL

See Backend Integration for production setup.

Monitoring Costs

Monitor credit usage and cost details in the LoreMind dashboard .

Cost-saving tips:

  • Use Terse verbosity for minor NPCs (configure in Entity Mind settings)
  • Clear conversation history when conversations end
  • Only enable memory for NPCs where persistence matters

API Summary

Properties

// Required
string EntityMindId { get; set; }
 
// Configuration
RuntimeContext Context { get; set; }
 
// State
bool IsProcessing { get; }
string LastResponse { get; }
NPCResponse LastResponseData { get; }
int ConversationHistoryCount { get; }
 
// Knowledge gating
string[] ActiveKnowledgeTags { get; set; }
 
// Context awareness
bool AutoSenseNearby { get; set; }
bool SyncGlobalContext { get; set; }
float SenseRadius { get; set; }
LayerMask SenseLayers { get; set; }
 
// Memory (requires playerId in production)
bool EnableMemoryRetrieval { get; set; }
bool EnableMemoryStorage { get; set; }
 
// Transport (advanced)
ILoreMindTransport Transport { get; }

Methods

// Core
Task<NPCResponse> RespondAsync(string playerText)
void Respond(string playerText)
void ClearConversationHistory()
 
// Context
void SetLocation(string location, string details = null)
void SetCustomContext(string key, string value)
string GetCustomContext(string key)
void RemoveCustomContext(string key)
 
// Transport (advanced)
void SetTransport(ILoreMindTransport transport)

Events

UnityEvent<string> OnResponseReceived
UnityEvent<NPCResponse> OnResponseComplete
UnityEvent<string> OnError
 
// Transport events (advanced)
UnityEvent<NPCRequest> OnRequestSending
UnityEvent<string> OnTransportError

Next Steps

Last updated on
Your First NPCContext System