FSM Code Generator | 易学教程

FSM Code Generator is a script code generator for Finite State Machine,

it has a viaual designer based on Animator Controller that helps you design an FSM.

First of all, I assume you know about what the Animator Controller is, if not, nvm. we just use it

as the tools of visual designer.(About Animator Controller : https://docs.unity3d.com/Manual/class-AnimatorController.html)

The Animator Controller is a state machine for play animation, it can make state transition, animation blending, avator mask, ect...

what we need for FSM designer is the transition.

Double click the Example Animator Controller in folder [Assets/FSM Code Generator/Example/Assets] you can see GameState and PlayerState examples,

and scenes to test them. see below

　　　　　　　　　　(GameState)　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　(PlayerState)

these are 2 kinds of FSM situation that we most using,

GameState is a single state machine like gearbox of a car, it only runs a state in a time,

PlayerState is a multi state machine in common, player can have run/poisioned states at the same time, and can not have run/dead at the same time, right?

and if you noticed the transition lines linking states, you will guess what is it means? is it the same as Animator Controller means transferable?

No, the Transition link is not means transferable, it means conflict/mutex states

See PlayerState Animator Controller, [Stand] <--> [Run] is bin-linked, it means these two states are single state that only one can run in a time, if you add Run state, Stand state will be ended, if you add Stand state, Run state will be ended,

and [Run] --> [Stun], [Stand] --> [Stun] are single-linked, it means they are conflicted, if Run state exists then add Stun state, the Run state should be ended automatically, and if Stun state exists then add Run state will be FAILED, right? it make sense.

So how can this happaned? FSM Code Generator will generate priority for all states, the bottom-right states are higher priority than the top-left states,

so the Stun state will eliminate lower conflicted states such as Run or Stand states(single-linked, direction is no means, ignor it), but the Run or Stand states can not added if Stun state exists.

And please notice the bin-linked states are have diferent priority but equals to eachother logically, the exists state will be ended while add new state which bin-linked.

And you can see the special transition lines from [Entry] and [Any State], the transition from [Entry] is default, we don't use it, just leave it alone.

The [Any State] meas all other states linking to target just like Dead state in PlayerState, it is conflict to all states, it is syntax sugar :)

and you can see GameState's all states has transition from [Any State], logically they are all bin-linked states, so GameState is a gear box.

These above are all about the logic of FSM Code Generator and some Usage scenarios of state machine, Finally we will generate this FSM to code

let's see how to make it:

1. Open Editor panel on menu bar [Tools/FSM Code Generator]

　　　　　　　　　　　　(FSM Code Generator Window)

2. Drag a Animator Controller to Selected AnimatorController field, like this

PlayerState was selected, the script file generate list is showing in the Editor Window, every state will generate a file named PlayerState_{StateName}.cs,

and generate state enum to PlayerStateDefine.cs file, And what's more a PlayerStateGenericManager.cs will be created, this is the state machine runtime manager, we will talk about it later.

you can choose which one to generate by check box, [Select All] [UnSelect All] button is used for it.(I found mistype of these words, I'll fix it later, don't worry)

[Don't over write exists...]check box is don't generate if file exists, whatever.

3. [Start Gen FSM] button is to start generate scripts. PlayerState and GameState were generated to [Assets/FSM Code Generator/Example/GameState] and [Assets/FSM Code Generator/Example/PlayerState] already.

PlayerState generated codes, we can see files in PlayerState folder,

The PlayerStateDefine is state enum and mutex map defines, I'll talk about it later.

The PlayerState_{StateName} files is the state script, with life cycle impement

The PlayerStateGenericManager is controlling the states

You can open the example scene to see how the state machine runs, let's open the TestPlayerState scene at [Assets/FSM Code Generator/Example/Assets/TestPlayerState]

and run the scene:

Screen shows all states of PlayerState, click them to see console output

Check the logic is run according your design or not !

you can open TestPlayerState.cs file to see how to create PlayerStateGenericManager and how to create any state instance,

here is a quick veiw for run a state machine(PlayerState) :

var playerStateManager = FSMCodeGenerator.FSM.PlayerStateFSM.PlayerStateGenericManager.Create();
playerStateManager.AddState(FSMCodeGenerator.FSM.PlayerStateFSM.Stand.Create());
playerStateManager.AddState(FSMCodeGenerator.FSM.PlayerStateFSM.Run.Create());
playerStateManager.AddState(FSMCodeGenerator.FSM.PlayerStateFSM.Dead.Create());

They all have Factory to create instance, we do recommand to use it.

The generated code review(PlayerState) :

1. PlayerStateDefine.cs : is the enum of PlayerState, and muetxMap, state conflict logic and priority implement is based on it

using UnityEngine;
using System;
using System.Collections;
using System.Collections.Generic;
using FSMCodeGenerator.FSM;

namespace FSMCodeGenerator.FSM
{
    public sealed partial class PlayerStateFSM
    {
        public enum  PlayerStateEnum
        {
            Stand = 0,
            Run = 1,
            Stun = 2,
            Poisoned = 3,
            Immortal = 4,
            Dead = 5
        }

        [UnityEngine.Scripting.Preserve]
        public static GenericStateTransitionMap<PlayerStateEnum> mutexMap = 
              new GenericStateTransitionMap<PlayerStateEnum>(null,
                    (_mutexMap) =>
                    {
                        _mutexMap.Clear();
                        // mutex setting
                        _mutexMap[PlayerStateEnum.Run] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                            PlayerStateEnum.Stand,
                            PlayerStateEnum.Stun,
                        };
                        _mutexMap[PlayerStateEnum.Immortal] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                        };
                        _mutexMap[PlayerStateEnum.Poisoned] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                            PlayerStateEnum.Immortal,
                        };
                        _mutexMap[PlayerStateEnum.Stand] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                            PlayerStateEnum.Stun,
                            PlayerStateEnum.Run,
                        };
                        _mutexMap[PlayerStateEnum.Dead] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                        };
                        _mutexMap[PlayerStateEnum.Stun] = new HashSet<PlayerStateEnum>()
                        {
                            PlayerStateEnum.Dead,
                            PlayerStateEnum.Immortal,
                        };
        
                    });
    }
}

