Behavior Tree Studio

Code-first, dependency-free Behavior Tree library for TypeScript focused on user experience, with a graphical interface for tracing, profiling and debugging.

Features

• Type-safe: Full TypeScript support with compile-time validation of decorator specs
• Lifecycle hooks: 12 hooks covering every phase of node execution and abort
• Three construction APIs: Direct instantiation, builder functions, and TSX/JSX
• Rich node library: 8 composite types, 30+ decorators, and built-in leaf nodes
• Ref system: Ref<T>, ReadonlyRef<T>, DerivedRef<T>, multiRef(), and patchRef() for type-safe, auto-traced state sharing between nodes
• Runtime inspector: Tick recording, time-travel snapshots, profiling, and flame graphs
• Zero dependencies: No runtime deps; ESM and CJS bundles via tsup

Quick Start

npm install @bt-studio/core

import { BehaviourTree, NodeResult } from '@bt-studio/core';
import { fallback, sequence, condition, action } from '@bt-studio/core/builder';

const entity = { health: 100, inDanger: false };

const tree = new BehaviourTree(
  fallback({}, [
    sequence({ name: 'Flee' }, [
      condition({ name: 'In danger?', eval: () => entity.inDanger }),
      action({ name: 'Run away', execute: () => {
        entity.inDanger = false;
        return NodeResult.Succeeded;
      }}),
    ]),
    action({ name: 'Patrol', execute: () => NodeResult.Running }),
  ])
);

// Game loop
setInterval(() => {
  tree.tick({ now: Date.now() });
}, 100);

Three Ways to Build Trees

The same tree can be expressed in three equivalent styles:

Direct instantiation:

import { Fallback, Sequence, ConditionNode, Action, NodeResult } from '@bt-studio/core';

const flee = Sequence.from('Flee', [
  ConditionNode.from('In danger?', () => entity.inDanger),
  Action.from('Run away', () => NodeResult.Succeeded),
]);
const patrol = Action.from('Patrol', () => NodeResult.Running);
const root = Fallback.from([flee, patrol]);

Builder functions:

import { fallback, sequence, condition, action } from '@bt-studio/core/builder';

const root = fallback({}, [
  sequence({ name: 'Flee' }, [
    condition({ name: 'In danger?', eval: () => entity.inDanger }),
    action({ name: 'Run away', execute: () => NodeResult.Succeeded }),
  ]),
  action({ name: 'Patrol', execute: () => NodeResult.Running }),
]);

TSX:

import { BT } from '@bt-studio/core/tsx';

const root = (
  <fallback>
    <sequence name="Flee">
      <condition name="In danger?" eval={() => entity.inDanger} />
      <action name="Run away" execute={() => NodeResult.Succeeded} />
    </sequence>
    <action name="Patrol" execute={() => NodeResult.Running} />
  </fallback>
);

Package Exports

Entry point	Description
@bt-studio/core	Core library: all node classes, BehaviourTree, types
@bt-studio/core/builder	Builder functions with NodeProps-based decorator application
@bt-studio/core/tsx	JSX factory (BT.createElement, BT.Fragment) and type declarations
@bt-studio/core/inspector	TreeInspector, TreeIndex, TickStore, Profiler, and related types
@bt-studio/core/activity	Standalone activity projection from SerializableNode + TickRecord
@bt-studio/react	React debugger component with tree visualization and time-travel
@bt-studio/cli	CLI (bt-studio) to launch studio server + UI
@bt-studio/studio-server	WebSocket/HTTP/TCP bridge between agents and UI with tick persistence
@bt-studio/studio-ui	Browser app for real-time trace visualization, time-travel, profiling
@bt-studio/studio-transport	TCP and WebSocket transports for agent-to-server connections
@bt-studio/studio-common	Shared Zod schemas and protocol definitions
@bt-studio/studio-plugins	First-party plugins; ships ReplPlugin (NaCl E2E encrypted JS eval)
@bt-studio/studio-mcp	MCP server — AI agent access to connected trees via REPL

Documentation

1. Getting Started - Installation, first tree, tick loop
2. Core Concepts - NodeResult, lifecycle hooks, TickContext, BTNode
3. Leaf Nodes - Action, ConditionNode, built-in leaves
4. Composite Nodes - Sequence, Fallback, Parallel, IfThenElse, and more
5. Decorators - All 30+ decorators grouped by category
6. Construction APIs - Direct instantiation, builder, TSX comparison
7. TSX - Full JSX/TSX reference
8. Inspector - TreeInspector, profiling, serialization
9. BehaviourTree Class - Wrapper class, state tracing, tick loop
10. Custom Nodes - Extending the library
11. Node Flags - NodeFlags bitfield reference
12. React Debugger - <BehaviourTreeDebugger> component
13. Roadmap - Planned features

React Debugger

The @bt-studio/react package provides a <BehaviourTreeDebugger> component with real-time tree visualization, time-travel, profiling, ref tracing, and activity displays. Uses Shadow DOM style isolation by default.

npm install @bt-studio/react

See docs/react-debugger.md for the full API reference.

Roadmap

See docs/roadmap.md for details.

License

MIT