Import & export formats

The Behavior Tree Editor supports three interchange formats: native JSON, generic XML, and BehaviorTree.CPP XML. Each has different strengths depending on your workflow — whether you're sharing trees with teammates, integrating with a C++ runtime, or version-controlling in Git.

Format comparison

* BTCPP XML may lose editor-specific metadata like node position and canvas zoom level.
** BTCPP uses a different port system (input/output vs. typed ports).

1. JSON (native format)

This is the editor's default format. It preserves every detail of your tree including node positions, port values, custom types, and layout preferences. Use JSON when:

• You want perfect round-trip editing (export → edit → re-import)
• You're storing trees in a database or API
• You need compact file sizes for network transfer
• You're using a JavaScript/TypeScript runtime

Schema structure

{
  "root": {
    "name": "Sequence",
    "type": 0,
    "children": [
      {
        "name": "IsEnable",
        "type": 3,
        "ports": {}
      },
      {
        "name": "Wait",
        "type": 1,
        "ports": {
          "duration": 2.0
        }
      }
    ]
  },
  "metadata": {
    "canvasZoom": 1.0,
    "canvasOffset": { "x": 0, "y": 0 },
    "layoutMode": "horizontal"
  }
}

Node type codes

• 0 — Composite nodes (Sequence, Selector, etc.)
• 1 — Action nodes (Wait, MoveTo, etc.)
• 2 — Decorator nodes (Inverter, Repeater, etc.)
• 3 — Condition nodes (IsEnable, IsBatteryLow, etc.)

Best practices

• Store the full JSON object (including metadata) to preserve visual layout
• Use consistent naming conventions for nodes (PascalCase recommended)
• Version your JSON schema if you extend it with custom fields

2. XML (generic format)

The generic XML format provides a human-readable, language-agnostic representation. It's suitable when:

• You need to integrate with non-JavaScript systems
• Your team prefers XML-based configuration
• You're working with legacy tools that expect XML

Example output

<behavior_tree>
  <node type="Sequence" name="PatrolIfSafe">
    <node type="Condition" name="IsEnable" />
    <node type="Action" name="Wait">
      <port name="duration" value="2.0" />
    </node>
  </node>
</behavior_tree>

Limitations

• Canvas metadata (zoom, offset) is not preserved
• Custom node libraries must be imported separately
• No standard schema — implementation-dependent

3. BehaviorTree.CPP XML

BehaviorTree.CPP is a popular C++ library for behavior trees. Its XML format is widely used in robotics (ROS, ROS2) and game development. Use this format when:

• You're deploying trees to a C++ runtime
• You need compatibility with ROS Navigation Stack
• You're collaborating with teams using BT.CPP

Example output

<root main_tree_to_execute="MainTree">
  <BehaviorTree ID="MainTree">
    <Sequence name="PatrolIfSafe">
      <Condition ID="IsEnable" />
      <Action ID="Wait" duration="2.0" />
    </Sequence>
  </BehaviorTree>

  <TreeNodesModel>
    <Condition ID="IsEnable" />
    <Action ID="Wait">
      <input_port name="duration">Duration in seconds</input_port>
    </Action>
  </TreeNodesModel>
</root>

Key differences from native JSON

• TreeNodesModel: BT.CPP requires explicit node registration in a model section
• Port types: BT.CPP distinguishes input/output ports; the editor uses a unified port system
• ID vs. name: BT.CPP uses ID attributes for node types and name for instances

Mapping rules

Round-tripping between formats

You can convert between formats, but be aware of potential data loss:

JSON → BTCPP XML → JSON

1. Export as BTCPP XML from the editor
2. Edit the XML externally (e.g., add ROS-specific parameters)
3. Re-import the BTCPP XML into the editor

⚠️ Canvas layout (node positions, zoom level) will be lost. Custom node libraries must be re-imported manually.

BTCPP XML → JSON → BTCPP XML

1. Import a BT.CPP XML file into the editor
2. Make visual edits (rearrange nodes, adjust ports)
3. Export back to BTCPP XML

✅ This workflow preserves all functional aspects of the tree. The generated XML will be valid for BT.CPP runtimes.

Import best practices

• Validate before importing: Use an XML validator or JSON linter to catch syntax errors
• Backup your canvas: Export your current tree before importing a new one
• Check node compatibility: Ensure all node types in the imported file exist in your current library
• Test after import: Verify the tree structure and port values match expectations

Export best practices

• Name your trees: Use descriptive root node names for clarity in exported files
• Document custom nodes: Include comments or documentation links for non-standard node types
• Version control: Commit JSON/XML files to Git with meaningful commit messages
• Automate exports: Use the editor's keyboard shortcuts (Ctrl/Cmd + S) for quick saves during iteration

Troubleshooting

Import fails with "Invalid JSON"

• Check for trailing commas in arrays or objects
• Ensure all strings are double-quoted (not single-quoted)
• Verify the file encoding is UTF-8

BTCPP XML import shows missing nodes

• Confirm the node IDs in the XML match registered types in the editor
• Import custom node libraries first via Import Nodes button
• Check the TreeNodesModel section for type definitions

Port values disappear after round-trip

• Some formats don't preserve port metadata — use JSON for full fidelity
• Verify port names match exactly (case-sensitive in most formats)
• Check for type mismatches (string vs. number vs. boolean)

Related resources

• Define custom node types — extend the library with domain-specific nodes
• Interop with BehaviorTree.CPP — advanced integration patterns
• Live monitor via WebSocket — stream tree execution in real-time

← Node types Log replay →

Last updated: 2026-07-16