Godot Animation Frame Duration — Milliseconds to SpriteFrames
In Godot 4 an AnimatedSprite2D frame has no time of its own: its duration is a multiplier of the animation's speed in frames per second. So 250 ms at 12 fps is 3.0, and a GIF with uneven delays needs a different number on almost every frame. The Studio keeps your timing in milliseconds and does that division for each frame when it writes the SpriteFrames resource.
In Godot 4 a SpriteFrames frame has no time in milliseconds. Its duration is a relative number (1.0 by default), and the animation's Speed in FPS turns it into seconds: seconds = duration ÷ (FPS × playing speed). 250 ms is therefore 2.5 at 10 FPS and 3.0 at 12 FPS. To keep uneven timing from a GIF or an .aseprite file, give each frame ms ÷ (1000 ÷ FPS). Nerulio's Godot 4 export does that for every frame; its tags are written at 10 FPS, so the duration is simply ms ÷ 100. Godot 4 only; checked in 4.7.2.
- Godot 4Verified· Godot 4.7.2
- Unity 6Verified· Unity 6000.5.3f1
- Phaser 3 / 4Verified· Phaser 3.90 + 4.2
- PixiJS 8Verified· PixiJS 8.21
- Aseprite JSONVerified· Phaser load.aseprite · PixiJS 8.21
- .asepriteVerified· Aseprite 1.3.18
- Spine / libGDXVerified· spine-canvas 4.2
- Starling / Sparrow XMLVerified· Phaser 4.2
- LÖVEVerified· LÖVE 11.5
- DefoldBuilt· Defold bob.jar 1.13.1
- GameMakerUNVERIFIED
- CSS spritesVerified· Chromium
- GIF / APNGDecoded· Pillow
How Godot 4 times a frame
Each SpriteFrames animation has a Speed in frames per second, and each frame has a relative duration. The Godot 4.7 class reference gives the rule: absolute duration = relative duration ÷ (animation FPS × |playing speed|), where the playing speed is the node's speed_scale times the custom_speed you pass to play(). At 10 FPS one tick is 100 ms, so 1.0 lasts 100 ms and 2.5 lasts 250 ms.
Because durations are ratios, changing Speed retimes the whole animation and keeps the rhythm: at 20 FPS every frame lasts half as long. Frames added by dragging images or with Add Frames from Sprite Sheet all get 1.0, so an animation built that way has one frame time for every frame; uneven timing has to be typed into each frame's Frame Duration field in the SpriteFrames panel, or set with add_frame(anim, texture, duration) or set_frame() in code.
Loop is a flag per animation, not a count. A looping animation never emits animation_finished (use animation_looped); a non-looping one stops on its last frame and emits it. Godot 4.7 also has a ping-pong loop mode that plays the end frames once at each turn.
Nerulio keeps every frame in milliseconds (GIF and APNG delays, Aseprite durations, or values typed on the timeline) and converts only when it writes the .tres. Tags are written at 10 FPS; a project without tags gets one implicit animation at 12 FPS. Reverse and ping-pong are written out as frame order (ping-pong without doubled end frames, like Godot's own mode), repeat ∞ becomes loop on and any finite repeat becomes loop off.
- Speed (FPS)
- An animation's ticks per second; 1000 ÷ FPS is the length of one tick in ms.
- Relative duration
- A frame's length in ticks (default 1.0). Shown as Frame Duration in the SpriteFrames panel.
- Playing speed
speed_scale× thecustom_speedofplay(); it divides every frame's time.- Loop
- On: the animation repeats and never emits animation_finished. Off: it plays once and stops.
Worked example: a GIF with uneven delays
A six-frame walk exported as a GIF, as Nerulio writes it for Godot and how to read it back:
GIF "walk": 6 frames, delays 80, 80, 80, 160, 80, 240 ms (one cycle 720 ms)
Nerulio → Godot: speed 10 FPS, one tick = 1000 / 10 = 100 ms
durations = 80/100 … = 0.8, 0.8, 0.8, 1.6, 0.8, 2.4
Back to seconds: duration / (FPS × playing speed)
2.4 / (10 × 1) = 0.24 s with speed_scale 2: 2.4 / (10 × 2) = 0.12 s
cycle: (0.8 × 4 + 1.6 + 2.4) / 10 = 0.72 s = 720 ms
The same timing typed by hand at 12 FPS (tick 83.33 ms):
80 → 0.96 160 → 1.92 240 → 2.88Both versions play identically; only the numbers in the resource differ. If you later set the Speed to 20 FPS, every frame halves and the cycle becomes 360 ms.
What it does
- Timing in milliseconds from wherever it comes: GIF and APNG delays, Aseprite per-frame durations, or values you type on the Timeline, one frame at a time or in bulk.
- Each animation's speed is its tag's fps, and each frame's duration = its ms ÷ (1000 ÷ fps), written with up to six decimals.
- Reverse and ping-pong are baked into the frame order, so Godot plays them forward exactly as the preview did; a ping-pong does not show its end frames twice.
- Repeat 0 (loop forever) sets loop on. A tag with a finite repeat count is written with loop off, because SpriteFrames has no repeat count.
- Checked in Godot 4.7.2: every animation's speed, loop flag and per-frame duration read back from the loaded resource matched what was written.
How to do it
- Drop a GIF, an .aseprite file or a sprite sheet.
- Open the Timeline and check each frame's ms; select several frames to set them together.
- Play the tag with Enter, honouring its direction and repeat, and fix what feels off.
- Open Pack & Export and choose Godot 4.
- Put the .tres on an AnimatedSprite2D's Sprite Frames, or open the .tscn that comes with it.
Files you get
The timing lives in two files of the Godot 4 bundle:
| File | What it is for |
|---|---|
hero.tres | Per animation: speed (10.0 for tags), loop, and one duration per frame with up to six decimals. |
hero.tscn | An AnimatedSprite2D that autoplays the first animation at speed_scale 1. |
Check and change the timing in Godot 4
- Load
hero.tresinto anAnimatedSprite2D's Sprite Frames property, or openhero.tscn. - In the SpriteFrames panel select the animation: its Speed shows 10 FPS. Select the long frame: its Frame Duration shows 2.4. Type a new value there to retime just that frame.
- To change the tempo of the whole animation, change Speed, not the frames: 10 → 12 FPS shortens every frame to 1 ÷ 1.2 of its time and keeps the rhythm.
- Read the timing in code:
sprite_frames.get_frame_duration("walk", 5) / sprite_frames.get_animation_speed("walk")gives 0.24 s. - For a one-shot animation turn loop off and connect
animation_finished; for a looping one useanimation_looped. - Leave Speed Scale at 1 and call
play("walk")without a custom speed, or every frame is divided by that factor.
Check the result
- Sum duration ÷ speed over all frames in a script; for the walk above it is 0.72 s, the length of one GIF cycle.
- The Frame Duration field of the 240 ms frame reads 2.4 and of the 160 ms frame 1.6.
- Play it next to the GIF in a browser: the pause on the last frame lasts as long in both.
Milliseconds at a given fps → Godot duration
| Frame time | Animation speed (fps) | One unit lasts | duration in the .tres |
|---|---|---|---|
| 100 ms | 10 | 100 ms | 1.0 |
| 250 ms | 12 | 83.33 ms | 3.0 |
| 120 ms | 10 | 100 ms | 1.2 |
| 50 ms | 20 | 50 ms | 1.0 |
| 500 ms | 12 | 83.33 ms | 6.0 |
Rule: duration = ms ÷ (1000 ÷ speed). The Studio writes speed = the tag's fps and converts every frame, so you never type these numbers yourself.
Troubleshooting
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Every frame lasts the same although the source was uneven | The frames were added by drag and drop or from a sprite sheet, so all have 1.0 | Click through the frames and read Frame Duration | Type each frame's ms ÷ (1000 ÷ FPS), or export the animation from Nerulio |
| The animation runs twice as fast as the GIF | speed_scale is 2, or play() got a custom speed | get_playing_speed() while it plays | Set Speed Scale to 1 and call play() without the second argument |
| A frame meant to last 250 ms flashes by | Seconds (0.25) were typed as the relative duration | At 10 FPS 0.25 is 25 ms | Enter ms ÷ (1000 ÷ FPS): 250 ms at 10 FPS is 2.5 |
animation_finished never fires | The animation loops; looping animations do not emit it | Loop toggle in the SpriteFrames panel | Turn loop off for one-shot actions, or listen to animation_looped |
| A ping-pong animation pauses on its end frames | The order was written by hand as 0-1-2-3-3-2-1-0, so the end frames play twice | Read the frame list of the animation | Remove the doubled frames, or use Godot's ping-pong loop mode; Nerulio writes 0-1-2-3-2-1 |
| Some GIF frames come out 100 ms instead of 10 ms | The GIF stores 0 or 1 hundredths, which browsers play as 100 ms | Nerulio shows this as a delay decision on import | Keep the browser reading, or switch to the file's raw values before export |
Other ways to do it
| Option | When it is the better choice |
|---|---|
| Type Frame Duration by hand in the SpriteFrames panel | A handful of frames that need a longer hold; no export step. |
Sprite2D + AnimationPlayer keying frame at exact times | You want timing in seconds on a timeline and other tracks (sound, hitboxes) on the same clip. |
| Even timing: one Speed for all frames | Every frame lasts the same: set Speed = 1000 ÷ ms and leave durations at 1.0; see sprite sheets in Godot. |
Engine exports and how each was checked
"Verified" means the exported files were loaded by the real engine or tool on real CC0 assets and the result was compared with the source. Anything that was not loaded is labelled as such.
| Target | Files | Check |
|---|---|---|
| Godot 4 | .tres SpriteFrames · .tscn AnimatedSprite2D · .png.import | Verified Godot 4.7.2Loaded by Godot; every animation frame drawn and compared with the source file. The scene uses Nearest filtering; rotation is never used. |
| Unity 6 | .unity.json · Editor/NerulioSpriteImporter.cs · AnimationClip | Verified Unity 6000.5.3f1Batch mode: sprite rects, pivots, pixels, clip keys and durations checked. |
| Phaser 3 / 4 | atlas JSON (multiatlas) · .anims.json | Verified Phaser 3.90 + 4.2Frames and animations drawn by both versions. |
| PixiJS 8 | spritesheet JSON · animations · anchor · meta.scale | Verified PixiJS 8.21Rotated and multi-page atlases included. |
| Aseprite JSON | hash / array · frameTags · slices | Verified Phaser load.aseprite · PixiJS 8.21Tags keep their direction and repeat count. |
| .aseprite | layers · tags · durations · slices | Verified Aseprite 1.3.18Opened and rendered by the Aseprite command line. |
| Spine / libGDX | .atlas | Verified spine-canvas 4.2Every region drawn by the Spine runtime, rotated and trimmed; libGDX itself was not run. |
| Starling / Sparrow XML | XML per page | Verified Phaser 4.2Phaser 3.90 draws trimmed XML frames wrongly (its own bug); the "Sparrow XML (Phaser 3)" preset turns trim off and passes in 3.90 and 4.2. |
| LÖVE | Lua quads · nerulio_atlas.lua · main.lua | Verified LÖVE 11.5Every frame drawn and every animation stepped through the shipped helper. |
| Defold | .atlas · .tilesource | Built Defold bob.jar 1.13.1Built by Defold's command-line builder; the built texture's UVs were read back. |
| GameMaker | spr_<name>_stripN.png · gamemaker.json | UNVERIFIEDNot loaded in GameMaker (no headless GameMaker). The strips are cut the way its strip importer cuts them. |
| CSS sprites | .css · preview .html | Verified ChromiumEvery class drawn from the shipped stylesheet. |
| GIF / APNG | one file per animation | Decoded PillowEvery frame and delay decoded again after export; APNG is exact. |
Evidence
GIF decoder: 408 of 408 frames identical to Pillow on 29 real GIFs; APNG 132 of 132 on 16 files. .aseprite: 231 corpus files imported, re-written and reopened in Aseprite 1.3.18 with the same tags, durations and pixels (231/231). Exports: 49 runs in the real engines on real CC0 assets, 47 pass — the 2 failures are Phaser 3.90's trimmed-XML bug, which the Phaser 3 preset avoids.
Limits
- SpriteFrames has no repeat count: play-3-times from Aseprite becomes loop off, and the extra plays are up to your script.
- Godot 3 has no per-frame duration and cannot read the exported resource.
- A grid or island guess is a preview with a confidence; nothing is cut until you press Apply, and every choice has one-click alternatives.
- .aseprite files whose layers do not compose exactly (e.g. group opacity) are imported flattened, and the Import panel says why.
- Rotated frames in an imported atlas stay rotated; their export is UNVERIFIED.
- Images up to 32,768 px per side (268 million pixels), subject to your browser's memory.
Versions and sources
In the verification runs Godot 4.7.2 loaded Nerulio's .tres and every animation's speed, loop flag and per-frame durations read back equal to what was written. The duration formula, speed_scale, get_playing_speed() and the signals are quoted from the Godot 4.7 class reference; the Frame Duration field name comes from the Godot 4.7 editor source.
Official documentation used
Questions
Why is my frame duration 3.0 and not 0.25?
Godot 4 measures a frame's duration relative to the animation speed. At 12 fps one unit lasts 1000 ÷ 12 ≈ 83.3 ms, so a 250 ms frame is 3.0 units. If you change the speed later, every frame scales with it and the ratios stay.
Can Godot 3 read these timings?
No. Godot 3's SpriteFrames has no per-frame duration and uses a different resource format. Only Godot 4 was checked (4.7.2).
Does speed_scale on the node change anything?
speed_scale on the AnimatedSprite2D multiplies the whole animation. Leave it at 1 and the frames last the milliseconds you set in the Studio.
A GIF says some frames last 0 or 1 hundredths of a second. What does Godot get?
Browsers stretch such frames, so the GIF import asks how to read them: as browsers play them, or the file's own values. It shows that as a decision you can switch, and whichever you keep is what the SpriteFrames receives.
Is it free, and do I need an account?
Everything on these pages is free and works without an account. There is no watermark and no export that is held back.
Are my sprites uploaded?
No. The Studio decodes, packs and exports in this browser tab. Projects are autosaved in the browser (IndexedDB) and can be saved as a .nerulio file.
Does it need Aseprite or an engine plugin installed?
No. .aseprite files are read and written in the browser, and each engine bundle carries what that engine needs (for Godot, the import settings and scene; for Unity and the Godot TileSet, a small editor script).