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);
    }
}

void Start()
{
    // Auto-speak NPC responses
    npc.OnResponseReceived.AddListener(text =>
    {
        voiceOutput.Speak(text);
    });
 
    // Track speech state
    voiceOutput.OnSpeechStarted.AddListener(() => speakingIcon.SetActive(true));
    voiceOutput.OnSpeechCompleted.AddListener(() => speakingIcon.SetActive(false));
}

// Assign unique voices
blacksmithVoice.VoiceId = "bm_george";  // British male
apprenticeVoice.VoiceId = "af_sky";     // American female

foreach (var voice in voiceOutput.GetAvailableVoices())
{
    Debug.Log($"{voice.name} ({voice.gender}): {voice.id}");
}

enum TTSProviderType
{
    None,
    Kokoro
}

enum STTProviderType
{
    None,
    Whisper
}

public interface ISpeechToTextProvider
{
    Task<string> TranscribeAsync(float[] audioData, int sampleRate, int channels);
    Task<bool> InitializeAsync();
    void Dispose();
    bool IsReady { get; }
    string ProviderName { get; }
}

public interface ITextToSpeechProvider : IDisposable
{
    Task<AudioClip> SynthesizeAsync(string text, string voiceId = null, TTSSynthesisOptions options = null);
    Task SynthesizeStreamingAsync(string text, AudioSource audioSource, string voiceId = null, TTSSynthesisOptions options = null);
    Task<bool> InitializeAsync();
    bool IsReady { get; }
    string ProviderName { get; }
    bool SupportsStreaming { get; }
    TTSVoiceInfo[] GetAvailableVoices();
    string GetDefaultVoiceId();
}

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 TransportMode
{
    EditorDirect,     // Direct API calls in Editor (testing)
    CustomBackend     // Route through your backend (production)
}

public interface ILoreMindTransport
{
    Task<NPCResponse> SendRequestAsync(NPCRespondRequest request);
    bool IsReady { get; }
    string TransportName { get; }
}

public class LoggingTransport : ILoreMindTransport
{
    private readonly ILoreMindTransport _inner;
 
    public LoggingTransport(ILoreMindTransport inner)
    {
        _inner = inner;
    }
 
    public bool IsReady => _inner.IsReady;
    public string TransportName => $"Logging({_inner.TransportName})";
 
    public async Task<NPCResponse> SendRequestAsync(NPCRespondRequest request)
    {
        Debug.Log($"Sending: {request.text}");
        var response = await _inner.SendRequestAsync(request);
        Debug.Log($"Received: {response.response}");
        return response;
    }
}

// Editor-only: The SDK creates this automatically from Control Panel settings.
// Direct construction requires baseUrl, serverApiKey, and playerId:
var transport = new DirectApiTransport(baseUrl, serverApiKey, playerId);
npc.SetTransport(transport);

var transport = new CustomBackendTransport(
    backendUrl: "https://api.yourgame.com/api/npc/interact"
);
npc.SetTransport(transport);