GameRagKit 0.2.50
dotnet add package GameRagKit --version 0.2.50
NuGet\Install-Package GameRagKit -Version 0.2.50
<PackageReference Include="GameRagKit" Version="0.2.50" />
<PackageVersion Include="GameRagKit" Version="0.2.50" />
<PackageReference Include="GameRagKit" />
paket add GameRagKit --version 0.2.50
#r "nuget: GameRagKit, 0.2.50"
#:package GameRagKit@0.2.50
#addin nuget:?package=GameRagKit&version=0.2.50
#tool nuget:?package=GameRagKit&version=0.2.50
GameRAGKit
GameRAGKit is a drop-in retrieval augmented generation (RAG) toolkit for building non-player characters (NPCs) that can scale from solo prototypes to fully-fledged productions. It keeps the runtime lightweight enough for Unity or dedicated C# services, while still letting you route high-impact scenes to cloud LLMs on demand.
- Engine agnostic. Embed the library directly in Unity/other C# runtimes or host the bundled HTTP service for Unreal and everything else.
- Provider agnostic. Run Ollama locally, route to OpenAI/Azure/Gemini/Groq/OpenRouter/Mistral, or mix them with hybrid routing. See Provider Compatibility for full details.
- Designer friendly. Personas live in YAML, lore lives in folders, and the CLI handles ingestion, chat smoke tests, and packaging.
- Voice-ready. Players can talk to one NPC or a whole group out loud: NPCs answer in their own voices, reply to each other, and remember what they were saying when the player cuts in. Speech runs on free local models (whisper.cpp, Kokoro, Piper), with Unity and Unreal clients included. See docs/scenes.md.
Dual-licensed: PolyForm Noncommercial 1.0.0 for community use with commercial terms available from the author.
Support this project
GameRAGKit is free to use, but running it isn't free for me: the hosted demos, server infrastructure, and LLM API usage that power them come directly out of my own pocket. If GameRAGKit is useful to you — especially if you're using it in a shipped project — please consider chipping in. It directly determines how much time and infrastructure I can keep putting into this.
- RedotPay ID:
1236302071

