Instinct GOAP

What you get

A GOAP planner for Unity. You write facts, actions and goals in C#. Each tick it searches for the cheapest sequence of actions that reaches the goal worth the most right now, runs the first action of that sequence, and can print the whole calculation.

Features

Where to look

Samples in the package

Install

Copy the folder, reference the assembly, done. Nothing inside depends on where the folder lives.

public sealed class Facts { public static readonly Fact<bool> Done = Fact<bool>.Declare(); }

var action = ActionBuilder.Create(ActionKey.Named("Finish")).Effect(Facts.Done, true).Cost(1f).Build();
var goal   = GoalBuilder.Create(GoalKey.Named("BeDone")).Satisfy(Facts.Done, true).Priority(1f).Build();

Debug.Log(GoapExplain.Chain(new GoapPlanner().BuildPlan(new[]{ action }, goal, WorldState.For<Facts>())));
// Finish

Without UniTask

Delete Runtime/Unity/GoapActionAsync.cs and GoapAsync.cs, drop "UniTask" from Instinct.GOAP.Unity.asmdef, and remove the Guard and Stalker samples' reference to it. You keep the planner, the agent, step-based behaviours (Instant, Run, Wait, Sequence), UnitySteps.MoveTo, the host and the graph window — only async bodies are lost.

As a UPM package

https://github.com/<user>/<repo>.git?path=Assets/InstinctGOAP

The manifest lives at Assets/InstinctGOAP/package.json. For a UPM-only distribution, rename Samples to Samples~ so consumers import them from Package Manager instead of compiling them.

Quick start — a farmer in 15 minutes

An agent that harvests until it runs out of energy, then walks home to sleep. You never write “if tired, go home” — it plans that itself.

public sealed class FarmerContext : IMoveContext, ITickContext
{
    public Transform Self, Home, Field;
    public int Energy = 100;
    public int CropsGrown;

    public Vector3 Position   => Self.position;
    public float DeltaTime  => Time.deltaTime;

    public float DistanceTo(Transform t)
        => Self && t ? Vector3.Distance(Self.position, t.position) : 999f;

    // The one movement implementation in the project. Actions only say "go there".
    public bool MoveTowards(Vector3 target) { /* step; true on arrival */ }
}

public sealed class FarmerFacts
{
    public static readonly Fact<int>   Energy          = Fact<int>.Declare();
    public static readonly Fact<float> DistanceToHome  = Fact<float>.Declare();
    public static readonly Fact<float> DistanceToField = Fact<float>.Declare();
    public static readonly Fact<int>   CropsGrown      = Fact<int>.Declare();
}

public static class FarmerActionKeys
{
    public static readonly ActionKey Harvest     = ActionKey.Declare();
    public static readonly ActionKey Rest        = ActionKey.Declare();
    public static readonly ActionKey WalkToField = ActionKey.Declare();
    public static readonly ActionKey WalkToHome  = ActionKey.Declare();
}

public static class FarmerGoalKeys
{
    public static readonly GoalKey WorkTheField = GoalKey.Declare();
    public static readonly GoalKey Recover      = GoalKey.Declare();
}

public sealed class Harvest : GoapAction<FarmerContext>
{
    protected override ActionKey Key => FarmerActionKeys.Harvest;

    protected override void Setup()
    {
        Require(FarmerFacts.DistanceToField, Compare.LessOrEqual, 1f);
        Require(FarmerFacts.Energy, Compare.GreaterOrEqual, 25);
        Add(FarmerFacts.Energy, -25, min: 0, max: 100);
        Add(FarmerFacts.CropsGrown, +1);
        Cost(1f);
    }

    protected override async UniTask Run(FarmerContext c) => await Wait(0.5f);
}

public sealed class WalkToField : GoapAction<FarmerContext>
{
    protected override ActionKey Key => FarmerActionKeys.WalkToField;

    protected override void Setup()
    {
        Require(FarmerFacts.DistanceToField, Compare.Greater, 1f);
        Effect(FarmerFacts.DistanceToField, 0f);
        Cost(1f);
    }

    protected override async UniTask Run(FarmerContext c)
    {
        if (c.Field == null) Fail("field is not assigned");
        await MoveTo(c, () => c.Field.position);   // target re-read every frame
    }
}

