Skip to Content
defold-typescript libraries
s-kania

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
    1. Pick a release from s-kania/def-behavior-tree releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as def_behavior_tree from "def_behavior_tree.behavior_tree"

Functions

new(2 overloads)

  1. <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 registerTemplates first.

    Parameters

    • config: { tree_name: string; payload: P; rng?: (this: void, range_start: number, range_end: number) => number; } — tree_name names a tree under the templates' TREES, payload is passed to every task callback, and rng returns a whole number between its two arguments for Random and RandomWithChances; it defaults to math.random.
      • tree_name: string
      • payload: P
      • rng?: (this: void, range_start: number, range_end: number) => number

    Returns

    • BehaviorTree<P>
  2. (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 with registerTemplates first.

    Parameters

    • config: { tree_name: string; payload?: undefined; rng?: (this: void, range_start: number, range_end: number) => number; } — tree_name names a tree under the templates' TREES, and rng returns a whole number between its two arguments for Random and RandomWithChances; it defaults to math.random.
      • tree_name: string
      • payload?: undefined
      • rng?: (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 to 1, 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 to 1, 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.

DecoratorTemplate.nodes?: never

InlineTemplates

InlineTemplates<P>

InlineTemplates.TREES: Record<string, { main_node: NodeTemplate<P, never>; }>

InlineTemplates.NODES?: undefined

On this page

Functionsnew(2 overloads)VariablesTask: NodeType<'Node'>Composite: NodeType<'Composite'>Sequence: NodeType<'Sequence'>Selector: NodeType<'Selector'>Random: NodeType<'Random'>RandomWithChances: NodeType<'RandomWithChances'>Decorator: NodeType<'Decorator'>InvertDecorator: NodeType<'InvertDecorator'>AlwaysFailDecorator: NodeType<'AlwaysFailDecorator'>AlwaysSucceedDecorator: NodeType<'AlwaysSucceedDecorator'>RepeatUntilFailDecorator: NodeType<'RepeatUntilFailDecorator'>ChanceDecorator: NodeType<'ChanceDecorator'>registerTemplates: <P>(templates: Templates<P>) => voidgetTreeTemplate: (treeName: string) => TreeNode[] | undefinedRegistry: { registerTemplates<P>(this: void, templates: Templates<P>): void; getTreeTemplate(this: void, treeName: string): TreeNode[] | undefined; getNodeFromTree(this: void, id: number, treeName: string): TreeNode | undefined; }Typestype TaskCallback<P> = (this: void, task: TaskControl, payload: P) => voidtype NodeTemplate<P, Ref extends string = string> = TaskTemplate<P> | CompositeTemplate<P, Ref> | DecoratorTemplate<P, Ref>type Templates<P> = NamedTemplates<P> | InlineTemplates<P>NodeTypeNodeType<Name extends string = string>NodeType.name: NameBehaviorTreeBehaviorTree<P = unknown>BehaviorTree.run(activeNodeID?: number)BehaviorTree.restart(activeNodeID?: number)BehaviorTree.setActiveNode(node: TreeNode)BehaviorTree.getNode(nodeID: number): TreeNode | undefinedBehaviorTree.success()BehaviorTree.fail()BehaviorTree.getRandomBetween(x: number, y: number): numberBehaviorTree.name: stringBehaviorTree.payload: PBehaviorTree.running: booleanBehaviorTree.activeNode: TreeNode | undefinedBehaviorTree.rng: (this: void, x: number, y: number) => numberTreeNodeTreeNode.id: numberTreeNode.name: stringTreeNode.type: NodeTypeTreeNode.chance?: numberTreeNode.nodes?: TreeNode[]TreeNode.node?: TreeNodeNamedTemplatesNamedTemplates<P>NamedTemplates.TREES: Record<string, { main_node: string | NodeTemplate<P>; }>NamedTemplates.NODES: Record<string, NodeTemplate<P>>TaskTemplateTaskTemplate<P>TaskTemplate.type: typeof TaskTaskTemplate.start?: TaskCallback<P>TaskTemplate.run?: TaskCallback<P>TaskTemplate.finish?: TaskCallback<P>TaskTemplate.chance?: numberTaskTemplate.nodes?: neverTaskTemplate.node?: neverTaskControlTaskControl.success(this: void)TaskControl.fail(this: void)CompositeTemplateCompositeTemplate<P, Ref extends string = string>CompositeTemplate.type: typeof Sequence | typeof Selector | typeof Random | typeof RandomWithChancesCompositeTemplate.nodes: (Ref | NodeTemplate<P, Ref>)[]CompositeTemplate.chance?: numberCompositeTemplate.node?: neverDecoratorTemplateDecoratorTemplate<P, Ref extends string = string>DecoratorTemplate.type: typeof InvertDecorator | typeof AlwaysFailDecorator | typeof AlwaysSucceedDecorator | typeof RepeatUntilFailDecorator | typeof ChanceDecoratorDecoratorTemplate.node: Ref | NodeTemplate<P, Ref>DecoratorTemplate.chance?: numberDecoratorTemplate.nodes?: neverInlineTemplatesInlineTemplates<P>InlineTemplates.TREES: Record<string, { main_node: NodeTemplate<P, never>; }>InlineTemplates.NODES?: undefined