[ Example ]

Companion AI — follow, help, retreat

A companion who follows the player, helps in combat, and retreats when low on HP. Companion AI is the genre most punished by flap — a wounded companion flickering between Help and Retreat every half-second breaks immersion in a way no other AI shape does. This page is the showcase for using the anti-flap stack in combination.

DIFFICULTY ▮▮▯ INTERMEDIATESHIPS AS WALKTHROUGHBUILD ~30 MIN · INT-31

Behaviour matrix

Anatomy

◢ Spec

Schema — DA_Schema_Companion

Five facts. Two are derived (filtered + latched); three feed direct from sensors.

PlayerDistanceScalar

Source

Sensor

Filter

EMA α=0.3

PlayerNearBool (latched)

Source

PlayerDistance

Band

400 / 600

EnemyInCombatBool

Source

Sensor

Triggers Replan

true

SelfHPScalar

Source

Sensor

Triggers Replan

true

IsLowHPBool (latched)

Source

SelfHP

Band

0.25 / 0.40

◢ Spec

Goals

DA_Goal_FollowIntentGoal

Priority

0.5

Scored by

PlayerNear

DA_Goal_HelpIntentGoal

Priority

1.0

Scored by

EnemyInCombat

DA_Goal_RetreatIntentGoal

Priority

2.0

Interruption

Critical

Scored by

IsLowHP

◢ Spec

Actions

MoveToPlayerIntentAction

Effect

PlayerNear = true

Executor

Move

AttackEnemyIntentAction

Precondition

EnemyInCombat

Effect

enemy dispatched

Executor

Custom

FleeToSafeDistanceIntentAction

Effect

IsLowHP = false (via distance)

Executor

Move

Why this example is here

Three layers of the anti-flap toolkit working together:

1. Family 4 (EMA filter) on PlayerDistance — smooths per-frame distance jitter that would otherwise cause PlayerNear to flicker.
2. Family 2 (Schmitt latch) on IsLowHP — when HP hovers near 30% (combat damage + healing tick), the 25%/40% band prevents Retreat / Help oscillation.
3. Family 1 (goal momentum bonus) — once Help is chosen, it scores +0.15 against Follow on subsequent ticks, preventing thrash when the player runs back behind cover momentarily.
4. Critical interruption on Retreat — bypasses the momentum bonus when actually necessary (HP threshold crossed in the dangerous direction).

How to build it

Pending the marketplace sample pack (Linear: INT-13). In the meantime, the schema/goals/actions above are enough to scaffold this yourself in any project using built-in executors plus a custom Attack executor.

◢ T+

Acceptance test

1. 01
   SpawnDefault state

   Follower's Inspector shows goal Follow.

2. 02
   Player engages enemyHelp fires

   Goal switches to Help within one replan tick.

3. 03
   HP oscillates near bandSchmitt holds

   Player takes damage then heals across the IsLowHP threshold range — goal stays Help (Schmitt band absorbs the oscillation).

4. 04
   HP < 25%Critical interrupt

   Goal immediately switches to Retreat. Critical interruption bypasses momentum.

5. 05
   HP > 40%Re-evaluate

   Follower retreats until HP rises back above the upper band edge, then re-evaluates between Follow and Help.

At no point should you see the goal flicker between Help and Retreat multiple times per second.

◢ Next

Try this next

Survival shape /Town NPC

Needs-driven NPC with the same anti-flap stack but for survival-sim shapes.

Escalation tiers /Guard

Patrol → investigate → pursue with similar interruption semantics.

Why this works /Anti-Flap Toolkit

Why this specific stack works at each pipeline layer.