unity-npc-behavior

NPC Behavior -- Design Translation Patterns

Prerequisite skills: unity-physics-queries (perception raycasts, NonAlloc query patterns), unity-state-machines (decision FSM/BT architecture), unity-game-architecture (event bus, Service Locator, component composition)

Claude's default NPC is a single MonoBehaviour with an Update() that raycasts, decides, and moves all in one method. This is untestable and unextensible -- changing perception logic requires touching decision logic, adding a new sense means rewriting the entire method, and squad coordination is impossible when each NPC is a self-contained island. These patterns decompose NPC behavior into pluggable layers that designers can configure without programmer intervention.

---

PATTERN: Perception System Architecture

DESIGN INTENT: NPCs sense the world through sight, hearing, and proximity. Different NPC types have different senses -- a guard has long-range sight but poor hearing; a dog has short sight but exceptional hearing. Senses are mix-and-match components that feed a unified target list.

WRONG (Claude default):

// Raycast inside decision code -- can't swap senses, no batching, untestable
public class EnemyAI : MonoBehaviour
{
    void Update()
    {
        // Perception and decision jammed together
        var dir = (player.position - transform.position).normalized;
        if (Physics.Raycast(transform.position, dir, out var hit, 20f))
        {
            if (hit.collider.CompareTag("Player"))
            {
                // Immediately decide and act -- no separation
                Chase(hit.collider.transform);
            }
        }
    }
}

RIGHT:

/// <summary>
/// Pluggable sense interface. Each sense is a separate component on the NPC.
/// Cross-ref: unity-physics-queries for OverlapSphereNonAlloc and raycast patterns.
/// </summary>
public interface IPerceptionSense
{
    /// <summary>Evaluate targets within range. Called by PerceptionComponent on staggered schedule.</summary>
    void EvaluateTargets(Collider[] scratchBuffer, List<PerceivedTarget> results);

    /// <summary>Maximum range of this sense for broad-phase overlap sphere.</summary>
    float MaxRange { get; }
}

/// <summary>
/// Central perception hub. Collects results from all IPerceptionSense components.
/// Maintains a deduplicated KnownTargets list for the decision layer.
/// </summary>
public class PerceptionComponent : MonoBehaviour
{
    [SerializeField] private float _updateInterval = 0.2f;
    [SerializeField] private LayerMask _detectionLayers;

    private readonly List<PerceivedTarget> _knownTargets = new();
    private IPerceptionSense[] _senses;
    private readonly Collider[] _scratchBuffer = new Collider[32];

    public IReadOnlyList<PerceivedTarget> KnownTargets => _knownTargets;
}