Half-Life 2 AI NPC Mod: Voice-Commanded Squads and Companions

Half-Life 2 gave modders the best squad AI of its era and a world full of people who only ever say what the script allows. A Half-Life 2 AI NPC mod changes that: rebels that react to your orders out loud, a companion who talks about what just happened, and story scenes that bend to the player's choices. Neocortex adds the AI characters, Conversation Flows, quizzes and on-device voice commands; Source SDK 2013 gives you the code to wire them in.

Screenshot: Half-Life 2 © Valve

What you could build with Neocortex in Half-Life 2

A rebel squad you command by voice

Half-Life 2 already lets you send your squad to a point and call them back. Voice commands replace the key press with speech: "move up", "hold here", "take cover behind the car", "regroup on me". In the Neocortex dashboard you design the command set as actors, actions and objects: actor "squad", actions "move", "hold" and "cover", objects such as "me", "car" and "door". Players speak naturally, and the mod receives matched commands instantly, including several actions and quantities in one sentence: "two of you watch the door, the rest follow me". It works with push-to-talk or always-listening, in multiple languages, and runs on the player's machine, so orders land mid-firefight without a cloud round trip. Voice Commands is a licensed SDK: contact us for a Voice Commands license.

A companion who talks about the situation

Create an original companion, say Mara Venn, a former field medic who joined the resistance after her clinic was shut down. Your mod sends the player's question along with what the game knows: nearby objects (the barricade, the ammo crate, the radio) and recent events ("two squad members down", "the player took the left tunnel", "health below 30"). Mara answers in voice with an emotion tag on every line, and can return actions such as handing over a medkit or opening the gate the player asked about. Group chat (Pro and Team plans) lets up to six characters share one conversation, so the whole squad can argue about the next move.

A resistance safehouse scene with a Conversation Flow

Picture a cellar safehouse where the player has to earn the trust of a wary cell leader before they share the route out of the city. A Conversation Flow defines the beats: introductions, proving whose side you are on, the deal, the route. The character steers the conversation through them however the player phrases things, and the API returns checkpoint keywords such as TRUST_EARNED or ROUTE_SHARED. Your mod reacts by opening the hidden door or spawning the guide who leads you out.

A quiz terminal

Put a terminal in the safehouse that drills new recruits: which enemy units to avoid, how to signal the squad, what supplies to carry. The Neocortex quiz engine (Team plan) runs the questions and scoring, and a correct streak can reward the player with ammo or a shortcut.

How Half-Life 2 modding works

Half-Life 2 runs on Source. A mod is a folder with its own gameinfo.txt, content, and two C++ libraries built from Valve's code: a server DLL for NPC AI, squads and game logic, and a client DLL for the HUD, VGUI panels and local effects.

• Source SDK 2013 is Valve's official code on GitHub. The master branch is the multiplayer code, updated in February 2025 with the Team Fortress 2 game code and 64-bit builds, and Valve still commits to it. The singleplayer branch holds the Half-Life 2 singleplayer code, which has not had a code update since 2015 and runs on the 32-bit Source SDK Base 2013 Singleplayer.
• Mapbase is a community-maintained base for singleplayer mods. Version 8.0 shipped in July 2025 and adds new entities, fixes and a VScript implementation for map scripting.

The SDK headers include the Steamworks HTTP interface, and many modders add libcurl instead. Either way, run requests on a worker thread and pass results back to the game loop. For UI, VGUI panels in the client DLL can show subtitles and a quiz screen. Source's closed captions and soundscripts are built for pre-authored lines, so live AI replies usually get their own subtitle panel, with the generated audio saved to a file and played through the engine.

Screenshot: Half-Life 2 © Valve

How Neocortex fits in

• Dialogue. The mod reads game state and sends it with the player's message to a Neocortex character through /v3/chat. It shows the reply as subtitles, plays the voice from /v3/audio/generate or /v3/audio/stream, and runs the actions the character returns.
• Conversation Flows. They steer story beats, like the safehouse scene, and return checkpoint keywords (flowState) the mod reacts to.
• Quizzes. The quiz engine runs question-and-answer games through /v3/quiz.
• Voice commands. On-device voice commands turn spoken phrases into game actions without a cloud round trip. The mod uses the Neocortex Voice Commands library on the player's machine.

A chat call from the client or server DLL, using libcurl, looks like this:

// bodyJson: {"characterIds":["CHARACTER_ID"],"message":"Where now?","playerId":"player-1",
//            "sessionId":"","events":[{"priority":1,"content":"Two squad members down"}]}
std::string AskCompanion(const std::string& apiKey, const std::string& bodyJson)
{
    std::string response;
    CURL* curl = curl_easy_init();
    curl_slist* headers = curl_slist_append(nullptr, "Content-Type: application/json");
    headers = curl_slist_append(headers, ("x-api-key: " + apiKey).c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.neocortex.link/v3/chat");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, bodyJson.c_str());
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, AppendToString); // appends bytes to response
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return response; // sessionId, lines with emotions, actions and flowState
}

Getting started with your Half-Life 2 AI NPC mod

1. Set up Source SDK 2013. Pick the singleplayer branch or Mapbase for a story mod, build it, and launch an empty test map.
2. Design your characters in the Neocortex dashboard: a companion, a cell leader with a Conversation Flow, a quiz for the terminal and a command set for the squad.
3. Call the API from your game DLL on a worker thread and reuse the sessionId from each reply.
4. Keep the API key in a config file the player fills in, never hard-coded in a mod you share.
5. Hook up subtitles, voice and actions, then map voice commands onto the existing squad code.
6. Test in single-player on one map before scaling up to a full campaign.

Mod policy and fair play

The Source 1 SDK license lets you distribute mods only for free; free mods can be published on Steam. Keep AI NPC mods single-player, never use them on multiplayer servers against their rules, and have each player use their own Neocortex API key.

To see how voice commands work in a mod, read on-device voice commands for game mods. For GoldSrc, see our Half-Life AI NPC mod guide, and for Source sandbox servers, the Garry's Mod AI NPC and quiz addon post.

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

Frequently Asked Questions