For the complete documentation index, see llms.txt. This page is also available as Markdown.
Source File
Introduction
The Source File property determines the file that is used by the Sprite. Sprite Source Files support the following formats:
.png files
.achx files (AnimationChains)
Images from URLs
Sprite displaying the FlatRedBall logo
If a Sprite has an empty Source File or if it references a missing file, then the missing file texture is displayed.
Sprite with a missing or emtpy Source File
Setting a PNG Source File
Source File can be set by typing a value or using the ... button to browser for a file.
All files are added as paths relative to the .gumx project.
Sprite referencing UISpriteSheet.png located in the same folder as the .gumx file
If a file is referenced outside of the .gumx folder, then Gum asks if you would like to copy the file or reference it outside of the current directory. Usually files should be copied to the project folder to keep the entire Gum project portable.
Gum asking whether a file should be copied or referenced in its current location.
ACHX Files
Gum natively supports referencing Animation Chain XML files (.achx) which are created by the FlatRedBall AnimationEditor. For more information on creating .achx files, see the FlatRedBall AnimationEditor page.
Once you have created an .achx file, you can reference it the same as a .png by entering its name or selecting it with the ... button.
Animated sprite referencing an .achx file
When referencing an .achx file, be sure to also check the Animate checkbox and to select the Current Chain Name.
.achx files are XML files which reference one or more other PNG files. If you are moving an .achx file be sure to also move the referenced PNG files.
Per-Frame Offsets and Sprite Origin
Frames in an .achx can carry per-frame RelativeX / RelativeY offsets, typically authored in the FlatRedBall AnimationEditor to keep visual content (e.g. the bottom of a collapsing object) anchored as the source rectangle changes size from frame to frame.
The AnimationEditor authors these offsets against a center-anchored Sprite. When a Sprite in Gum plays back an .achx with non-zero offsets, set both XOrigin and YOrigin to Center so the offsets compensate as intended.
If the Sprite's origin is left at the default (top-left) and its Width/Height units track the source file (such as PercentageOfSourceFile), frames that change size will drift — typically the visual will appear to climb or slide as the animation progresses, even though the offsets look correct in the AnimationEditor. The Gum tool will surface a warning in the Errors tab when it detects this combination.
Referencing URLs
Gum Sprites can also reference URLs. Gum can display images from URLs with standard file extensions such as .png and .jpg
Gum Sprite referencing an image of Super Mario World from gameuidatabase.com
Sprites can also reference images without extensions, such as urls from https://picsum.photos/
