@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   — Behavior Tree nodes, composites, decorators, and lifecycle
├── 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 | 20+ node types — composites, decorators, leaves, and cross-system connectors | | 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 |

Quick Start

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

Changelog

| Version | Highlights | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | 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