Skip to content

VS Code extension for behavior tree modeling and visualization.

Notifications You must be signed in to change notification settings

jan-dolejsi/vscode-btree

Repository files navigation

VS Code Behavior Tree editor

CI/CD

Behavior trees are a technique used in video games and robotics to model behavior AI. Their use has become increasingly popular due to their simple implementation, ease of understanding, and flexibility.
This extension provides visualization of trees authored in the language suggested by Dan Abad's behavior_tree project.

Specifying behavior trees in a declarative concise way gives you these benefits:

  • the model is very readable; a subject matter expert can review it for correctness
  • the implementation of action logic is separate (see SoC)
    • the logic is testable
    • implementation may evolve separately
    • new version of the tree may be deployed without pushing any code changes (which are inherently more difficult to validate and verify)

Features

Behavior Tree Visualization and Testing

Open a *.tree that adheres to the syntax.
Right-click on the editor text and select Preview or invoke the Open Preview to the Side command.

Note that for the preview options to be visible, the file has to be saved.

Dense trees with longer action/condition names may be stretched using Shift + Mouse Wheel. Here are other ways to manipulate the view:

Tree Manipulation Gesture
Pan Hold left mouse button and move
Zoom Mouse Wheel
Horizontal Stretch Shift + Wheel
Vertical Stretch Shift + Alt + Wheel

Double-click on a condition node to toggle its state between _success/failed.
Double-click on an action node to switch its state between running/success/failed. Hold the shift key to transition from running to failed.

Tree visualization and state changes

Behavior Tree Editing

Enable the editor.formatOnType in your VS Code settings. This enables following behaviors:

  • When you type |, white-space corresponding to one tab (per your configuration) is inserted
  • When you press [Tab], one tree indentation level is inserted (when multiple lines are selected or while your cursor is in the indentation part of the code line)
  • When you press [Enter], the same indentation is inserted to the new line. In addition, if you pressed enter after ->, ? or =N nodes, additional level is added.
  • When you press [Backspace] one level of indentation is removed
  • When you press Ctrl+[ or Cmd+[, the active row (or all selected rows) are indented +1 level
  • When you press Ctrl+] or Cmd+], the active row (or all selected rows) are un-indented -1 level

Tree editing

You can enable the on-type formatting selectively just for the Tree language and/or just for one workspace using the settings.json in your workspace .vscode or in your global user settings:

{
    "[tree]": {
        "editor.formatOnType": true
    }
}

Action and Condition name validation

When authoring larger trees, or multiple trees in one folder, it becomes hard to keep the names of all conditions and actions in sync across multiple files.

This extension works with the concept of tree workspace, which consists of a directory containing one ore more .tree files and an optional btrees.json file. The btrees.json structure is expected as follows:

{
  "actions": {
    "action1": {},
    "action2": {},
  },
  "conditions": {
    "Condition XYZ": {}
  }
}

Where both the actions and conditions are optional. However, once the actions / conditions property is created, VS Code starts flagging all undeclared actions and conditions in all the trees in the directory. The undeclared actions may be added by simply invoking the code action (via the light bulb icon).

Declaring action and condition names

The empty {} structures in the json sample above are free form so far. It may be used for documentation, or bindings to the system you want to automate with the trees.

This feature is available as opt-in. Create/delete the btrees.json and/or the actions and/or condition nodes within to opt in or out of the action/condition name validation.

The format of the file is JSON, so the same file may be used by other parts of the system to statically validate the system at continuous integration time or at start of execution.

As a special case, action names that match name of another behavior tree file in the same folder (but without the .tree extension) are implicitly added to the list of declared actions.

Action and Condition definition and references

The Action and Condition nodes in trees support the Go to Definition feature via context menu, F12 key, or Control+Click. If the directory contains the btrees.json, the editor will jump to the corresponding action/condition element in the JSON structure. If the btrees.json is not present, the editor shows all references instead (as there is no one clear definition point).

The Action and Condition tree nodes support the Go to References and Find all References in the context menu. References across all trees in the same directory are shown.

Go to definition, show references

Release Notes

See CHANGELOG.md.

About

VS Code extension for behavior tree modeling and visualization.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published