blueshell
v5.1.0
Published
A Behavior Tree implementation in modern Javascript
Downloads
1,276
Readme
Blueshell
Blueshell is a Behavior Tree implementation written in Typescript.
It is synchronous for performance - asynchronous operations can be handled by returning async operations to your framework for evaluation, these can then generate new events to drive the behavior tree.
Node Types
Actions (aka Tasks or Execution Nodes)
Action
- Handles the event normally and must return a result
Predicate
- Executes a provided synchronous function (
(state, event) => boolean
) and returnsSUCCESS
orFAILURE
based upon the boolean result of such function.
SideEffect
- Executes a provided synchronous function (
(state, event) => void
) and always returnsSUCCESS
.
Success
- Immediately returns
SUCCESS
when activated.
Composites (aka Control Flow Nodes)
Selector
(aka Priority or Fallback)
- Sends an event to each child until one of them returns
SUCCESS
orRUNNING
, then returns that value. - If we exhaust all the children, return
FAILURE
.
LatchedSelector
- Sends an event to each child until one of them returns
SUCCESS
orRUNNING
, then returns that value. - If we exhaust all the children, return
FAILURE
. - If a child returns
RUNNING
, subsequent events start at that child.
Sequence
- Sends an event to each child until one of the returns
FAILURE
, orRUNNING
, then returns that value. - If all children return
SUCCESS
, returnSUCCESS
.
LatchedSequence
- Sends an event to each child until one of the returns
FAILURE
, orRUNNING
, then returns that value. - If all children return
SUCCESS
, returnSUCCESS
. - If a child returns
RUNNING
, subsequent events start at that child.
IfElse
- Accepts a
conditional
function aconsequent
node, and an optionalalternative
node. - If
conditional(state, event)
returns true, will return the result of activating theconsequent
node. - If
conditional(state, event)
returns false, will return the result of activating thealternative
node, if one is provided. - If
conditional(state, event)
returns false, will returnFAILURE
if noalternative
node is provided.
Decorators
Decorators intercept and can modify the event sent to or the result from the child.
Not
- Returns 'FAILURE' when the child returns 'SUCCESS', and vice-versa
RepeatWhen
- Repeats the child when an evaluation function returns true.
RepeatOnResult
- Repeats the child if it returns the specified status.
ResultSwap
- Allows you to swap one result of a child node for another.
- For example, you can use this to mask
FAILURE
asSUCCESS
.
Base Classes
Base
- The base of all nodes.
Composite
- The base class for all nodes which have children.
Decorator
- The base class for decorators.
- Can only have one child.
Publishing
- The publisher can be registered with the tree which will log each transition.
Inspiration and Further Reading
The following are sources used when designing this library
- Handling Node Traversal
- Difference between a Decision Tree and a Behavior Tree
- Behavior Trees for AI
- Wikipedia Article
- What is a Behavior Tree?
- Halo 2's AI
- Halo 2 was the first game to popularize Behavior Trees.
Name
Blueshell
is named for a Skroderider from the novel A Fire Upon the Deep
by Vernor Vinge. Skroderiders are intelligent plants (trees) that use mechanical constructs to give them locomotion
and short-term memory.
In other words, Blueshell
is an intelligent tree. Or a tree with behavior. Get it?