Debugging FSMs with State Transition Logging

1. The Power of a Good Log

When an NPC gets stuck in a wall or a menu doesn't appear when it should, your first question will be, "What state is the FSM in?". A well-designed logging system answers that question instantly. The goal isn't just to print messages, but to create a readable history of the FSM's life.

A good log for an FSM should tell you:

• Which state the FSM just entered or exited.
• What event triggered a transition.
• When an invalid transition was attempted and blocked.
• The exact sequence of these events.

Look at the following image from a game development console. This is the kind of clarity we're aiming for.

Notice the structured format. You can immediately see the flow from IdleState to ChaseState and so on. This is far more useful than random print("I'm here!") messages scattered through your code.

2. Implementing Structured Logging

Let's upgrade the turnstile FSM from our last lesson with a more professional logging system. We will create a simple helper function to format our messages and then integrate it into our FSM's key functions.

Step 1: Create a Logger Function

To keep our log messages consistent, we can create a small helper function. This also makes it easy to disable all FSM-related logs later by simply commenting out the print line inside this one function.

-- Add this at the top of your script
local FSM_NAME = "Turnstile"

function log(message)
    -- Using string.format for a clean, consistent prefix
    print(string.format("[%s FSM] %s", FSM_NAME, message))
end

Step 2: Integrate Logging into the FSM

Now, let's replace the print statements in our FSM logic with calls to our new log function. This will give us standardized output.

Here is the complete, updated script. The core logic is the same as last lesson's; the only changes are the addition of the log function and replacing print with log.

-- The complete, debug-ready Turnstile FSM script

-- Logger setup
local FSM_NAME = "Turnstile"
function log(message)
    print(string.format("[%s FSM] %s", FSM_NAME, message))
end


-- FSM Definition
local states = {
    Locked = {
        transitions = {
            Coin = "Unlocked"
        },
        OnEnter = function()
            log("▶️ ENTER: Locked. The turnstile is now locked.")
        end,
        OnExit = function()
            log("◀️ EXIT: Locked. Leaving the locked state.")
        end,
    },
    Unlocked = {
        transitions = {
            Push = "Locked"
        },
        OnEnter = function()
            log("▶️ ENTER: Unlocked. You may now push the turnstile.")
        end,
        OnExit = function()
            log("◀️ EXIT: Unlocked. Leaving the unlocked state.")
        end,
    }
}

local currentStateName = "Locked"

function transitionTo(newStateName)
    -- 1. VALIDATION
    local isAllowed = false
    local currentStateData = states[currentStateName]
    if currentStateData and currentStateData.transitions then
        for event, targetState in pairs(currentStateData.transitions) do
            if targetState == newStateName then
                isAllowed = true
                break
            end
        end
    end

    if not isAllowed then
        -- Log invalid attempts
        log("❌ INVALID TRANSITION: From '" .. currentStateName .. "' to '" .. newStateName .. "'. Denied.")
        return
    end

    -- 2. TRANSITION LOGIC
    -- Log the successful transition
    log("TRANSITIONING: " .. currentStateName .. " -> " .. newStateName)

    if currentStateData and currentStateData.OnExit then
        currentStateData.OnExit()
    end

    currentStateName = newStateName
    local newStateData = states[currentStateName]

    if newStateData and newStateData.OnEnter then
        newStateData.OnEnter()
    end
end

function handleEvent(event)
    log("-------------------------")
    log("EVENT received: " .. event)

    local currentStateData = states[currentStateName]
    local nextStateName = currentStateData.transitions[event]

    if nextStateName then
        transitionTo(nextStateName)
    else
        log("No transition found for event '" .. event .. "' in state '" .. currentStateName .. "'.")
    end
end

-- FSM Initialization
log("Initializing...")
local initialStateData = states[currentStateName]
if initialStateData.OnEnter then
    initialStateData.OnEnter()
end

-- Test sequence
wait(2)
log("Attempting an illegal direct transition...")
transitionTo("Locked") -- Should be denied and logged
wait(2)
handleEvent("Coin") -- Should succeed
wait(2)
handleEvent("Push") -- Should succeed

When you run this in Roblox Studio, your output window will now show a clean, prefixed log that is much easier to read and filter.

3. Using Callbacks as Debugging Hooks

The OnEnter, OnExit, and OnUpdate callbacks are the perfect places to insert debugging logs. They allow you to see exactly when a state becomes active, when it ceases to be active, and what it's doing on every frame or tick. This pattern is widely used in practice.

This strategy of embedding log messages directly into the state definitions is incredibly effective. It turns your state configuration table into a self-documenting and self-debugging tool.

The same pattern appears in another example from the Roblox developer forum.

4. Beyond the Console: Visual Debugging

Printing to the console is essential, but sometimes you need a more immediate, in-game way to see what state your FSM is in. This is especially true for NPCs or interactive objects. Visual debugging provides this at-a-glance feedback.

Simple techniques for visual debugging include:

• Changing a Part's BrickColor or Material.
• Displaying the current state name in a BillboardGui or TextLabel above the object.
• Playing a small sound or particle effect on state entry.

This is not just for debugging; changing an object's color or appearance can be part of the actual game mechanic, and the FSM is the perfect tool to drive it.

You can also use the Roblox Studio debugger to pause execution and inspect the FSM object directly to see the value of currentStateName, as shown in the image below.

Conclusion

You have now learned how to properly instrument your FSM for testing and debugging. While it may seem simple, establishing good logging practices early on will save you countless hours of troubleshooting as your projects grow in complexity.

Key Takeaways:

• Structured Logging is Key: Use a consistent format (e.g., [FSM Name] Message) for your log output to make it easy to read and filter.
• Leverage Callbacks: The OnEnter, OnExit, and OnUpdate callbacks are the ideal places to put log statements to trace the lifecycle of your states.
• Log What Matters: Focus on logging state transitions, the events that cause them, and any invalid attempts that were blocked.
• Think Visually: Don't forget about visual debugging. Changing colors or displaying text in-game can provide immediate insight into your FSM's behavior.

This lesson concludes our module on implementing a basic FSM. You've gone from simple if/else logic to a robust, table-driven, and debuggable FSM.

In the next module, we will take a significant step forward. We'll encapsulate all this logic into a reusable ModuleScript. This will allow you to create multiple, independent FSM instances from a single, clean, object-oriented module, preparing you for managing many NPCs, UI systems, or game states at once.