RBXStateMachine

RBXStateMachine is a high-performance, full-stack architectural framework for Roblox. It is designed to manage complex gameplay logic, server-authoritative state replication, and CPU budgeting for games that need to scale from a handful of agents to thousands.

It is not just a finite-state-machine library. It is a complete runtime — registry, scheduler, networking, persistence, dev console, and AI primitives — built around four cooperating components: Brain, Body, Pulse, and Nervous System.

📖 Full documentation lives in the Project Wiki (36 pages, ~500 KB). Start with the 5-Minute Quick Start or the System Architecture deep dive.

---

🏛️ The "4 Pillars" Architecture

The framework enforces a strict separation of concerns through four cooperating components:

Pillar	Component	Responsibility	Analog
🧠 Brain	BaseStateMachine	Decision making, transitions, AI logic	The thinker
🛡️ Body	BaseEntity	Schema-validated data + Instance proxy	The actor
⚡ Pulse	Scheduler	Frame-budgeted time-slicing	The heartbeat
🕸️ Nervous System	Orchestrator	Registry, factory, replication, lifecycle	The microkernel

This separation is what lets you put 500+ NPCs on a server without dropping frames, replicate state to clients without writing a single RemoteEvent, and refactor the AI for one entity without touching the visuals for another.

📐 See System Architecture for the runtime diagram and bootstrap order.

---

🌟 Key Features

Core Runtime

• ⚡ Frame-Budgeted Execution — The Scheduler caps work per frame at a configurable budget (default 5–15 ms) with priority aging so background jobs never starve.
• 🧬 Hierarchical FSMs (HFSM) — Nest sub-machines inside states (e.g. a Combat state containing Melee / Ranged). See Hierarchical FSM.
• 🌳 Functional Behavior Trees — Composable Sequence, Selector, Parallel, Decorator, Action, Condition nodes via BehaviorTree.
• ♻️ Resource Tracking — Every FSM/Entity has a Manage() method that auto-disconnects connections, destroys instances, and runs cleanup callbacks on Stop().

Data & Replication

• 🔒 Transactional Schema — Entities use a stage-and-commit flow (SetField → UpdateEntity()); validation fails atomically with no partial writes. See Replication Pipeline.
• 📡 Automatic Replication — Mark a schema field with Replicate = true and the framework wires the RemoteEvent, batches deltas, applies rate limits, and sanitizes inbound writes.
• 💾 Integrated Persistence — One-line opt-in via EntityPersistence saves entity state to DataStores. Includes versioning + migrations (Versioning) and a 7-second write throttle out of the box.
• 🛡️ Server Authority — Inbound RemoteEvent payloads are sanitized to a configurable depth (default 8) and rate-limited per player.

Performance & Scaling

• 🧵 Parallel Workers — ActorPool dispatches CPU-heavy jobs to Roblox Actor instances for true parallel execution.
• ♻️ Entity Pooling — Recycle entities across spawns to avoid GC pressure in high-frequency systems (projectiles, particles). See Pooling Strategy.
• 📊 Performance Tuning — Capacity planning, profiling, and budget math: Performance Tuning.

Operations & Debugging

• 🖥️ Built-in Dev Console — ServiceManager ships a 9-page in-game UI: logs, entities, FSMs, performance, history, terminal, settings, etc.
• 📝 Structured Logger — Logger with a 500-entry circular buffer, log levels, and console streaming.
• 🧪 Spec-style Tests — Full unit + integration suite under FSM/Tests/ (Replication, Pooling, Discovery, Scheduler, Logger, Mocking, etc.). See Testing & Validation.

---

📂 Project Structure

RBXStateMachine/
├── FSM/                          ← The core engine (4 Pillars + auxiliary systems)
│   ├── Orchestrator/             ← Registry, Factory, ActorPool, ServiceManager, NetworkManager
│   ├── Factory/                  ← BaseEntity, BaseStateMachine, PersistenceManager, Registry
│   ├── EntityRegistry.luau       ← Runtime entity registry
│   ├── StateMachineRegistry.luau ← Runtime state-machine registry
│   ├── Client.client.luau        ← Client bootstrap script
│   ├── Tests/                    ← Spec-style unit & integration tests
│   └── README.md                 ← Deep technical implementation reference
│
├── example/                      ← Working reference implementations
│   ├── DoorEntityExample.luau    ← Schema, replication, instance proxying
│   ├── DoorStateMachineExample.luau ← Multi-state FSM with validation & failure paths
│   └── GameControllerExample.luau   ← Bootstrap + entity/FSM creation flow
│
└── RBXStateMachine.wiki/         ← Wiki source (36 pages, comprehensive guide)

