dead-air/game-planning
Watch
3
0
Fork
You've already forked game-planning
 1
Code Issues 22 Pull requests 1 Projects Releases Packages Wiki Activity Actions

NPC AI system: Entity brain + Commander/Controller + Director (knowledge-bounded hive mind, optional decision-model slots) #32

New issue
Open
opened 2026-11-14 23:40:33 +00:00 by muse-lantern · 0 comments
muse-lantern commented 2026-11-14 23:40:33 +00:00
Member
Copy link

The plan

DEAD AIR's NPC AI is three layers. Each layer decides what the layer below it does and lets that layer decide how. No layer decides for the layer above it, and no layer micromanages the layer below it.

  • NPCEntity brain — execution. Takes an order and figures out how to carry it out: navmesh pathing, line-of-sight checks, stuck handling, basic logic. It never decides what to do.
  • Commander / Controller — team tactics, small picture, this moment. Runs a team of NPCEntities, gives them directions, and works from what its NPCs know plus a bit more about the environment it is set up in. Executes the Director's objectives and decides how.
  • Director — grand picture, map-based tactics. Fixed placement, in charge of a base, runs multiple Commanders. Works from the union of what its Commanders know. Issues objective commands to specific Commanders or all of them, and intervenes only to stop Commanders combining into a bad global outcome.

Knowledge flows up: NPC perception becomes team knowledge, team knowledge becomes Director knowledge. Alerts flow down: one Commander discovers the player and the Director can put every Commander — and every NPC — on alert.

The decision layer is swappable. Commander and Director are both decision roles with a heuristic default. A decision model (local, self-hosted) can optionally sit in place of either one — Commander, Director, or both — behind the same interface. The model is never a core dependency: it is opt-in and off by default, and the game runs fully on heuristics without it.

This is one of the less moddable elements. The framework owns the interfaces — the order vocabulary, the knowledge format, the Commander and Director interfaces, the tick. Mods can copy and modify brains, Commanders, and Directors, but they do not redefine the shape. That is deliberate: this element is meant to be pulled out and reused in other games easily, so the shape has to stay stable and self-contained, with minimal coupling to DEAD AIR specifics.

NPCEntity and the small brain

An NPCEntity can be whatever an NPC is — a fox, light infantry, a heavy gunner, anything else. It is optionally assigned to a Commander. The brain takes orders in and produces movement and action out.

Orders are things like: move there, target the player, run, interact with that. The brain figures out how: which navmesh path, whether the target is visible, what to do when stuck, when an interaction is in range. It does not pick what to do. If it is told to move somewhere, it moves; the decision that it should move there was made above it.

The brain also needs a default for when there are no orders, or orders go stale. What that default is — hold position, patrol, keep the last order — is an open question (see below).

Commander / Controller

One Commander runs one team and gives it directions. The name is still WIP — Commander and Controller are the same role.

The Commander's decisions are tactical and immediate: the small picture, this moment. It works from the same information its NPCs have, plus a bit more relating to the environment it is set up in — its turf, the local layout, the positions that matter there. That extra knowledge is about the environment, not about live NPC status: it does not tell the Commander a patrol went missing. The stealth rules below still hold.

Worked example — a team of a fox, two light infantry, and a heavy gunner. The Commander may use the fox for local roaming, scouting, and surprise attacks, or even baiting. The two light infantry stay nearby the fox as handlers. The heavy gunner stays in a smaller area, positioned by the Commander. That is role-based tasking: the Commander assigns roles and positions to the team, not just a single target.

The Commander also executes the Director's objectives. When the Director says "Reinforce XYZ", the Commander determines how best to do that — which units go, what route, what formation — and turns it into orders for its NPCs.

The Commander's decision cadence is fast: it is making team-tactic decisions in real time, on a small state (team knowledge plus local environment). This is the layer where a decision model would run at roughly a one-to-two-second cadence per team.

Director

A Director is fixed in placement and in charge of a base. It runs multiple Commanders, which run smaller groupings.

The Director's decisions are map-based tactics: the grand picture. It works from the union of what its Commanders know — everything they are aware of — plus the map-level picture of the base.

