owl-bt

owl-bt is editor for Behavior trees. It has been inspired by Unreal engine behavior trees in a way, that it supports special node items like decorators and services. This makes trees smaller and much more readable.

Why

owl-bt has been created because we needed a behavior tree editor for our game Tendril: Echo Received, where we are focusing on live npc behavior.

We have tried some of the existing solutions, but they haven't meet our requirements like:

• focus on content and not on layout
• open format - we did not want to be bound to a specific game engine. For instance, we have created some of our game prototypes in Unity and the game itself is developed in MonoGame. In this way, we were able to take behavior trees from prototypes and use them directly in the game itself.
• ability to fully define item types
• to have fun developing it ;)

Install

npm install owl-bt -g

Usage

• help

owlbt -h

• Create a new project

cd <project-dir>
owlbt i

• Create a new tree (tree must be under an existing project)

owlbt c <tree-path>

• Open an existing tree

owlbt o path

Configuration

owl-bt runs as a service on port 8955 by default. This can be changed in config file .owlbtrc, that must be created in the user`s home directory.

{
	"port" : 1234
}

Tree items

In owl-bt, there are three types of items:

• Node - represents a single task that can be executed at once or in multiple ticks. Composite nodes may contain child nodes.
• Decorator - node sub item, that guards access to its node and transforms node's return value.
  • It is possible to mark decorator as periodic - represents, that the decorator should be reevaluated each tick, if its node is on the execution path.
• Service - node sub item, that executes a specific task at given times, if its node is on the execution path.

Features

• Automatic layout - In order to focus only on content creation, there is no option for manually layout the tree. Tree is laid out automatically.
• Keyboard control - Almost entire tree can be created and edited using just keyboard. owl-bt contains command palette as in Sumblime Text. It can be accessed through ctrl+shift+p

• Hot project reload - each change to project file is instantly updated in running editor instance. Therefore it is easy to define or update node items without reloading tree, that is currently being edited.

• Undo/redo - owl-bt supports undo/redo for all actions
• Json format - trees and project are stored as simple json files, which makes it easy to integrate with more or less any game engine

Project file

Project file (owl-bt.json) defines all nodes and node item types that can be used in trees.

Node

• name - (required) node type name
• base - item to inherit from
• isAbstract - whether to allow creating items of this type - mainly for inheritance purposes
• icon - node icon (name of the icon from font-awesome without fa- prefix)
• color - custom color (css syntax - e.g. '#bada55' or 'green')
• description - node description. It may contain placeholders for properties {{PropertyName}}
• isComposite - whether node may contain another child nodes
• properties - list of node properties (see property definition)

Decorator

• name - (required) decorator type name
• base - item to inherit from
• isAbstract - whether to allow creating items of this type - mainly for inheritance purposes
• icon - decorator icon (name of the icon from font-awesome without fa- prefix)
• color - custom color (css syntax - e.g. '#bada55' or 'green')
• description - decorator description. It may contain placeholders for properties {{PropertyName}}
• properties - list of decorator properties (see property definition)

Service

• name - (required) service type name
• base - item to inherit from
• isAbstract - whether to allow creating items of this type - mainly for inheritance purposes
• icon - service icon (name of the icon from font-awesome without fa- prefix)
• color - custom color (css syntax - e.g. '#bada55' or 'green')
• description - service description. It may contain placeholders for properties {{PropertyName}}
• properties - list of service properties (see property definition)

Property

• name - (required)
• default - default value
• type - type of the property
  • string
  • number
  • bool
  • enum
  • custom type defined in project file
• values- (required for enum type) - list of possible enum values
• min- (for number type) - min allowed value
• max- (for number type) - max allowed value

Types

Enables to define custom property types

• type - (required) base type for this custom type ['string' or 'number']
• pattern - regular expression for validation purposes

Example:

{
  "types":{
    "myString" : {
      "type" : "string",
      "pattern" : "v[0-9]"
    }
  },
  "nodes": [
    {
      "name": "SetAlertLevel",
      "icon": "exclamation",
      "description": "Set alert level to \"{{Level}}\"",
      "isComposite": false,
      "properties": [
        {
          "name": "Level",
          "default": "None",
          "type": "enum",
          "values": [
            "None",
            "Investigate",
            "HighAlert",
            "Panic"
          ]
        }
      ]
    }
  ],
  "decorators": [
    {
      "name": "HasZoneReportedEnemy",
      "icon": "phone",
      "properties": [
        {
          "name": "MaxReportAge",
          "default": 1,
          "type": "number"
        }
      ]
    }
  ],
  "services": [
    {
      "name": "ReadPlayerPos",
      "icon": "pencil",
      "description": "Store player pos to \"{{BlackboardKey}}\"",
      "properties": [
        {
          "name": "BlackboardKey",
          "default": "Target",
          "type": "string"
        }
      ]
    }
  ]
}

Tree file

{
	"type": "Selector",
	"name": "rootNode",
	"childNodes": [
		{
			"type": "Sequence",
			"services": [
				{
					"type": "Sample service"
				}
			],
			"decorators": [
				{
					"type": "IsBlackboardValueSet",
					"properties": [
						{
							"name": "Field",
							"value": "myValue"
						}
					],
					"periodic": true
				}
			]
		}
	]
}

Inheritance

It is possible to derive a node item type from another type using base setting.

It is possible to use string or array of strings for base setting. In case of array, base item types are applied in a specified order. That means, that the later item type overrides item specified before it.

E.q. we may create a base node:

{
      "name": "MyBaseNode",
      "icon": "arrow-right",
      "color": "red",
      "isAbstract" : true,
      "properties": [
        {
          "name": "prop-from-base1",
          "type": "string"
        },
        {
          "name": "prop-from-base2",
          "type": "number"
        }
      ]
    },

And derived node:

{
      "name": "MyDerivedNode",
      "color": "blue",
      "base": "MyBaseNode",
      "properties": [
        {
          "name": "prop1",
          "type": "string"
        },
        {
          "name": "prop-from-base2",
          "default" : "abc",          
          "type": "string"
        }
      ]
    },

Resulting node after applying inheritance is going to look like:

{
      "name": "MyDerivedNode",
      "icon": "arrow-right",      
      "color": "blue",
      "base": "MyBaseNode",
      "properties": [
        {
          "name": "prop-from-base1",
          "type": "string"
        },
        {
          "name": "prop-from-base2",
          "default" : "abc",          
          "type": "string"
        },
        {
          "name": "prop1",
          "type": "string"
        }
      ]
    },

Plugins

owl-bt.js file in the same directory as project file owl-bt.json is considered plugin. Plugin js file exports object with plugin functions.

module.exports = {
	onTreeSave: ({ tree, path, project, projectPath }) => {
	},
	onTreeLoad: ({ tree, path, project, projectPath }) => {
	}
}

• onTreeSave - executed before the tree json file is saved to disk. Only modifications of tree object are allowed.
  • tree - tree object (according to tree json file)
  • path - tree file path
  • project - project object (according to owl-bt.json file)
  • projectPath - project file path
  • return - when the return value is false or a string, then the save is prevented and error is returned to client
• onTreeLoad - executed after loading tree json file from disk. Only modifications of tree object are allowed.
  • tree - tree object (according to tree json file)
  • path - tree file path
  • project - project object (according to owl-bt.json file)
  • projectPath - project file path

It is possible for example to create a custom tree file formats using onTreeSave and onTreeLoad. If we wanted to have project path stored in the tree file, we could create the following plugin:

module.exports = {
	onTreeSave: ({ tree, path, project, projectPath }) => {
		tree.projectPath = projectPath;
	}
}

Changelog

1.1.0

• Add support for tree item type inheritance - see base and isAbstract properties in project definition
• Add support to override tree item type color
• Add support to remove items from MRU list
• Add support to modify tree before save and after load through plugins
• Prevent save of tree when current node item has validation errors in property editor
• Add support for custom property types
• Add item color to new item selection dialog
• Add item palette side panel
• Make side panels collapsible

1.2.0

• Add support for multiple base types. Thanks to dauryg
• Add save success notification message

1.3.0

• Add support to prevent save of a tree in plugin
• Add reloading of plugins
• Prevent losing values of invalid properties in property editor form
• Add highlighting of all tree items with invalid properties
• Add save confirmation before saving a tree with invalid properties

2.0.0

• Add option to change type of an existing node. (ctrl+shift+p->'core:Set Node Type' or rmb->'Set Node Type')
• (breaking change): Fontawesome upgraded to 5.*
• (chore): Convert from Grunt+Bower+Karma to Webpack+Jest

2.1.0

• Add custom label to node items
• Add comment to node items