The wiki is a separate git repository mounted as a nested directory; it is published at https://github.com/iKryptonic/RBXStateMachine/wiki.

---

🚀 Quick Installation

1. Sync into your project

Use Rojo (or your tool of choice) to sync the FSM/ directory into ReplicatedStorage as RBXStateMachine. Place your custom Entity and StateMachine modules as direct children of ReplicatedStorage — the Orchestrator's Factory discovers these folders by name:

ReplicatedStorage/
├── RBXStateMachine/    ← The framework (this repo's FSM/ folder)
├── Entity/             ← Your *Entity.luau modules go here
└── StateMachine/       ← Your *StateMachine.luau modules go here

📚 Folder layout details: Registration Guide.

2. Bootstrap (Server)

-- ServerScriptService/Bootstrap.server.luau
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local FSM = require(ReplicatedStorage:WaitForChild("RBXStateMachine"))

-- Discover Entity/StateMachine modules and wire up remotes, scheduler, logger.
FSM.Orchestrator:RegisterComponents()

3. Bootstrap (Client)

-- StarterPlayerScripts/Bootstrap.client.luau
local ReplicatedStorage = game:GetService("ReplicatedStorage")
ReplicatedStorage:WaitForChild("Entity")
ReplicatedStorage:WaitForChild("StateMachine")

local FSM = require(ReplicatedStorage:WaitForChild("RBXStateMachine"))
FSM.Orchestrator:RegisterComponents()

FSM/Client.client.luau ships as a ready-to-use client bootstrap if you'd rather sync that directly under StarterPlayerScripts.

📚 Full walkthrough with error handling and verification: Installation Guide.

---

⚡ Hello, World — A Spinning Part

-- ServerScriptService/Bootstrap.server.luau
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local FSM = require(ReplicatedStorage:WaitForChild("RBXStateMachine"))
FSM.Orchestrator:RegisterComponents()

local part = workspace.SpinningPart -- any Part in workspace

-- 1. Wrap the Instance in a schema-validated Entity.
local entity = FSM.Orchestrator.CreateEntity({
    EntityClass = "SpinnerEntity",
    EntityId    = "Spinner1",
    Context     = { Instance = part },
})

-- 2. Attach a brain that drives it.
local fsm = FSM.Orchestrator.CreateStateMachine({
    StateMachineClass = "SpinnerStateMachine",
    StateMachineId    = "Spinner1_FSM",
    Context           = { SpinnerEntity = entity },
})

fsm:Start({ State = "Spinning" })

The SpinnerEntity and SpinnerStateMachine modules live under ReplicatedStorage/Entity/ and ReplicatedStorage/StateMachine/ respectively. See example/DoorEntityExample.luau for a complete reference implementation, or the Quick Start for a full walkthrough.

---

📖 Documentation Map

The wiki is structured by audience:

You want to…	Go to
Build your first agent in 5 minutes	Quick Start
Understand the runtime end-to-end	Architecture
Look up a method signature	API Reference
Learn how state replicates to clients	Replication Pipeline
Build nested AI states	Hierarchical FSM
Persist player/entity data	EntityPersistence + Versioning
Hit 60 FPS with 500+ NPCs	Performance Tuning + Pooling Strategy
Write production-grade code	Best Practices + Production Readiness
Diagnose a bug	Debugging + FAQ
Migrate from another FSM library	Migration Guide
Look up unfamiliar terms	Glossary

💡 The Wiki Home has full Beginner / Intermediate / Expert learning paths.

---

🎯 Should I Use This Framework?

✅ Use RBXStateMachine if you are…

• Building a multiplayer game with server authority
• Managing 50+ NPCs / agents / entities concurrently
• Need persistent player or world data
• Working in a team where consistent patterns matter
• Building anything where dropped frames are unacceptable

❌ Consider alternatives if you are…

• Prototyping a 3-day game jam entry
• Building a single-player showcase with simple if/else logic
• Working solo on a small project where the architectural overhead outweighs the benefits

---

🧪 Testing

The framework ships with a comprehensive Spec-style test suite under FSM/Tests/:

• Unit tests: Logger, Mocking, Orchestrator, Discovery, Scheduler, Replication Security, Registry, Pool Reuse, Fail-with-nil-history, …
• Integration tests: DataStoreEntity, EntityPooling, Factory, ServiceManager, Replication, Iteration Safety, …

Run them via your Roblox test runner of choice. See Testing & Validation for setup and authoring conventions.

---

📚 Learn More

• 🏠 Wiki Home — Full table of contents and learning paths
• 📐 FSM/README.md — Deep technical reference for framework internals
• 💬 FAQ & Troubleshooting — Common questions answered
• 🐛 Issues — Bug reports and feature requests welcome