API Reference

Task<NPCResponse> RespondAsync(string playerText)

var npc = GetComponent<LoreMindNPC>();
var response = await npc.RespondAsync("What do you know about the dragon?");
 
if (response.success)
{
    dialogueUI.ShowText(response.response);
    Debug.Log($"Credits used: {response.metadata.creditsUsed}");
}
else
{
    Debug.LogError($"Error: {response.error} - {response.message}");
}

void Respond(string playerText)

void Start()
{
    npc.OnResponseReceived.AddListener(text => dialogueUI.ShowText(text));
    npc.OnError.AddListener(error => Debug.LogError(error));
}
 
void OnPlayerSpeak(string text)
{
    npc.Respond(text);
}

void SetLocation(string location, string details = null)

// Before conversation
npc.SetLocation("The Rusty Anvil Tavern", "Crowded, smell of ale");
 
var response = await npc.RespondAsync("Is it always this busy?");
// NPC responds knowing they're in a busy tavern

void SetCustomContext(string key, string value)
string GetCustomContext(string key)
void RemoveCustomContext(string key)

// Set quest context
npc.SetCustomContext("active_quest", "Find the missing merchant");
npc.SetCustomContext("player_reputation", "trusted_ally");
 
var response = await npc.RespondAsync("Any news about missing people?");
// NPC knows about the quest and trusts the player
 
// Clear when quest completes
npc.RemoveCustomContext("active_quest");

void ClearConversationHistory()

void OnPlayerLeaveNPC()
{
    npc.ClearConversationHistory();
    // Next conversation starts fresh
}

var context = npc.Context;
context.location = "Blacksmith Shop";
context.locationDetails = "Hot forge, smell of metal";
context.timeOfDay = "afternoon";
context.npcActivity = "hammering at the anvil";
context.npcMood = "focused";
context.playerAppearance = "carrying a broken sword";
context.recentEvents = new[] { "Dragon spotted near the village" };

context.SetCustom("faction", "Silver Hawks");
string faction = context.GetCustom("faction");
context.RemoveCustom("faction");

var response = await npc.RespondAsync("Hello!");
 
if (response.success)
{
    dialogueUI.ShowText(response.response);
    Debug.Log($"Credits: {response.metadata.creditsUsed}");
}
else if (response.error == "INSUFFICIENT_CREDITS")
{
    ShowBuyCreditsPrompt();
}
else if (response.error == "RATE_LIMITED")
{
    await Task.Delay(response.retryAfter * 1000);
    // Retry...
}

npc.OnResponseWithMetadata.AddListener(response =>
{
    var meta = response.metadata;
    Debug.Log($"Model: {meta.model}");
    Debug.Log($"Tokens: {meta.promptTokens} in, {meta.completionTokens} out");
    Debug.Log($"Cost: {meta.creditsUsed} credits");
    Debug.Log($"Remaining: {meta.creditsRemaining} credits");
 
    // Set your own threshold based on your game's usage patterns
    if (meta.creditsRemaining < YOUR_LOW_CREDITS_THRESHOLD)
        ShowLowCreditsWarning();
});

var zone = gameObject.AddComponent<LocationZone>();
// Configure via inspector fields or serialized properties

// In inspector:
// Display Name: "Hooded stranger"
// Category: Character
// Details: "Covered in dried blood, watching the door"
// Details Radius: 5.0
 
// When player asks NPC about surroundings:
// "There's a hooded stranger over there. Be careful - I saw blood on his cloak."

public class DayNightManager : MonoBehaviour
{
    void OnTimeChanged(float gameHours)
    {
        var global = GlobalContextManager.Instance;
 
        if (gameHours < 6) global.SetTimeOfDay("night");
        else if (gameHours < 12) global.SetTimeOfDay("morning");
        else if (gameHours < 18) global.SetTimeOfDay("afternoon");
        else global.SetTimeOfDay("evening");
    }
 
    void OnMajorEvent(string eventDescription)
    {
        GlobalContextManager.Instance.AddWorldEvent(eventDescription);
        // All NPCs with SyncGlobalContext=true now know about this event
    }
}

async void OnVoiceButtonPressed()
{
    // Duration depends on expected speech length - adjust for your game
    string text = await voiceInput.CaptureAndTranscribeAsync(maxDuration);
 
    if (!string.IsNullOrEmpty(text))
    {
        npc.Respond(text);
    }
}

public interface INpcContextProvider
{
    NpcContextData GetCurrentContext();
}

public class QuestContextProvider : MonoBehaviour, INpcContextProvider
{
    public NpcContextData GetCurrentContext()
    {
        return new NpcContextData
        {
            situation = QuestManager.ActiveQuest?.Type ?? "exploring",
            npcMood = HostilitySystem.IsHostile(gameObject) ? "hostile" : "neutral",
            playerReputation = FactionSystem.GetReputation("Innkeepers") > 50 ? "trusted" : "stranger",
            recentEvents = QuestManager.GetRecentEventSummaries(3)
        };
    }
}

enum VerbosityPreset
{
    Terse,      // 1-2 sentences
    Balanced,   // 2-4 sentences (default)
    Verbose     // Detailed responses
}

enum ContextCategory
{
    Character,  // NPCs, creatures, enemies
    Object,     // Furniture, decorations
    Item,       // Weapons, tools, consumables
    Landmark    // Buildings, monuments
}

enum AuthMode
{
    DirectClient,      // Device-based JWT sessions
    ServerMediated     // API key authentication
}