s-kania/def-behavior-tree/def_behavior_tree
Event-driven behavior trees for NPC logic. Register node templates once with
registerTemplates, create a tree over a payload with new, and call run: each
node moves on only when the one before it reports success or failure, and a tree can
start from any node id, so an active node saved with a game can be resumed on load.
- GitHub: s-kania/def-behavior-tree — pinned to
1.0.0- Pick a release from s-kania/def-behavior-tree releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as def_behavior_tree from "def_behavior_tree.behavior_tree"
- Pick a release from s-kania/def-behavior-tree releases and add its Source code (zip) URL (or a packaged
Functions
new(2 overloads)
<P>(config: { tree_name: string; payload: P; rng?: (this: void, range_start: number, range_end: number) => number; }): BehaviorTree<P>Creates a tree that runs a registered tree template over a payload. Register the templates with
registerTemplatesfirst.Parameters
config:{ tree_name: string; payload: P; rng?: (this: void, range_start: number, range_end: number) => number; }—tree_namenames a tree under the templates'TREES,payloadis passed to every task callback, andrngreturns a whole number between its two arguments forRandomandRandomWithChances; it defaults tomath.random.tree_name:stringpayload:Prng?:(this: void, range_start: number, range_end: number) => number
Returns
BehaviorTree<P>
(config: { tree_name: string; payload?: undefined; rng?: (this: void, range_start: number, range_end: number) => number; }): BehaviorTree<undefined>Creates a tree that runs a registered tree template with no payload, so its task callbacks receive
undefined. Register the templates withregisterTemplatesfirst.Parameters
config:{ tree_name: string; payload?: undefined; rng?: (this: void, range_start: number, range_end: number) => number; }—tree_namenames a tree under the templates'TREES, andrngreturns a whole number between its two arguments forRandomandRandomWithChances; it defaults tomath.random.tree_name:stringpayload?:undefinedrng?:(this: void, range_start: number, range_end: number) => number
Returns
BehaviorTree<undefined>
Variables
Task: NodeType<'Node'>
The lowest-level node, which has no children and runs your behavior code through
its template's start, run and finish. Its type name is "Node".
Composite: NodeType<'Composite'>
The archetype the four composites build on. Not a template type itself: use
Sequence, Selector, Random or RandomWithChances.
Sequence: NodeType<'Sequence'>
A composite that runs its children in order, the next one when the last succeeds. It fails as soon as a child fails, and succeeds when the last child succeeds.
Selector: NodeType<'Selector'>
A composite that runs its children in order, the next one when the last fails. It succeeds as soon as a child succeeds, and fails when every child fails.
Random: NodeType<'Random'>
A composite that runs one child picked at random, by the tree's rng over
1 to the child count, and reports that child's result.
RandomWithChances: NodeType<'RandomWithChances'>
A composite that runs one child picked by weight: the tree's rng draws from 1 to
100, and each child's chance is its share of that range, so the chances should
add up to 100. To weight a node registered by name, wrap it in a ChanceDecorator.
Decorator: NodeType<'Decorator'>
The archetype the five decorators build on. Not a template type itself: use one of the decorators.
InvertDecorator: NodeType<'InvertDecorator'>
A decorator that reports the opposite of its child's result.
AlwaysFailDecorator: NodeType<'AlwaysFailDecorator'>
A decorator that fails whatever its child reports.
AlwaysSucceedDecorator: NodeType<'AlwaysSucceedDecorator'>
A decorator that succeeds whatever its child reports.
RepeatUntilFailDecorator: NodeType<'RepeatUntilFailDecorator'>
A decorator that runs its child again each time it succeeds, and succeeds once the child fails. A good root node.
ChanceDecorator: NodeType<'ChanceDecorator'>
A decorator that passes its child's result through, so a node registered by name
can carry a chance inside a RandomWithChances.
registerTemplates: <P>(templates: Templates<P>) => void
Registers the tree templates, giving every node of each tree under TREES its own
id. Call it once, before new creates any tree.
getTreeTemplate: (treeName: string) => TreeNode[] | undefined
Returns a registered tree template's nodes, indexed by node id.
Registry: { registerTemplates<P>(this: void, templates: Templates<P>): void; getTreeTemplate(this: void, treeName: string): TreeNode[] | undefined; getNodeFromTree(this: void, id: number, treeName: string): TreeNode | undefined; }
The registry the tree templates are stored in.
Types
type TaskCallback<P> = (this: void, task: TaskControl, payload: P) => void
type NodeTemplate<P, Ref extends string = string> = TaskTemplate<P> | CompositeTemplate<P, Ref> | DecoratorTemplate<P, Ref>
type Templates<P> = NamedTemplates<P> | InlineTemplates<P>
NodeType
NodeType<Name extends string = string>
NodeType.name: Name
BehaviorTree
BehaviorTree<P = unknown>
BehaviorTree.run(activeNodeID?: number)
Starts the tree at a node. Does nothing while the tree is running.
Parameters
activeNodeID?:number— The id of the node to start at. Defaults to1, the root.
BehaviorTree.restart(activeNodeID?: number)
Starts the tree at a node whether or not it is running.
Parameters
activeNodeID?:number— The id of the node to start at. Defaults to1, the root.
BehaviorTree.setActiveNode(node: TreeNode)
Sets the node the tree is at, without running it.
Parameters
node:TreeNode— A node of this tree.
BehaviorTree.getNode(nodeID: number): TreeNode | undefined
Returns a node of this tree by id.
Parameters
nodeID:number— The node's id.
Returns
TreeNode | undefined
BehaviorTree.success()
Finishes the root node and stops the tree. Called when the root succeeds.
BehaviorTree.fail()
Finishes the root node and stops the tree. Called when the root fails.
BehaviorTree.getRandomBetween(x: number, y: number): number
Returns a number from the tree's rng.
Parameters
x:number— The low end of the range.y:number— The high end of the range.
Returns
number
BehaviorTree.name: string
The registered tree this tree runs, from config.tree_name.
BehaviorTree.payload: P
The payload every task callback receives.
BehaviorTree.running: boolean
Whether the tree is running: set by run and restart, cleared when the root finishes.
BehaviorTree.activeNode: TreeNode | undefined
The node the tree is at, unset until the first run or restart. Save its id to resume later.
BehaviorTree.rng: (this: void, x: number, y: number) => number
The number generator Random and RandomWithChances draw with.
TreeNode
TreeNode.id: number
The node's id in its tree, from 1 at the root. Pass it to run or restart.
TreeNode.name: string
The template's name for a node registered under NODES, followed by
| <type name> for one that is not a task; the type name for an inline node.
TreeNode.type: NodeType
The node's type.
TreeNode.chance?: number
The template's chance, if it gave one.
TreeNode.nodes?: TreeNode[]
A composite's children.
TreeNode.node?: TreeNode
A decorator's child.
NamedTemplates
NamedTemplates<P>
NamedTemplates.TREES: Record<string, { main_node: string | NodeTemplate<P>; }>
NamedTemplates.NODES: Record<string, NodeTemplate<P>>
TaskTemplate
TaskTemplate<P>
TaskTemplate.type: typeof Task
TaskTemplate.start?: TaskCallback<P>
TaskTemplate.run?: TaskCallback<P>
TaskTemplate.finish?: TaskCallback<P>
TaskTemplate.chance?: number
This node's share of 1 to 100, read only when a RandomWithChances lists it.
TaskTemplate.nodes?: never
TaskTemplate.node?: never
TaskControl
TaskControl.success(this: void)
Reports the task as succeeded, which moves the tree on.
Parameters
this:void
TaskControl.fail(this: void)
Reports the task as failed, which moves the tree on.
Parameters
this:void
CompositeTemplate
CompositeTemplate<P, Ref extends string = string>
CompositeTemplate.type: typeof Sequence | typeof Selector | typeof Random | typeof RandomWithChances
CompositeTemplate.nodes: (Ref | NodeTemplate<P, Ref>)[]
CompositeTemplate.chance?: number
This node's share of 1 to 100, read only when a RandomWithChances lists it.
CompositeTemplate.node?: never
DecoratorTemplate
DecoratorTemplate<P, Ref extends string = string>
DecoratorTemplate.type: typeof InvertDecorator | typeof AlwaysFailDecorator | typeof AlwaysSucceedDecorator | typeof RepeatUntilFailDecorator | typeof ChanceDecorator
DecoratorTemplate.node: Ref | NodeTemplate<P, Ref>
DecoratorTemplate.chance?: number
This node's share of 1 to 100, read only when a RandomWithChances lists it.