Agents (NPC AI)

The attack seam this piece OWNS: a behavior decides WHEN to attack (range, cooldown); this seam decides WHAT an attack does — spawn a projectile, apply a stat change, start a dialogue, tag a player — so Agents never references a combat piece (rule 13). The piece defaults it to NullAgentAttackHandler (a TryAdd seam): with nothing registered, attacks are inert and ranged brains degrade to pure chase.

sealed class ProjectileAttackBridge : IAgentAttackHandler
{
    public void Attack(WorldEntity attacker, WorldEntity target)
        => _projectiles.Spawn(attacker.Zone, attacker.X, attacker.Y, attacker.Z,
               targetX: target.X, targetY: target.Y, targetZ: target.Z, kind: 3);
}
services.AddSingleton<IAgentAttackHandler, ProjectileAttackBridge>(); // before AddCrossplayAgents

• void Attack(WorldEntity attacker, WorldEntity target)

  One attack moment: attacker struck at target.

One NPC brain — the SPI to implement for custom AI. The piece ships WanderBehavior/PatrolBehavior/ChaseNearestBehavior built-ins; implement this for anything smarter. Attach an instance to a server entity with Attach; the piece then calls Tick at the configured agent rate, on the poll thread. How to implement. Read the world through the AgentContext (its position, the nearest player, distances) and drive locomotion through the same context (MoveToward / Stop) — every move rides the standard entity broadcast wire, so the piece adds no messages of its own. Stash per-agent scratch in Memory (it persists across ticks and the piece never touches it). Keep Tick allocation-free — it runs per agent per think.

public sealed class FleeBehavior : IAgentBehavior
{
    private readonly float _radius, _speed;
    public FleeBehavior(float radius, float speed) { _radius = radius; _speed = speed; }

    public void Tick(AgentContext ctx, float dt)
    {
        var threat = ctx.NearestPlayer(_radius);
        if (threat is null) { ctx.Stop(); return; }
        // run to the opposite side of home from the threat
        ctx.MoveToward(2 * ctx.HomeX - threat.X, 2 * ctx.HomeZ - threat.Z, _speed, dt, locomotion: 2);
    }
}

• void Tick(AgentContext context, float deltaSeconds)

  Advance this agent one think.