idered / behavior-tree

🌲 Manage React state with Behavior Trees

JavaScript/TypeScript implementation of Behavior Trees.

📕 Read the documentation to learn the API.

Note: This software is in early development stage. It's not production ready. API may change.

Behavior Tree Toolkit

• 🌲 @btree/core - Framework agnostic behavior trees implementation
• ⚛ @btree/react - Hooks and docs how to use BT with React

Quick start

npm install @btree/core

import {nodes} from '@btree/core'

const initialState = {
  isLoggedIn: false
}

const AuthBehavior = nodes.root('Auth behavior', () =>
  /* Selector runs child one by one until one of them succeeds */
  nodes.selector([
    /* Sequence runs child one by one and stops if any child return failure status */
    nodes.sequence([
      /* Condition node run logic checks on current state */
      nodes.condition('Is logged in', (state, props) => state.isLoggedIn),
      /* Action node is used for side effects and state modifications */
      nodes.action('Redirect to dashboard', (state, props) => {
        navigate('/dashboard')
      }),
    ]),
    nodes.sequence([
      nodes.action('Redirect to login page', () => {
        navigate('/login')
      }),
    ]),
  ])
)

// Create instance of tree
const authTree = AuthBehavior(initialState)

// Run tree logic
authTree.tick()

// You can also run it with props
authTree.tick({authKey: 'xyz'})

Why?

Getting app features done is cool but what about future changes? As time passes, you will forgot how given feature works. Writing comments or docs is not something that developers have in mind all the time. This library will handle that for you.

With Behavior Tree notation all your code will be wrapped with nodes - that allows to visualize how it works. Check /packages/react/example for implementation of this logic.

behavior-tree's Issues

Create TodoMVC

Creating TodoMVC example will help spotting potential bugs. It will also help to determine good use cases for behavior trees - because you probably should not use it everywhere, right?

Add tests

Without a suit of tests, this should not be used in production.

Move DevTools to browser extension

Currently DevTools is just a React component and it has some cons:

• It's unusable in pure JS environment
• You need to add it to your app tree
• It can collide with application UI

Browser extension like React DevTools would be a perfect solution.

Custom nodes - plugins

All current nodes should be in form of a plugin.

Example: nodes.sequence() returns an object without function to interpret it. If we want pluggable nodes then it should contain interpretation logic.

Here are some ideas after pluggable nodes will be implemented:

1. Move default nodes to separate package @btree/nodes
2. @btree/core should only contain functions for creating nodes and executing tree
3. Allow people to create custom set of nodes
4. Default nodes implementation should be optional
5. If default nodes will be in separate package then nodes.root should not be a node but a normal function eg. createTree - it should be in core package.

Implementing this is crucial for library future. People have different needs and there's no way to fulfill them all. With solid plugin system we could keep this lib alive.

Alternative names

selector - or
sequence - and
condition - if
action - do

useTree - useBehavior as suggested in HN comment

Selector, sequence is typical naming for behavior trees but might be a little hard to understand for beginners.

Add portals documentation

nodes.portal is missing documentation.