WBP Anim State Machine Reference

WBP Anim State Machine

The WbpAnimStateMachine module is a runtime and editor authoring system for driving UUserWidget animation behavior with explicit states, transitions, rules, debug tooling, and Sequencer support.

This document is the technical reference for what the module does today.

Purpose

Use the module when a widget has recognizable UI states such as:

Idle
Hover
Pressed
Focused
Disabled
Intro
Visible
Outro

Instead of spreading PlayAnimation calls across many Blueprint branches, the widget creates one or more state machines and asks them to move between named states.

High-Level Architecture

The module has eight major layers:

Authoring data

UWbpAnimStateMachineDefinition
FWbpAnimStateConfig
FWbpAnimTransitionConfig
FWbpAnimConditionRule
FWbpAnimInputBinding
FWbpAnimGasEventBinding
editor-only graph layout data
curve-atlas timed sequence bindings

Runtime controller

UWbpAnimStateMachine

Parallel track host

UWbpAnimStateMachineGroup

Blueprint-facing convenience API

UWbpAnimStateMachineBlueprintLibrary

Framework integration helpers

UWbpAnimCommonActivatableMixin - CommonUI bridge with no hard plugin dependency

Editor tooling

asset editor
graph widget
details/property customization
live debugger
tester/fuzz tooling
tester save/load via UWbpAnimTestSequenceAsset

Blueprint editor ergonomics

editor-only WbpAnimStateMachineEditor module
custom Go To WBP State K2 node
definition-aware state dropdowns on Blueprint state pins

Sequencer integration

UMovieSceneWbpAnimStateTrack
UMovieSceneWbpAnimStateSection
runtime evaluation template
Sequencer track editor registration

File Map

Public runtime-facing files

Source/WbpAnimStateMachine/Public/WbpAnimStateMachine.h
main runtime state machine object
transition, playback, blackboard, persistence, sub-machine, and stats APIs
Source/WbpAnimStateMachine/Public/WbpAnimStateMachineTypes.h
enums
state, transition, rule, input binding, GAS event binding, curve-atlas binding, snapshot, stats, and delegate types
Source/WbpAnimStateMachine/Public/WbpAnimStateMachineDefinition.h
asset-backed authoring surface
presets, export/import, enum generation, validation hooks, authored GAS bindings, and editor graph layout data
Source/WbpAnimStateMachine/Public/WbpAnimStateMachineBlueprintLibrary.h
Blueprint helpers for creation, transitions, latent flow, snapshots, tracks, input, and Sequencer helpers
Source/WbpAnimStateMachine/Public/WbpAnimCommonActivatableMixin.h
CommonUI activation/deactivation bridge
no hard CommonUI plugin dependency
uses delegate reflection to detect CommonUI widgets
Source/WbpAnimStateMachine/Public/WbpAnimTestSequenceAsset.h
UWbpAnimTestSequenceAsset data asset for persisting tester sequences
FWbpAnimTestSequenceStep - single saved transition step
Source/WbpAnimStateMachineEditor/Private/K2Node_WbpGoToState.h
editor-only Blueprint node for authored state transitions
provides a definition-driven state dropdown instead of a freeform FName
Source/WbpAnimStateMachine/Public/WbpAnimStateMachineGroup.h
named multi-track host for layered UI behavior
Source/WbpAnimStateMachine/Public/MovieSceneWbpAnimStateTrack.h
Source/WbpAnimStateMachine/Public/MovieSceneWbpAnimStateSection.h
Sequencer-facing types

Private implementation files

