BehaviorTree Studio is a visual editor for BehaviorTree.cpp XML. It uses a workspace-based workflow, a shared subtree library, and an interactive canvas for building and editing behavior trees.
- Creates and edits BehaviorTree.cpp v4 XML files
- Maintains a shared subtree library for reuse across tree files within workspace
- Provides a drag-and-drop editor with node/subtree properties and variables
- Supports undo/redo and switching between the main tree and subtrees
Open a workspace folder that contains tree XML files or start with a blank folder. The app creates and uses a shared library file named subtree_library.xml inside the workspace folder to store reusable subtrees.
Each XML file contains a main tree plus optional subtrees. The main tree is exported with the tag main_tree_to_execute and an ID matching its initial filename to match BehaviorTree.cpp expectations. Subtrees are referenced by name and are defined as additional <BehaviorTree> elements in the same file.
The library is the ground truth for shared subtrees. When you save, the current file is saved, the library is updated, and any other files within your workspace that reference those subtrees are updated as well.
- Node.js 22+ recommended
- npm (ships with Node.js)
- macOS 14+ or Linux
- ARM64 or AMD64
npm installnpm run electron:devThis starts the Vite dev server and the Electron shell together. The app will open automatically.
npm run buildnpm testRuns the Vitest test suite (XML serializer, workspace store, node library, selection helpers). Use npm run test:watch for watch mode.
- Use File → Open Workspace.
- Choose a folder that contains tree XML files.
- The app will load or create
subtree_library.xmlin that folder.
- Use File → Open Tree to open an existing XML file.
- Use File → New Tree to create a new tree file. The main tree ID is set to
main_tree_to_executeautomatically.
- Drag nodes from the Node Palette (left) onto the canvas.
- Click a node to edit its fields and optional node name.
- Use the Variables panel (right) to manage local variables for the active tree.
- Switch to the Subtree Library tab in the palette to view and create subtrees.
- When creating a subtree, optionally pick a custom color and description. The color and description are stored in an XML comment so it does not interfere with BehaviorTree.CPP.
- Drag a subtree onto the canvas to insert it into the active tree. Subtrees with a custom color display that color in both the palette and the canvas.
- Click a subtree in the top navigation bar to edit it.
- Existing trees can be imported as subtrees.
- Use File → Save or the standard shortcut (Cmd+S / Ctrl+S).
- Saving writes the current file, updates the subtree library, and updates other files that reference the same subtrees.
- Use File → Export Tree… or the shortcut (Cmd/Ctrl+E) to save a copy of the current working tree.
- The app shows a native Save dialog (choose location); the exported file is written as a copy and the active file in the editor is not opened or changed.
- In the workspace the export includes the main tree plus embedded subtrees; in the web UI it uses a download or the File System Access API.
- Right sidebar → Add variable (e.g., "counter", number, 0)
- Drag "Set Variable" to canvas
- Click node → Set variable_name field
- Toggle "value" field to Variable mode
- Select variable from dropdown
- Search bar: Filter nodes by name/description
- Category buttons: Filter by node type
- Drag nodes onto canvas to add them
- Nodes tab: Nodes and subtree nodes
- Library tab: Workspace subtrees
- Drop zone for nodes from palette
- Connect nodes by dragging handles
- Zoom/pan controls in bottom-left corner
- Click nodes to select and edit
- Add new variables with type
- Edit initial values inline
- Delete unwanted variables
- Appears when node selected
- Shows node info (type, category, ID)
- Edit field values
- Toggle Literal ↔ Variable
- Set custom node names
- Zoom: Mouse wheel or controls in bottom-left
- Pan: Click and drag on background
- Select node: Click on node
- Delete: Select node and press Delete key
- Deselect: Click on background
- Toggle: Click the BoxSelect button in the canvas toolbar, press Cmd/Ctrl+B, or hold Shift while dragging.
- Copy: Cmd/Ctrl+C copies selected nodes and edges fully contained within the selection.
- Paste: Cmd/Ctrl+V pastes the clipboard with an offset. The clipboard persists across subtree tabs within the current workspace session.
- Delete: Delete or Backspace removes selected nodes (the root node is always protected) and their connected edges.
- Save: Cmd+S / Ctrl+S
- Undo: Cmd+Z / Ctrl+Z
- Redo: Cmd+Shift+Z / Ctrl+Shift+Z
- Toggle box select: Cmd+B / Ctrl+B
- Copy selection: Cmd+C / Ctrl+C
- Paste selection: Cmd+V / Ctrl+V
- Delete selection: Delete or Backspace
- Restart: Cmd+R / Ctrl+R (reloads window and closes file without saving)
- 🟥 Root (Red): Entry point for behavior tree
- 🟧 Control (Orange): Sequence, Fallback, Parallel
- 🟪 Decorator (Purple): Inverter, Retry, Repeat, Timeout
- 🟩 Action (Green): PrintMessage, SetVariable, Delay
- 🟦 Condition (Blue): CheckVariable, CompareNumbers
- 🟦 SubTree (Cyan or Custom): Reusable subtree instances
Node names are exported as the name attribute in BehaviorTree.cpp XML format:
<Sequence name="MainLoop">
<Action name="MoveForward"/>
<Condition name="CheckObstacle"/>
</Sequence>- This app targets BehaviorTree.cpp v4 XML format.
- This does not interoperate with Groot2 projects.
- There is no automatic save; use File -> Save.
- Node names use the standard BehaviorTree.cpp
nameattribute. - Blackboard is NOT shared between subtrees; use ports for data passing.
- Be prepared to dive into XML when necessary; renaming and other refactoring functions are not in the GUI.
- Be careful when making edits to the XML outside of BTstudio as it can lead to unexpected behavior.
- Developer details: PROJECT.md
- Extending the app: CUSTOMIZATION.md