---
title: Routine Driven NPC Framework
description: "The **Routine-Driven NPC Framework** is a modular Unreal Engine NPC framework for large, living worlds. It separates population, routines, perception, and combat so designers can author NPC behavior through data while programmers extend capabilities without rewriting content. The framework supports…"
url: "https://gamesbyhyper.com/docs/ai/routine-driven-npc-framework/"
updated: "2026-05-25"
category: AI
---

# Routine Driven NPC Framework

The **Routine-Driven NPC Framework** is a modular Unreal Engine NPC framework for large, living worlds. It separates population, routines, perception, and combat so designers can author NPC behavior through data while programmers extend capabilities without rewriting content.

The framework supports humanoid and non-humanoid NPCs through the same architecture. It uses State Trees, Data Tables, Data Assets, AI Perception, Smart Objects, Gameplay Behavior, gameplay tags, and tagged world placeables. For shared setup guidance, see the [Migration Guide](/docs/getting-started/migrate-and-integrate-hyper/) and [Integration Guide](/docs/getting-started/migrate-and-integrate-hyper/). Use the [System Atlas](/docs/system-atlas/) to look up functions, variables, events, components, and ownership references.

# Architecture

The system is built around four isolated pillars:

| Pillar | Owns | Does not own |
| --- | --- | --- |
| **Population** | Which NPCs exist, where they exist, activation, despawn, respawn, and authoring/debug controls. | Behavior, perception, combat, and decision-making. |
| **Routine** | What NPCs do over time, task selection, target resolution, routine placeables, patrol splines, and fallback behavior. | Population lifecycle, perception escalation, and combat execution. |
| **Perception** | Sight/hearing interpretation, stealth modifiers, team context, threat evaluation, alert propagation, and awareness state. | Combat style execution or long-running routine tasks. |
| **Combat** | How an NPC fights after Perception selects a target: combat style, weapon/ability selection, and combat State Tree execution. | Target selection and population/routine ownership. |

The design intent is simple: behavior is data-defined, NPC logic scales from small scenes to open worlds, and debug visibility is part of the system rather than an afterthought.

# Population

The Population system controls which NPCs exist in the world, where they exist, and when they are active. A **Population Manager** actor defines a bounded population area and manages NPC lifecycle inside that area.

![NPC Classes and Archetypes screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-npc-classes-and-archetypes-screenshot-001.png)

Population Managers support two workflows:

| Workflow | Use for | Behavior |
| --- | --- | --- |
| **Automatic Population** | Wildlife, ambient town NPCs, enemy camps, large-scale simulation. | Spawns configured NPC classes inside the population area using min/max counts, respawn rules, delays, and optional respawn conditions. |
| **Assigned NPC Population** | Vendors, guards, authored spaces, handcrafted narrative locations. | Level designers place NPCs manually, then assign them to the Population Manager for activation and lifecycle control. |

NPC configuration Blueprints typically inherit from a shared NPC base class and define visuals, assigned NPC behavior component, routine data, perception data, and combat data. Villagers, guards, rebels, vendors, and creatures are all treated consistently by population logic.

## Using the Population Manager

1. Place a Population Manager actor in the level.
2. Resize its box extents to cover the population area.
3. Add NPC classes to spawn, with minimum and maximum counts.
4. Configure respawn options if the population should regenerate.
5. Assign manually placed NPCs when authored placement is required.
6. Use debug mode, Force Load, and Force Unload while simulating to validate behavior.

![Using the Population Manager screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-using-the-population-manager-screenshot-002.png)

![Using the Population Manager screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-using-the-population-manager-screenshot-003.png)

![Using the Population Manager screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-using-the-population-manager-screenshot-004.png)

# Routine System

The Routine System is time-driven and location-agnostic. NPCs decide *what* to do based on time and routine data. The world decides *where* the task can happen through tagged placeables, Smart Objects, patrol splines, and interaction targets.

This keeps routines reusable across towns, regions, and levels. A villager routine can ask for a sitting spot or work target without knowing where those targets are placed in a specific map.

## Core Dependencies

- **BP_TimeManager**: placed in the level; controls in-game time, day/night, and optional seasonal variation.
- **GameState Time Component**: receives time updates and broadcasts interval changes.
- **Interval-Based Evaluation**: evaluates routines on configured intervals, such as every 30 in-game minutes.
- **AC_CH_NPC_Behavior**: owns routine logic, subscribes to time events, and runs State Tree behavior for the NPC.

![Core Dependencies screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-core-dependencies-screenshot-005.png)

![Core Dependencies screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-core-dependencies-screenshot-006.png)

## Routine Data

Routines are configured in Data Tables. The primary table is **DT_NPC_Config_Routine_Base**. Each row represents a routine profile, usually for an archetype such as Villager, Guard, Rebel, Vendor, Wildlife, or a custom NPC type.

![Routine Configuration (Data Tables) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-routine-configuration-data-tables-screenshot-007.png)

![Routine Configuration (Data Tables) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-routine-configuration-data-tables-screenshot-008.png)

Each routine profile contains time slots. A time slot defines begin time, end time, weighted predefined tasks, and an optional fallback routine.

