Skip to content

FWAISystem

Version 1.0 | MMO-style NPC behavior framework for Unreal Engine 5

FWAISystem provides a complete NPC behavior framework built for massively multiplayer games. It implements industry-standard mechanics found in games like World of Warcraft, Final Fantasy XIV, and Guild Wars 2 -- threat tables, leashing, patrol behavior, zone-based spawning, and difficulty-based instance scaling.

Features

  • Threat Tables -- Per-NPC cumulative threat tracking with decay, transfer, taunts, and automatic target prioritization.
  • Leashing -- Soft and hard leash radii with pursuit speed reduction, configurable reset delay, and full HP regeneration on return.
  • Patrol -- Waypoint and random-roam patrol modes with configurable wait times and navmesh validation.
  • Spawning -- Point-based and volume-based spawners with weighted spawn tables, respawn timers, and density control.
  • Instance Scaling -- Difficulty tiers (Normal, Hard, Mythic) with per-player party scaling for HP, damage, and XP.
  • Data-Driven NPCs -- UFWNpcDefinition data assets define all NPC parameters in a single, reusable configuration.
  • Behavior Tree Integration -- Pre-built BT tasks, services, and decorators for threat, leash, patrol, and combat.
  • Faction Integration -- Optional FWFactionSystem support for attitude-based aggro gating.
  • GAS Integration -- Optional FWGASSystem support for ability activation and attribute scaling.

Architecture

                    UFWNpcDefinition (Data Asset)
                           |
              +------------+------------+
              |                         |
     AFWNpcSpawnPoint          AFWNpcSpawnVolume
     (Point Spawner)           (Zone Spawner)
              |                         |
              +-------> APawn <---------+
                         |
          +--------------+--------------+
          |                             |
  UFWThreatComponent          UFWLeashComponent
  (Threat Table)              (Spawn Anchor)
          |                             |
          +-------> Behavior Tree <-----+
                    |    |    |
            +-------+    |    +--------+
            |             |            |
    BT Tasks        BT Services    BT Decorators
    - FindThreat    - UpdateThreat - HasThreat
    - MoveToTarget  - CheckLeash   - IsLeashing
    - ReturnToSpawn                - FactionAttitude
    - Patrol
    - PlayAbility

  UFWInstanceScalingLibrary (Static Scaling Functions)

Key Concepts

Threat

Every NPC with a UFWThreatComponent maintains a threat table -- a sorted list of actors ranked by cumulative threat value. Threat is generated by damage, healing, taunts, proximity, and AoE. The highest-threat actor becomes the NPC's current target. Threat decays over time when a source stops attacking, and entries are pruned when actors are destroyed or leave the table.

Server-Authoritative

The threat table is server-authoritative. Clients do not need or receive threat data. Target selection runs entirely on the server.

Leashing

The UFWLeashComponent anchors NPCs to their spawn location with two configurable radii:

Zone Behavior
Normal range (0 to SoftLeashRadius) NPC pursues at full speed
Soft leash (SoftLeashRadius to LeashRadius) NPC pursuit speed is reduced
Hard leash (beyond LeashRadius) NPC disengages, clears threat, walks home, regenerates HP

Bosses can disable leashing entirely by setting bCanLeash = false.

Instance Scaling

The UFWInstanceScalingLibrary provides static functions to scale NPC stats based on difficulty tier and party size. Default tier multipliers:

Tier HP Damage XP
Normal 1.0x 1.0x 1.0x
Hard 2.0x 1.5x 1.75x
Mythic 4.0x 2.5x 3.0x

Party scaling applies additive multipliers per extra player beyond the expected count (default: +30% HP, +10% damage per additional player).

Spawning

Two spawner types cover different use cases:

  • AFWNpcSpawnPoint -- Level-placed actor for precise NPC placement. Supports auto-spawn on BeginPlay, respawn timers, and optional patrol waypoints.
  • AFWNpcSpawnVolume -- Box volume for zone-based density spawning. Uses weighted UFWSpawnTable data assets, manages NPC density within the volume, and spawns/despawns based on player proximity for performance.

Plugin Dependencies

Plugin Required Purpose
FWFactionSystem Optional Faction attitude checks for aggro gating via FWBTDecorator_FactionAttitude
FWGASSystem Optional Ability activation via FWBTTask_PlayAbility and attribute scaling via ApplyScalingToNpc

Both dependencies are auto-detected at compile time. When absent, the corresponding features compile out gracefully via WITH_FWFACTIONSYSTEM and WITH_FWGASSYSTEM preprocessor defines.

Module Dependencies

FWAISystem.Build.cs (Public)
Core, CoreUObject, Engine, AIModule, GameplayTags,
GameplayAbilities, GameplayTasks, NavigationSystem, NetCore

Next Steps