Spawn NPCs in Garry's Mod that you can actually talk to. Supports multiple AI providers including genuinely free options — Groq, OpenRouter free models, OpenAI, DeepSeek, and self-hosted Ollama.
- Free tier actually works — no more dead hardcoded API key. First launch walks you through getting a free key from Groq or OpenRouter in about 30 seconds.
- Press E to talk to an NPC instead of typing
/sayevery time. You can also just speak in chat when you're near an NPC and it'll respond automatically. - 3D nametag above every AI NPC with a live "thinking…" indicator while it waits for a reply.
- Live OpenRouter free-model list — the addon fetches the current free models daily so you don't have to update it when the free lineup rotates.
- Proper multiplayer safety: admin gate, per-player NPC cap, spawn/chat cooldowns, and API keys never appear in chat errors.
- Fixed the crashes people were hitting (
pairs(nil),attempt to index nil, silent/sayfailures). - Rewritten Ollama support that actually honours
max_tokensandtemperature. - Added DeepSeek provider.
- Subscribe to the addon on the Steam Workshop.
- Launch Garry's Mod in a sandbox game.
- Press C to open the context menu.
- Click the AI NPCs icon on the right-hand side of the C menu.
- On first launch, you'll get a welcome popup — click the "Get free Groq key" button, create an account (no credit card required), copy your key back into the panel, and hit Spawn NPC.
- Walk up to the NPC and press E to open a chat window.
| Provider | Free? | Region blocks | Get a key |
|---|---|---|---|
| Groq | Yes — daily rate limit on free tier, no credit card required | None known | https://console.groq.com/keys |
| OpenRouter | Many :free models available, ~50 req/day without credits, ~1000/day with a one-time $10 top-up |
None known | https://openrouter.ai/keys |
| OpenAI | Paid only (~$5 minimum top-up) | Russia, China, Iran, others | https://platform.openai.com/api-keys |
| DeepSeek | Paid only (very cheap, ~$0.14/M tokens) | None known | https://platform.deepseek.com/api_keys |
| Ollama | Completely free (runs on your own computer) | N/A — self-hosted | https://ollama.com/download |
TL;DR for free use: pick Groq. For more model variety, pick OpenRouter. For total privacy, pick Ollama and point it at your own machine.
- Open C menu → AI NPCs.
- Pick a provider from the dropdown (Groq is the default).
- Click the Get free key → button to open the right signup page.
- Paste your key into the API Key field.
- Fill in Character description — e.g. "A grumpy Russian bartender who hates everyone but has a soft spot for cats".
- Optionally give the NPC a name.
- Pick the NPC class you want them to look like (citizen, combine, zombie, whatever).
- Click Spawn NPC.
- Walk up to the NPC and press E, or just type in regular chat when you're within ~250 units. You can also use
/say <message>from anywhere.
All of these are FCVAR_ARCHIVE so they persist across restarts.
| Convar | Default | Description |
|---|---|---|
ainpc_enabled |
1 | Master kill switch |
ainpc_admin_only |
0 | If 1, only admins can spawn AI NPCs |
ainpc_max_per_player |
3 | Max concurrent AI NPCs per player |
ainpc_cooldown_seconds |
5 | Cooldown between spawns per player |
ainpc_chat_cooldown_seconds |
1.5 | Cooldown between chat requests per player |
ainpc_proximity_chat |
1 | If 1, chat in range auto-routes to the nearest NPC |
ainpc_proximity_range |
250 | Distance for proximity chat routing |
ainpc_interact_range |
140 | Distance for press-E-to-talk |
ainpc_tts_allowed |
1 | Allow clients to enable TTS |
ainpc_openrouter_autorefresh |
1 | Auto-fetch OpenRouter free models daily |
If you're not using the Workshop:
- Clone this repo.
- Rename the folder to
ai-npcs(optional, but nicer). - Move it into your Garry's Mod
garrysmod/addons/folder. - Restart Garry's Mod.
"No AI NPC nearby" — You need to spawn one first. Press C → AI NPCs.
"API key required" — The free API button isn't a magic hardcoded key any more (the old one was long-dead and fake). You need to sign up for an actual free key. Click the big "Get free key" button in the panel.
NPC says "... can't respond right now: HTTP error 401" — Your API key is wrong or expired. Paste it again, or generate a new one from the provider's dashboard.
NPC says "... can't respond right now: HTTP error 429" — You're rate-limited. Wait a bit or top up credits.
I'm in Russia / Iran / a region blocked by OpenAI — Use Groq or OpenRouter instead. Neither is region-blocked in any country we know of.
I want an uncensored NPC for RP — Use OpenRouter and pick the Venice Uncensored model from the dropdown, or run Ollama locally with an uncensored model like dolphin-mixtral.
Pressing E doesn't open the chat window — Make sure you're within ~140 units of the NPC and that it has the golden nametag above its head (if not, it's a regular NPC, not an AI one).
PRs welcome. If you find a bug, file an issue at github.com/SonnyTaylor/AI-NPCs-GMod with the exact error message (including stack trace if there is one).
MIT.