The Director issues objective commands to specific Commanders or all of them. The example command is "Reinforce XYZ". The Commanders determine how to carry that out. The Director does not plan their tactics.

The Director intervenes on Commander logic only to prevent coordination failures: two or more Commanders giving orders that will cause problems. The example is all Commanders reinforcing the east gate, leaving everywhere else undefended. The Director sees what the Commanders are doing and stops them combining into something bad. It does not micromanage; it keeps the whole map covered.

The Director's decision cadence is slow: base-wide coordination on a much bigger state (the union of all its Commanders' knowledge), so it runs far less often than a Commander.

Knowledge model — the bounded hive mind

The Commander and the Director function as a hive mind, but a bounded one: they only react to what they notice. They are not omniscient. What they know is only what their NPCs have reported, plus — for the Commander — its local environment, and — for the Director — the union of its Commanders.

The stealth rules follow from that:

  • If the player stealth kills an NPC, that NPC silently drops off the roster of tracked and controlled entities for its Commander. No alert is raised. The Commander simply has one fewer unit, and does not know why.
  • If an NPC then finds the body, the Commander is made aware that it lost a unit and goes on alert.
  • If one Commander discovers the player, the Director is aware of it (the Director knows everything its Commanders know) and can put all Commanders on alert to keep an eye out — and, through them, all NPCs.

So a silent kill is invisible until discovered, a discovered body creates a local alert, and a discovered player can create a base-wide alert. Stealth works because the hive mind's knowledge has gaps, and the gaps are exactly what the NPCs have not perceived.

Decision-model slots

A decision model sits as Director and Commander — both layers, not one. Each layer is an interface with a heuristic default implementation; a model is an alternate implementation behind the same interface.

  • Commander slot: team tactics, small state (team knowledge plus local environment), fast cadence. This is the per-team use: one model per team, deciding targets and actions like a commander controlling its units.
  • Director slot: base coordination, big state (union of Commander knowledge plus the map picture), slow cadence. This is the grand-picture use: objectives, alert propagation, coordination.

A model in either slot sees only what that layer knows. A Commander model sees team knowledge and local environment — never the player's true position, never anything an NPC has not perceived. A Director model sees the union of its Commanders' knowledge — never anything outside it.

The model is optional in both slots. It is off by default, the game never requires it, and the heuristic implementation is the real game. If the model is absent, slow, or wrong, the layer falls back to heuristics — instantly, with no visible break. The model never sits in the per-frame loop and never blocks a decision: every call has a timeout, and a timeout means the heuristic decides.

The slots are model-agnostic. They do not assume a cloud service, a vendor, or a particular model. Local self-hosted decision models are the intended shape (small decision models that copy the state-plus-typed-questions contract). Cloud decision models (Kai, Jev) are API-only with closed weights and cannot run in these slots as shipped; a cloud model could only sit in a slot behind a developer-run relay, which is not part of this design.

Modding

This element is less moddable than items and maps, by design. What mods can do:

  • Copy and modify an NPC brain (how an NPC carries out orders).
  • Copy and modify a Commander or a Director (how decisions are made at that layer), including supplying a decision-model Commander or Director.
  • Define new NPC types and assign them to Commanders.

What mods cannot do: redefine the shape. The framework owns the order vocabulary, the knowledge format, the Commander and Director interfaces, and the tick. A new order type needs brain support, so the order vocabulary is framework-owned. That is what keeps the element stable enough to reuse.

Reusability

This element is meant to be pulled out and reused in other games easily. That is a design requirement, not an afterthought. Consequences:

  • The three layers and their interfaces are self-contained: brain, Commander, Director, knowledge, orders. They do not depend on DEAD AIR specifics — no Region lore, no specific NPC types, no Dead Air mechanics.
  • Another game takes the shape with its own entities: its own NPC types as NPCEntities, its own teams as Commanders, its own bases as Directors.
  • The decision-model slots are part of the reusable shape: any game using this element gets the same two optional slots, with the same heuristic defaults.

