Garry's Mod AI NPC Addon: Smart NPCs and a Quiz Show Host

A Garry's Mod AI NPC addon is a Lua addon that sends what players say to an AI character through the game's built-in HTTP() function and acts on the reply. Garry's Mod servers live on the stuff players invent, and NPCs that only stand there are a wasted opportunity. With Neocortex, sandbox and roleplay servers get characters that actually talk: a shopkeeper who haggles, a quiz show host who runs a game for the whole server, and helpers that follow voice commands. Neocortex adds the AI characters, Conversation Flows, the quiz engine and on-device voice commands; Lua connects them to your server.

Screenshot: Garry's Mod © Valve

What runs on the server and what runs on the client

Garry's Mod addons are folders of Lua scripts and content, installed in garrysmod/addons or subscribed through the Steam Workshop. Lua runs in two realms, and an AI NPC addon splits cleanly between them. The Garry's Mod wiki documents every function.

A few details matter. HTTP() launches an asynchronous request with a URL, method, headers, body and callbacks, and http.Fetch and http.Post wrap it for simple cases; the success callback also fires for error status codes, so always check the code. sound.PlayURL plays external sound files, so serve the generated voice from a small endpoint you control and clients can stream it without ever seeing the API key. Native modules (gmsv_ for the server, gmcl_ for the client) go in garrysmod/lua/bin and load with require, but they cannot be installed through a Workshop addon, so anything native is a separate install for players or server owners.

Roleplay NPCs that talk back

On a roleplay server, give the city a cast: a shopkeeper who haggles and remembers who stiffed him, a bartender who knows the server's lore, a police dispatcher who reacts to what players report. Each character gets a Personality, an Emotion setting and a Knowledge base in the Neocortex editor, such as your server rules, the map's locations and your economy.

Players press use on the NPC and type in chat. Your addon sends the message along with nearby objects (the shop counter, the vending machine, the jail door) and recent events ("a player was arrested", "the bank alarm is ringing"). The character replies with an emotion tag on every line and actions such as { "name": "OPEN_DOOR", "targetId": "jail_door" } that the addon runs on the server.

Group chat (Pro and Team plans) puts up to six characters in one conversation, so a gang of NPCs can argue with a player at once. A Conversation Flow can steer a longer scene, like a roleplay heist briefing, and return checkpoint keywords (flowState) the addon reacts to.

Running a quiz night

The quiz engine (Team plan) turns a stage, some buzzers and a scoreboard into a server event:

1. You build the question set in the Neocortex dashboard: a server trivia night, a lore quiz for new roleplayers, or a rules check that new players pass before they get a job.
2. A host NPC on the stage opens the round.
3. Players answer in chat, and the addon routes each answer to the quiz engine through /v3/quiz.
4. The host announces who is right, and the quiz engine handles scoring and the leaderboard.
5. Between rounds, your addon draws the standings on a HUD panel.

Screenshot: Garry's Mod © Valve

Helpers that follow voice commands

Give each player a helper NPC that listens: "follow me", "wait here", "guard the door", "bring two crates". In the Neocortex dashboard you design a command set as actors, actions and objects: actor "helper", actions "follow", "wait", "guard" and "bring", objects "me", "door" and "crate".

Players speak naturally, and the addon receives matched commands instantly, including several actions and quantities in one sentence. It works with push-to-talk or always-listening, in multiple languages, without a cloud round trip. Because it runs on the player's machine, the client side sends matched commands to the server.

Voice Commands is a licensed SDK: contact us for a Voice Commands license.

The Garry's Mod AI NPC addon code

Everything that touches the API runs server-side. The server reads game state and sends it with the player's message to a Neocortex character through /v3/chat, then shows the reply as subtitles, plays the voice from /v3/audio/generate or /v3/audio/stream, and runs the actions the character returns:

-- Server realm only: the key stays in garrysmod/data and never reaches players.
local apiKey = string.Trim(file.Read("neocortex_key.txt", "DATA") or "")
local function AskNPC(ply, text, sessionId, onReply)
    HTTP({
        url = "https://api.neocortex.link/v3/chat",
        method = "POST", type = "application/json",
        headers = { ["x-api-key"] = apiKey },
        body = util.TableToJSON({
            characterIds = { "CHARACTER_ID" },
            message = text,
            playerId = ply:SteamID64(),
            sessionId = sessionId or ""
        }),
        success = function(code, body)
            local data = util.JSONToTable(body)
            if code == 200 and data then onReply(data) end -- data.sessionId, data.messages
        end,
        failed = function(reason) print("[Neocortex] " .. reason) end
    })
end

House rules for AI NPCs

Garry's Mod servers set their own rules, so run AI NPC addons only on servers you own or where the owner agrees, and tell players they are talking to an AI. Follow the Steam Workshop rules when you publish, and make sure each server owner uses their own Neocortex API key. Add a per-player cooldown so one player cannot spam the NPC.

The bottom line for server owners

Five steps get you from an empty folder to a talking NPC:

1. Create an addon folder with a server-side Lua file and a spawnable NPC entity.
2. Design your characters in the Neocortex dashboard: a shopkeeper, a quiz host with a question set, and a command set for helpers.
3. Call /v3/chat and /v3/quiz from the server with HTTP(), and send replies to players with the net library.
4. Keep the API key in a server-side config file, never in client Lua or a Workshop upload.
5. Test on a local listen server with a friend before you run it on a public server.

Start with the shopkeeper. One character, one HTTP() call and a chat hook are enough to show your players what a Neocortex NPC can do, and the quiz show builds on the same server code. To learn how voice commands work on the player's machine, read on-device voice commands for game mods. For engine-level Source mods, see our Half-Life 2 AI NPC mod guide.

Tool versions and links checked October 2026. Modding tools change often; check each project's page for the latest release.

Frequently Asked Questions