Source/WbpAnimStateMachine/Private/WbpAnimStateMachine.cpp
runtime implementation
state lookup cache
transition evaluation
playback and finish callbacks
timers
snapshots
stats
shipping debug stripping
Unreal Insights regions
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineDefinition.cpp
preset generation
validation
SVG export
JSON export/import
generated enum header output
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineBlueprintLibrary.cpp
Blueprint wrappers
latent GoToStateAndWait
machine lookup by definition
Sequencer track/section helper creation
Source/WbpAnimStateMachineEditor/Private/WbpAnimStateMachinePinFactory.cpp
swaps state-name pins for dropdowns when a definition asset can be resolved
supports the custom node directly and inferred Blueprint-library transition nodes
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineDefinitionEditor.cpp
dedicated asset editor toolkit
native graph, details, debugger, test, and diff tabs
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineEdGraph.cpp
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineEdGraphNode.cpp
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineEdGraphSchema.cpp
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineConnectionDrawingPolicy.cpp
native Unreal graph-framework editor surface, schema actions, node widgets, and connector drawing
Source/WbpAnimStateMachine/Private/SWbpAnimStateMachineDebugger.cpp
live debugger panel
instance browser
blackboard watch
timeline
transition log
condition breakpoints
Source/WbpAnimStateMachine/Private/SWbpAnimStateMachineTester.cpp
authoring-time test harness
coverage display
random-walk fuzz testing
Source/WbpAnimStateMachine/Private/WbpAnimStateMachineDefinitionDetails.cpp
details panel customization
live validation panel
summary-first health and direct-action guidance
Source/WbpAnimStateMachine/Private/WbpAnimStateMachinePropertyCustomization.cpp
animation and function dropdowns
Source/WbpAnimStateMachine/Private/MovieSceneWbpAnimStateTrack.cpp
Source/WbpAnimStateMachine/Private/MovieSceneWbpAnimStateSection.cpp
Source/WbpAnimStateMachine/Private/MovieSceneWbpAnimStateTemplate.cpp
Sequencer runtime evaluation
Source/WbpAnimStateMachine/Private/WbpAnimStateSequencerEditor.cpp
Sequencer editor integration
add-track and add-section workflow

Core Data Types

`FWbpAnimStateConfig`

Represents a single named state.

Important fields:

StateName
AnimationName
PlayMode
PlaybackRate
StartTime
bRestoreState
ReEnterPolicy
InterruptPriority
AutoTransitionDelay
AutoTransitionState
EntryFunctionName
ExitFunctionName
Group
StateTags
DesignerNotes
EditorNodeColor
editor-only node tint used by the graph
SubMachineDefinition
SubMachineMode
nested machine behavior for this state
CurveAtlasDuration
CurveAtlasBindings
optional timed property playback driven by UCurveLinearColor rows, with an atlas reference for authoring clarity and validation

Curve Atlas Timed Sequences

States can play a lightweight timed property sequence without requiring a full UMG animation timeline. Set CurveAtlasDuration and add one or more CurveAtlasBindings. Each binding samples a UCurveLinearColor row over normalized time and applies it to a named widget, or to the owner widget when WidgetName is empty.

Supported targets include render opacity, render translation, render scale, render shear, render angle, render pivot, color/tint for common widget classes, and visibility thresholding. Scalar properties choose one channel from the sampled RGBA value.

Curve Atlas sequences follow the state’s PlayMode and PlaybackRate. Finite curve-only states can trigger OnAnimationFinished transitions when their duration completes. Looping and ping-pong sequences continue until the state changes. Like notifies and tick conditions, runtime evaluation requires MachineTick(DeltaTime).

`FWbpAnimTransitionConfig`

Represents a valid edge between states.

Important fields:

FromState
NAME_None acts as a wildcard
ToState
Trigger
Manual or OnAnimationFinished
BlendTime
ConditionFunctionName
Rules
RuleMatchMode
TransitionTag
DesignerNotes
bEnableBreakpoint
editor/runtime breakpoint toggle for PIE debugging

TransitionGuard is a C++-only escape hatch on UWbpAnimStateMachine. It is not authorable from Blueprint. Blueprint users should put per-transition checks in ConditionFunctionName or built-in Rules instead.

`FWbpAnimConditionRule`

Built-in transition rule block evaluated directly in the runtime machine.

Supported sources:

blackboard float
blackboard bool
blackboard name
blackboard int
blackboard string
time in state
animation progress
current state
previous state

Supported comparisons:

equal
not equal
greater
greater or equal
less
less or equal
is true
is false

`FWbpAnimInputBinding`

Enhanced Input-driven transition rule authored on the definition.

Fields:

InputAction
TriggerEvent
TargetState
bForce
CallerPriority

`FWbpAnimGasEventBinding`

Gameplay Ability System event tag to state machine transition mapping. See GAS Event Bindings for the complete runtime integration pattern.

Fields:

EventTag — FGameplayTag to match (parent tags match children via MatchesTag)
TargetState
bForce — calls GoToState in force mode, bypassing the transition table
CallerPriority — priority used when bForce is true; it must meet or exceed the current state’s InterruptPriority

State-level input contexts

FWbpAnimStateConfig also supports Enhanced Input mapping-context ownership:

EntryInputContext
EntryInputContextPriority
ExitInputContext

Typical pattern:

set EntryInputContext to the context that should become active while the state is active
set ExitInputContext to that same context when the state should remove it on exit

`FWbpAnimStateMachineSnapshot`

Portable save/load payload for full machine restoration.

Stores:

current state
float blackboard values
bool blackboard values
name blackboard values
int blackboard values
string blackboard values
object references

`FWbpAnimStateMachineStats`

Runtime stats snapshot used by debug tooling.

Includes:

total transitions
blocked transitions
total runtime
time per state
entries per state

Runtime Object: `UWbpAnimStateMachine`

UWbpAnimStateMachine is the main runtime controller.

Ownership model

The machine is created with the widget as its Outer, which means:

it lives with the widget
it can safely resolve widget animations
it can search and call functions on the owner widget

Main responsibilities

cache state definitions and transitions
resolve AnimationName to UWidgetAnimation
maintain CurrentState and PreviousState
drive playback
evaluate manual and finish-driven transitions
run built-in rules and optional widget condition functions
maintain a lightweight blackboard
keep history
save/restore both simple state and full snapshots
own a nested child machine when a state requests one
bind Enhanced Input actions when configured
emit runtime delegates
collect stats and editor-only transition logs

O(1) state lookup

During Initialize(), the machine builds a StateIndexCache so FindStateConfig() is constant-time instead of scanning the full state list every request.

Recycle / pooling support

Recycle(UWbpAnimStateMachineDefinition* NewDefinition) resets the machine in place and reinitializes it without allocating a new UObject. This is intended for reused widgets such as list or tile entries.

Shipping build behavior

The module strips non-essential debug strings in shipping builds. Human-readable blocked reasons, transition summaries, and blackboard debug text do not carry runtime memory cost in shipping.

Unreal Insights integration

The machine emits named CPU profiler regions for state entry/exit timing. This makes active state durations visible in Unreal Insights while remaining effectively free in shipping.

Parallel Tracks: `UWbpAnimStateMachineGroup`

UWbpAnimStateMachineGroup is a lightweight host for multiple named machines on one widget.

Use it when UI behaviors should layer instead of exploding into combined states.

Examples:

Base for screen flow
Hover for pointer/controller feedback
Attention for pulse behavior
Modal for overlay state

Core methods:

AddTrack
GetTrack
GetTrackNames
GoToStateOnTrack
MachineTick
StopAll

Runtime Lifecycle

1. Creation

Typical path:

StateMachine = UWbpAnimStateMachine::CreateStateMachine(this, DefinitionAsset);

Blueprint path:

CreateAndInitializeStateMachine

2. Initialization

Initialization does the following:

copies definition data into runtime arrays
builds the state index cache
resolves widget animations
binds input actions if configured
enters the initial state

3. Entering a state

When a state is entered, the machine:

updates CurrentState and PreviousState
updates timers
calls entry function if authored
starts the state animation
arms any OnAnimationFinished handling
starts auto-transition timers
spawns or resumes a sub-machine if configured
broadcasts OnStateChanged and OnStateEntered

4. Requesting a transition

GoToState checks:

machine initialized
target state exists
re-entry policy
force priority rules
matching transition exists, if transitions are authored
rule block passes
condition function passes

If successful, it:

optionally begins blend signaling
logs the transition
ends previous state
stops or updates old playback
enters the new state

5. Finishing animation-driven transitions

For OnAnimationFinished transitions:

the current animation completion callback triggers evaluation
queued transitions are honored first
matching finish-driven transitions are then considered

6. Timed transitions

If a state has AutoTransitionDelay > 0 and AutoTransitionState != NAME_None, the machine arms a timer on entry and transitions automatically when it fires.

Blackboard System

The blackboard is intentionally small and UI-oriented.

Stored types:

float
bool
FName
int32
FString
UObject* as weak references

