@rbxts/state-management

A comprehensive state management library for roblox-ts. Provides modular, type-safe primitives for building AI and game logic: finite state machines, behavior trees, goal-oriented action planning, and a shared blackboard.

Installation

npm install @rbxts/state-management
# or
bun add @rbxts/state-management

Modules

docs/
├── blackboard.md      — Key-value store shared across AI systems
├── fsm.md             — Finite State Machine with priority transitions and events
├── behavior-tree.md   — Shared-tree Behavior Tree: one tree for all agents, nodes, lifecycle, ECS ids
├── custom-nodes.md    — Writing your own composites and decorators for the Behavior Tree
├── goap.md            — Goal Oriented Action Planning with A* planner
└── btcreator.md       — Data-driven BehaviorTree builder from JSON

| Module | Export | Description | | -------------------------------------- | ------------ | ---------------------------------------------------------------------------- | | Blackboard | Blackboard | Typed + untyped key-value store for sharing data between systems | | FSM | FSM | Finite state machine with condition, event, and any-state transitions | | Behavior Tree | BTree | Shared-tree behavior tree: 30+ node types, one tree for all agents, zero per-tick garbage | | GOAP | Goap | A*-based action planner with hierarchical goals and weighted requirements | | BTCreator | BTCreator | Build behavior trees from JSON with a registry-based node factory |

BTCreator App

external/BTCreatorApp is the visual editor that bakes the JSON BTCreator loads (Wails + React). Run it with wails dev from that folder; see its baking docs for the file format.

Quick Start

import { BTree, FSM, Goap, Blackboard, BTCreator } from "@rbxts/state-management";

Changelog

| Version | Highlights | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | 0.4.1 | BehaviorTree fixes: TickAgent with several agents, removal/halt re-entrancy, throwing hooks no longer disable the tree | | 0.4.0 | BehaviorTree rewritten as a shared tree (10–30x faster, zero garbage); BTCreator and connectors updated (breaking) | | 0.3.6 | New Plug and OneShot BehaviorTree nodes; BTCreator versioned schema support | | 0.3.5 | Fixed BehaviorTree.Halt() not cleaning up all running/active nodes | | 0.3.4 | BTCreator versioned node loading (1.0.0 / 2.0.0 schemas) | | 0.3.3 | New WasEntryUpdated node — blackboard change detection | | 0.3.2 | IFullActionConfig key renames to match lifecycle API | | 0.3.1 | Fixed KeepRunningUntilSuccess/Failure max attempts logic | | 0.3.0 | BehaviorTree lifecycle refactor; FSM ForceSetState & any-event transitions; separate docs |

License

MIT