gum-tool-animations
Skill659 starsChanged 2 months agoMITView on GitHub
How the Gum tool authors state-based animations — StateAnimationPlugin, Animations tab, .ganx sidecars. Triggers: Animations tab, StateAnimationPlugin, ElementAnimationsSave, AnimationSave, AnimatedStateSave, .ganx, named events.
In this repository69 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-docs-writingSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-itemscontrolSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monogame-renderingSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-undoSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-variable-deep-diveSkill
- The first 60 shown.
The file
Files
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
- Split like the editor tab (phase 80 of the Avalonia migration): the neutral
Tool/StateAnimationPlugin.Core(net10.0) holdsStateAnimationPluginBase(all event wiring, menu, tab, undo, delete option), the load/save and settings managers, the shared list hotkeys (AnimationTabKeyHandler), and the timeline math (Timeline/TimelineLayout,InterpolationCurve). Each head derives the exported plugin: WPFMainStateAnimationPlugin(Gum/StateAnimationPlugin/, viewsViews/MainWindow.xaml,Timeline.xaml,StateView.xaml) and AvaloniaAvaloniaStateAnimationPlugin(Tool/Gum.Avalonia/Plugins/StateAnimation/, whoseTimelineViewdraws natively inRender). A behavior change to the tab belongs in the core, not in either view. Tab is hidden until View ▸ View Animations. - VMs (in Gum.Presentation):
ElementAnimationsViewModel→AnimationViewModel→AnimatedKeyframeViewModel; the business logic isAnimationTabController.
Data model & serialization
- Persisted as a per-element
.ganxsidecar:<ElementName>Animations.ganxnext 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/*, namespaceGum.StateAnimation.SaveClasses.ElementAnimationsSave→List<AnimationSave>; eachAnimationSaveholds 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.
AnimatedKeyframeViewModelis 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) areFlatRedBall.Glue.StateInterpolationtypes from the standaloneFlatRedBall.InterpolationCorepackage — 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 inAssignEvents. - One user action, one undo step. Hold
IUndoManager.RequestLock()(ctor-injected intoElementAnimationsViewModel) around any action that changes the keyframe/animation lists more than once; the plugin's per-change undo flush then records once when the lock is released. Declare the lock beforeCoalesceSaves()(the private scope that makes a gesture reportAnyChange, and so save the .ganx, once) so it is released after the final save.AddKeyframeinserts in time order so a list is never reported mid-sort. - Save is whitelist-filtered.
HandleDataChangeonly re-saves on specific property changes; a new persisted keyframe field won't save unless added there.
Dogfooding the Avalonia tab headlessly
Full guide: Tests/Gum.Avalonia.Tests/Animations/README.md.
Tests/Gum.Avalonia.Tests/Animations/AnimationEditorHarness.cs hosts the real Animations tab (a
plugin instance of its own on the head's real service graph, over a temp project) in a headless
window and drives it with pointer and key input, so nothing reaches the desktop. Dialogs are
answered by ScriptedDialogService (AnswerNext<T>, AnswerNextMessage, AnswerNextUserString);
an unanswered dialog throws instead of hanging. Read results from ViewModel, the controls
(AnimationList, KeyframeList, Timeline, Detail, DetailCombos, Scrubber) and the saved
sidecar (ReadSavedAnimations). KeyframeMarkerCenter gives a marker's point on the timeline for a
click or hover; SaveFrame writes a PNG of the window (folder from GUM_HEADLESS_FRAMES, else
%TEMP%\GumAnimationEditor\frames) to look at, and AnyPixelNear reads the rendered pixels
(match thin antialiased lines by hue, not exact color). Scenarios live beside it, one file per
area (editor, list, reload, timeline, instance sub-animations, element lifecycle, playback,
keyframe editing, errors, tab lifecycle, JSON projects, detail column, external changes); add a
new gesture there first, then fix what it finds. ThrowIfPluginFailed surfaces a crash the
plugin manager would otherwise swallow by disabling the plugin. The plugin must be in
PluginManager.PluginContainers as well as Plugins, or no tool event reaches it; the harness
stands in for the head's own plugin instance while it runs, so events are not handled twice.
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

