DefoldMetadata export

Sprite Sheet Generator for Defold

The Defold preset writes spritesheet.png and spritesheet.tilesource. The tile size, zero margin and spacing, and a looping default animation are already in the file, so a Sprite component can play it straight away.

A sprite sheet exported as a uniform PNG grid, next to the settings it needs in Defold
What you export

Format menu

Defold

Tile Source (.tilesource)

Format > Defold downloads spritesheet.png and spritesheet.tilesource. The tile source points at /spritesheet.png in the project root, sets Tile Width and Tile Height to the cell size, leaves Tile Margin and Tile Spacing at 0, and defines one looping animation named default from tile 1 to the last frame at 12 FPS. Put the PNG at the project root, or edit the image line to wherever it lives. Inner Padding and Extrude Borders are still yours to set in the editor: they add space around each tile in the texture Defold builds, not in your PNG.

Step by step

Getting the sheet into Defold

  1. 1

    Export the pair

    Click Format in the Export panel and choose Defold. The ZIP holds spritesheet.png and spritesheet.tilesource.

  2. 2

    Place the files

    Copy spritesheet.png to the project root, where /spritesheet.png points, and the .tilesource wherever you like. If the PNG goes in a subfolder, change the image line in the .tilesource to that path.

  3. 3

    Add a Sprite

    Add a Sprite component to a game object and set Image to the .tilesource. The animation named default is ready to play.

  4. 4

    Play it

    Call sprite.play_flipbook("#sprite", "default") from a script. Add more animations in the Tile Source editor if the sheet holds more than one.

  5. 5

    Nearest filtering

    In game.project under Graphics, set Default Texture Min Filter and Default Texture Mag Filter to nearest.

Lua
function init(self)
    sprite.play_flipbook("#sprite", "default")
end

function on_input(self, action_id, action)
    if action_id == hash("right") then
        sprite.play_flipbook("#sprite", "default")
    end
end
Cheat sheet
SettingDefold value
ImportPNG at the project root, .tilesource anywhere
Asset typeTile Source (.tilesource), written for you
Image/spritesheet.png in the project root
Cell sizeTile Width / Tile Height, already set
Tile Margin / Tile Spacing0, the cells touch
Animationdefault, tiles 1 to frame count, 12 FPS
Crisp pixelsgame.project > Graphics > filters: nearest
Built for the workflow

A ready Tile Source

The .tilesource is plain text with the image path, tile size, margin, spacing and one animation already filled in. Open it in the editor to add more animations or collision groups.

Tile numbers in your order

Tiles number left to right, top to bottom, the same order you arranged the frames. The generated animation runs from tile 1 to the last frame.

Frames for an Atlas too

The ZIP export writes each frame as its own PNG (frames/frame_001.png and up), ready to drag into an Atlas if you want Defold to pack and trim them.

Troubleshooting

When the sheet fights Defold

play_flipbook logs that the animation cannot be found

Cause
The id passed to play_flipbook has to match an animation Id in the Tile Source exactly. The generated file names its first animation default.
Fix
Use sprite.play_flipbook("#sprite", "default") for the generated animation, or open the Tile Source and copy the Id of any animation you added rather than retyping it.

The animation starts on the wrong pose

Cause
Tile numbers in a Tile Source start at 1, not 0, and run left to right then top to bottom. The generated animation covers tiles 1 to the frame count.
Fix
Open the Tile Source and check Start Tile and End Tile. If the sheet holds several animations, split them into separate rows and add one animation per range.

Thin seams appear between tiles in a tilemap

Cause
Neighbouring tiles are sampled at their shared edge, and without extrusion the sampler picks up the next tile.
Fix
Set Extrude Borders to 1 or 2 in the Tile Source. Defold adds the extrusion when it builds the texture, so the PNG and tile size stay the same.

Pixel art scales unevenly

Cause
The game object has a fractional scale, which no filter setting can make even.
Fix
Scale game objects, or the camera zoom, by whole numbers only.

Build size grows faster than the art you add

Cause
A Tile Source cannot trim, so duplicated frames and wide transparent margins survive into the build.
Fix
Drop repeated poses before exporting. If trimming matters more than having one grid image, use an Atlas built from the ZIP frames instead.
Versions and edge cases

Versions and edge cases

Tile Source fields
Image, Tile Width, Tile Height, Tile Margin, Tile Spacing, Inner Padding, and Extrude Borders. The Defold export fills in the first five and one animation; Inner Padding and Extrude Borders stay at their defaults until you set them in the editor.
Tilemaps
A tilemap component needs a Tile Source, not an Atlas, so the grid export is the route for level tiles.
Collision from tiles
A Tile Source can generate a collision shape per tile from the alpha of a Collision image. Point it at the same PNG and set Collision Groups on the tiles that should block.
Defold FAQ

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

Other engines

Export for Defold

Load your frames, check the loop in the Preview tab, then export. For Defold that means: Tile Source (.tilesource).