Use it for lightweight UI decision-making such as:

HasUnread
SelectedTab
CanDismiss
ToastMode
InputSource

Persistence

Simple state restore

SaveState()
RestoreState()

These store and restore only the current state name.

Full snapshots

SaveSnapshot()
RestoreSnapshot(...)

These store and restore the current state plus the complete blackboard.

Blueprint wrappers:

SaveMachineSnapshot
RestoreMachineSnapshot

Delegates

Main runtime delegates:

OnStateChanged
OnStateEntered
OnStateExited
OnTransitionBlocked
OnTransitionBegin
OnBlackboardChanged

These are the main bridge between the runtime machine and widget/game logic.

Blueprint Library

UWbpAnimStateMachineBlueprintLibrary is the easiest entry point for Blueprint users.

Important helpers:

CreateAndInitializeStateMachine
GoToState
GoToStateAndWait
latent version for linear Blueprint flows
FindMachineByDefinition
GoBack
CanTransitionTo
GetAvailableTransitions
SetBlackboard* and GetBlackboard*
SaveState
RestoreState
SaveMachineSnapshot
RestoreMachineSnapshot
CreateStateMachineGroup
AddTrack
GoToStateOnTrack
AddInputBinding
AddSequencerStateTrack
AddSequencerStateSection

Blueprint node ergonomics

Editor builds also ship an authoring-specific node:

Go To WBP State
Go To WBP State And Wait

This wraps the same runtime GoToState call, but adds an optional State Definition pin that drives the State pin as a dropdown of authored state names.

Go To WBP State And Wait does the same thing for the latent flow helper, so designers can keep the authored-state dropdown while still building linear Blueprint sequences.

The editor pin factory also upgrades existing Blueprint-library GoToState and GoToStateAndWait nodes when it can infer the definition asset from a connected CreateAndInitializeStateMachine or CreateStateMachine node.

Recommended Blueprint workflow:

Create the machine from a definition asset
Use Go To WBP State for explicit authored transitions
Set State Definition on the node when the source definition cannot be inferred automatically

Definition Asset: `UWbpAnimStateMachineDefinition`

This asset is the main authoring surface for most users.

It stores:

InitialState
States
Transitions
InputBindings
OwnerWidgetClass
editor graph positions
group boxes
sticky notes
preset selection

Why `OwnerWidgetClass` exists

It is editor-only metadata used to:

populate animation dropdowns
populate entry/exit/condition function dropdowns
validate names against the real widget class

Presets

The asset includes quick presets such as:

Button
ToggleButton
Panel
Toast
Tab
LoadingScreen
Carousel

Export/import utilities

Call-in-editor utilities:

Export State Diagram (SVG)
Export Definition (JSON)
Import Definition (JSON)
Generate State Enum Header

Files are written to:

Saved/WbpAnimStateMachineExports

Generated enum headers are written to:

Saved/WbpAnimStateMachineExports/GeneratedHeaders

The enum header is intentionally generated outside your game’s compiled source tree. Copy it into your project Source folder if you want it included in your build.

Editor Tooling

Dedicated asset editor

The definition asset opens in a dedicated editor with:

Graph tab
Details tab
Debugger tab

Graph editor features

The graph supports:

pan and zoom
zoom LOD
minimap
search/filter
frame all
frame selected
rubber-band selection
multi-select
copy/paste/duplicate/delete
grid snap toggle
auto-arrange
alignment and distribution tools
live state heatmap
comment/group boxes
sticky notes
compact definition-health status in the graph header, so the editor surfaces healthy / warning / error state without leaving the graph
compact definition-level clip-risk counts in the graph header, so missing owner-widget clips and shared-clip reuse cases are visible without opening the validation list
when those definition-level clip risks are present, the graph header now also exposes a direct Open Owner Widget action so you can jump straight into the owning Widget Blueprint
selected-state status cues in the graph header for bound clips, child definitions, missing bindings, and unreachable-state warnings
selected-state next-step guidance in the graph header, now phrased with the same repair-path framing as the workbench so both tools describe fixes in a more consistent way
selected-clip review cues in the graph header, so a state also tells you whether its clip exists on the owner widget and whether that clip is shared by multiple states
transition creation by drag
selected-state handoff back into the owning Widget Blueprint animation context via Open Matching Clip
when the state machine is opened from the workbench, the graph header now acknowledges the incoming clip context directly with a compact From clip <Name> cue, so the current focus reads as an intentional bridge target instead of just a selected node
that same incoming bridge context now also elevates the matching state node itself with a dedicated bridge accent, so the graph and workbench both treat the bridged clip/state pair as the primary context instead of only exposing it in summary text
transition creation from any node edge
selected transition inspector
context menus for canvas, nodes, transitions, groups, and sticky notes
transition breakpoint toggles
quick keyboard editing for transitions
welcome overlay for empty assets