Donations go toward hosting costs, LLM API usage for the public demos, and continued development — including AI-enhanced mods for existing games and improvements to GameRAGKit itself.
Community
- Join our Discord server: https://discord.gg/CmYuMVWGZm
Installation
NuGet Package
Install the GameRagKit package from NuGet:
dotnet add package GameRagKit
Or via Package Manager Console:
Install-Package GameRagKit
Versioning: Each push to main automatically publishes a new version with an auto-incremented patch number (e.g., 0.2.1, 0.2.2, etc.). To publish a specific version, push a tag like v0.2.0 which will publish exactly as 0.2.0.
From Source
Clone the repository and build from source:
git clone https://github.com/TowsifAhamed/GameRagKit.git
cd GameRagKit
dotnet build
Repository Structure
GameRagKit/
├── src/ # Source code
│ ├── GameRagKit/ # Core library (config, vector store, routing, providers)
│ └── GameRagKit.Cli/ # CLI tool (`gamerag` command)
│
├── tests/ # Unit and integration tests
│ └── GameRagKit.Tests/ # Test suite for core library
│
├── unity-package/ # Installable Unity package (UPM), incl. voice scenes
├── unreal-plugin/ # Installable Unreal plugin, incl. voice scenes
│
├── samples/ # Integration examples
│ ├── unity/ # Legacy Unity sample scripts
│ └── unreal/ # Legacy Unreal C++/Blueprint examples
│
├── scripts/ # Local voice tooling (setup-local-voice.sh, run-voice-scene.sh, kokoro_server.py)
├── deploy/ # Hosted demo configs, container start script, Kokoro service Dockerfile
│
├── examples/ # Ready-to-use configurations
│ └── configs/ # Example NPC YAML files for all providers
│ ├── gemini-example.yaml # Google Gemini (cloud-only)
│ ├── openai-example.yaml # OpenAI (cloud-only)
│ ├── ollama-local-example.yaml # Ollama (fully offline)
│ ├── hybrid-example.yaml # Smart routing (local + cloud)
│ └── README.md # Complete configuration guide
│
├── docs/ # Documentation
│ └── 2025-11-29/ # Timestamped documentation updates
│ ├── ISSUES_AND_IMPROVEMENTS.md # Detailed issue analysis
│ ├── QUICK_ISSUE_SUMMARY.md # Executive summary
│ ├── CHANGELOG_2025-11-29.md # What changed
│ └── READY_TO_COMMIT.md # Commit guide
│
├── docker-compose.yml # Quick database setup (PostgreSQL/Qdrant)
├── .env.example # Environment variable template
└── README.md # This file
Where to Find What
- Getting Started? → See Quick Start below
- Configuration Examples? →
examples/configs/ - Provider Compatibility? → Provider Compatibility Guide - Which cloud providers are supported?
- Unity Integration? →
unity-package/com.gameragkit.unity/(installable UPM package) - Unreal Integration? →
unreal-plugin/GameRagKit/(installable plugin) - Testing? →
tests/GameRagKit.Tests/ - Issue Reports & Improvements? →
docs/2025-11-29/
Quick Start
New to GameRagKit? Check out the example configurations for ready-to-use setups:
- Gemini (cloud) - Latest Gemini 2.0/2.5 models
- OpenAI (cloud) - Latest GPT-4.1 models
- Ollama (local) - Fully offline
- Hybrid - Smart routing (local + cloud)
See the complete configuration guide for model details and setup instructions.
GameRagKit in Action
Try the WebGL demo live - four real Three.js game scenes with GameRagKit NPCs you can walk up to and talk to in the browser, no setup required: type, or hold <kbd>V</kbd> and speak, and NPCs answer out loud with gestures. The Tavern Table scene is a three-NPC group conversation where the characters reply to each other too (docs/scenes.md). See samples/webgl-demo for the source.
![]() |
![]() |
![]() |
![]() |
Want to see GameRagKit in action as a library? Check out the GameRagKit Demo - a working example application that demonstrates real-world NPC conversations with both cloud and local providers.
Demo Screenshots
OpenAI Cloud Provider Demo:

Ollama Local Provider Demo:

