# Behavior Tree Authoring

Level: Beginner

## Goal

Create a Behavior Tree (BT) branch inside a Flow Graph, let Flow activate it, and route the BT result back into normal Flow nodes.

## When To Use This

Use a BT branch when the graph needs priority-based decisions: attack if possible, chase if needed, patrol otherwise; pick the first valid interaction; or run an ordered set of checks before an action. Use Flow around the BT when you need orchestration, timing, side effects, UI feedback, or handoff to another module.

## Prerequisites

* A Flow Graph asset exists.
* A `FlowCoreProcess` is assigned to a scene GameObject.
* Debug Context is set to that GameObject when you want summaries and visual debugging.
* Any Blackboard values used by BTConditions or BTActions already exist.

## Mental Model

A BT branch is a decision subtree inside the larger Flow Graph. Flow decides when the tree starts. `BTRoot` owns the BT tick. BT child ports define evaluation order. BT composites decide which child runs. Leaves do checks or work. `BTRoot` returns Success, Failure, Abort, or Invalid back to Flow so the graph can continue.

In practice, keep the split simple:

* Flow starts the decision and handles visible side effects.
* BT chooses which branch should run.
* Blackboard carries the data both sides read.

## Steps

1. Create the Flow start path.

   Add a `Trigger` or `Enter` node, then connect it to the `BTRoot` Active control input. The BT does not tick by itself just because it exists on the canvas. A Flow path must activate the root.
2. Add a BTRoot.

   Place `BTRoot` near the Flow chain that starts it. Give nearby comments enough context to explain what decision the tree owns, such as "Combat choice" or "Interaction priority."
3. Add child outputs.

   Use the BT child section on `BTRoot` to add child outputs. Child order matters. Read children left to right as priority or sequence order, depending on the composite you connect.
4. Choose the top composite.

   Use a `BtSelector` when the tree should choose the first valid option. Use a `BtSequence` when the tree must pass checks and actions in order. Use `BtParallel` only when multiple children should run together and the policy is clear.
5. Add BT leaves.

   Use `BTCondition` for checks, such as Has Target, Is In Range, or Can Interact. Use `BTAction` for work that should run as a BT leaf. A BTAction normally returns Success unless it is aborted or the surrounding node behavior maps the result differently.
6. Connect Success and Failure back to Flow.

   Route `BTRoot` Success to the Flow node that handles the successful decision. Route Failure to a fallback, retry, idle, or no-op path. Do not leave the result outputs unplanned in graphs that need an observable result.
7. Add services only when needed.

   Use `BtService` for side tasks that run every N root ticks while a child is running, such as refreshing target data. Keep services small. If a service becomes the main behavior, move that work into Flow or a leaf action.
8. Protect non-interruptible work.

   If a child must finish once started, wrap it with a BT Shield decorator. This matters when a Reactive Selector or Sequence could otherwise re-evaluate higher-priority children and interrupt running work.
9. Reuse with BtSubGraph.

   Add `BtSubGraph` when the same BT branch should be shared. Assign the Flow Graph asset, select the intended BTRoot inside that graph, and choose the Return Mode that maps the subgraph result back to the parent tree.
10. Debug the tree from Flow inward.

    First confirm the Flow chain reaches `BTRoot`. Then read child order, composite mode, leaf values, and Blackboard bindings. If selection is wrong, use [BT Debugging](/flow-core-docs/documentation/troubleshooting/bt-debugging.md).

## Expected Result

A complete BT branch should have:

* A Flow path into `BTRoot` Active.
* At least one connected BT child output.
* Clear child order.
* Conditions and actions that read the expected Blackboard data.
* Success and Failure outputs routed back to Flow.
* A Play Mode result that can be observed in the scene, Console, Blackboard, or visual debugging.

## Common Mistakes

* Adding `BTRoot` but never connecting Flow into Active.
* Forgetting to add child outputs before connecting BT nodes.
* Reading child order as visual layout only. It is behavior.
* Connecting Flow outputs into BT child ports.
* Leaving `BtSubGraph` without a selected BTRoot.
* Expecting BTAction to return Failure for gameplay conditions. Put checks in BTCondition or Guards.
* Using a Reactive composite when a running child should continue uninterrupted.
* Keeping side effects only inside the BT when Flow should handle the result handoff.

## Related

* [Graph Editor](/flow-core-docs/documentation/editor-guide/graph-editor.md)
* [BT Cookbook](/flow-core-docs/documentation/gameplay-modules/bt-cookbook.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)
* [Concepts Overview](/flow-core-docs/documentation/core-concepts/concepts-overview.md)
* [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md)
* [BTRoot](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-root.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/behavior-tree-authoring.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.