# BT Cookbook

Level: Intermediate

## Goal

Use common Behavior Tree patterns without guessing which composite, decorator, or Flow handoff should own each part of the behavior.

## When To Use This

Use these patterns after you can create a `BTRoot` and connect its result back to Flow. Each pattern starts with the gameplay intent, then describes the visual shape to build.

## Pattern 1: Priority Decision

Use this when the actor should try the highest-priority valid behavior first.

Typical shape:

1. Flow Trigger or Entry activates `BTRoot`.
2. `BTRoot` child connects to `BtSelector`.
3. Selector children are ordered by priority:
   * `BTCondition` Has Attack Target, then `BTAction` Attack.
   * `BTCondition` Has Chase Target, then `BTAction` Chase.
   * `BTAction` Patrol or Idle.
4. `BTRoot` Success returns to Flow for feedback or next steps.

Authoring rule: move the most important valid choice left. If Patrol runs before Attack, check child order before changing conditions.

## Pattern 2: Ordered Check Then Action

Use this when every step must pass before the action is valid.

Typical shape:

1. `BTRoot` child connects to `BtSequence`.
2. Sequence child 0 is `BTCondition` Has Target.
3. Sequence child 1 is `BTCondition` In Range.
4. Sequence child 2 is `BTAction` Aim.
5. Sequence child 3 is `BTAction` Shoot.
6. Failure routes from `BTRoot` back to Flow for fallback behavior.

Authoring rule: keep cheap checks before expensive work. If a later action should run even when a check fails, it does not belong in the same strict Sequence.

## Pattern 3: Flow Handoff After Decision

Use this when BT should choose intent, but Flow should perform the visible sequence.

Typical shape:

1. BT selects a branch such as Attack, Interact, Flee, or Idle.
2. The selected BT leaf writes an intent key to Blackboard, such as `ChosenAction`.
3. `BTRoot` Success returns to a Flow `Switch`, `IfElse`, or Action chain.
4. Flow handles animation, sound, UI, camera, timers, or other ordered side effects.

Authoring rule: this pattern keeps BT focused on decision-making. It is a good default when side effects need timing or multiple systems.

## Pattern 4: Non-interruptible Work

Use this when a child must finish once it starts, even if a higher-priority option becomes valid.

Typical shape:

1. Use a Reactive Selector or Sequence for normal priority updates.
2. Wrap the non-interruptible child with a BT Shield decorator.
3. Put the action or subtree that must finish under the shield.
4. Route completion back to the parent composite.

Authoring rule: use BT Shield for short commitments such as attack wind-up, pickup, reload, or interaction confirmation. Avoid shielding long-running idle behavior unless interruption is truly invalid.

## Pattern 5: Cooldown Special Action

Use this when a powerful action should be considered often but only execute after a cooldown.

Typical shape:

1. Put the special action branch before lower-priority fallback branches.
2. Add a Cooldown decorator above the special action subtree.
3. Put required checks inside the subtree, such as Has Target and In Range.
4. Let the Selector continue to fallback behavior while cooldown blocks the special action.

Authoring rule: place cooldown close to the action it protects. If you put it too high, it may block unrelated choices.

## Pattern 6: Concurrent Support Behavior

Use this when a secondary behavior should run while the main branch is active.

Typical shape:

1. Use `BtParallel` only when both child responsibilities are intended to run together.
2. Put the main behavior in one child, such as Move To Target.
3. Put the support behavior in another child, such as Look At Target.
4. Choose the Parallel policy based on which result should finish or fail the parent.

Authoring rule: if one child is just refreshing data, consider `BtService` instead of Parallel. If order matters, use Sequence instead.

## Pattern 7: Reusable Subtree

Use this when several graphs need the same decision branch.

Typical shape:

1. Move the shared BT branch into a separate Flow Graph asset.
2. Ensure that graph has a clear `BTRoot`.
3. In the parent tree, add `BtSubGraph`.
4. Assign the graph asset and select the intended BTRoot.
5. Configure Return Mode so Success, Failure, Abort, and Invalid map correctly to the parent tree.

Authoring rule: a reusable subtree should depend on stable Blackboard keys and clear input assumptions. If it depends on scene-only objects, document that near the subgraph node.

## Pattern 8: Memory Versus Reactive Selection

Use Reactive mode when higher-priority checks should keep interrupting lower-priority running work. Use Memory mode when the running child should continue until it finishes.

Typical reading:

| Situation                                            | Prefer                        |
| ---------------------------------------------------- | ----------------------------- |
| Combat target appears and should interrupt patrol.   | Reactive Selector             |
| Attack animation should finish once started.         | Memory composite or BT Shield |
| Ordered task should continue from the running child. | Memory Sequence               |
| Sensor updates should immediately change choice.     | Reactive Selector             |

Authoring rule: if behavior keeps restarting, suspect Reactive preemption. If behavior ignores new priority changes, suspect Memory mode or BT Shield.

## Verify the Pattern

For any cookbook pattern:

* Confirm Flow reaches `BTRoot`.
* Confirm child order matches the intended priority or sequence.
* Confirm Blackboard keys resolve in Debug Context.
* Confirm `BTRoot` Success and Failure both route somewhere intentional.
* Test one visible result in Play Mode before adding the next branch.

## Related

* [Behavior Tree Authoring](/flow-core-docs/documentation/gameplay-modules/behavior-tree-authoring.md)
* [BT Debugging](/flow-core-docs/documentation/troubleshooting/bt-debugging.md)
* [Flow, FSM, and BT Patterns](/flow-core-docs/documentation/gameplay-modules/flow-fsm-bt-patterns.md)
* [BTRoot](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-root.md)
* [BtSelector](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-selector.md)
* [BtSequence](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-sequence.md)
* [BtSubGraph](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-sub-graph.md)


---

# Agent Instructions: 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/bt-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.