# Flow, FSM, and BT Patterns

Level: Intermediate

## Goal

Choose clear responsibilities for Flow, FSM, and BT so a graph can combine sequencing, long-lived state, and priority decisions without becoming tangled.

## When To Use This

Use this page when a behavior is larger than one chain. Typical examples include combat AI, interaction modes, UI flows, character states, or gameplay systems that need both event sequencing and ongoing decisions.

If you only need a single event sequence, use Flow. If you only need a simple priority choice, start with a BT branch. Add FSM when the object has a mode that lasts over time and changes which logic is allowed to run.

## Decision Guide

| Need                                                                      | Prefer | Reason                                                       |
| ------------------------------------------------------------------------- | ------ | ------------------------------------------------------------ |
| Run ordered steps, waits, side effects, signals, or handoff logic.        | Flow   | Flow is easiest to read as "what happens next."              |
| Represent a long-lived mode such as Patrol, Combat, Dialogue, or Stunned. | FSM    | FSM makes active mode explicit and controls entry/exit.      |
| Choose the best valid option from several candidates.                     | BT     | BT child order, composites, and conditions express priority. |
| Temporarily layer modes such as pause menu or input override.             | Stack  | Stack owns top-only update and push/pop lifecycle.           |
| Plan a multi-step route from current facts to a desired fact state.       | GOAP   | GOAP searches actions from boolean facts and costs.          |

Do not force one module to own every responsibility. Flow Core works best when each module has one job and returns control through clear outputs.

## Mental Model

Flow is the conductor. It starts work, passes data, waits, calls instructions, and reacts to results.

FSM is the mode owner. It answers "which state family is active right now?" and runs entry, active, transition, and exit behavior.

BT is the decision owner. It answers "which child should run now?" and returns Success, Failure, Abort, or Invalid back to Flow.

Blackboard is the shared language. Flow, FSM, and BT should communicate with stable keys rather than hidden assumptions inside one node.

## Pattern 1: Flow Drives FSM, FSM Embeds BT

Use this for AI or character behavior where the actor has long-lived modes and each mode may need decisions.

Typical shape:

1. Flow receives a Trigger or Entry, such as `StartAI` or `EnemySeen`.
2. Flow activates an `FsmState` such as `Patrol`, `Combat`, or `Dialogue`.
3. The FSM state uses Graph mode for its active logic.
4. The state subgraph contains a `BTRoot` for priority decisions inside that state.
5. `BTRoot` Success or Failure returns to Flow or to state-level transition logic.

Example: Flow activates `Combat`. The Combat state owns enter and exit effects. Inside Combat, a BT chooses Attack, Chase, Reload, or Take Cover.

Authoring rule: FSM owns whether Combat is active. BT owns what Combat does next. Flow owns the visible handoff and side effects.

## Pattern 2: BT Chooses Intent, Flow Performs Effects

Use this when a BT should make the decision, but the result needs timed animation, sound, UI, camera, or multi-system side effects.

Typical shape:

1. Flow activates `BTRoot`.
2. BT selects an intent such as Attack, Flee, Interact, or Idle.
3. The selected leaf writes an intent key to Blackboard or routes through a result output.
4. `BTRoot` returns Success to Flow.
5. Flow reads the intent and runs the visible sequence.

This keeps the BT short and readable. It also prevents long timelines from being hidden inside BT leaves.

## Pattern 3: Flow For UI Or Timeline, BT For AI

Use this when UI, cutscenes, tutorials, or interaction flows need predictable sequencing while AI continues to make decisions elsewhere.

Typical split:

* Flow handles button events, transitions, waits, dialogue beats, or timeline-like steps.
* BT handles AI choices such as target selection, movement choice, or fallback behavior.
* Blackboard carries shared facts such as `PlayerInMenu`, `DialogueActive`, `TargetVisible`, or `CanAttack`.

If a UI Flow needs to pause AI decisions, write a Blackboard fact or disable the relevant root through a supported control path. Avoid making UI nodes directly rewrite the internal structure of the AI tree.

## Pattern 4: FSM Families With Exclusive And Parallel States

Use `Exclusive` when only one state in a group should be active. Use different `FSM Group ID` values when two state families should coexist.

Typical setup:

| State family  | Group ID     | Policy                | Example                              |
| ------------- | ------------ | --------------------- | ------------------------------------ |
| Locomotion    | `Locomotion` | Exclusive             | Idle, Walk, Run, Jump                |
| Upper body    | `UpperBody`  | Exclusive or Parallel | Aim, Reload, Gesture                 |
| Ambient logic | `Ambient`    | Parallel              | Breathing, idle look, sensor updates |

The empty `FSM Group ID` is the default group. Leave it empty only when those states really belong to the same family.

Authoring rule: do not read `Parallel` as "transition overlap." A direct `A -> B` transition still waits for `A.Exit` before `B.Enter`.

## Verify The Composition

* Each module has one responsibility written near the graph section.
* Flow paths into FSM or BT roots are visible and intentional.
* `BTRoot` Success and Failure return somewhere useful.
* FSM state names and group IDs are stable.
* Shared facts are explicit Blackboard keys.
* Debug Context is set before reading summaries or visual debugging.
* One visible Play Mode result works before adding another module layer.

## Common Failure Modes

| Symptom                                  | Likely cause                                                | Fix                                                                       |
| ---------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
| Behavior is hard to debug.               | Flow, FSM, and BT all own the same decision.                | Pick one owner and route the result back to the others.                   |
| BT keeps restarting a long action.       | Reactive decision logic is interrupting timeline work.      | Move the timeline to Flow or protect the BT child with the right pattern. |
| State changes cancel unrelated behavior. | Multiple state families share the same FSM group.           | Give independent families different `FSM Group ID` values.                |
| Subgraph Triggers seem silent.           | The subgraph activation window is not active.               | Start the owning Flow/FSM/BT path before expecting its Trigger to fire.   |
| UI logic changes AI unexpectedly.        | UI Flow writes shared facts without a clear ownership rule. | Name the Blackboard fact and document which module may write it.          |

## Related

* [Behavior Tree Authoring](/flow-core-docs/documentation/gameplay-modules/behavior-tree-authoring.md)
* [BT Cookbook](/flow-core-docs/documentation/gameplay-modules/bt-cookbook.md)
* [BT Debugging](/flow-core-docs/documentation/troubleshooting/bt-debugging.md)
* [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md)
* [Design Levers](/flow-core-docs/documentation/core-concepts/design-levers.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/flow-fsm-bt-patterns.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.