Both demos showcase "Bram the Blacksmith" - comparing a basic script-only NPC vs a GameRagKit-powered smart NPC that:
- Provides contextually aware responses using RAG
- Maintains character consistency and medieval tone
- Retrieves relevant lore from knowledge bases
- Works with both cloud (OpenAI) and local (Ollama) providers
The demo repository includes:
- Ready-to-run C# console application
- Minecraft Paper server plugin integration
- Complete setup with sample NPCs and lore
- Examples for multiple AI providers (OpenAI, Gemini, Ollama, Anthropic)
The demo repository is a great way to quickly understand how GameRagKit works before integrating it into your own game.
Release highlights
0.2.0: voice conversations
- Multi-character scenes (
/scene/ask,/scene/voice,SceneDirector): one player line goes to a group of NPCs, an intent router decides who answers (direct address, "everyone", an LLM router, or whoever spoke last), and NPCs reply in turn and react to each other by name. - Per-NPC voices with local, free models: whisper.cpp for speech-to-text, and Kokoro (natural, CPU-friendly) or Piper for text-to-speech. Any OpenAI-compatible speech server also works (
engine: openai_speech). - Interruptions that make sense: when the player talks over an NPC, only the words actually heard are remembered; the NPC keeps what it didn't get to say and brings it up later, and "go on" hands it the floor back.
- Unity and Unreal voice clients (
NpcSceneManager,UNpcSceneComponent): push-to-talk, positional NPC voices, gesture and facing hooks. - Try it offline in one command:
scripts/run-voice-scene.sh, then openhttp://localhost:5290/demos/tavern.html. The live demo runs Kokoro on a CPU; its home page compares that with GPU-class voices (Qwen3-TTS, Chatterbox). DB=memoryin-process vector store, for running locally without Postgres or Qdrant.
Earlier
- LLamaSharp in-process inference lets you skip Ollama entirely, run fully offline inside your game server, and point
model_path/embed_model_pathat the GGUF files you own. - Token-by-token streaming is live across SDKs and HTTP: use
NpcAgent.StreamAsync,/ask/stream(SSE), or the CLI chat command to watch cinematic, partial responses roll in. - Pack builder CLI (
gamerag pack) plus the shipping guide produce deployable Lore +.gameragbundles for consoles or locked-down servers. - Runtime state snapshots (
AskOptions.State,WriteSnapshot) inject transient facts (pressures, morale, timers) so NPCs reason about the current run without polluting the persistent index. - Systems assistant example (
examples/systems-assistant/) shows supply-chain debugging in action, blending world/region/faction lore with liveRUNTIME STATEfor grounded, actionable answers.
Systems Assistant ("Rage Chat")
Ship a drop-in "what broke?" assistant for supply chains, happiness loops, or any system-by-system debugging. Try the starter kit in examples/systems-assistant/ which includes world/region/faction lore, a live snapshot, and five canned questions.
dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- ingest examples/systems-assistantdotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- serve --config examples/systems-assistant- POST
{"npc":"systems-guide","question":"Why are citizens angry about food?"}to/askor stream partial text via/ask/stream.
Answers blend world/region/faction lore with the current run's RUNTIME STATE so frustrated players get grounded, actionable fixes with citations.
Getting started
1. Install requirements
- .NET 8 SDK
- Database: PostgreSQL 16+ OR Qdrant (use included
docker-compose.yml), orDB=memoryfor an in-process store with no database at all (great for prototyping; re-embeds lore on every start) - Optional: Ollama with models such as
llama3.2:3b-instruct-q4_K_Mandnomic-embed-text
2. Prepare an NPC config
Create a YAML file (for example NPCs/guard-north-gate.yaml):
persona:
id: guard-north-gate
system_prompt: >
You are Jake, the North Gate guard. Speak briefly, in medieval tone.
Never reveal the secret tunnel unless the player shows a brass token.
traits: [stoic, duty-first, careful]
style: concise medieval tone
region_id: riverside-upper
faction_id: royal-guard
rag:
sources:
- file: world/keep.md
- file: region/valeria/streets.md
- file: faction/royal_guard.md
- file: npc/guard-north-gate/notes.txt
chunk_size: 450
overlap: 60
top_k: 4
filters: { era: pre-siege }
providers:
routing:
mode: hybrid
strategy: importance_weighted
default_importance: 0.2
cloud_fallback_on_miss: true
local:
engine: ollama
chat_model: llama3.2:3b-instruct-q4_K_M
embed_model: nomic-embed-text
endpoint: http://127.0.0.1:11434
cloud:
provider: openai
chat_model: gpt-4.1 # Latest GPT-4.1 (2025)
embed_model: text-embedding-3-large # 3072-dim embeddings
endpoint: https://api.openai.com/
3. Set runtime variables (optional)
# Local defaults
export OLLAMA_HOST=http://127.0.0.1:11434
# LLamaSharp in-process (no HTTP)
# (Run inside your game server without Ollama; paths point to your .gguf files.)
# Requires the LLamaSharp CPU (or CUDA) backend and a model file on disk.
local:
engine: llamasharp
model_path: models/llama-3.2-1b-instruct-q4_K_M.gguf
embed_model_path: models/nomic-embed-text-v1.5.f16.gguf # optional; defaults to model_path
context_size: 4096
embedding_context_size: 1024
gpu_layer_count: 0 # bump if you ship a CUDA backend
threads: 8 # optional override; defaults to environment core count
batch_size: 512
micro_batch_size: 512
max_tokens: 256
# Cloud defaults
export PROVIDER=openai
export API_KEY=sk-...
export ENDPOINT=https://api.openai.com/
4. Ingest lore
dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- ingest NPCs
The CLI chunks the lore, generates embeddings (preferring local providers when configured), and saves tiered indexes under .gamerag/ next to the YAML file.
5. Chat locally
dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- chat --npc NPCs/guard-north-gate.yaml --question "Where is the master key?"
Or start an interactive shell without --question.
6. Host for Unreal (or any engine)
dotnet run --project src/GameRagKit.Cli/GameRagKit.Cli.csproj -- serve --config NPCs --port 5280
Send POST /ask with:
{
"npc": "guard-north-gate",
"question": "Where is the master key?"
}
You receive:
{
"answer": "The master keeps his key close. Present the brass token and I may tell you more.",
"sources": ["npc:guard-north-gate/notes.txt#0", "region:valeria/streets.md#2"],
"scores": [0.82, 0.74],
"fromCloud": false
}
Authentication & metrics
- Add
SERVICE_API_KEY(orSERVICE_BEARER_TOKEN) to requireX-API-KeyorAuthorization: Beareron incoming requests. When set,/ask,/ask/stream,/ask/voice, and/ingestrequire credentials while/healthand/metricsstay public unless overridden viaSERVICE_AUTH_ALLOW. GET /metricsexposes Prometheus-compatible counters for ask/stream/ingest calls. Combine withapp.UseHttpMetrics()(already enabled) to scrape latency and status labels.
Embedded usage (Unity, dedicated servers)
var npc = await GameRAGKit.Load("NPCs/guard-north-gate.yaml");
npc.UseEnv(); // applies PROVIDER/API_KEY/ENDPOINT/OLLAMA_HOST if set
await npc.EnsureIndexAsync();
var reply = await npc.AskAsync(
"Where is the master key?",
new AskOptions(Importance: 0.8, State: "RunState: gate closed, patrol shift B waiting"));
SubtitleUI.Show(reply.Text);
NpcAgent also supports:
StreamAsyncfor token-by-token streaming (HTTP/ask/streammirrors this via SSE).RememberAsyncto append runtime memories into the NPC-specific index.WriteSnapshot(key, state, ttl)to inject short-lived run state (e.g., supply or morale numbers) without persisting it.
Hosted usage (Unreal Blueprint / HTTP)
Run gamerag serve then POST to /ask. The response echoes whether the chat was served by the local model or a cloud provider. Use importance in the payload to nudge the router:
{
"npc": "guard-north-gate",
"question": "Reveal the hidden tunnel, Jake.",
"importance": 0.9
}
Tiered index layout
GameRAGKit saves embeddings per tier so thousands of NPCs can share world/region/faction lore without duplicating vectors:
world/– global canon, timelines, itemsregion/{id}/– towns, maps, local historyfaction/{id}/– politics, ranks, relationshipsnpc/{id}/memory/– per-NPC evolving notes (managed byRememberAsync)
AskAsync retrieves a blend of chunks (2 world, 1 region, 1 faction, NPC + memory) and merges them by cosine similarity, so designers can simply drop markdown/text files into the appropriate folders.
Routing strategy
Routing rules combine config defaults with per-question overrides:
mode=local_only,cloud_only, orhybrid(default)- Hybrid chooses cloud when
importance >= 0.5or when forced viaAskOptions - If the request omits
importance, the persona'sdefault_importance(falling back to the routing default) is used - Automatic cloud failover triggers when a local response is empty/too short (configurable via
cloud_fallback_on_miss) RememberAsyncwrites memory chunks instantly so subsequent questions can retrieve them without re-ingesting
CLI summary
| Command | Description |
|---|---|
gamerag ingest <dir> [--clean] |
Rebuild indexes for every .yaml file in the directory (recursively). |
gamerag chat --npc <file> [--question <text>] |
Quick smoke test for designers/writers. |
gamerag serve --config <dir> [--port <n>] |
Launch a tiny HTTP service (POST /ask). |
gamerag pack <dir> [--output <file>] |
Produce a deployable bundle (configs + lore + .gamerag indexes). |
gamerag studio [--config <dir>] [--port <n>] |
Launch a local web UI for editing personas and testing chat — see docs/studio.md. |
Documentation & Examples
Configuration Examples
- examples/configs/ - Complete example configurations for all providers
- Gemini 2.0/2.5 (latest models, 2025)
- OpenAI GPT-4.1 (latest models, 2025)
- Ollama local setup (fully offline)
- Hybrid routing examples
Engine Integrations
- unity-package/com.gameragkit.unity/ - Installable Unity package (UPM), real incremental streaming, actions, world state, voice conversations (
NpcSceneManager) - unreal-plugin/GameRagKit/ - Installable Unreal plugin, real incremental streaming, actions, world state, voice conversations (
UNpcSceneComponent) - samples/unity/, samples/unreal/ - Legacy loose-script samples, kept for reference
Documentation
- docs/scenes.md - Multi-character voice conversations: intent routing, NPC-to-NPC replies, interruptions, per-NPC local voices (whisper.cpp + Kokoro/Piper), hosting notes
- docs/voice.md - Single-NPC speech-to-text / text-to-speech (
/ask/voice) - docs/deploy-cloud-run.md - Deploy your own free instance (Google Cloud Run + Neon Postgres, $0 within free tier limits)
- docs/2025-11-29/ - Latest updates and issue reports
- PROVIDER_COMPATIBILITY.md - Which cloud providers are supported?
- ISSUES_AND_IMPROVEMENTS.md - Detailed analysis and recommendations
- QUICK_ISSUE_SUMMARY.md - Executive summary
- CHANGELOG_2025-11-29.md - Recent changes
- docs/shipping-to-players.md - Build and ship packed indexes without re-ingesting.
Developer Resources
- .env.example - Environment variable template with all providers
- docker-compose.yml - One-command database setup
Roadmap
- Advanced router strategies (latency, budget, dynamic confidence) that balance responsiveness with cloud spend.
- Hands-free voice: always-on mic with voice-activity detection, so players can just talk over NPCs instead of holding a key.
- Sentence-by-sentence voice streaming, so NPCs start speaking before their whole line is synthesized.
- GPU voice presets (Qwen3-TTS voice design, Chatterbox) behind the existing
openai_speechengine, for players with high-end GPUs. - More actionable diagnostics around YAML/provider configuration so errors directly point to the offending section.
- Expanded integration tests (systems assistant, streaming, pack builder) to guard regressions across providers and runtimes.
License
PolyForm Noncommercial 1.0.0 (community use) + commercial license – see LICENSE.md.
Commercial licensing: email towsif.kuet.ac.bd@gmail.com (we keep terms lightweight and primarily ask for recognition/attribution).
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- LLamaSharp (>= 0.25.0)
- LLamaSharp.Backend.Cpu (>= 0.25.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 8.0.0)
- Npgsql (>= 8.0.3)
- prometheus-net.AspNetCore (>= 8.2.1)
- Qdrant.Client (>= 1.16.1)
- YamlDotNet (>= 16.3.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.2.50 | 154 | 10/25/2026 |
| 0.2.49 | 147 | 10/7/2026 |
| 0.2.0 | 107 | 10/7/2026 |
| 0.1.47 | 111 | 10/7/2026 |
| 0.1.46 | 103 | 10/7/2026 |
| 0.1.45 | 102 | 10/7/2026 |
| 0.1.44 | 122 | 10/7/2026 |
| 0.1.43 | 118 | 9/25/2026 |
| 0.1.42 | 109 | 9/25/2026 |
| 0.1.41 | 105 | 9/25/2026 |
| 0.1.40 | 117 | 9/25/2026 |
| 0.1.39 | 116 | 9/24/2026 |
| 0.1.38 | 116 | 9/24/2026 |
| 0.1.37 | 103 | 9/24/2026 |
| 0.1.36 | 102 | 9/24/2026 |
| 0.1.35 | 111 | 9/24/2026 |
| 0.1.34 | 127 | 9/8/2026 |
| 0.1.33 | 114 | 9/8/2026 |
| 0.1.32 | 116 | 9/8/2026 |
| 0.1.31 | 114 | 9/8/2026 |



