Validating State Transitions

1. Why Transitions Need Rules

A Finite State Machine isn't just a collection of states; it's also the set of defined pathways between them. A state diagram's arrows don't just show possibilities; they also define limitations. Any transition not represented by an arrow is implicitly forbidden.

Consider this FSM for an NPC.

According to this diagram, it's impossible for an NPC to go from the Idle / Guard state directly to the Attack state. It must first spot a player. Likewise, an NPC in an Attack state that has killed the player should return to its post, not magically jump to a Patrol waypoint in a different area.

Our code must enforce these rules. If we allow illegal transitions, we could end up with an NPC stuck in an animation, trying to attack a non-existent target, or simply behaving erratically. By adding validation, we make our FSM foolproof and ensure it behaves exactly as designed.

2. Defining Permissible Transitions

So, how do we represent these rules in our code? The most straightforward way is to explicitly list which transitions are allowed from each state. This is often called a "whitelist" approach.

For our table-driven FSM, this information is already present in our states table!

-- From our previous lesson
states = {
    Locked = {
        transitions = {
            Coin = "Unlocked"
        },
        -- ...
    },
    Unlocked = {
        transitions = {
            Push = "Locked"
        },
        -- ...
    }
}

In the Locked state, the transitions table specifies that the only possible target state is "Unlocked". In the Unlocked state, the only target is "Locked". This table, which we previously used to map events to new states, also serves as our list of permissible transitions.

Our validation logic will be simple: before executing a transition, we will check if the requested new state exists as a value anywhere inside the current state's transitions table.

3. Hands-On: Implementing Validation

Let's modify the transitionTo function from our last lesson to include this validation check.

We'll use the same turnstile script. The only part that will change is the transitionTo function, plus a few new test cases to prove our validation works.

Here is the updated script. Pay close attention to the new validation block at the start of transitionTo.

local RunService = game:GetService("RunService")

local states = {
    Locked = {
        transitions = {
            Coin = "Unlocked"
        },
        OnEnter = function()
            print("▶️ ENTER: Locked. The turnstile is now locked.")
        end,
        OnExit = function()
            print("◀️ EXIT: Locked. Leaving the locked state.")
        end,
        -- OnUpdate can be omitted for this example
    },
    Unlocked = {
        transitions = {
            Push = "Locked"
        },
        OnEnter = function()
            print("▶️ ENTER: Unlocked. You may now push the turnstile.")
        end,
        OnExit = function()
            print("◀️ EXIT: Unlocked. Leaving the unlocked state.")
        end,
        -- OnUpdate can be omitted for this example
    }
}

local currentStateName = "Locked"

-- MODIFIED: The transition function now validates the requested state
function transitionTo(newStateName)
    -- 1. VALIDATION STEP
    local isAllowed = false
    local currentStateData = states[currentStateName]
    
    -- Check if the requested 'newStateName' is a valid destination 
    -- from the current state's transition table.
    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
        print("❌ INVALID TRANSITION: Cannot move from '" .. currentStateName .. "' to '" .. newStateName .. "'.")
        return -- Stop execution if the transition is not allowed
    end

    -- 2. TRANSITION LOGIC (from previous lesson)
    print("TRANSITIONING: " .. currentStateName .. " -> " .. newStateName)

    -- Call OnExit for the state we are LEAVING
    if currentStateData and currentStateData.OnExit then
        currentStateData.OnExit()
    end

    -- Update the state name
    currentStateName = newStateName

    -- Call OnEnter for the state we are ENTERING
    local newStateData = states[currentStateName]
    if newStateData and newStateData.OnEnter then
        newStateData.OnEnter()
    end
end

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

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

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

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


-- Simulate events to test the validation
wait(2)
-- This is an attempt to force an ILLEGAL transition directly.
-- The turnstile can't go from Locked to Locked. Our validation should catch this.
print("Attempting an illegal direct transition...")
transitionTo("Locked") 
wait(2)

-- This is a legal event-based transition. It should work.
handleEvent("Coin")
wait(2)

-- This is another legal transition.
handleEvent("Push")

Analysis of the Change

When you run this script, look at the output for the "illegal direct transition" test. You should see:
❌ INVALID TRANSITION: Cannot move from 'Locked' to 'Locked'.

The function immediately stops, and no OnExit or OnEnter calls are made. This is our validation at work! The handleEvent calls continue to work as before because they only ever request legal transitions defined in the transitions table.

Our transitionTo function is now robust. It's the single, safe gateway for all state changes, whether triggered by an event (handleEvent) or forced directly by another part of your game's logic (like a timer ending).

4. A Preview of Dynamic Validation: Guard Conditions

Our current validation is static—it only depends on the fixed structure of the FSM. But what if a transition should only be allowed under certain dynamic conditions?

• An NPC can only transition to Attack if the player is within a certain range.
• A player can only transition to Reload if they have reserve ammunition.
• A user can only transition to LoggedIn if their password attempt count is less than 3.

These checks are called guard conditions. They are extra logic, usually a function that returns true or false, that must pass for a transition to be allowed.

This is a more advanced topic that we will fully implement later in the course. For now, it's useful to see how it adds another layer of control.

Conclusion

You've now made your FSM significantly more reliable by adding a crucial validation layer. By enforcing the rules of your FSM's design, you prevent bugs and ensure predictable behavior.

Key Takeaways:

• State diagrams define both the states and the only permissible transitions between them.
• Validating transitions within the FSM prevents illegal state changes and makes the system more robust.
• A simple and effective validation method is to check if a requested transition is listed in the current state's configuration (a "whitelist" approach).
• Our transitionTo function is now the single, secure entry point for all state changes.

In the next lesson, we'll formalize something we've been doing all along: debugging. We will learn how to test and debug an FSM by printing state transitions to the output console in a structured way, which is essential for troubleshooting more complex machines.