HFSM

A production-oriented Hierarchical Finite State Machine (HFSM) for Unity — featuring nested/parallel states, state history, flexible transitions, async flows, and a live Editor debugger.

Version Compatibility

Unity 6000.3.20f1 or newer (6000.3 stream).

Platform Support

Any platform Unity supports — pure C#, no native plugins, no platform-specific code.

Dependencies (Not included — must be added separately, see documentation)

• Encosy Tower 0.1.7-preview.3 — required. Added via a tagged Git package URL (not on the Unity registry or OpenUPM).
• Unity Collections 2.6.8 — required. Resolves automatically from Unity's registry.
• Unity Mathematics 1.3.3 — required. Resolves automatically from Unity's registry.
• UniTask 2.5.11 — optional. Only needed if you prefer it over Unity's built-in Awaitable for async transitions.

What's Included

• Runtime assembly (ApexionGame.HFSM):The state machine core — builder API, transitions, history, parallel regions, async flows, pooling, the shared runner.
• Editor assembly:[A live runtime debugger window (pan/zoom graph, active-leaf/transition animation, guard inspector, scene marker).
• Authoring assembly: The MachineGraphAsset data model and typed MachineGraphBindings for the visual editor.
• Test assembly: The full EditMode test suite (155 tests) used to develop this package.
• Sample: "HFSM Playground" — a self-running Play Mode scene with 5 live machine instances (4 interchangeable enemy archetypes + 1 flagship Boss using parallel regions).

Known Limitations

• The UI Toolkit visual graph editor is implemented but gated behind a "coming soon" notice in this version. All machines must currently be authored through the code-first builder API (fully documented, used throughout the included sample).

Documentation

Full README covers installation, quick start, async transitions, performance characteristics, and the debug scripting defines (APEXION_HFSM_DEBUG, DISABLE_APEXION_CHECKS).

ApexionGame HFSM is a production-ready Hierarchical Finite State Machine built for complex gameplay AI. Designed for performance and flexibility, it supports nested composites, parallel regions, shallow/deep history, guard/trigger/timer transitions, async enter/exit flows, pooled instances, and runtime diagnostics.

KEY FEATURES

• Nested Composites & Parallel Regions: Run multiple independent state regions (e.g., locomotion, combat, status effects) simultaneously on a single machine.
• Shallow & Deep History: Remembers and resumes active state paths instead of forcing a reset to initial child states.
• Flexible Transition Pipeline: Supports Guard, Trigger, Timer, Priority, and Internal transitions evaluated in a deterministic order (AnyState first, deepest node next).
• Async Enter/Exit Flows: Smoothly handles async operations (loading scenes, playing animations, state fades) using UniTask or Unity's built-in Awaitable.
• Live Editor Debugger: Features a pan/zoom graph view, animated active-leaf/transition indicators, per-guard eligibility inspection, and scene markers for selected actors.
• Zero-GC Performance: Optimized steady-state tick with zero garbage collection, verified by an included 256-node benchmark suite.

INCLUDED SAMPLE — HFSM PLAYGROUND

Includes a ready-to-run Play Mode scene demonstrating:

• Enemy Archetypes: Guard, Coward, Turret, and Scout.
• Flagship Boss AI: Built using a single Parallel node driving 4 concurrent regions (Locomotion, Attack Combo, Guard/Parry/Riposte, and Health Phase Region).
• Data-Driven Tuning: All stats live on MonoBehaviour prefabs — tweak balance directly in the Inspector without recompiling.

REQUIREMENTS & DEPENDENCIES

• Unity Version: Unity 6000.3.20f1 or newer.
• Dependencies: Requires Encosy Tower (installed via Git package URL — see README for step-by-step instructions).
• Optional: UniTask (supported if present, falls back to Unity Awaitable).

ROADMAP / COMING SOON

• A UI Toolkit visual graph authoring tool is currently in development. You can construct state machines using the intuitive code-first Builder API in the meantime.

COMMUNITY & SUPPORT

Need help or have questions? Join our Discord community:

https://discord.gg/RWxZqHDYP