Home
RBXStateMachine is a Roblox gameplay runtime for building server-authoritative Entities, finite state machines, behavior trees, scheduled jobs, replication pipelines, and a first-class developer dashboard from one cohesive framework.
It is built for teams shipping multiplayer systems, NPC-heavy gameplay, persistent worlds, and any experience where ad-hoc remotes, task.delay, and one-off state logic stop scaling.
- What it does — boots an Orchestrator-centered runtime that compiles Entities and FSMs, schedules work inside a frame budget, replicates schema-backed state, persists data, and exposes live tooling.
- Who it's for — Roblox developers building authoritative multiplayer gameplay, reusable framework code, large NPC populations, or production debugging workflows.
-
Why it stands out — native FSM timing (
ScheduleTransition,WaitSpan,Timeout), schema-validated entities, optional persistence, actor-based parallelism, and the ServiceManager dashboard.
| I want to... | Start here |
|---|---|
| Install and bootstrap the framework | Getting Started |
| Build a tiny working example fast | Quick Start |
| Look up modules and APIs | API Reference |
| Understand the runtime design | Architecture |
| Learn the framework vocabulary | Glossary |
Your game code
(Entity / StateMachine modules)
│
▼
Orchestrator
├─→ Factory + Registry
│ ├─→ BaseEntity
│ │ schema, context, versioning
│ └─→ BaseStateMachine
│ states, transitions, timeouts
│ └─→ BehaviorTree
│ Selector / Sequence
├─→ Scheduler
│ frame budget + global heartbeat
│ └─→ BaseStateMachine
├─→ NetworkManager
│ requests, commands, replication
│ └─→ BaseEntity
├─→ EntityPersistence + DataStoreHandler
└─→ ServiceManager
9-subsystem dashboard
- Discrete states, transitions, lifecycle hooks, and hierarchical sub-machines.
- Native timing with ScheduleTransition, WaitSpan, and declarative
Timeout/OnTimeout. - See: API: BaseStateMachine, Hierarchical FSM
- Schema-validated properties, staged commits, versioned replication, and persistence hooks.
- Server-authoritative updates flow through
UpdateEntity()instead of ad-hoc remotes. - See: API: BaseEntity, Replication Pipeline, Versioning
- Compose
Selector,Sequence,Condition, and state-setting nodes around FSM logic. - Useful for reusable AI decisions without deeply nested conditionals.
- See: API: BehaviorTree
- Frame-budgeted task execution, priority-aware scheduling, task history, and Actor-backed parallel jobs.
- Designed for large numbers of agents without giving every system its own uncontrolled loop.
- See: API: Scheduler, API: ActorPool, Performance Tuning
- Built-in diagnostics for
TASKS,FSM,ENTITY,NETWORK,DATASTORE,INSIGHTS,CONSOLE,LOGS, andPROFILER. - Snapshot-driven inspection with Z-axis drill-down navigation for live debugging.
- See: API: ServiceManager, Debugging
| Path | Recommended pages |
|---|---|
| First-time setup | Getting Started → Quick Start → Registration Guide |
| Gameplay authoring | Examples → Best Practices → API: BaseEntity → API: BaseStateMachine |
| Runtime internals | Architecture → API: Orchestrator → API: NetworkManager → API: Scheduler |
| Production hardening | Replication Pipeline → Pooling Strategy → Performance Tuning → Production Readiness |
| Reference lookup | API Reference → Glossary → FAQ |
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local RunService = game:GetService("RunService")
local FSM = require(ReplicatedStorage:WaitForChild("RBXStateMachine"))
FSM.Orchestrator:RegisterComponents()
if RunService:IsStudio() then
FSM.Orchestrator:StartServiceManager()
end