Repository navigation
feat: Show the behavior tree of a component in the Flame devtools - #4103
Merged
Merged
Conversation
DevToolsConnector and DevToolsService are exported from flame/devtools.dart, and DevToolsService.registerConnector adds a connector from another package after the game was created, and tells it about the observed game. This is how a package built on top of Flame can expose its own service extensions to the devtools extension.
The name does not change how a node behaves. Tools use it to tell nodes apart, which makes a tree of Tasks and Conditions readable.
BehaviorTreeConnector registers the ext.flame_devtools.getBehaviorTree service extension, which describes the tree of a component, what each node returned last and the contents of the blackboard. It is registered the first time that a component with HasBehaviorTree is mounted in debug mode, so games without behavior trees do not get it.
When the selected component has a behavior tree, the extension shows the nodes and what each of them is doing, which refreshes live, and the blackboard.
Describe the new service extension, how to give nodes a name, and how the tree is shown in the devtools. The example names the nodes of its tree.
The named helper of the examples sets the name of the node, so that the examples and the Flame devtools show the same labels.
ufrshubham
force-pushed
the
devkage/behavior-tree-devtools
branch
from
October 6, 2026 18:41
ba7906d to
1a2a36d
Compare
The tree and the blackboard are next to each other when there is room, with their headings on the same row and the live controls at its end, and below each other otherwise. The text has the same sizes as the rest of the selected component, an empty blackboard says so, and the tick interval is only mentioned when the tree is not ticked on every update.
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
A selection change can permanently lose its refresh while live updates are disabled.
Review effort: Balanced
Findings: 1
Open (1)
What changed in this PR
Adds behavior-tree inspection to Flame DevTools, including live node states, names, tick intervals, and blackboard values.
Changes:
- Adds extensible DevTools connectors and behavior-tree service integration.
- Adds responsive behavior-tree and blackboard views with refresh controls.
- Adds node naming, tests, examples, and documentation.
| File | Description |
|---|---|
packages/flame/test/devtools/dev_tools_service_test.dart |
Tests dynamic connector registration. |
packages/flame/lib/src/devtools/dev_tools_service.dart |
Supports registering external connectors. |
packages/flame/lib/devtools.dart |
Exports connector APIs. |
packages/flame_devtools/test/behavior_tree_test.dart |
Tests snapshots, rendering, and layout. |
packages/flame_devtools/README.md |
Documents external connectors. |
packages/flame_devtools/pubspec.yaml |
Adds Flutter test support. |
packages/flame_devtools/lib/widgets/component_tree.dart |
Adds behavior-tree details. |
packages/flame_devtools/lib/widgets/behavior_tree_view.dart |
Renders trees and blackboards. |
packages/flame_devtools/lib/widgets/behavior_tree_section.dart |
Adds live snapshot polling. |
packages/flame_devtools/lib/repository.dart |
Calls the behavior-tree extension. |
packages/flame_devtools/lib/behavior_tree_snapshot.dart |
Models extension responses. |
packages/flame_behavior_tree/test/behavior_tree_connector_test.dart |
Tests serialization and registration. |
packages/flame_behavior_tree/README.md |
Documents DevTools debugging. |
packages/flame_behavior_tree/lib/src/has_behavior_tree.dart |
Registers the connector on mount. |
packages/flame_behavior_tree/lib/src/devtools/behavior_tree_connector.dart |
Exposes behavior-tree snapshots. |
packages/flame_behavior_tree/example/lib/main.dart |
Adds descriptive node names. |
packages/flame_behavior_tree/behavior_tree/test/node_test.dart |
Tests node names. |
packages/flame_behavior_tree/behavior_tree/README.md |
Documents node naming. |
packages/flame_behavior_tree/behavior_tree/lib/src/node.dart |
Adds optional node names. |
examples/lib/stories/bridge_libraries/flame_behavior_tree/common.dart |
Reuses node names in examples. |
doc/flame/other/debug.md |
Documents the service extension. |
doc/bridge_packages/flame_behavior_tree/flame_behavior_tree.md |
Documents naming and debugging. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…light When another component was selected while the tree of the previous one was being fetched, the refresh for the new selection was dropped, and the result of the running one was discarded because it was for another component. With the live updates off nothing asked again, so the section stayed hidden. The running refresh now fetches again when the selection changed in the meantime.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Makes the behavior tree of a component visible in the Flame DevTools, to help with debugging trees.
When a component that uses
HasBehaviorTreeis selected in the Flame tab, the extension shows itstree, what every node is doing, and the blackboard.
nodes have the color of the status they returned last (green for success, red for failure), and
grey nodes have not been ticked yet or were aborted. The view refreshes twice a second, and a
switch freezes it. The tick interval of the tree is shown as well.
How it works
flame_behavior_treehas a newBehaviorTreeConnector, which registers theext.flame_devtools.getBehaviorTreeservice extension. It is registered the first time acomponent with
HasBehaviorTreeis mounted in debug mode, so games without behavior trees getnothing registered, and nothing is registered in release mode. The service extension is
documented with the others in
doc/flame/other/debug.md.DevToolsConnectorandDevToolsServiceare now exported frompackage:flame/devtools.dart, andDevToolsService.registerConnectoradds a connector fromanother package after the game was created. This is the way for any package built on top of Flame
to expose its own information to the extension.
Nodehas a new optionalname, which does not change how a node behaves. The tree of a typicalgame is mostly
Tasks andConditions, which would all be shown as identical rows without names.It can be set with a cascade:
Condition((context) => ...)..name = 'is hungry?'. The examplesand the docs use it, and the examples app and the DevTools now show the same labels.
Demo
BehaviorTreeDevTools.mp4
Checklist
docsand added dartdoc comments with///.examplesordocs.Breaking Change?
Related Issues
Follow up to #4094 and #4095.