LocalNPC Documentation
Welcome to the LocalNPC developer manual. LocalNPC is an on-device conversational NPC framework for Unity 6000.0 or newer on 64-bit Windows. Speech recognition (Whisper) and the language model (Qwen 2.5, through llama.cpp) run on the player's PC, with no cloud service and no per-token API costs. LocalNPC sends no data about the player: its only network use is downloading the model files from Hugging Face (huggingface.co) over HTTPS, with the server's certificate checked and each file checked with SHA-256 (and the licence links in the Editor). LocalNPC runs no server of its own; Hugging Face sees the IP address of the computer that downloads. (Checked by reading the code; no network capture was made.) The NPC speaks with the Windows system voice (OneCore, SAPI 5 as last fallback); nothing is downloaded for it, and with no voice installed the NPC answers in text only.
📚 Table of Contents
| Guide | Description | Target Audience |
|---|---|---|
| 1. Quick Start | Set up a talking NPC in a new project | New Developers |
| 2. Installation & Requirements | Hardware requirements, Unity version, and project settings | Technical Leads & IT |
| 3. Personality Writing Guide | System prompt craft, few-shot examples, and token constraints | Writers & Game Designers |
| 4. Choosing a Model Preset | Compare the Balanced (1.5B, default) and Fast (0.5B, low-end PCs) tiers | Producers & Designers |
| 5. API Reference | Comprehensive public C# contracts and code samples | Programmers |
| 6. Performance Tuning | CPU thread allocation, context windows, and latency budgets | Optimization Engineers |
| 7. Lip Sync Setup | A jaw that opens with the loudness of the voice, and blendshape mapping with an ARKit preset for viseme weights from your own code or the optional uLipSync bridge (not yet tested on a real character) | Technical Artists |
| 8. Shipping Your Game | Build pipeline, standalone Windows, and player deployment | Build Engineers |
| 9. Offline & Kiosk Deployment | Pre-bundled StreamingAssets, air-gapped systems, and kiosk microphone setup (Push-to-Talk planned for v1.1) | Enterprise & Exhibits |
| 10. Language Support | Multilingual architecture seam and custom phonemizers | Localization Teams |
| 11. Troubleshooting | Diagnostic solutions for common audio, model, and DLL issues | All Developers |
Support: email localnpcsupport@gmail.com (what to include: Getting help).
âš¡ Architecture Pipeline in One Line
Microphone → VAD (energy; the downloaded voice activity model is not used) → Speech-to-Text (Whisper) → LLM (Qwen 2.5) → Sentence Splitter → TTS (Windows system voice) → Audio Queue (+ optional jaw by loudness)The core streaming innovation: each sentence begins synthesizing and speaking out loud while the language model is still generating subsequent tokens. Reply time: Typically about 3 seconds after you stop talking: a 0.9 second end-of-speech wait plus about 2 seconds (measured 2.04 to 2.25 s on one laptop, Balanced preset, five voice turns). It depends on your hardware, and we have not measured other machines yet.