public static GoapDomain<FarmerContext> Build()
{
    var d = GoapDomainBuilder<FarmerContext>.For<FarmerFacts>();

    // Two-way: world -> state before planning, effects -> world after success.
    d.Bind(FarmerFacts.Energy,     c => c.Energy,     (c, v) => c.Energy = v);
    d.Bind(FarmerFacts.CropsGrown, c => c.CropsGrown, (c, v) => c.CropsGrown = v);

    // Derived values are read-only: movement changes them, not an effect.
    d.Bind(FarmerFacts.DistanceToHome,  c => c.DistanceTo(c.Home));
    d.Bind(FarmerFacts.DistanceToField, c => c.DistanceTo(c.Field));

    d.Use(new WalkToField(), new WalkToHome(), new Harvest(), new Rest());

    d.Goal(FarmerGoalKeys.WorkTheField)
        .Satisfy(FarmerFacts.Energy, Compare.LessOrEqual, 15)
        .RelevantWhen(s => s.Get(FarmerFacts.Energy) >= 45)
        .Priority(40)
        .Heuristic(s => (s.Get(FarmerFacts.Energy) - 15) / 60f);

    d.Goal(FarmerGoalKeys.Recover)
        .Satisfy(FarmerFacts.Energy, Compare.GreaterOrEqual, 100)
        .RelevantWhen(s => s.Get(FarmerFacts.Energy) < 45)
        .Priority(80)
        .Heuristic(s => (100 - s.Get(FarmerFacts.Energy)) / 100f);

    return d.Build();
}

private void Awake()
{
    _ctx   = new FarmerContext { Self = transform, Home = home, Field = field };
    _brain = new GoapBrain<FarmerContext>(FarmerBrain.Build(), _ctx,
                 new GoapPlanner(maxIterations: 100, maxDepth: 6),
                 new FarmerPolicy());

    var issues = _brain.Domain.Describe();   // null when the domain is clean
    if (!string.IsNullOrEmpty(issues)) Debug.LogWarning(issues);
}

private void Update() => _brain.Tick();

Concepts

Each tick: snapshot the world, score every relevant goal by Priority − PlanCost, run the first action of the winner.

Facts & world state

A fact is a typed handle to one slot. The class that declares them is the schema — WorldState.For<GuardFacts>() allocates exactly that many slots.

public static readonly Fact<bool>  IntruderVisible = Fact<bool>.Declare();
public static readonly Fact<int>   Ammo            = Fact<int>.Declare();
public static readonly Fact<Alert> AlertLevel      = Fact<Alert>.Declare();  // any enum

// Enums compare like real numbers, because they are stored as one:
.Require(GuardFacts.AlertLevel, Compare.GreaterOrEqual, Alert.Suspicious)
.Effect(GuardFacts.AlertLevel, Alert.Hunting)

Actions

An action declares three things for the planner: what must be true before it can run, what it changes, and what it costs at this moment. If those three match what the action really does in the game, plans come out correct.

Every effect resolves against the pre-action state, so declaration order never changes the outcome. Cost runs at every expansion during the search, so keep it cheap and pure; it is clamped to ≥ 0.01, and returning NaN or Infinity is the supported way to say “this action is unavailable right now”.

Goals

The planner

Forward A* from the current state towards the goal condition: binary min-heap on f = g + h, a best-known-cost map per state, pooled nodes. maxDepth caps plan length — above it you get no plan, never a truncated one.

Goal selection & policy

Irrelevant goals are dropped, the rest are sorted by Priority + PolicyBias and planned in that order. The pass stops early as soon as the next goal's best possible score cannot beat the current winner — exact pruning, because cost is never negative.

public float UtilityBias(IGoal g, IGoal current, WorldState s)
    => current != null && g.Key == current.Key
       ? (g.Key == GoalKeys.Chase ? 6f : 2f)
       : 0f;

public bool ShouldAbandonPlan(IPlan plan, int step, WorldState s)
    => s.Get(Facts.PlayerVisible)
       && plan.Goal.Key != GoalKeys.Chase;

The agent replans when there is no plan, the plan finished, the policy says so, the goal stopped being relevant, or the current step's preconditions no longer hold — and never otherwise.

Five rules that keep plans correct

Choose an API

The same planner, two entry points. Pick one per agent; do not mix them inside a single agent.

Flow API — the loop

Effect mirroring removes the classic GOAP duplication — Effect(Energy, -25) here and board.Energy -= 25 there. After a successful action its own effects are written back through the two-way bindings, touching only the facts it declared. Disable it per action with NoMirror() when the world applies the change itself.

Behaviour can also be composed from steps, with no UniTask involved:

d.Action(Keys.Deliver)
    .Require(Facts.HasParcel, true)
    .Effect(Facts.ParcelDelivered, true)
    .Cost(1f)
    .Run(Steps.Sequence(
        UnitySteps.MoveTo<AiContext>(c => c.Target.position),
        Steps.Wait<AiContext>(0.4f),
        Steps.Instant<AiContext>(c => c.DropParcel())));

Command API — feeding an existing pipeline

var agent = new GoapAgent<GuardCommand>(
    new GoapPlanner(maxIterations: 200, maxDepth: 6),
    GuardGoals.All(), GuardActions.All(),
    new GuardStateProvider(board),   // IWorldStateProvider: world -> WorldState
    new GuardExecutor(board));       // IActionExecutor<T>: IAction -> your command

GuardCommand command = agent.Tick();

Integration

Where each piece of your game goes, and the four decisions that matter.

Sensing

d.Bind(Facts.HasWeapon,
      c => c.Inventory.HasWeapon,
      (c, v) => c.Inventory.HasWeapon = v);   // two-way

