--- title: "Hierarchical Final State Machine - s&box library" description: "About Hierarchical Final State Machine\n\nHFSM (Hierarchical Finite State Machine) is a simple and flexible library for building state machines in C#. The library provides an easy-to-use API for defining states, transitions, and hierarchical relationships between states.\n\nFeature\n\n- Define states with custom behavior (OnEnter, OnUpdate, OnExit)\n\n- Define transitions based on events and/or guard conditions\n\n- Hierarchical state organization\n\n- State machine builder for easy construction and configuration\n\n- Event-driven state updates\n\nExemple of usage - Fictionnal\n\n// Define your state and event enums\npublic enum MyState { Root, Idle, Walk, Run }\npublic enum MyEvent { FreezePlayer , StartRun}\n\nprivate HFSM m_hfsm;\n\nprivate void BuildHFSM()\n{\n// Create a new HFSMBuilder instance\n var builder = new HFSMBuilder();\n\n // Add states to the builder\n builder.AddState(MyState.Movement);\n builder.AddState(MyState.Idle, MyState.Movement);\n builder.AddState(MyState.Walk, MyState.Movement, OnStartWalk, OnUpdateWalk, OnExitWalk);\n builder.AddState(MyState.Run, MyState.Movement);\n builder.AddState(MyState.Freeze, OnEnterFreeze);\n\n //// Define transitions between states\n // Can use a guard\n builder.AddTransition(MyState.Idle, MyState.Walk, () => IsMoving);\n\n // An event\n builder.AddTransition(MyState.Movement, MyState.Freeze, MyEvent.FreezePlayer);\n\n // Or both\n builder.AddTransition(MyState.Walk, MyState.Run, () => Pawn.Velocity > 15, MyEvent.StartRun);\n\n // Build the state machine\n var hfsm = builder.Build();\n\n}\n\nprotected override void OnActivate()\n{\n BuildHFSM();\n base.OnActivate();\n}\n\n[GameEvent.Tick]\nprivate void OnUpdate()\n{\n // Update the state machine\n m_hfsm.Update();\n}\n\nprivate void OnStartWalk()\n{\n Log.Info(\"I'm walking!\")\n}\n\nprivate void OnUpdateWalk()\n{\n // Do stuff\n}\n\nprivate void OnExitWalk()\n{\n // Do stuff\n}\n\nprivate void OnEnterFreeze()\n{\n Log.Info(\"It's getting cold in there!\")\n}\n\nprotected override void OnDeactivate()\n{\n // Stop the state machine\n m_hfsm.Stop();\n}\n\nAnother exemple - Movement controller\n\npublic partial class MovementsController : EntityComponent\n{\n private void BuildHFSM()\n {\n HFSMBuilder builder = new HFSMBuilder();\n builder.AddState( States.OnGroundState , OnEnterGroundState, OnUpdateGroundState, OnExitGroundState);\n {\n builder.AddState( States.JogState ,States.OnGroundState, OnEnterJogState);\n {\n builder.AddTransition( States.JogState, States.RunState , () => Input.Down( \"run\" ));\n builder.AddTransition( States.JogState, States.WalkState , () => Input.Down( \"walk\" ));\n builder.AddTransition( States.JogState, States.DuckState , () => Input.Down( \"duck\" ));\n }\n builder.AddState( States.RunState ,States.OnGroundState, OnEnterSprintState);\n {\n builder.AddTransition( States.RunState, States.JogState , () => !Input.Down( \"run\" ));\n builder.AddTransition( States.RunState, States.WalkState , () => Input.Down( \"walk\" ));\n builder.AddTransition( States.RunState, States.DuckState , () => Input.Down( \"duck\" ));\n }\n builder.AddState( States.WalkState ,States.OnGroundState, OnEnterWalkState);\n {\n builder.AddTransition( States.WalkState, States.JogState , () => !Input.Down( \"walk\" ));\n builder.AddTransition( States.WalkState, States.DuckState , () => Input.Down( \"duck\" ));\n }\n builder.AddState( States.DuckState, States.OnGroundState, OnEnterDuckState, null , OnExitDuckState);\n {\n builder.AddTransition( States.DuckState, States.JogState , () => !Input.Down( \"duck\" ) && CanUnduck());\n }\n builder.AddTransition( States.OnGroundState, States.InAirState , () => !Grounded);\n }\n builder.AddState( States.InAirState , OnEnterAirState, OnUpdateAirState, OnExitAirState);\n {\n builder.AddTransition( States.InAirState, States.DuckState , () => Input.Down( \"duck\" ) && Grounded );\n builder.AddTransition( States.InAirState, States.OnGroundState , () => Grounded );\n }\n m_hfsm = builder.Build();\n }\n}\n}" canonical: "https://sbox.watch/libraries/utopia/hfsm/" generated_at: "2026-07-22T23:17:23.213Z" --- # Hierarchical Final State Machine No summary provided. - Type: library - Ident: utopia.hfsm - Creator: UTOPIA - Canonical: https://sbox.watch/libraries/utopia/hfsm/ - Markdown: https://sbox.watch/libraries/utopia/hfsm.md - sbox.game: https://sbox.game/utopia/hfsm/ - Generated: 2026-07-22T23:17:23.213Z ## Stats - 24h momentum: +0 - Terry score: 43% - Favorites: 1 - Upvotes: 2 - Downvotes: 0 - Updated: Jul 29, 2023 - Created: Jul 26, 2023 - Size: 23.1 KB - Files: 4 - Tags: fsm, hfsm, code, library ## Description About Hierarchical Final State Machine HFSM (Hierarchical Finite State Machine) is a simple and flexible library for building state machines in C\#. The library provides an easy-to-use API for defining states, transitions, and hierarchical relationships between states. Feature - Define states with custom behavior (OnEnter, OnUpdate, OnExit) - Define transitions based on events and/or guard conditions - Hierarchical state organization - State machine builder for easy construction and configuration - Event-driven state updates Exemple of usage - Fictionnal // Define your state and event enums public enum MyState { Root, Idle, Walk, Run } public enum MyEvent { FreezePlayer , StartRun} private HFSM m\_hfsm; private void BuildHFSM() { // Create a new HFSMBuilder instance var builder = new HFSMBuilder(); // Add states to the builder builder.AddState(MyState.Movement); builder.AddState(MyState.Idle, MyState.Movement); builder.AddState(MyState.Walk, MyState.Movement, OnStartWalk, OnUpdateWalk, OnExitWalk); builder.AddState(MyState.Run, MyState.Movement); builder.AddState(MyState.Freeze, OnEnterFreeze); //// Define transitions between states // Can use a guard builder.AddTransition(MyState.Idle, MyState.Walk, () => IsMoving); // An event builder.AddTransition(MyState.Movement, MyState.Freeze, MyEvent.FreezePlayer); // Or both builder.AddTransition(MyState.Walk, MyState.Run, () => Pawn.Velocity > 15, MyEvent.StartRun); // Build the state machine var hfsm = builder.Build(); } protected override void OnActivate() { BuildHFSM(); base.OnActivate(); } \[GameEvent.Tick\] private void OnUpdate() { // Update the state machine m\_hfsm.Update(); } private void OnStartWalk() { Log.Info("I'm walking!") } private void OnUpdateWalk() { // Do stuff } private void OnExitWalk() { // Do stuff } private void OnEnterFreeze() { Log.Info("It's getting cold in there!") } protected override void OnDeactivate() { // Stop the state machine m\_hfsm.Stop(); } Another exemple - Movement controller public partial class MovementsController : EntityComponent { private void BuildHFSM() { HFSMBuilder builder = new HFSMBuilder(); builder.AddState( States.OnGroundState , OnEnterGroundState, OnUpdateGroundState, OnExitGroundState); { builder.AddState( States.JogState ,States.OnGroundState, OnEnterJogState); { builder.AddTransition( States.JogState, States.RunState , () => Input.Down( "run" )); builder.AddTransition( States.JogState, States.WalkState , () => Input.Down( "walk" )); builder.AddTransition( States.JogState, States.DuckState , () => Input.Down( "duck" )); } builder.AddState( States.RunState ,States.OnGroundState, OnEnterSprintState); { builder.AddTransition( States.RunState, States.JogState , () => !Input.Down( "run" )); builder.AddTransition( States.RunState, States.WalkState , () => Input.Down( "walk" )); builder.AddTransition( States.RunState, States.DuckState , () => Input.Down( "duck" )); } builder.AddState( States.WalkState ,States.OnGroundState, OnEnterWalkState); { builder.AddTransition( States.WalkState, States.JogState , () => !Input.Down( "walk" )); builder.AddTransition( States.WalkState, States.DuckState , () => Input.Down( "duck" )); } builder.AddState( States.DuckState, States.OnGroundState, OnEnterDuckState, null , OnExitDuckState); { builder.AddTransition( States.DuckState, States.JogState , () => !Input.Down( "duck" ) && CanUnduck()); } builder.AddTransition( States.OnGroundState, States.InAirState , () => !Grounded); } builder.AddState( States.InAirState , OnEnterAirState, OnUpdateAirState, OnExitAirState); { builder.AddTransition( States.InAirState, States.DuckState , () => Input.Down( "duck" ) && Grounded ); builder.AddTransition( States.InAirState, States.OnGroundState , () => Grounded ); } m\_hfsm = builder.Build(); } } } ## More by UTOPIA | Package | Ident | Players | Favorites | Upvotes | Score | Markdown | | --- | --- | --- | --- | --- | --- | --- | | NPBehave for SANDBOX | utopia.npbehavesbox | 0 | 2 | 0 | -- | https://sbox.watch/libraries/utopia/npbehavesbox.md |