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

Half-Life 2 has squad AI that listens to key presses, and a world full of people who only ever say what the script allows. The rebels follow you, but you cannot tell them anything; the citizens talk, but never about what just happened. A Half-Life 2 AI NPC mod fixes both: rebels that react to your orders out loud, a companion who talks about the fight you just survived, and story scenes that bend to the player's choices. Neocortex adds the AI characters, Conversation Flows, quizzes and on-device voice commands, and Source SDK 2013 gives you the code to wire them in.

Screenshot: Half-Life 2 © Valve

Voice orders for a rebel squad

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". Your code maps them onto the existing squad code.

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.

Worked example: Mara Venn and the safehouse

The companion. 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.

The squad argues back. Group chat (Pro and Team plans) lets up to six characters share one conversation, so the whole squad can argue about the next move.

The cellar. Mara leads the player to a cellar safehouse, where they have to earn the trust of a wary cell leader before he shares 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.

The terminal. In the corner, a terminal 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.

Screenshot: Half-Life 2 © Valve

Source SDK 2013 branches for a Half-Life 2 AI NPC mod

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. Pick the base before anything else:

For a story mod like the safehouse above, start from the singleplayer branch or Mapbase.

Calling Neocortex from a Source DLL

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. A chat call from the client or server DLL, using libcurl:

// 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
}

The mod reads game state and sends it with the player's message to a Neocortex character through /v3/chat, 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 return checkpoint keywords (flowState) in the same reply, the quiz engine runs through /v3/quiz, and on-device voice commands turn spoken phrases into game actions without a cloud round trip, with Neocortex Voice Commands running on the player's machine.

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.

Before you ship: the Source 1 SDK license

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.

From empty map to talking squad

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.

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. Mara and her squad can be tested in the Neocortex browser editor today, long before the first map compiles.

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

Frequently Asked Questions