FAQ

Frequently Asked Questions

Common questions about the current RBXStateMachine runtime, with answers grounded in the source code rather than older snippets.

---

1. Setup and boot

Q: What is the minimum code to start the framework?

Server:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Orchestrator = require(ReplicatedStorage:WaitForChild("Orchestrator"))

Orchestrator:RegisterComponents()

Client:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Orchestrator = require(ReplicatedStorage:WaitForChild("Orchestrator", 30))

Orchestrator:RegisterComponents()

In this repository's default Rojo project, the framework module is ReplicatedStorage.Orchestrator.

Q: Is the framework still ReplicatedStorage.RBXStateMachine?

Not in this repo's current default mapping. The source-of-truth path is:

ReplicatedStorage.Orchestrator

Q: Do I need to start the scheduler manually?

Not in the normal bootstrap path. Orchestrator:RegisterComponents() initializes the scheduler and calls:

Orchestrator.Scheduler:Start()

It also schedules GlobalStateMachineHeartbeat after disabling the base FSM internal loop.

Q: Do I pass folders or registries into RegisterComponents()?

No. The current public usage is simply:

Orchestrator:RegisterComponents()

---

2. Discovery and registration

Q: Where do I put Entity and StateMachine modules?

Recommended:

ReplicatedStorage/
├── Entity/
└── StateMachine/

But the current factory actually scans all game descendants for supported alias names.

Q: Can I use custom folder locations?

Yes, as long as the folder name matches a supported alias:

• Entity side: Entity, Entities
• FSM side: StateMachine, StateMachines, SM, FSM

The location can vary; the folder name must match.

Q: Do I still manually require each class after boot?

No. The factory requires and compiles discovered ModuleScripts automatically.

Q: What must a component module return?

A table definition describing the class.

For entities, that usually includes Name, Schema, and methods such as GetContext / ApplyChanges. For FSMs, that usually includes Name, ValidStates, InitialState, and RegisterStates.

---

3. State machine behavior

Q: Does CreateStateMachine() auto-start the machine?

Yes, by default. The current factory auto-starts the new machine unless you pass:

AutoStart = false

Q: When should I still call :Start() manually?

When you intentionally created the FSM with AutoStart = false, or when you instantiated a child/new machine outside the usual factory helpers and need to control the exact first state yourself.

Q: What's the difference between ScheduleTransition, Timeout, Transitions[].Condition, and WaitSpan?

• ScheduleTransition → one-shot delayed exit from the current state
• Timeout + OnTimeout → state-owned deadline
• Transitions[].Condition → reactive branching checked during _Update
• WaitSpan → delayed same-state re-entry / polling pattern

Q: My FSM seems stuck. What should I check first?

Check, in order:

1. did the machine actually get created?
2. is GlobalStateMachineHeartbeat running?
3. is the current state legal and registered?
4. did the state schedule or trigger an exit?
5. is the bug actually in the wrong context (client vs server)?

ServiceManager FSM, TASKS, and CONSOLE are the fastest places to verify those.

Q: Does WaitSpan delay any transition?

It is most useful for delayed same-state re-entry/self-loop patterns. Use ScheduleTransition() instead for straightforward fixed exits.

---

4. Entity behavior

Q: Why does UpdateEntity() return false?

The current BaseEntity fast-fails when:

• the entity is invalid/destroyed
• the entity is locked by another caller
• there are no pending changes
• the entity is not mutable

Q: What makes an entity mutable?

Declare:

Mutable = true

in the entity definition if the entity is expected to commit staged changes via UpdateEntity().

Q: What belongs in schema versus context?

• Schema → authoritative, validated game state
• Context → runtime references like Instance, Humanoid, Animator, or other non-replicated helpers

Q: Why didn't the client reflect my server entity change?

Check all of these:

• field marked Replicate = true
• server actually called UpdateEntity()
• ApplyChanges() handles the field
• versioning is not stale on the client
• update is visible in ServiceManager NETWORK / ENTITY

---

5. ServiceManager and debugging

Q: Where does ServiceManager run?

On the client. You start it from a client script with:

Orchestrator:StartServiceManager()

Q: Can it inspect server state?

Yes. Switch the dashboard to server context. The client fetches server snapshots and polls periodically.

Q: What tabs exist right now?

The current dashboard exposes these root tabs:

• TASKS
• FSM
• ENTITY
• NETWORK
• DATASTORE
• INSIGHTS
• CONSOLE
• LOGS
• PROFILER

Q: What console commands are built in?

Current built-ins include:

• help
• clear
• echo
• version
• mode
• tasks
• fsm
• entities
• network
• ds
• perf
• switch

---

6. Testing and examples

Q: Where are the automated tests?

Current source-of-truth automated tests live in:

FSM/Orchestrator/ServiceManager/Tests

with RunAllTests.luau, TestRunner.luau, and Specs/*.spec.luau.

Q: Are the example files still useful?

Yes, but read them as examples, not perfect production templates.

Important current-runtime notes:

• add Mutable = true to example entities that commit with UpdateEntity()
• manual :Start() after CreateStateMachine() is often redundant now because auto-start is the default

Q: What is the easiest end-to-end demo in the repo?

Use:

• test/main.server.luau
• test/Client.client.luau

Those boot the framework and ServiceManager with almost no extra setup.

---

7. Performance and production

Q: What scheduler frame budget does the repo default to?

Core/Settings.luau currently sets:

FrameBudget = 0.015

Q: How does Replication.RateLimit work?

In the current factory logic, it behaves like updates per second because the send interval is calculated as 1 / RateLimit.

Q: Should I ship ServiceManager in production?

Usually no. Treat it as a development/staging tool unless you have a very deliberate reason to expose it.

Q: What is the fastest production hardening win?

These three usually matter most:

• minimize replicated fields
• choose FSM priorities intentionally
• connect Failed handlers and log real error boundaries

---

Related guides

• Getting Started
• Registration Guide
• Best Practices
• Debugging
• Tests
• Production Readiness