The editor now uses a native Unreal graph-framework surface as its default Graph tab. It is built on UEdGraph and SGraphEditor, bringing the state machine editor closer to Unreal’s standard graph tooling.

The native graph is a synchronized editor representation of the same definition asset, not a second serialized runtime format. The older bespoke Slate canvas has been removed; the native Graph tab is now the single graph-authoring path.

The native graph includes:

richer state badges and secondary metadata
bridge-target emphasis
custom native wire styling
native bidirectional transitions now render as parallel lanes instead of collapsing into one path
native endpoints now distribute across each node edge, so overlapping incoming/outgoing connection points remain readable as connection counts grow
native connector routing now pushes wires farther clear of the state cards and mirrors bidirectional pairs with matching curvature
native connector anchors now choose and space the closest sensible state edge based on the relative positions of connected states, rather than always forcing incoming links onto the left side
native pins are visually quieter now, so the graph reads more like state-to-state flow and less like a generic socket graph
native transition wires now use metadata-aware color and weight cues for breakpoints, conditions/rules, and blend timing/curves without adding extra mid-wire decoration
native connector anchors now use the surrounding node edge as a placement range instead of collapsing to side midpoints, then separate nearby endpoints so dense graphs remain readable
native straight-facing links now use straight tangents, and arrowheads rotate to match the incoming connector direction
live rebuild when the definition changes in the details panel
native authoring sync for layout and transition wiring, so node movement and graph rewiring now write back into the definition asset
standard graph comments for node-level notes and production annotations
Backspace/Delete deletion for selected states and comments
auto-layout modes for compact, flow-first, wide, and selected-only graph reshaping
graph-first state authoring:
add state from the graph context menu
drag from a pin into empty space to create and autowire a state
connect to existing states from node context menus
rename and delete authored states
linked-transition pin actions:
remove individual connected transitions
add reverse transitions from an existing link
toggle transition breakpoint metadata
explicit native authoring for special machine semantics:
Make Initial State
Add Any-State Transition
Remove Any-State Transition
Clear Initial State Link

See Native graph implementation history for the completed migration notes.

Debugger features

The debugger includes:

live machine instance list
active machine summary
graph-linked live selection
blackboard watch
pinned watch presentation
transition log
log filter
state timeline strip
runtime stats view
condition breakpoints
transition breakpoints
multi-instance comparison

Tester features

The tester includes:

authored transition simulation without PIE
visited-state coverage view
random-walk fuzz testing
save test sequences to a UWbpAnimTestSequenceAsset data asset
load previously saved sequences from an asset path
per-step bForce and Comment fields

The tester is intentionally a structural simulation tool. It checks whether the authored transition graph would allow a requested state path, but it does not execute Blueprint condition functions, transition rule arrays, or the runtime InterruptPriority gate used by forced transitions. Use PIE or the live debugger when you need runtime-accurate conditioned behavior.

Sub-State Machines

States can host child definitions through:

SubMachineDefinition
SubMachineMode

Supported behaviors:

run child concurrently
pause parent while child runs
wait for child exit

This is the main composition feature for large or reusable flows.

Enhanced Input Integration

Definitions and runtime instances can bind UInputAction events to transitions, and states can directly manage mapping contexts.

Authoring path:

add FWbpAnimInputBinding entries on the definition

Runtime path:

machine resolves the owning player controller
looks for an UEnhancedInputComponent
binds action events during Initialize()
adds EntryInputContext when a state is entered
removes ExitInputContext when a state exits
clears any machine-applied mapping contexts on stop, recycle, and destroy

This is useful for:

button confirm/cancel states
gamepad menu focus flows
controller-driven tab switching
focused widgets that should temporarily expand or narrow available controls

GAS Event Bindings

FWbpAnimGasEventBinding maps a FGameplayTag to a state machine transition. Add entries to UWbpAnimStateMachineDefinition::GasEventBindings or call AddGasEventBinding before Initialize().

USTRUCT(BlueprintType)
struct FWbpAnimGasEventBinding
{
    FGameplayTag EventTag;      // tag to match (parent tags match all children via MatchesTag)
    FName        TargetState;   // state to enter when the tag fires
    bool         bForce = false;       // bypass transition table if priority allows
    int32        CallerPriority = 0;   // must meet current state's InterruptPriority
};

Runtime integration:

The machine does not subscribe to UAbilitySystemComponent automatically. Call HandleGameplayEvent(Tag) from your own GAS subscriber whenever a tag fires:

// C++ — subscribe inside your widget or ability
AbilitySystem->AddGameplayEventTagContainerDelegate(
    FGameplayTagContainer(DamageTag),
    FGameplayEventTagMulticastDelegate::FDelegate::CreateWeakLambda(this,
        [StateMachine](FGameplayTag Tag, const FGameplayEventData*)
        {
            if (StateMachine) StateMachine->HandleGameplayEvent(Tag);
        }));

Blueprint: bind to any GAS event, get your state machine reference, and call Handle Gameplay Event (returns int32 — the number of bindings that fired).

Tag matching: Uses FGameplayTag::MatchesTag — a parent tag binding (e.g. Gameplay.Damage) matches any child that fires (e.g. Gameplay.Damage.Fire). Use exact tags to restrict to specific events.

Multiple matches: All matching bindings are evaluated in declaration order. Each GoToState call is independent, so a later binding runs from the state the earlier binding left the machine in. If two matching bindings target different states, the second may succeed or be blocked depending on the transition table from that new current state.

Force priority: bForce bypasses the transition table, but it does not bypass state interrupt protection. CallerPriority must meet or exceed the current state’s InterruptPriority; otherwise the forced transition is rejected.

Validation: The definition validator checks that every TargetState in a GasEventBinding is a defined state and that every EventTag is valid. Errors appear in RunValidation() and IsDataValid.

No hard dependency: GameplayAbilities is not in the module’s PublicDependencyModuleNames. FGameplayTag comes from GameplayTags, which is already a public dependency.

API reference:

Symbol	Description
`UWbpAnimStateMachine::HandleGameplayEvent(FGameplayTag)`	Process a GAS event tag against all bindings. Returns match count.
`UWbpAnimStateMachine::AddGasEventBinding(Tag, State, bForce, Priority)`	Inline authoring. Must be called before `Initialize()`.
`UWbpAnimStateMachineDefinition::GasEventBindings`	DataAsset array of `FWbpAnimGasEventBinding`.

Focus-Aware Transitions

Definitions can now opt into automatic focus-aware transitions:

bEnableFocusAwareTransitions
FocusGainedState
FocusLostState

When enabled, MachineTick watches the owning widget’s focus state and requests the matching transition when focus changes. This gives you a lightweight built-in focus flow even before you add deeper UI-framework-specific integrations.

Typical use:

Idle -> Focused when the widget gains focus
Focused -> Idle when focus is lost

See examples/WbpAnimStateMachine/EX_FocusAwareButton.json.

CommonUI Integration

UWbpAnimCommonActivatableMixin bridges the CommonUI activation lifecycle to the state machine without creating a hard CommonUI plugin dependency.

How it works

The mixin uses TFieldIterator<FMulticastDelegateProperty> to check at runtime whether a widget exposes OnWidgetActivated and OnWidgetDeactivated delegate properties. If neither is found, a warning is logged and the function returns false. No hard CommonUI plugin dependency is introduced.

Because FMulticastScriptDelegate binding requires a UFUNCTION trampoline that cannot be generated at runtime, the design stores the config in a global table and expects the widget to call the two notify functions from its native overrides.

Usage

Blueprint

In NativeConstruct or Construct, call BindActivationEvents(Self, StateMachine, "Active", "Inactive").
In the widget’s OnWidgetActivated Blueprint event, call NotifyActivated(Self).
In OnWidgetDeactivated, call NotifyDeactivated(Self).