d.Bind(Facts.DistanceToPlayer,
      c => c.DistanceTo(c.Player));            // read-only

public WorldState GetState() => WorldState.For<GuardFacts>()
    .Set(GuardFacts.AlertLevel,        _board.Alert)
    .Set(GuardFacts.IntruderVisible,   _board.CanSeeIntruder)
    .Set(GuardFacts.DistanceToIntruder, _board.Distance);

Both run every tick, so keep them to field reads. Raycasts, OverlapSphere and pathfinding belong in a sensor on its own slower schedule, writing into the blackboard.

Movement

Implement IMoveContext once per project; from then on actions only say “go there”.

public bool MoveTowards(Vector3 target)
{
    if (Nav.destination != target) Nav.SetDestination(target);
    return !Nav.pathPending && Nav.remainingDistance <= Nav.stoppingDistance;
}

Many agents

Guard it in CI

[Test] public void DomainIsClean()
    => Assert.IsNull(brain.Describe(), brain.Describe());

[Test] public void HeuristicNeverOverestimates()
{
    var plan = new GoapPlanner(500, 10).BuildPlan(actions, goal, start);
    Assert.LessOrEqual(goal.Heuristic(start, null) ?? 0f, plan.TotalCost);
}

[Test] public void EveryStateHasARelevantGoal()
{
    for (int energy = 0; energy <= 100; energy++)
        Assert.IsTrue(goals.Any(g => g.IsRelevant(StateWith(energy))), $"gap at {energy}");
}

Debugging

Nothing is ever “stuck in a state”. The agent either chose something you did not expect, or chose nothing — and both have a printable answer.

Explain a decision

Debug.Log(brain.ExplainDecision());                                  // flow API
Debug.Log(GoapExplain.Decision(agent.GoalEvaluations, agent.CurrentPlan)); // command API

The graph window

Window → Analysis → GOAP Graph — actions → facts → goals, with the running plan highlighted while you play.

public sealed class GuardGraphSource : GoapGraphSource
{
    public override IReadOnlyList<IAction> Actions => GuardActions.All();
    public override IReadOnlyList<IGoal>   Goals   => GuardGoals.All();
    public override IGoapAgentView FindLiveAgent() => Object.FindObjectOfType<GuardHost>()?.Agent;
}

Validate the domain

var report = new DomainBuilder()
    .AddActions(GuardActions.All())
    .AddGoals(GuardGoals.All())
    .DeclaredGoalsIn(typeof(GuardGoalKeys))     // declared but never registered -> error
    .DeclaredActionsIn(typeof(GuardActionKeys))
    .Describe();                                // null when clean

var report = domain.Describe();                    // flow API: already wired

Catches duplicate keys, keys declared but never registered, actions with no effects, goals with no conditions, and goals that no action can satisfy.

Performance

Numbers below come from the shipped core compiled as a plain .NET 8 library and run on a desktop CPU. Unity's Mono and IL2CPP are roughly 1.5–3× slower, so read these as the best case.

Budgets

How to make planning cheaper

1. Give every goal a heuristic. Without one the search checks far more states than it needs to. This is the largest single win in any domain past a handful of actions.
2. Declare fewer facts. The fact count is the size of the state, and the state is copied, hashed and compared at every step of the search.
3. Use RelevantWhen aggressively. It is checked before any search starts, so an irrelevant goal costs nothing at all.
4. Prefer Require(fact, …) over a lambda. A lambda is a delegate call at every step, and neither the validator nor the graph window can see through it.
5. Keep Cost cheap. It runs at every step of the search, not once per frame — no distance loops, no GetComponent, no allocation.
6. Give each NPC type its own domain. One 40-action domain shared by four types makes every agent search through actions it can never use.
7. Spread the ticks out. Give each agent a random phase offset and tick the distant ones at 5–10 Hz; keep full rate only near the player.

Threads. A planner instance keeps mutable working memory, so it cannot be used from two threads at once. Give every agent that ticks concurrently its own GoapPlanner; agents that tick one after another on the main thread can share a single instance.

API reference

Three assemblies: Instinct.GOAP is the planner and needs no Unity reference, Instinct.GOAP.Unity adds async actions, movement and the MonoBehaviour host, Instinct.GOAP.EditorTools is the graph window.

Facts & state

Identity

Builders

Planner & agent

Flow API

Enums you read and return

Interfaces you implement

Unity layer

Troubleshooting

Symptom → cause → fix, in the order these actually happen.

Still stuck — collect this first

Four values explain almost every misbehaviour, and all four are one line each. Log them together at the moment the agent does the wrong thing:

Debug.Log(brain.ExplainDecision());                       // what every goal scored, and why it lost
Debug.Log(GoapExplain.State<FarmerFacts>(provider.GetState()));  // the world as the planner sees it
Debug.Log(brain.Domain.Describe() ?? "domain is clean");       // mistakes in the domain itself
Debug.Log($"planned {agent.LastPlannedGoals} goals, expanded {planner.LastExpandedNodes} nodes");