> For the complete documentation index, see [llms.txt](https://flow-core.gitbook.io/flow-core-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flow-core.gitbook.io/flow-core-docs/documentation/gameplay-modules/goap-cookbook.md).

# GOAP Cookbook

Level: Intermediate

## Goal

Use GOAP patterns for agents that need to choose a goal, plan a sequence of actions from Blackboard facts, and react when the world state changes.

## When To Use This

Use GOAP when the important question is "what sequence of actions can satisfy this goal from the current facts?" Use BT when the important question is "which valid child should run now?" Use FSM when the important question is "which mode is active?"

GOAP works best when facts are small, boolean, and owned clearly. Keep rich gameplay state in normal systems or Blackboard values, then expose the few planning facts the agent needs.

## Authoring Rules

* Use boolean Blackboard keys as facts.
* Keep fact names stable, such as `EnemySeen`, `InRange`, `HasResource`, or `AtCover`.
* Lower goal priority numbers are more urgent.
* Lower action cost is preferred when two plans can satisfy the same goal.
* Each `GoapAction` must be connected to the `GoapRoot` child list and must target the correct root name.
* Use Flow outputs for visible work, animation, sound, and side effects; GOAP chooses the plan.

## Pattern 1: Patrol, Chase, Attack

Use this for a basic combat agent with escalating goals.

Goals:

| Goal         | Priority | Desired fact        |
| ------------ | -------- | ------------------- |
| `AttackGoal` | 0        | `EnemyDead = True`  |
| `ChaseGoal`  | 1        | `InRange = True`    |
| `PatrolGoal` | 2        | `AtWaypoint = True` |

Actions:

| Action         | Preconditions      | Effects             | Cost |
| -------------- | ------------------ | ------------------- | ---- |
| `AttackAction` | `InRange = True`   | `EnemyDead = True`  | 1    |
| `ChaseAction`  | `EnemySeen = True` | `InRange = True`    | 2    |
| `PatrolAction` | none               | `AtWaypoint = True` | 1    |

Behavior: when the enemy is seen but not in range, the planner can satisfy `AttackGoal` through `ChaseAction` then `AttackAction`. If the enemy is not seen, `AttackGoal` and `ChaseGoal` may have no valid plan, so the agent can fall back to patrol.

Authoring rule: activate the urgent goal when the situation begins, but let the planner discover the required actions.

## Pattern 2: Multi-step Resource Collection

Use this when one action prepares the fact required by another action.

Goal: `HasResource = True`

Actions:

* `MoveToSource`: Preconditions none, Effects `AtSource = True`, Cost 3.
* `CollectResource`: Preconditions `AtSource = True`, Effects `HasResource = True`, Cost 1.

The planner sequences `MoveToSource -> CollectResource` because the first action creates the fact the second action needs.

Authoring rule: effects are how actions connect. If a plan cannot be found, check whether one action's effect actually matches the next action's precondition.

## Pattern 3: Dynamic Replanning

Use this when the world can change while an action is running.

Setup:

* `AttackGoal` is active with plan `ChaseAction -> AttackAction`.
* `EnemyDead` is a watched fact in the current plan.
* Another actor kills the enemy while this agent is chasing.

Behavior: the watched fact changes, the planner requests a replan, and the goal may complete immediately because the desired fact is already true.

Authoring rule: let watched facts represent meaningful plan invalidation. Do not add noisy facts that change every frame unless they are truly needed for planning.

## Pattern 4: Replan Versus Fail

Use this when an action's preconditions can become false during execution.

Example: `AttackAction` starts, then the enemy leaves range.

| Mode   | Result                                     | Use when                                         |
| ------ | ------------------------------------------ | ------------------------------------------------ |
| Replan | Planner searches again from current facts. | Dynamic worlds where recovery is normal.         |
| Fail   | Goal fails and its Failed output fires.    | The goal should be abandoned or handled by Flow. |

Authoring rule: use Replan for AI adaptation. Use Fail when the failed attempt should trigger a different visible sequence, cooldown, bark, or state transition.

## Pattern 5: Forced Goal

Use `ForceActivateGoapGoal` when a scripted or high-authority event must override normal priority competition.

Examples:

* Story sequence forces `TalkToPlayerGoal`.
* Stun effect forces `RecoverGoal`.
* Tutorial step forces `MoveToMarkerGoal`.

Other goals can remain active, but the forced goal owns planning until it completes, fails, or is cancelled.

Authoring rule: reserve forced goals for explicit control moments. If everything is forced, priority numbers stop communicating design intent.

## Pattern 6: Cost Tuning

Use cost when several action paths can satisfy the same goal.

Example:

* `AttackMelee`: Preconditions `InRange = True`, Effects `EnemyDead = True`, Cost 1.
* `AttackRanged`: Preconditions `HasAmmo = True`, Effects `EnemyDead = True`, Cost 3.

When both are possible, the planner picks the lower total cost. Increase cost for slower, riskier, or less preferred actions. Lower cost for default behavior.

Authoring rule: cost is preference, not permission. Preconditions decide whether an action can run.

## Pattern 7: Planner Pause And Resume

Use Disable and Enable instructions when another module temporarily owns the agent.

Examples:

* Disable GOAP during a cutscene.
* Disable GOAP while a Stack layer owns a dialogue input mode.
* Re-enable GOAP after an FSM state exits Stunned.

Authoring rule: pause planning at module boundaries. Do not leave the planner running if another module must have exclusive control.

## Verify A GOAP Pattern

* Debug Context points to the agent process.
* The `GoapRoot` title matches action target root names.
* Each goal and action title is unique inside the root.
* Required facts exist as boolean Blackboard keys.
* The intended goal is active or force-active.
* `GetGoapRootStatus` reports the expected current goal and action.
* Planned, Goal Changed, Replanned, Completed, Failed, and No Plan outputs are wired when the design needs them.
* The visible action result updates the same facts the planner expects.

## Common Mistakes

* Modeling too many facts in one root and making planning expensive.
* Using non-boolean Blackboard values as GOAP facts.
* Forgetting to connect actions or goals to the root child list.
* Treating cost as a condition.
* Letting Flow side effects change facts without a clear ownership rule.
* Renaming goals, actions, or roots after instructions reference them.
* Replanning on noisy facts that change every frame.

## Related

* [GOAP Authoring](/flow-core-docs/documentation/gameplay-modules/goap-authoring.md)
* [GOAP Runtime Model](/flow-core-docs/documentation/runtime-guide/goap-runtime.md)
* [Flow, FSM, and BT Patterns](/flow-core-docs/documentation/gameplay-modules/flow-fsm-bt-patterns.md)
* [GoapRoot](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-goap-root.md)
* [GoapGoal](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-goap-goal.md)
* [GoapAction](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-goap-action.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flow-core.gitbook.io/flow-core-docs/documentation/gameplay-modules/goap-cookbook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.