C++ (on a `UCommonActivatableWidget` subclass)

// NativeConstruct
UWbpAnimCommonActivatableMixin::BindActivationEvents(this, MyMachine, TEXT("Active"), TEXT("Inactive"));

// NativeOnActivated
Super::NativeOnActivated();
UWbpAnimCommonActivatableMixin::NotifyActivated(this);

// NativeOnDeactivated
Super::NativeOnDeactivated();
UWbpAnimCommonActivatableMixin::NotifyDeactivated(this);

API

BindActivationEvents(OwnerWidget, StateMachine, ActivatedStateName, DeactivatedStateName, bForce)
Registers the config. Returns false if the widget is not a CommonUI activatable widget.
UnbindActivationEvents(OwnerWidget)
Removes all stored config for the widget. Called automatically on rebind.
NotifyActivated(OwnerWidget)
Drives the machine to the registered ActivatedStateName. No-op if no config exists.
NotifyDeactivated(OwnerWidget)
Drives the machine to the registered DeactivatedStateName. No-op if no config exists.

Notes

The binding is self-cleaning: stale entries for destroyed widgets are removed on each notify call and on UnbindActivationEvents.
If CommonUI is not present in the project, BindActivationEvents will return false and log a warning, but nothing crashes.

View-Model Blackboard Bridge

Definitions can also author lightweight reflected bindings between widget-owned view-model objects and blackboard keys:

WidgetViewModelProperty
ViewModelField
BlackboardKey
Direction

The runtime resolves the view-model object from a property on the widget, reflects the target field, and keeps it synchronized with the blackboard during MachineTick.

Supported reflected field types:

bool
integer types
float / double
FString
FName
object references

This is useful when you want transition rules to react to UI data without writing repeated glue code for each widget.

The source repository includes a worked example at examples/WbpAnimStateMachine/EX_ViewModelBoundPanel.md.

Sequencer Integration

The module includes a dedicated Sequencer track path for triggering widget state transitions from Movie Scene playback.

Main pieces:

UMovieSceneWbpAnimStateTrack
UMovieSceneWbpAnimStateSection
FWbpAnimMovieSceneSectionTemplate
FWbpAnimStateTrackEditor

Sections store:

target state
direct machine property name or machine-group property name
optional group track name
bForce
CallerPriority
optional definition filter

Editor authoring supports:

adding a WBP Anim State track to widget object bindings
adding sections from the outliner
readable labels and tooltips
track context actions for sweep behavior

Test Sequence Asset

UWbpAnimTestSequenceAsset is a UDataAsset subclass that persists a named sequence of tester steps as a Content Browser asset.

This makes test scripts reusable, diffable, and sharable across the team.

Data types

FWbpAnimTestSequenceStep

TargetState - state to attempt
bForce - use GoToState with bForce=true
Comment - optional note shown in tester results

UWbpAnimTestSequenceAsset

InitialState - state the machine should be in before the sequence begins
Steps - ordered array of FWbpAnimTestSequenceStep
Description - multiline documentation or test-case name

Creating an asset

In the Content Browser: Right-click -> Miscellaneous -> Data Asset -> WbpAnimTestSequenceAsset.

Using from the tester panel

Build or load a sequence in the tester panel.
Enter the asset content path in the State Machine Test Asset box (e.g. /Game/Tests/DA_ButtonSequence), or pick an existing UWbpAnimTestSequenceAsset with the asset picker.
Press Save to write the sequence to disk.
Press Load to restore a saved sequence into the tester.

Using from Blueprint or C++

UWbpAnimTestSequenceAsset is a BlueprintType data asset. You can load it with LoadObject, iterate Steps, and call GoToState manually for scripted test automation flows.

Validation

Validation checks include:

empty states
duplicate state names
invalid initial state
invalid animation references
invalid function references
invalid auto-transition targets
invalid transition endpoints
duplicate transitions
missing rule keys where required
invalid input bindings
unreachable states

The native definition editor and details customization surface live validation output while authoring. The old separate editor-module details hint/preview has been removed, so the Graph, Details, Debugger, Test, and Diff tabs are the canonical authoring surfaces.

