Warning
Work in progress. Aspid.Core.HSM is under active development. The public API is not yet stable and may change without notice between releases. Use with care in production.
Aspid.Core.HSM is a Roslyn-powered Hierarchical State Machine for Unity, built from small composable abstractions: states with Enter / Exit hooks, a parent→child hierarchy expressed through the generic IChildState<TParent> interface, pluggable per-frame controllers (IUpdateController, IFixedUpdateController, ILateUpdateController, …) aggregated via [ControllerGroup], composites that pick their own leaf (IEntrySelector), declarative guarded transitions ([Transition]), extension states ([ExtensionFor]), state scopes and async enter/exit (ChangeStateAsync). IEnteredController runs once the transition that entered a state has completed, with a token that lives as long as the state. MonoStateMachine wires it all to the Unity MonoBehaviour lifecycle.
Aspid.Core.HSM needs two packages installed: UniTask first, then the HSM itself. In the Package Manager click + → Install package from git URL… and paste each URL below.
The async enter/exit controllers are built on UniTask, so the package does not compile without it.
https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.5.11
Why this is a manual step. UPM does not resolve git dependencies transitively — a
dependenciesentry pointing at a git URL is simply ignored for anyone installing this package. Declaring UniTask in the manifest would therefore not install it, so it is installed explicitly instead. If you already get UniTask from the OpenUPM scoped registry, that installation works just as well; nothing here depends on how UniTask arrived.
The upm-preview branch always points to the latest preview release (alpha, beta, rc, …):
https://github.com/VPDPersonal/Aspid.Core.HSM.git#upm-preview
To pin a specific preview version, target the immutable per-release tag (see Releases for the list of available versions):
https://github.com/VPDPersonal/Aspid.Core.HSM.git#upm-preview/0.0.1-alpha.6
Note. There is no stable release yet, so the
upmbranch does not exist. The Release workflow creates it — along withupm/<version>tags and a#upminstall URL — when the first non-prerelease version ships.
Import it from the package's Samples tab. Its scripts read input through the Input System, so install com.unity.inputsystem from the Unity Registry first, or the sample does not compile.
ChangeStateAsync, TransitionToAsync and TransitionViaAsync tell why they ended without completing. Every case is an
OperationCanceledException, so an existing catch (OperationCanceledException) keeps catching all of them. The cause is
recorded when the transition is cancelled, not guessed from the machine's state when the exception arrives.
| Exception | Meaning | Usual handling |
|---|---|---|
TransitionSupersededException |
A newer transition took over; SupersedingState names its target, RollbackExceptions holds what the rollback threw |
Nothing: the newer transition owns the machine |
StateMachineDisposedException |
The machine was disposed | Nothing: the machine is gone |
OperationCanceledException (exactly) |
The caller's token, or an enter/exit callback cancelled itself (a load gave up) | A failure: apply your error policy |
| any other exception | An enter, exit or hook threw | A failure: apply your error policy |
A stage that waits for an event after its state is entered implements IAsyncEnteredController: the machine starts
OnEnteredAsync(StateEntry entry) once the transition is over and owns its outcome. The state exiting, the next
transition being superseded and the machine being disposed stay silent; any other failure goes to the nearest
IEnteredFailedController on the stage's state or above it when the stage started, or to the machine's
OnEnteredFailed. Leave the state through entry.ChangeStateAsync<T>(), so a failure of that transition is reported
even after the state has exited. Once the state has exited, the entry starts no transition.
MIT.