Public API Reference

The complete public API surface under the LocalNPC namespace. Conforms strictly to the Frozen API Specification (§7.1).

🏛 Top-Level Facade: LocalNPC.LocalNpc

The static entry point for project-wide package initialization and model provisioning.

namespace LocalNPC
{
    public static class LocalNpc
    {
        /// <summary>Global LocalNPC runtime settings and project defaults.</summary>
        public static LocalNpcSettings Settings { get; }

        /// <summary>True if models required by the default configuration are verified on disk.</summary>
        public static bool AreModelsReady { get; }

        /// <summary>Ensures models are installed and verified asynchronously.</summary>
        public static Task EnsureModelsAsync(IProgress<ProvisionStatus> p = null, CancellationToken ct = default);

        /// <summary>Immediately releases and unloads all shared models and background worker threads.</summary>
        public static void UnloadAll();
    }
}

Usage Example:

using UnityEngine;
using LocalNPC;

public class GameInitializer : MonoBehaviour
{
    private async void Start()
    {
        if (!LocalNpc.AreModelsReady)
        {
            Debug.Log("Downloading on-device models...");
            await LocalNpc.EnsureModelsAsync();
        }
        Debug.Log("LocalNPC models ready!");
    }
}

🤖 Main Component: LocalNPC.NpcAgent

The primary MonoBehaviour through which games orchestrate character interactions.

Public Properties

Public Methods

// Prewarms and loads required inference models into memory
public Task PrewarmAsync(CancellationToken ct = default);

// Begins listening for player speech via the microphone. Only one NpcAgent can listen at a time;
// call StopListening on one before StartListening on another.
public void StartListening();

// Stops listening for player speech and returns the agent to Idle
public void StopListening();

// Executes a conversational turn directly from typed text input
public Task SayAsync(string userText, CancellationToken ct = default);

// Stops the current reply at once. Call it from your code; speaking does not interrupt the NPC.
public void Interrupt();

// Clears conversational chat history
public void ResetConversation();

// Updates personality asset at runtime with optional history reset
public void SetPersonality(NpcPersonality p, bool resetHistory = true);

// Lists the Windows voices installed on this PC for a language (every voice for an empty tag); plays no sound
public static NpcVoiceInfo[] GetInstalledVoices(string languageTag);

Public Events

// Fired when the agent transitions between operational states
public event Action<NpcState, NpcState> OnStateChanged;

// Fired when the player's microphone speech is transcribed into text
public event Action<string> OnUserTranscript;

// Fired as incremental token chunks stream from the LLM
public event Action<string> OnReplyChunk;

// Fired as each individual sentence begins audible speech playback.
// With no Windows voice installed, it fires for each sentence, which is then shown as text only.
public event Action<string> OnSentenceSpoken;

// Fired when the full reply generation and audio playback completes
public event Action<string> OnReplyComplete;

// Fired on pipeline or stage errors (guaranteeing zero unhandled exceptions)
public event Action<NpcError> OnError;

🔊 Installed Voice: LocalNPC.NpcVoiceInfo

One installed Windows voice, as NpcAgent.GetInstalledVoices lists it.

public readonly struct NpcVoiceInfo
{
    // Display name, for example "Microsoft Zira"; a value for NpcAgent.SystemVoice
    public readonly string Name;

    // BCP-47 language tag, for example "en-US"
    public readonly string Language;
}

⚠️ Error Codes: LocalNPC.NpcErrorCode

public enum NpcErrorCode
{
    None = 0,
    ModelMissing,
    ModelCorrupt,
    NativeLibraryMissing,
    AbiMismatch,
    MicrophoneUnavailable,
    MicrophonePermissionDenied,
    OutOfMemory,
    InferenceFailed,
    SynthesisFailed,
    LanguageUnsupported,
    Cancelled,
    Unknown
}

🎙 Push-To-Talk: LocalNPC.Audio.PushToTalkController

Gated microphone control for kiosks, noisy rooms, or walkie-talkie style mechanics.

v1.0: PushToTalkController is not connected to the microphone. It records only the audio your own code passes to PushAudioFrame, so holding the key or button alone sends nothing to the NPC. Connecting it to the microphone is planned for v1.1. Until then, use NpcAgent.StartListening() (the built-in microphone).

// Programmatically activates recording (ideal for UI buttons or VR triggers)
public void SetPressed(bool isPressed);

// Key/button configuration
public PushToTalkMode Mode { get; set; } // PressAndHold or Toggle
public KeyCode LegacyKey { get; set; }   // KeyCode.Space