2. PlayerState_{StateName}.cs : State Script with life cycle. below is Run State, if you don't care about the base class(Common.FSM.FSMState<T> which is a Generic State Machine),

you should just write your code in life cycle.

2.1 OnInit(object param) is first called if a state was added to GenericManager(here is PlayerStateGenericManager), and you can pass any object to it

2.2 OnEnter() is called after OnInit, and you can do test if this state can enter or not, if return false, GenericManager will end it

2.3 OnUpdate(float deltaTime) if state enter successed, this will be call every frame, if return false, GenericManager will end it

2.4 OnExit() if state will be ended, this will be called

using UnityEngine;
using System;
using System.Collections;
using System.Collections.Generic;
using FSMCodeGenerator.FSM;

namespace FSMCodeGenerator.FSM
{
    public sealed partial class PlayerStateFSM
    {
        public class Run : FSMCodeGenerator.FSM.FSMState<PlayerStateEnum>
        {
            public FSMCodeGenerator.FSM.GenericManager<PlayerStateEnum> fsmManager { get; private set; }            
        
            // ctor
            public Run() { }
        
            // Factory
            [UnityEngine.Scripting.Preserve]
            public static Run Create(FSMCodeGenerator.FSM.GenericManager<PlayerStateEnum> mamager = null)
            {
                var comp = Create<Run>(PlayerStateEnum.Run);
                comp.fsmManager = mamager;
                return comp;
            }
        
            protected override void OnInit(object param)
            {
                Debug.Log(this.GetType().Name + " : OnInit()");
                
            }
        
            protected override bool OnEnter()
            {
                Debug.Log(this.GetType().Name + " : OnEnter()");
                return true;
            }
        
            protected override void OnExit()
            {
                Debug.Log(this.GetType().Name + " : OnExit()");
                
            }
        
            protected override bool OnUpdate(float deltaTime)
            {
                return true;
            }
        }
    }
}

3. PlayerStateGenericManager.cs : This is the manager for running all added states, control the life cycles, and tick states every frame

using UnityEngine;
using System;
using System.Collections;
using System.Collections.Generic;
using FSMCodeGenerator.FSM;

namespace FSMCodeGenerator.FSM
{
    public sealed partial class PlayerStateFSM
    {        
        public class PlayerStateGenericManager : FSMCodeGenerator.FSM.GenericManager<PlayerStateEnum>
        {
            protected FSMCodeGenerator.Common.StateMachineRunner runner;
            // ctor
            public PlayerStateGenericManager() { }
        
            [UnityEngine.Scripting.Preserve]
            public static PlayerStateGenericManager Create()
            {
                var manager = Create<PlayerStateGenericManager>();
                manager.runner = (new GameObject()).AddComponent<FSMCodeGenerator.Common.StateMachineRunner>();
                manager.runner.Run(manager);
                return manager;
            }
        }
    }
}

Base class API : used for control the states, the quick veiw example shows how a state machine to add a state, these are other APIs.

public bool AddState(FSMState<ID> state, object param = null);
public bool AddState(ID id, System.Func<FSMState<ID>> stateCreator, object param = null);

public bool ContainsState(ID id);
public bool ContainsState(FSMState<ID> tagState);

public T GetState<T>(bool fromTail = false) where T : FSMState<ID>;
public List<T> GetAllStates<T>() where T : FSMState<ID>;

public void EndState(ID id, bool fromTail = false);
public void EndState(FSMState<ID> tagState, bool fromTail = false);
public void EndStates(ICollection<ID> endStateIDs, bool fromTail = false);
public void EndStates(ICollection<FSMState<ID>> endStates, bool fromTail = false);
public void EndStates(System.Func<FSMState<ID>, bool> predicate, bool fromTail = false);
public void EndAllStates(bool fromTail = false);