> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/gum-elements/sprite/source-file.md). # 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

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 .gumj project.

Sprite referencing UISpriteSheet.png located in the same folder as the .gumj file

If a file is referenced outside of the .gumj 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 you create with the [AnimationEditor](https://github.com/vchelaru/FlatRedBall2/releases/tag/animationeditor-latest). Download the latest AnimationEditor from that 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**. {% hint style="info" %} .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. {% endhint %} #### Per-Frame Offsets and Sprite Origin Frames in an .achx can carry per-frame `RelativeX` / `RelativeY` offsets, typically authored in the 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. {% hint style="warning" %} 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. {% endhint %} ### 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

400x320 image referenced from Lorem Picsum

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flatredball.com/gum/gum-tool/gum-elements/sprite/source-file.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.