![Time Slots and Routine Selection screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-time-slots-and-routine-selection-screenshot-009.png)

1. The current in-game time is evaluated.
2. The matching time slot is selected.
3. A predefined task is selected by weight.
4. The task resolves a valid world target.
5. The behavior executes through the routine/state tree flow.

## Predefined Routine Tasks

Routine tasks are Data Assets such as **DA_NPC_Task_***. They describe how a task is performed, not where it happens. Examples include Patrol, Sit, Sleep, Work, Socialize, Roam, Gather, Eat, and Drink.

![Predefined Routine Tasks (Data Assets) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-predefined-routine-tasks-data-assets-screenshot-010.png)

Target resolution uses three gameplay tag dimensions:

- **Routine Task Tag**: the action, such as **NPC.Task.Movement.Patrol**.
- **Routine Target Tag**: the required target type, such as **NPC.Target.Town** or **NPC.Target.Generic.SittingSpot**.
- **NPC Identifier Tag**: who may use the target, such as Guard, Villager, Vendor, or generic/no identifier.

![Predefined Routine Tasks (Data Assets) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-predefined-routine-tasks-data-assets-screenshot-011.png)

![Predefined Routine Tasks (Data Assets) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-predefined-routine-tasks-data-assets-screenshot-012.png)

The resolver gathers matching targets, prioritizes identifier-specific targets, falls back to generic targets, respects occupancy limits, and uses fallback routines when no valid target exists.

## Routine Placeables and Patrols

Routine Placeables are drag-and-drop world actors that define task tags, target tags, optional identifier tags, and optional occupancy limits.

![Routine Placeables (World Setup) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-routine-placeables-world-setup-screenshot-013.png)

Patrol splines are custom routine actors for path-based movement. They support nearest-point-on-spline resolution, occupancy limits, and the same task/target/identifier tag workflow.

![Spline-Based Routines (Patrols) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-spline-based-routines-patrols-screenshot-014.png)

Fallback routines can be defined per time slot, per routine profile, or globally so NPCs do not stall when a target cannot be resolved.

![Fallback Routines screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-fallback-routines-screenshot-015.png)

## Smart Object Execution Models

The Routine System builds on **Unreal Engine Smart Objects** and **Gameplay Behavior**. See Epic's [Smart Objects quick start](https://dev.epicgames.com/documentation/en-us/unreal-engine/smart-objects-in-unreal-engine---quick-start) for the underlying engine concept.

| Model | Use for | Behavior |
| --- | --- | --- |
| **Behavior Objects** | Simple localized logic such as Tend Shop, Enable Vendor Mode, Sit Idle, or simple work/leisure actions. | Lightweight, data-driven, usually instant or simple state toggles. |
| **Interaction Objects** | Complex interactions such as socializing, group interactions, multi-step work, or activities that need branching/waiting/looping. | Run a State Tree and can maintain internal state while occupied. |

Routine tasks do not need to know whether a resolved target is a Behavior Object or an Interaction Object. Resolution is tag-based and execution is delegated to the target type.

![Interaction Objects vs Behavior Objects screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-interaction-objects-vs-behavior-objects-screenshot-016.png)

## Routine Setup Flow

1. Place **BP_TimeManager** in the level.
2. Ensure the GameState has the Time component.
3. Create or select a routine row in **DT_NPC_Config_Routine_Base**.
4. Define time slots and assign predefined task Data Assets.
5. Assign the routine row on **AC_CH_NPC_Behavior**.
6. Place matching Routine Placeables or patrol splines in the world.
7. Use matching task, target, and identifier tags so targets resolve automatically at runtime.

# Perception

Perception combines sensing, social context, threat evaluation, and reaction routing. It is not only a sight/hearing check; it converts world stimuli into meaningful awareness and behavior state.

- **Sensing**: sight, hearing, stealth, and visibility modifiers.
- **Social context**: team affiliations and relationship overrides.
- **Threat evaluation**: one active highest-threat event drives reaction.
- **Reaction routing**: lightweight reactions in perception, long-running behavior in State Trees.

![Key Runtime Flow screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-key-runtime-flow-screenshot-017.png)

![Key Runtime Flow screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-key-runtime-flow-screenshot-018.png)

![Key Runtime Flow screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-key-runtime-flow-screenshot-019.png)

## NPC Components

**AC_CH_Perception** handles sensing, action event interpretation, threat evaluation, alert propagation, and voice-line or single-speaker selection.

![Components on NPCs screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-components-on-npcs-screenshot-020.png)

**AC_CH_NPC_Behavior** binds to perception events, translates perception updates into State Tree triggers, and routes NPCs between routine, alerted, investigation, and combat behavior.

![Components on NPCs screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-components-on-npcs-screenshot-021.png)

**AC_Actor_Identifier** provides social context: own affiliations, friendly affiliations, enemy affiliations, and custom team tags.

![Components on NPCs screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-components-on-npcs-screenshot-022.png)

## Perception Configuration

Each NPC assigns a perception row on **AC_CH_NPC_Behavior**. The example table is **DT_NPC_Config_Perception**. Rows define high-level reaction defaults such as whether to perceive stealth targets and how to respond when Curious, Suspicious, or Alert.