That validation surface is now less of a raw warning list and more of a compact health summary:

a top summary chip shows healthy / warning / error state directly in the details panel
the summary also calls out state count, transition count, bound clip count, missing clip references, and shared clip reuse counts
a compact recommended next step now sits directly under that summary so authoring can move from what is wrong to what should I do next
a context-aware summary action now appears when useful, so the details panel can jump straight into the owner Widget Blueprint for clip-risk review or back into the dedicated graph editor for graph-side repair work
definition-wide validation now also warns when a state references a clip that does not exist on the owner widget blueprint, and when the same clip is reused across multiple states
the detailed warning/error rows remain below it for drilldown

Automated Tests

The module ships a suite of IMPLEMENT_SIMPLE_AUTOMATION_TEST tests compiled under WITH_DEV_AUTOMATION_TESTS.

Run them in the Unreal Editor via the Session Frontend Automation tab or with Unreal Automation Tool.

Runtime tests (all build configurations)

Test name	Path	What it covers
`FWbpAnimStateMachineBasicTransitionTest`	`UIFoundry.WbpAnimStateMachine.Runtime.BasicTransition`	Machine creation, `Initialize`, `CanTransitionTo`, `GoToState`, `GetCurrentState`, `GetPreviousState`
`FWbpAnimStateMachineBlackboardTest`	`UIFoundry.WbpAnimStateMachine.Runtime.Blackboard`	Float, bool, name, int, string read/write round-trips; missing key defaults; `ClearBlackboard`
`FWbpAnimStateMachineSnapshotTest`	`UIFoundry.WbpAnimStateMachine.Runtime.Snapshot`	`SaveSnapshot`, `RestoreSnapshot` - state, float, bool, and name restored correctly
`FWbpAnimStateMachineTransitionGuardTest`	`UIFoundry.WbpAnimStateMachine.Runtime.TransitionGuard`	Lambda guard blocks `GoToState`; `ClearTransitionGuard` re-enables it
`FWbpAnimStateMachineGoBackTest`	`UIFoundry.WbpAnimStateMachine.Runtime.GoBack`	History push/pop via `GoBack`; returns false when history is empty
`FWbpAnimStateMachineGameplayEventBindingTest`	`UIFoundry.WbpAnimStateMachine.Runtime.GameplayEventBindings`	`HandleGameplayEvent` exact and parent/child tag matches, uninitialized/no-match returns, and invalid target skip behavior

Editor-only tests (`WITH_EDITOR`)

Test name	Path	What it covers
`FWbpAnimStateMachineEmptyDefinitionValidationTest`	`UIFoundry.WbpAnimStateMachine.Editor.EmptyDefinitionValidation`	`IsDataValid` returns `Invalid` and reports the `States array is empty` error
`FWbpAnimStateMachineDuplicateStateValidationTest`	`UIFoundry.WbpAnimStateMachine.Editor.DuplicateStateValidation`	`IsDataValid` returns `Invalid` and reports a `Duplicate StateName` error

Build and Dependencies

The module build file is Source/WbpAnimStateMachine/WbpAnimStateMachine.Build.cs.

Notable runtime dependencies:

Core
CoreUObject
Engine
UMG
MovieScene
MovieSceneTracks
EnhancedInput
GameplayTags

Soft / optional runtime dependencies:

CommonUI - required only if you use UWbpAnimCommonActivatableMixin with real CommonUI activatable widgets. The mixin compiles and runs without it but returns false and logs a warning for non-CommonUI widgets.

Notable editor dependencies:

AssetTools
PropertyEditor
Sequencer
Slate
SlateCore
InputCore
UnrealEd

Typical Authoring Workflow

Create a UWbpAnimStateMachineDefinition
Set OwnerWidgetClass
Apply a preset or author states manually
Arrange states in the graph
Add transitions, rules, and notes
Add breakpoints or test paths in the editor
Create the runtime machine in the widget
Drive transitions from Blueprint, C++, input, or Sequencer
Use the debugger during PIE if something behaves incorrectly

Design Philosophy

The module is meant to be:

easier to reason about than ad hoc Blueprint animation webs
faster to author than bespoke widget logic for every transition
easier to debug than silent failures
useful for both small indie widgets and large multi-state production UI