achx-format

name	achx-format
description	The .achx animation file format and its save/runtime split. Triggers: .achx, AnimationChainListSave, AnimationChainSave, AnimationFrameSave, ToAnimationChainList, FromXElement.

.achx Animation File Format

.achx is the XML serialization of an AnimationChainListSave. It describes texture-flip animations: a list of chains, each a list of frames, each frame naming a texture + UV/pixel coordinates + timing (and, more recently, optional per-frame color). See the AnimationChainList file docs and the runtime API.

The save ↔ runtime split (the core thing to internalize)

There are two parallel class trees — a serialized "Save" tree and a runtime tree — and you convert between them. Don't confuse the two.

Save (.achx, Content/AnimationChain/)	Runtime (Graphics/Animation/)
AnimationChainListSave ([XmlType("AnimationChainArraySave")])	AnimationChainList
AnimationChainSave ([XmlRoot("AnimationChain")])	AnimationChain
AnimationFrameSave	AnimationFrame

• Load: AnimationChainListSave.FromFile(fileName) → ToAnimationChainList(...) → per chain ToAnimationChain(...) → per frame AnimationFrameSave.ToAnimationFrame(...).
• Save: the AnimationFrameSave(AnimationFrame template) ctor copies runtime → save.
• Apply to a Sprite: runtime frames are pushed onto a Sprite in Sprite.UpdateToAnimationFrame (called from UpdateToCurrentAnimationFrame / AnimateSelf). That method is the single hook where per-frame texture/coords/flip/color land on the Sprite.

Landmines

• Two deserialization paths, kept in sync by hand. Desktop uses reflection-based FileManager.XmlDeserialize<AnimationChainListSave>. Android/iOS use a hand-written manual path (AnimationChainListSave.DeserializeManually / LoadFromElement, and AnimationFrameSave.FromXElement — a switch on element local-name). Any new serialized element must be added to BOTH, or it loads on desktop and silently vanishes on mobile.
• ShouldSerializeXxx() controls XML output. Save-class fields use ShouldSerializeXxx() methods so defaults/nulls are omitted from the .achx. New optional fields follow this pattern to stay backward-compatible (old files just lack the element).
• Coordinate + time units differ from runtime. AnimationChainListSave.CoordinateType is UV or Pixel — ToAnimationFrame converts Pixel→UV by dividing by texture width/height. TimeMeasurementUnit (seconds vs. milliseconds) makes ToAnimationChain divide FrameLength by 1000. The runtime is always UV + seconds.

Per-frame color (signpost)

Frames carry optional nullable tint: Red/Green/Blue/Alpha and a color operation. The .achx/Save side stores 0–255 ints and an editor-flavored op enum; the runtime side stores 0–1 floats and FlatRedBall.Graphics.ColorOperation, with mapping done in AnimationFrameSave.ToAnimationFrame. Applied to the Sprite in Sprite.UpdateToAnimationFrame (ApplyAnimationFrameColor). Read the source there for the exact channels, identity-on-null rules, and op mapping.

Key files

File (Engines/FlatRedBallXNA/FlatRedBall/)	Purpose
Content/AnimationChain/AnimationChainListSave.cs	.achx root; FromFile, ToAnimationChainList, manual load
Content/AnimationChain/AnimationChainSave.cs	one chain; ToAnimationChain, FromXElement
Content/AnimationChain/AnimationFrameSave.cs	one frame; ToAnimationFrame, FromXElement, color map
Graphics/Animation/AnimationFrame.cs	runtime frame
Sprite.cs	UpdateToAnimationFrame — where a frame is applied to a Sprite