![Perception Configuration (Data Table) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-perception-configuration-data-table-screenshot-023.png)

Alertness sensitivity Data Assets convert actions into threat. They can distinguish between broadcast sensitivity and receiving sensitivity, allowing the initiating NPC and nearby NPCs to react differently.

![Alertness Sensitivity Profiles (Data Assets) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-alertness-sensitivity-profiles-data-assets-screenshot-024.png)

Sensitivity assets define base alertness propagation, event sensitivities for gameplay tags such as equipped item, used equipment, dealt damage, killed actor, stole item, and sound, plus relationship overrides such as friendly/enemy threat differences.

## Sight, Hearing, and Obscured Vision

AI Perception handles sight and hearing at the AI Controller level, while **AC_CH_Perception** filters and translates incoming stimuli before NPC logic reacts.

- **Sight** can escalate alertness based on line of sight, team relationship, current alertness, and obscured vision checks.
- **Hearing** increases alertness more gradually and typically results in Curious or Suspicious unless reinforced.
- **Obscured Vision Volumes** block or reduce visibility for stealth areas, cover, bushes, shadows, and level-design-controlled sight breaks.

![Sight vs Hearing (Split) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-sight-vs-hearing-split-screenshot-025.png)

![Obscured Vision Volumes screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-obscured-vision-volumes-screenshot-026.png)

## Investigation and Alert Propagation

Investigation is the bridge between passive behavior and combat. Perception produces a stimulus and threat value; State Trees execute the investigation behavior.

1. NPC hears a sound or detects a suspicious action.
2. The stimulus location is stored.
3. The NPC moves to investigate.
4. The NPC escalates if confirmation occurs.
5. The NPC de-escalates if no further evidence appears.

![Investigation Logic screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-investigation-logic-screenshot-027.png)

![Investigation Logic screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-investigation-logic-screenshot-028.png)

![Investigation Logic screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-investigation-logic-screenshot-029.png)

Alert propagation uses a shared Alert Proxy. NPCs join or leave a proxy tied to the perceived target instead of directly notifying each other. This prevents alert spam, keeps group focus stable, and supports influence weights where guards or leaders can outweigh civilians.

![Alerting Other NPCs screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-alerting-other-npcs-screenshot-030.png)

## Threat and Awareness UI

The awareness UI visualizes the NPC's internal perception state: Neutral, Curious, Suspicious, or Alert. It is driven directly by **AC_CH_Perception** and reflects the highest active threat.

![Threat & Awareness UI screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-threat-and-awareness-ui-screenshot-031.png)

# Combat

The Combat System is a data-driven execution layer. Perception decides *who* the target is; Combat decides *how* the NPC engages that target.

![Core Principle screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-core-principle-screenshot-032.png)

Combat has four layers:

1. **DT_NPC_Config_Combat**: high-level combat configuration row assigned through **AC_CH_NPC_Behavior**.
2. **DA_CombatStyle** / **PDA_CombatStyle**: reusable decision rules for range, movement, weapons, abilities, pressure, and conditions.
3. **Weapon and ability resolution**: dynamic selection based on combat style, target distance, inventory, and probability weights.
4. **ST_NPC_Combat**: State Tree execution for melee, ranged, override, and fallback combat states.

## Combat Configuration

**DT_NPC_Config_Combat** defines which style logic the NPC uses, how aggressive or defensive it is, and which weapons or abilities are available.

![1. Combat Configuration (DT_NPC_Config_Combat) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-1-combat-configuration-dt-npc-config-combat-screenshot-033.png)

Typical use: Villagers use untrained styles, guards use defensive or mixed styles, rebels use aggressive styles, and creatures use creature-specific melee or pounce behavior.

## Combat Styles and Execution

Combat Style Data Assets define decision rules, not execution. They can handle range-based style switching, weighted weapon selection, ammo handling, ability slots, distance maintenance, and conditional behavior for taking damage, low health, or target distance changes.

![2. Combat Style Data Assets (PDA_CombatStyle) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-2-combat-style-data-assets-pda-combatstyle-screenshot-034.png)

Weapons and abilities are resolved dynamically from combat style rules, target distance, available inventory, and weights. No weapon logic lives inside the State Tree itself.

**ST_NPC_Combat** executes the resolved combat behavior. It equips the selected weapon or ability, applies movement and aiming behavior, and loops until conditions change.

![4. Combat State Tree Execution (ST_NPC_Combat) screenshot](/wp-content/uploads/docs/AI/Routine%20Driven%20NPC%20Framework/routine-driven-npc-framework-4-combat-state-tree-execution-st-npc-combat-screenshot-035.png)

# Why It Scales

The framework scales because each concern stays in its own layer. Population does not decide behavior. Routines do not decide combat targets. Perception does not execute combat styles. Combat does not pick targets. Designers work in data assets, tables, tags, and placeables, while programmers extend reusable capabilities.

This allows enemy variety, creature behavior, role-based NPCs, stealth reactions, combat escalation, and ambient simulation without duplicating State Trees or hardcoding archetypes.