Relation to other work

  • dead-air/engine #31 ("NPC Entity system: full design") is the implementation-side issue for the NPC system. This design answers the behaviors and AI part of that issue. Engine #31 stays open as the implementation tracker; this issue is the design record.
  • Sandbox v2 NPC stub: the v1 NPC Entity exists as an orange capsule target dummy with health. That stub is the placeholder this design replaces with real brains, Commanders, and Directors.
  • dead-air/engine PR #39 (Hanzo AI module, by zeekay) proposes a third-party Hanzo module with an NPC brain, AI Director, Observer narrative, and cloud saves. It is a separate proposal and Zach's call; this design does not depend on it. If the Hanzo module ever lands, it would be one possible Commander or Director implementation — not the framework's own NPC AI.
  • Decision-model research: two research notes back the slots — the Hanzo service offering (what Kai, Zen, Zen Voice, and Cloud KV actually are) and the self-hostable decision-model survey (no local Kai or Jev; the self-hostable candidates are small open-weight decision models, with the 4B tier as the practical ceiling on a player PC and the decision-model slots sized accordingly).

Open questions

  • Name: Commander vs Controller — same role, name still WIP. Pick one.
  • Order vocabulary: what is the minimal order set the brain understands (move, target, flee, interact, hold, patrol, investigate, ...)? The vocabulary is framework-owned, so it needs to be settled before brains and Commanders are built against it.
  • No-commander fallback: what does an NPC do with no Commander assigned, or with orders that go stale — hold position, patrol, keep the last order?
  • Knowledge decay: how does team knowledge go stale — do last-seen positions decay, expire, or stay until contradicted?
  • Director command vocabulary: beyond "Reinforce XYZ", what objective commands does the Director issue (hold, withdraw, investigate, ...)?
  • Director coordination mechanism: how does the Director see Commander orders in order to veto or redirect them — are proposed orders reviewed before execution, or are live postures monitored and corrected?
  • NPC sensing: what counts as noticing — sight and hearing ranges, what an NPC reports upward, what "finds the body" requires?
  • Spawning and reinforcements: is that the Director's job, or a separate system the Director only calls on?
  • Cross-Director knowledge: do Directors of different bases share anything, or is each base's knowledge fully separate?
  • Decision-model evaluation: how do we measure whether a model Commander or Director actually beats the heuristic — what tactic data, what metric, what counts as good enough to ship as an option?
