gum-runtime-animation-chains
Skill659 starsChanged 2 months agoMITView on GitHub
AnimationChain playback on Sprites and NineSlices — .achx -> AnimationChain pipeline, AnimationChainLogic tick loop, apply-frame vs render-time split, RelativeX/Y mismatch with FRB AnimationEditor. Triggers: .achx, AnimationChain, AnimationFrame, AnimationChainList, AnimationChainLogic, SpriteAnimationLogic, ApplyAnimationFrame, RelativeX/Y offsets, CurrentChainName.
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-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-animationsSkill
- 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
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 57
All backends' NineSlice compose AnimationChainLogic and apply the frame offset (GetRenderOffset) and keyframe color (ApplyKeyframeColor) …
- Very specific: line 84
Only the MonoGame-family, Skia and raylib Sprites and NineSlices wire ApplyKeyframeColor.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Runtime Animation Chains
Gum plays back FRB-style .achx/.achj animations on Sprite and NineSlice. .achx (XML) and .achj (JSON, matching FlatRedBall2's AnimationChain.Common writer) both deserialize into AnimationChainListSave — see AnimationChainListSave.FromFile. Each chain is a list of frames with a texture, source rect, frame length, optional flip flags, optional RelativeX/RelativeY per-frame offsets, and optional per-frame color (see below).
Pipeline: Save → Runtime
AnimationChainListSave (XML) → ToAnimationChainList() → AnimationChainList (a List<AnimationChain>). Each AnimationChainSave.Frames[i] becomes an AnimationFrame via AnimationFrameSave.ToAnimationFrame(loadTexture, coordinateType).
TextureCoordinateType matters at load time, not render time. The AnimationFrame.LeftCoordinate/RightCoordinate/TopCoordinate/BottomCoordinate fields are always stored as UV (0–1). If the source .achx declares <CoordinateType>Pixel</CoordinateType>, the loader divides by Texture.Width/Height during conversion. UV-mode .achx files copy the values verbatim. A frame loaded before its texture resolves cannot perform pixel-to-UV conversion — its coords stay zero.
Playback: AnimationChainLogic
Both Sprite and NineSlice compose an AnimationChainLogic instance (XNA, Sokol, Raylib, Skia all share the same playback type). SpriteAnimationLogic is a back-compat [Obsolete] subclass; new code should use AnimationChainLogic.
State lives entirely on AnimationChainLogic:
_currentChainIndexdefaults to 0 so assigningAnimationChains+Animate = trueworks without settingCurrentChainName.CurrentChainNameset to the chain already playing keeps playback (the first naming of the implicit chain only seeds looping and applies its frame); a different name restarts (time 0, frame derived from time 0, so a Reverse chain shows its last frame at once), sets_currentChainIndex = -1and resolves the desired name lazily once chains are populated (RefreshCurrentChainToDesiredName), then seeds_isLoopingfrom the newly-resolved chain'sAnimationChain.Loop(itself threaded fromAnimationChainSave.Loop, defaulttrue) — still freely overridable per-instance afterward viaIsAnimationChainLooping. The implicit index-0-without-CurrentChainNamepath does not reseed;_isLoopingstays at its owntruedefault there.AnimateSelf(secondDifference)advances_timeIntoAnimation, loops or clamps based onIsAnimationChainLooping, picks a new frame viaUpdateFrameBasedOffOfTimeIntoAnimation, and callsUpdateToCurrentAnimationFrame()only if the frame index changed.- Events:
AnimationChainCycledfires only when a looping chain wraps (either direction).AnimationChainFinishedfires once when a non-looping chain hits its end (forward: last frame; negative speed: first frame), afterAnimateturns false and the final frame is applied. Both are forwarded bySprite,NineSliceandSpriteRuntime, and nulled inClone; a new forwarder or event must do both. The frame lookup wraps at exactlyTotalLength, so the forward end sets the last index directly instead of calling it. UpdateToCurrentAnimationFrame()invokes theApplyFramedelegate the host wired up. It does not directly mutate the renderable.- With a chain set, an out-of-range frame index or negative time is clamped to the chain (
SeekToFrame), on set and again inUpdateToCurrentAnimationFrameafter a chain switch; with no chain they are stored raw.
AnimateSelf is driven once per frame by GraphicalUiElement.AnimateSelf (recursively). Event handlers may add or remove elements mid-walk, so a list of elements is animated through GraphicalUiElement.AnimateEach (children and GumService.AnimateRoots), which resumes after the element it just animated wherever it now is; Sokol's Renderer.TickEach walks renderables and keeps its own copy. Never foreach or snapshot the list (throws or allocates per frame).
Idle subtrees are skipped. An element whose whole subtree had nothing to animate sets _isIdle and AnimateSelf returns at once until InvalidateSubtreeCaches (GraphicalUiElement.SubtreeCaches.cs) clears it. Anything new that can give an element per-frame work must call it: a new playback flag on a renderable (implement IAnimationChainRenderable and raise the callback when it turns on, as AnimationChainLogic.Animate does), a new IUpdateEveryFrame-style hook, or a new way to add or show children. An IAnimatable that does not implement IAnimationChainRenderable is ticked every frame and keeps its ancestors from going idle.
Chains follow the SourceFile that produced them. GraphicalUiElement.SetProperty("SourceFile") remembers the list a chain file produced. When SourceFile later becomes empty or a non-chain file (including a variable removed by a hot reload), it drops that list, if the renderable still holds it, and puts TextureAddress/Texture*/FlipHorizontal back to what the default state and the category states applied on the containing element give. The renderable keeps the chain name asked for, so a later chain file plays it. Chains assigned by code are never dropped.
Frame application is split across two times
Sprite handles each frame in two phases:
- On frame change (
Sprite.ApplyAnimationFrame, wired intoAnimationLogic.ApplyFrame): copiesTexture, computes pixelSourceRectanglefrom UV coords × texture size, and copiesFlipHorizontal/FlipVertical. Persistent state. - At every render (
Sprite.Render, whenCurrentFrameIndex < CurrentChain.Count): readsAnimationLogic.GetRenderOffset(absoluteRotation)(the frame's liveRelativeX/RelativeY, or the keyframe-evaluated offset, rotated with the sprite and Y-negated for the Y-down screen), mutatesthis.X/Y, calls the static draw, then restores the originals.
This split matters: changing RelativeX/Y on a live frame takes effect on the next render without needing UpdateToCurrentAnimationFrame. The offset is applied at the render call site, not in ApplyFrame.
FlipDiagonal is a transpose applied after the H/V flips (flip the source, then reflect across the main diagonal), keeping the sprite's own footprint. MonoGame synthesizes it as a 90 degree rotation about the sprite's center plus a horizontal flip with the scale axes swapped (Sprite.GetDiagonalFlipComposite), so any source rectangle shape is transposed and stretched to the footprint; FlipVertical passes through unchanged. Skia concatenates a swap-axes matrix onto the canvas in DrawBound; raylib draws a swapped-size, 90-degree-turned rectangle with a mirrored source (Sprite.GetDiagonalFlipDraw). Both handle non-square sprites, and raylib skips it on its tiled (Wrap) and out-of-texture-bounds clamped paths.
Skia and raylib Sprite apply the same GetRenderOffset at draw time: raylib shifts the destination rectangle, and Skia translates the canvas in DrawBound, which is already rotated with the sprite, so it passes 0 rotation.
The RelativeX/Y anchor mismatch (recurring gotcha)
Sprite.Render applies the per-frame offset as a literal pixel shift around a top-left anchor (origin = Vector2.Zero in the static Render). The Y component is negated on apply (this.Y -= offsetVector.Y) because AnimationFrame.RelativeY follows FRB's Y-up convention while Gum is Y-down.
The values inside an .achx are authored against FRB's center-anchored Sprite. When the Sprite's destination height is constant (e.g. HeightUnits = Absolute), the offset is just a translation and the anchor difference doesn't matter. When destination height tracks the source rect (e.g. HeightUnits = PercentageOfSourceFile), the FRB-authored values only compensate half the per-frame height change — because the other half was absorbed by FRB's centered anchor. The Gum-rendered sprite drifts in the direction the source rect is shrinking (typically "climbs upward" for collapse animations).
To match FRB visuals on a height-tracking Sprite, the offset has to be applied around the sprite's center, not its top-left — or an extra (referenceHeight - currentHeight) / 2 must be added to Y.
NineSlice: same playback as Sprite
All backends' NineSlice compose AnimationChainLogic and apply the frame offset (GetRenderOffset) and keyframe color (ApplyKeyframeColor) like Sprite. XNA shifts the absolute origin in Render, raylib shifts the destination, Skia translates the canvas in DrawBound.
All backends flip the whole drawn nine-slice, flipping first and then transposing (a non-square one stretches the transposed image to its footprint): canvas mirror/transpose on Skia; per-section destination mirror plus Sprite.GetDiagonalFlipDraw on raylib, where any flip forces the per-section path instead of DrawTextureNPatch. XNA places each of the nine child sprites (and each tile) through NineSlice.SliceLayout.Place, which mirrors its rectangle, then draws a transposed piece as a quarter turn about its bottom-left corner plus a horizontal mirror, so it works for non-square pieces unlike the square-only Sprite composite. XNA ApplyAnimationFrame distributes the frame texture to the 9 internal sprites via SetSingleTexture.
Per-frame color (Alpha/Multiply/Add)
AnimationFrameSave/AnimationFrame carry nullable Red/Green/Blue/Alpha (0-255) and an AnimationFrameColorOperation? (Multiply/Add), matching FRB2's Animation Editor fields. Each backend's ApplyAnimationFrame sets the renderable's own Alpha when authored, and its own Red/Green/Blue whenever a ColorOperation is authored — snapshotted once per frame change, not re-combined at render time, so a frame that authors neither leaves the renderable's current color alone.
There is one set of colors. Color is the only tint source on a renderable; the renderable's RenderingLibrary.Graphics.ColorOperation decides how it is read (#4880) — the same shape as Alpha and Blend. A frame's AnimationFrameColorOperation selects that operation:
| Frame op | Sets ColorOperation | Unset-channel default |
Multiply | Modulate | 255 (multiply identity) |
Add | Add | 0 (add identity) |
| none | resets Add → Modulate | color untouched |
Add draws the texture untinted and adds Color on top: a second additive pass on XNA (Renderer.DrawAdditiveColorOverlay), and a single pass on raylib (ColorOperationShader.CreateAdd) and Skia (SKColorFilter.CreateColorMatrix offset), both faded by the tint alpha. It works on both Sprite and NineSlice across XNA/raylib/Skia. There is no separate additive color field — an earlier AdditiveTintColor was folded into Color + ColorOperation.Add.
A separate nullable field, AnimationFrame.RenderColorOperation/AnimationFrameSave.RenderColorOperation, also picks the renderable's ColorOperation (its original purpose was the Modulate/ColorTextureAlpha technique selector). It writes the same field as the table above, so when a frame authors both, the AnimationFrameColorOperation wins — it is applied second. Applied in Sprite.ApplyAnimationFrame only, on every backend's Sprite.
Note for tool work: exposing ColorOperation as a tool-editable variable means codegen emits X.ColorOperation = ..., which older runtimes' NineSliceRuntime does not have. That needs a syntax-version bump and gate — see gum-runtime-syntax-version.
Keyframe interpolation (offset and color glides)
Every frame is a keyframe; a keyframe's curve runs to the next keyframe of the same group (Offset: RelativeX/Y, Color: Red/Green/Blue/Alpha). The six per-frame fields (SkipOffsetKeyframe, OffsetInterpolation, ...) are stored as raw strings so unknown names round-trip. The math is KeyframeEvaluator/KeyframeCurve (ported from FlatRedBall2's AnimationChain.Common, using the FlatRedBall.InterpolationCore tweener GumCommon already references).
- A chain without keyframe data (
KeyframeEvaluator.HasOffsetKeyframes/HasColorKeyframes) takes the old path, byte for byte. Only a chain with color keyframes setsAnimationChainLogic.IsColorDrivenByKeyframes; eachApplyAnimationFramemust then skip its own color step, becauseApplyKeyframeColor(called right afterApplyFrameand on everyAnimateSelftick) already applied the inherited color, and a skipped frame's own channels must not leak. - Only the MonoGame-family, Skia and raylib Sprites and NineSlices wire
ApplyKeyframeColor. Sokol's Sprite applies no color or offset and ignoresRelativeX/Yentirely; the MonoGame-family, Skia and raylib Sprites and NineSlices apply offset and color glides. - In keyframe mode, channels inherit from the last keyframe that set them and the operation inherits through skipped frames. Red/Green/Blue still reach the sprite only under a Multiply or Add operation, matching FlatRedBall2 (
SpriteFrameColor.Apply); Alpha applies on its own.
Key Files
| File | Purpose |
RenderingLibrary/Graphics/Animation/AnimationChainLogic.cs | Platform-agnostic playback state and tick |
RenderingLibrary/Graphics/Animation/SpriteAnimationLogic.cs | [Obsolete] back-compat subclass of AnimationChainLogic |
RenderingLibrary/Graphics/Animation/KeyframeEvaluator.cs, KeyframeCurve.cs | Pure glide math and curve-name parsing (new files must be added to GumCoreShared.projitems and each runtime csproj that links AnimationChainLogic.cs) |
RenderingLibrary/Graphics/Animation/AnimationFrame.cs | Runtime frame; ToAnimationFrame extension converts from save with TextureCoordinateType |
RenderingLibrary/Graphics/Animation/AnimationChain.cs | List<AnimationFrame>; ToAnimationChain extension |
RenderingLibrary/Graphics/Animation/AnimationChainList.cs | List<AnimationChain>; .achx deserialization entry point |
RenderingLibrary/Graphics/Sprite.cs | ApplyAnimationFrame (frame-change side) and Render (per-render RelativeX/Y application) |
RenderingLibrary/Graphics/NineSlice.cs | ApplyAnimationFrame distributes frame texture across 9 slices; applies the frame offset in Render |
Gum/Graphics/Animation/Content/AnimationFrameSave.cs | XML/JSON-serializable frame; pixel or UV coords per AnimationChainListSave.CoordinateType; per-frame color fields |
Gum/Graphics/Animation/Content/AnimationChainListSave.cs | .achx (XmlSerializer) and .achj (ParseJson/ParseFrameJson) parsing, dialect picked by extension in FromFile |
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.

