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

Setting	Required?	What it does
Entity Mind	Yes	The NPC’s personality and knowledge
Location	No, but recommended	Where the conversation happens
Time of Day	No	Affects NPC responses (“It’s getting late…”)
Everything else	No	Advanced 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

Verbosity

How long should responses be?

Setting	Result	Use for
Terse	1-2 sentences	Quick interactions, minor NPCs, saving credits
Balanced	2-4 sentences	Most conversations (default)
Verbose	Detailed	Important story moments

TopK

How much lore should the NPC reference?

Value	Effect	Use for
1-2	Faster, cheaper, less informed	Generic NPCs, quick chats
3	Good balance (default)	Most NPCs
5-10	Slower, more expensive, very knowledgeable	Lore-heavy NPCs, scholars

Temperature

How creative should responses be?

Value	Effect	Use for
0-0.3	Very consistent, predictable	Quest givers, important NPCs
0.7	Natural variation (default)	Most NPCs
0.9+	Very creative, unpredictable	Eccentric characters

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 (Server Mediated mode only):


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

Requires: Server Mediated authentication. See Long-Term Memory.

Monitoring Costs

Each response costs credits. Monitor usage:


npc.OnResponseWithMetadata.AddListener(response =>
{
    Debug.Log($"Credits used: {response.metadata.creditsUsed}");
    Debug.Log($"Credits remaining: {response.metadata.creditsRemaining}");
 
    // Set your own low-credits threshold
    if (response.metadata.creditsRemaining < lowCreditsThreshold)
    {
        Debug.LogWarning("Running low on credits!");
    }
});

Cost-saving tips:

Use Terse verbosity for unimportant NPCs
Lower TopK for NPCs that don’t need much lore
Clear conversation history when conversations end

API Summary

Properties


// Required
string EntityMindId { get; set; }
 
// Configuration
RuntimeContext Context { get; set; }
int TopK { get; set; }                    // Lore chunks to retrieve
VerbosityPreset Verbosity { get; set; }   // Terse, Balanced, Verbose
float Temperature { get; set; }           // Creativity level
 
// State
bool IsProcessing { get; }
string LastResponse { get; }
NPCResponse LastResponseData { get; }
int ConversationHistoryCount { get; }
 
// Context awareness
bool AutoSenseNearby { get; set; }
bool SyncGlobalContext { get; set; }
float SenseRadius { get; set; }
LayerMask SenseLayers { get; set; }
 
// Memory (Server Mediated only)
bool EnableMemoryRetrieval { get; set; }
bool EnableMemoryStorage { get; set; }

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)

Events


UnityEvent<string> OnResponseReceived
UnityEvent<NPCResponse> OnResponseWithMetadata
UnityEvent<string> OnError

Next Steps

Context System - Auto-detect locations and nearby entities
Voice Input - Let players speak to NPCs
Long-Term Memory - NPCs remember players across sessions
API Reference - Complete API documentation