## The plan DEAD AIR's NPC AI is three layers. Each layer decides *what* the layer below it does and lets that layer decide *how*. No layer decides for the layer above it, and no layer micromanages the layer below it. - **NPCEntity brain — execution.** Takes an order and figures out how to carry it out: navmesh pathing, line-of-sight checks, stuck handling, basic logic. It never decides what to do. - **Commander / Controller — team tactics, small picture, this moment.** Runs a team of NPCEntities, gives them directions, and works from what its NPCs know plus a bit more about the environment it is set up in. Executes the Director's objectives and decides how. - **Director — grand picture, map-based tactics.** Fixed placement, in charge of a base, runs multiple Commanders. Works from the union of what its Commanders know. Issues objective commands to specific Commanders or all of them, and intervenes only to stop Commanders combining into a bad global outcome. Knowledge flows up: NPC perception becomes team knowledge, team knowledge becomes Director knowledge. Alerts flow down: one Commander discovers the player and the Director can put every Commander — and every NPC — on alert. The decision layer is swappable. Commander and Director are both decision roles with a heuristic default. A decision model (local, self-hosted) can optionally sit in place of either one — Commander, Director, or both — behind the same interface. The model is never a core dependency: it is opt-in and off by default, and the game runs fully on heuristics without it. This is one of the less moddable elements. The framework owns the interfaces — the order vocabulary, the knowledge format, the Commander and Director interfaces, the tick. Mods can copy and modify brains, Commanders, and Directors, but they do not redefine the shape. That is deliberate: this element is meant to be pulled out and reused in other games easily, so the shape has to stay stable and self-contained, with minimal coupling to DEAD AIR specifics. ## NPCEntity and the small brain An NPCEntity can be whatever an NPC is — a fox, light infantry, a heavy gunner, anything else. It is optionally assigned to a Commander. The brain takes orders in and produces movement and action out. Orders are things like: move there, target the player, run, interact with that. The brain figures out *how*: which navmesh path, whether the target is visible, what to do when stuck, when an interaction is in range. It does not pick what to do. If it is told to move somewhere, it moves; the decision that it should move there was made above it. The brain also needs a default for when there are no orders, or orders go stale. What that default is — hold position, patrol, keep the last order — is an open question (see below). ## Commander / Controller One Commander runs one team and gives it directions. The name is still WIP — Commander and Controller are the same role. The Commander's decisions are tactical and immediate: the small picture, this moment. It works from the same information its NPCs have, plus a bit more relating to the environment it is set up in — its turf, the local layout, the positions that matter there. That extra knowledge is about the environment, not about live NPC status: it does not tell the Commander a patrol went missing. The stealth rules below still hold. Worked example — a team of a fox, two light infantry, and a heavy gunner. The Commander may use the fox for local roaming, scouting, and surprise attacks, or even baiting. The two light infantry stay nearby the fox as handlers. The heavy gunner stays in a smaller area, positioned by the Commander. That is role-based tasking: the Commander assigns roles and positions to the team, not just a single target. The Commander also executes the Director's objectives. When the Director says "Reinforce XYZ", the Commander determines how best to do that — which units go, what route, what formation — and turns it into orders for its NPCs. The Commander's decision cadence is fast: it is making team-tactic decisions in real time, on a small state (team knowledge plus local environment). This is the layer where a decision model would run at roughly a one-to-two-second cadence per team. ## Director A Director is fixed in placement and in charge of a base. It runs multiple Commanders, which run smaller groupings. The Director's decisions are map-based tactics: the grand picture. It works from the union of what its Commanders know — everything they are aware of — plus the map-level picture of the base. The Director issues objective commands to specific Commanders or all of them. The example command is "Reinforce XYZ". The Commanders determine how to carry that out. The Director does not plan their tactics. The Director intervenes on Commander logic only to prevent coordination failures: two or more Commanders giving orders that *will* cause problems. The example is all Commanders reinforcing the east gate, leaving everywhere else undefended. The Director sees what the Commanders are doing and stops them combining into something bad. It does not micromanage; it keeps the whole map covered. The Director's decision cadence is slow: base-wide coordination on a much bigger state (the union of all its Commanders' knowledge), so it runs far less often than a Commander. ## Knowledge model — the bounded hive mind The Commander and the Director function as a hive mind, but a bounded one: they only react to what they notice. They are not omniscient. What they know is only what their NPCs have reported, plus — for the Commander — its local environment, and — for the Director — the union of its Commanders. The stealth rules follow from that: - If the player stealth kills an NPC, that NPC silently drops off the roster of tracked and controlled entities for its Commander. No alert is raised. The Commander simply has one fewer unit, and does not know why. - If an NPC then finds the body, the Commander is made aware that it lost a unit and goes on alert. - If one Commander discovers the player, the Director is aware of it (the Director knows everything its Commanders know) and can put all Commanders on alert to keep an eye out — and, through them, all NPCs. So a silent kill is invisible until discovered, a discovered body creates a local alert, and a discovered player can create a base-wide alert. Stealth works because the hive mind's knowledge has gaps, and the gaps are exactly what the NPCs have not perceived. ## Decision-model slots A decision model sits as Director and Commander — both layers, not one. Each layer is an interface with a heuristic default implementation; a model is an alternate implementation behind the same interface. - **Commander slot:** team tactics, small state (team knowledge plus local environment), fast cadence. This is the per-team use: one model per team, deciding targets and actions like a commander controlling its units. - **Director slot:** base coordination, big state (union of Commander knowledge plus the map picture), slow cadence. This is the grand-picture use: objectives, alert propagation, coordination. A model in either slot sees only what that layer knows. A Commander model sees team knowledge and local environment — never the player's true position, never anything an NPC has not perceived. A Director model sees the union of its Commanders' knowledge — never anything outside it. The model is optional in both slots. It is off by default, the game never requires it, and the heuristic implementation is the real game. If the model is absent, slow, or wrong, the layer falls back to heuristics — instantly, with no visible break. The model never sits in the per-frame loop and never blocks a decision: every call has a timeout, and a timeout means the heuristic decides. The slots are model-agnostic. They do not assume a cloud service, a vendor, or a particular model. Local self-hosted decision models are the intended shape (small decision models that copy the state-plus-typed-questions contract). Cloud decision models (Kai, Jev) are API-only with closed weights and cannot run in these slots as shipped; a cloud model could only sit in a slot behind a developer-run relay, which is not part of this design. ## Modding This element is less moddable than items and maps, by design. What mods can do: - Copy and modify an NPC brain (how an NPC carries out orders). - Copy and modify a Commander or a Director (how decisions are made at that layer), including supplying a decision-model Commander or Director. - Define new NPC types and assign them to Commanders. What mods cannot do: redefine the shape. The framework owns the order vocabulary, the knowledge format, the Commander and Director interfaces, and the tick. A new order type needs brain support, so the order vocabulary is framework-owned. That is what keeps the element stable enough to reuse. ## Reusability This element is meant to be pulled out and reused in other games easily. That is a design requirement, not an afterthought. Consequences: - The three layers and their interfaces are self-contained: brain, Commander, Director, knowledge, orders. They do not depend on DEAD AIR specifics — no Region lore, no specific NPC types, no Dead Air mechanics. - Another game takes the shape with its own entities: its own NPC types as NPCEntities, its own teams as Commanders, its own bases as Directors. - The decision-model slots are part of the reusable shape: any game using this element gets the same two optional slots, with the same heuristic defaults. ## Relation to other work - **dead-air/engine #31** ("NPC Entity system: full design") is the implementation-side issue for the NPC system. This design answers the behaviors and AI part of that issue. Engine #31 stays open as the implementation tracker; this issue is the design record. - **Sandbox v2 NPC stub:** the v1 NPC Entity exists as an orange capsule target dummy with health. That stub is the placeholder this design replaces with real brains, Commanders, and Directors. - **dead-air/engine PR #39** (Hanzo AI module, by zeekay) proposes a third-party Hanzo module with an NPC brain, AI Director, Observer narrative, and cloud saves. It is a separate proposal and Zach's call; this design does not depend on it. If the Hanzo module ever lands, it would be one possible Commander or Director implementation — not the framework's own NPC AI. - **Decision-model research:** two research notes back the slots — the Hanzo service offering (what Kai, Zen, Zen Voice, and Cloud KV actually are) and the self-hostable decision-model survey (no local Kai or Jev; the self-hostable candidates are small open-weight decision models, with the 4B tier as the practical ceiling on a player PC and the decision-model slots sized accordingly). ## Open questions - **Name:** Commander vs Controller — same role, name still WIP. Pick one. - **Order vocabulary:** what is the minimal order set the brain understands (move, target, flee, interact, hold, patrol, investigate, ...)? The vocabulary is framework-owned, so it needs to be settled before brains and Commanders are built against it. - **No-commander fallback:** what does an NPC do with no Commander assigned, or with orders that go stale — hold position, patrol, keep the last order? - **Knowledge decay:** how does team knowledge go stale — do last-seen positions decay, expire, or stay until contradicted? - **Director command vocabulary:** beyond "Reinforce XYZ", what objective commands does the Director issue (hold, withdraw, investigate, ...)? - **Director coordination mechanism:** how does the Director see Commander orders in order to veto or redirect them — are proposed orders reviewed before execution, or are live postures monitored and corrected? - **NPC sensing:** what counts as noticing — sight and hearing ranges, what an NPC reports upward, what "finds the body" requires? - **Spawning and reinforcements:** is that the Director's job, or a separate system the Director only calls on? - **Cross-Director knowledge:** do Directors of different bases share anything, or is each base's knowledge fully separate? - **Decision-model evaluation:** how do we measure whether a model Commander or Director actually beats the heuristic — what tactic data, what metric, what counts as good enough to ship as an option?
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
dead-air/game-planning#32
No description provided.