Migration Guide

Migration Guide

A practical upgrade guide for teams moving from older RBXStateMachine snippets and docs to the current FSM/Orchestrator runtime.

Important

This page focuses on the migration issues most likely to affect real projects using older wiki examples: bootstrap path changes, auto-registration assumptions, FSM auto-start, scheduler startup, testing paths, and entity mutability.

---

1. The biggest doc-era differences

If your project was built from older examples, these are the first things to verify.

Older assumption	Current runtime
framework is ReplicatedStorage.RBXStateMachine	repo default maps to ReplicatedStorage.Orchestrator
scheduler is separate/manual	scheduler is started during RegisterComponents()
CreateStateMachine() returns idle machine by default	auto-start is now the default unless AutoStart = false
tests are under FSM/Tests	real automated suite is under FSM/Orchestrator/ServiceManager/Tests
entity/FSM folders must be one exact path	factory scans all descendants for alias-named folders
any entity with ApplyChanges can always commit	UpdateEntity() requires Mutable = true

---

2. Update your require path first

Old snippets often look like this:

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

Current repo-aligned bootstrap should look like this:

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

If your Rojo project still intentionally exposes a different module name, that is fine—but this repository's own source-of-truth mapping is ReplicatedStorage.Orchestrator.

---

3. Stop manually starting what the bootstrap already starts

3.1 Scheduler startup

Older guidance often treated the scheduler as optional manual setup. In the current Orchestrator bootstrap:

• scheduler is initialized
• Orchestrator.Scheduler:Start() is called
• the global FSM heartbeat task is scheduled

So code like this is usually redundant in normal usage:

Orchestrator.Scheduler:Start()

3.2 FSM startup

Older gameplay code often did:

local job = Orchestrator.CreateStateMachine({...})
job:Start({ State = "Validate" })

In the current factory, CreateStateMachine() auto-starts unless you explicitly pass:

AutoStart = false

When manual :Start() is still correct

• you intentionally disabled auto-start
• you created the machine outside the usual factory flow
• you need strict delayed orchestration after construction

---

4. Update your folder assumptions

Older docs often implied only one hard-coded folder path. The current factory scans all descendants for these alias names:

Entity aliases

• Entity
• Entities

FSM aliases

• StateMachine
• StateMachines
• SM
• FSM

Migration recommendation

Even though discovery is more flexible now, standardize on:

ReplicatedStorage/Entity
ReplicatedStorage/StateMachine

unless you have a strong architectural reason to do otherwise.

---

5. Audit entity mutability

This is one of the most important upgrade checks.

If an entity ever does:

self:UpdateEntity()

then declare:

Mutable = true

Older example patterns may appear to work conceptually but now fail fast at commit time on immutable entities.

Quick search checklist

Search for entities that:

• define Open, Close, Reset, Damage, Heal, or similar mutating methods
• call UpdateEntity() directly
• stage schema values before committing

Then confirm each one explicitly opts into mutability.

---

6. Modernize timing patterns

If your older code uses task.delay() or hand-rolled timers inside states, prefer the current native timing model:

• fixed delayed exit → ScheduleTransition()
• state-owned deadline → Timeout + OnTimeout
• reactive branching → Transitions[].Condition
• delayed self-loop/polling → WaitSpan

Example migration

Old style:

self:AddState("Idle", function(fsm)
    task.delay(2, function()
        if fsm.State == "Idle" then
            fsm.State = "Spin"
        end
    end)
end)

Better current style:

self:AddState("Idle", function(fsm)
    fsm:ScheduleTransition(2, "Spin")
end, { "Spin" })

---

7. Update your debugging workflow

Older docs often stop at logs. The current runtime has a much richer debugging surface through ServiceManager.

Current root tabs:

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

Migration recommendation:

• keep log-based debugging for failures
• add ServiceManager-driven inspection for state, replication, and performance issues
• use server context when debugging authoritative problems

---

8. Update test references

Older text may mention FSM/Tests as the main suite location.

Current automated test source of truth is:

FSM/Orchestrator/ServiceManager/Tests

with:

• TestRunner.luau
• RunAllTests.luau
• Specs/*.spec.luau

The repo currently contains 18 spec files there.

---

9. Migration checklist by area

Bootstrap

• require path updated to ReplicatedStorage.Orchestrator
• both server and client call RegisterComponents()
• no redundant manual scheduler startup in normal boot flow

Components

• entity and FSM folders use supported alias names
• modules return table definitions
• entity definitions that commit changes declare Mutable = true

FSM usage

• manual :Start() calls reviewed for redundancy
• timing patterns modernized to ScheduleTransition / Timeout / Condition
• duplicate ID assumptions removed

Debugging / tooling

• ServiceManager started only in development/staging contexts
• test references updated to ServiceManager/Tests
• profiling workflow uses TASKS, PROFILER, and INSIGHTS

---

10. Safe migration sequence

A low-risk order for upgrading an existing game:

1. update the framework require path
2. confirm registration folders are discoverable
3. audit mutable entities
4. remove redundant manual starts only after verifying auto-start expectations
5. modernize timer patterns
6. validate replication in Studio with ServiceManager
7. run automated specs / smoke tests before shipping

---

Related guides

• Getting Started
• Registration Guide
• Examples
• Debugging
• Tests