FNF & SparrowMetadata export

Load a Sprite Sheet into FNF and Psych Engine

How the Sparrow XML export lands in a Friday Night Funkin mod: where the files go, how animation prefixes are matched, and what to check when a pose will not play. Starling and HaxeFlixel read the same file.

Need the sheet first? Use the FNF sprite sheet maker

A sprite sheet exported as a Sparrow TextureAtlas XML, next to the settings it needs in FNF and Sparrow
What you export

Format menu

Sparrow / Starling XML

Sparrow TextureAtlas (.xml)

Sparrow has no animation list. Frames belong to an animation because their names start with the same prefix and end in a four digit index, so idle0000, idle0001 and up are all idle. The Format dialog has an Animation name field, filled in from the active layer name, and the XML names every frame with it. Only letters, digits, underscores, and hyphens are kept, so a base-game style name with spaces comes out without them. When Trim Transparent is on, each frame also gets frameX, frameY, frameWidth, and frameHeight.

Step by step

Getting the sheet into FNF & Sparrow

  1. 1

    One animation per sheet

    Keep frames in playback order. One sheet per animation maps cleanly onto one name.

  2. 2

    Name the layer

    Rename the active layer to the animation name, for example singLEFT. The Format dialog picks it up.

  3. 3

    Export the XML

    Click Format, check the Animation name field, then choose Sparrow / Starling XML. The ZIP holds spritesheet.png and spritesheet.xml with frames named singLEFT0000 and up.

  4. 4

    Drop into the mod

    Rename both files to the character name, put them side by side in the character images folder, and update imagePath in the XML if you renamed the PNG.

  5. 5

    Set the offsets

    If a pose sits too high or too far left, fix it with the animation offsets in the character file rather than editing the sheet.

Sparrow XML
<?xml version="1.0" encoding="UTF-8"?>
<TextureAtlas imagePath="hero.png">
  <SubTexture name="idle0000" x="0" y="0" width="32" height="32"/>
  <SubTexture name="idle0001" x="32" y="0" width="32" height="32"/>
  <SubTexture name="idle0002" x="64" y="0" width="32" height="32"/>
</TextureAtlas>
Cheat sheet
SettingFNF & Sparrow value
Frame namingname + four digit index (idle0000)
FormatSparrow TextureAtlas (.xml)
Animation lookupBy frame name prefix, case sensitive
Allowed charactersLetters, digits, _ and -
Also read byStarling, HaxeFlixel
Built for the workflow

You name the animation

Type the name at export time, or let it come from the layer name, and frames come out as idle0000 or singLEFT0000 without a rename pass.

Read existing sheets

The Splitter reads Sparrow XML, so you can pull an existing character sheet apart, edit it, and export a fresh XML.

Recolour variants

Hue and saturation controls make an alt-colour version of a character without repainting every frame.

Troubleshooting

When the sheet fights FNF & Sparrow

The mod reports that an animation was not found

Cause
The prefix in the XML does not match the name the character file asks for, usually a casing difference or spaces the export removed.
Fix
Open the XML and compare the SubTexture names with the character file. Change whichever side is easier; both are plain text.

One animation plays frames from another

Cause
Flixel matches by prefix, so a name that is the start of another name, such as singLEFT and singLEFTmiss, collects both sets of frames.
Fix
Give each animation a name that is not the start of another one, for example singLEFT_hit and singLEFT_miss.

Frames play in the wrong order

Cause
Readers sort frames by the number at the end of the name, so a gap or an uneven index width breaks the sequence.
Fix
Let the export write the indexes. If you hand-edit the XML, keep four digits on every entry and keep the numbering contiguous from 0000.

The atlas loads but no image appears

Cause
imagePath at the top of the XML still names spritesheet.png after you renamed the image.
Fix
Edit the imagePath attribute to the new file name. It is one line at the top of the file.

The character is tiny next to the others

Cause
Base game characters are drawn at a much higher resolution than most pixel-art sheets.
Fix
Scale the character in the character file rather than upscaling the sheet, and turn antialiasing off for pixel art so the scaled pixels stay sharp.

Only the first animation works after merging several XMLs

Cause
The merged file has more than one TextureAtlas root element, or two animations share a prefix.
Fix
Keep a single TextureAtlas root with every SubTexture inside it, and give each animation a distinct name.
Versions and edge cases

Versions and edge cases

FNF base game and Psych Engine
Both load Sparrow atlases through HaxeFlixel and pick an animation by frame name prefix. In Psych Engine, the prefix goes in the animation name field of the character editor, and offsets are set per animation in the same place.
Starling and HaxeFlixel
Sparrow is the Starling texture atlas format, and HaxeFlixel reads it with FlxAtlasFrames.fromSparrow. The file works outside the modding scene as is.
Adobe Animate
Animate can publish sprite sheets in the Starling format, which is why many FNF sheets look like Animate output. This export writes that plain Sparrow form, not the newer Animate texture atlas with Animation.json.
FNF & Sparrow FAQ

More detail in the related guide, or compare every export format.

Other engines

Export for FNF & Sparrow

Load your frames, check the loop in the Preview tab, then export. For FNF & Sparrow that means: Sparrow TextureAtlas (.xml).