| name | gum-tool-animations |
| description | How the Gum tool authors state-based animations — StateAnimationPlugin, Animations tab, .ganx sidecars. Triggers: Animations tab, StateAnimationPlugin, ElementAnimationsSave, AnimationSave, AnimatedStateSave, .ganx, named events. |
Gum Tool Animations
State-based animation authoring in the editor: timeline animations that interpolate
between named States over time. NOT the same as runtime AnimationChains (see Landmines).
Where it lives
- Whole feature is a MEF plugin under
Gum/StateAnimationPlugin/; entry
MainStateAnimationPlugin.cs. Tab is hidden until View ▸ View Animations.
- View
Views/MainWindow.xaml(.cs); VMs ElementAnimationsViewModel →
AnimationViewModel → AnimatedKeyframeViewModel.
Data model & serialization
- Persisted as a per-element
.ganx sidecar: <ElementName>Animations.ganx next to
the element's .gucx/.gusx (path: Managers/AnimationFilePathService.cs). NOT embedded
in the element file or .gumx. Load/save: Managers/AnimationCollectionViewModelManager.cs.
- Save classes live in
GumDataTypes/SaveClasses/*, namespace Gum.StateAnimation.SaveClasses.
ElementAnimationsSave → List<AnimationSave>; each AnimationSave holds three parallel
keyframe lists: state keyframes, sub-animation refs, named events.
- A state keyframe binds to a state by name string,
"Category/State" convention
(uncategorized = no slash). Resolution: AnimationViewModel.GetStateFromCategorizedName.
- Keyframes are cumulative — each combines with prior ones; preview rebuilds via
RefreshCumulativeStates.
Named events — FRB-only
"Add Named Event" authors a NamedEventSave (name + time). It round-trips to .ganx, but
Gum's own runtime never dispatches it — only FlatRedBall consumes named events. Skip in
non-FRB docs.
Runtime relationship (do NOT conflate)
- State animations (this skill) —
.ganx, interpolate between states. Runtime driver:
GumCommon/Runtime/AnimationController.cs + AnimationRuntime.cs (undocumented elsewhere).
- AnimationChains —
.achx, sprite-sheet flipbook on Sprite/NineSlice; see
[[gum-runtime-animation-chains]]. Different concept, different file, different runtime.
Landmines
- "Keyframe" is a union of 3 things.
AnimatedKeyframeViewModel is a state keyframe OR
sub-animation ref OR named event, discriminated by which string is non-empty (StateName →
state, else AnimationName → sub-anim, else event). No type enum; fans out into 3 lists on save.
- Misleading names on
AnimationSave. States = state keyframes (not element states);
Animations = sub-animation keyframes (not child animations).
- Interpolation types come from a NuGet package, not Gum.
InterpolationType/Easing
(state keyframes only) are FlatRedBall.Glue.StateInterpolation types from the standalone
FlatRedBall.InterpolationCore package — an easing/tweening library under the FlatRedBall
brand, NOT the FRB engine. The animation data model serializes these into .ganx.
- Sidecar must follow the element. Element rename/duplicate/delete must move the
.ganx;
wired via RenameManager/DuplicateService/ElementDeleteService in AssignEvents.
- Save is whitelist-filtered.
HandleDataChange only re-saves on specific property
changes; a new persisted keyframe field won't save unless added there.
Docs
User-facing content today is a 4-part tutorial under
docs/gum-tool/tutorials-and-examples/animation-tutorials/. Issue #480 wants a reference
section on the Animations tab itself (data model, named events, the tab UI), not tutorial-style.
