Most failures here look the same from the outside — nothing on screen — and are told apart by their causes rather than their symptoms. Check Godot's Output panel first: the plugin and the engine both name the path or the resource they could not use.
The extension did not load. In the GDExtension build, check in this order:
res://addons/spritestudio/spritestudio.gdextensionexists — theaddonsfolder must be copied to the project root, not into a subfolder.- The editor is a Godot 4.7 build. GDExtension is officially supported from 4.7, and a library built against a different
godot-cppwill not load. addons/spritestudio/bin/<platform>/contains a library for the platform you are running. The Output panel names the file it tried to open.
In the custom module build there is no addons folder — the node exists only if the module was compiled into the editor binary you are running.
Export needs the same target you export with: --export-debug uses the template_debug library and --export-release the template_release one. If only an editor build exists, the export still "succeeds" and ships an extension with no library behind it. See Build Guide.
Assigning the .ssab is not enough. Pick a name in the Animation dropdown (or call set_animation()), then play() — or turn Autoplay on.
A name that is not in the pack leaves the node drawing nothing. The Output panel names the pack and the name you asked it for:
[SS] res://ssab_generated/Ringo/Ringo.ssab has no animation "wakl".
The Animation dropdown only offers real names, so this is a set_animation() in a script — usually a typo, or a name that belongs to a different pack, which is why the pack is named too. get_animation_names() lists what the pack actually has.
[SS] … is not a usable SSAB: it carries no parts or no animations. in the Output panel means the binary loaded but carries no parts or no animations. Reconvert the .sspj; the file is most likely truncated or from an incompatible converter version.
Textures and sounds are resolved relative to the directory the .ssab was loaded from. Moving the .ssab out of the converter's output directory — without the .png files that were copied next to it — leaves the animation with nothing to sample. Godot logs the path it failed to load.
Keep the output directory (res://ssab_generated by default) intact, or move the whole directory.
SpriteStudioPlayer2D draws in SpriteStudio's pixel coordinates around the node's origin. An animation authored around a far-from-origin point can land outside the camera. Use Offset to shift the drawing without moving the node.
- Text parts and 9-slice parts are not drawn yet. They keep their slot in the draw order, so the animation plays with a hole in it. See Limitations & Scope.
- A part hidden on this frame is hidden by the animation, not by the plugin. Check the timeline in SpriteStudio, and check that no visibility override is left over from a script.
- A part inside an Instance part cannot be addressed by name from the outside — the child animation runs as a separate player. The Instance part itself can.
While playback is stopped or paused — or on any frame that does not advance — the drawing is not rebuilt, so setting or clearing an override changes nothing visible. Force a redraw with set_frame_no(get_frame_no()).
Under an infinite loop (loop_count of -1, or 0) it never fires by design. animation_looped fires on every wrap instead.
Seeking fires only the destination frame's events. This is a shared runtime constraint, not something the player can work around — drive logic off the frame number if you need to survive seeks.
independent=true parts evaluate correctly under forward playback only. A reverse direction and ping-pong return legs are not supported for them. (A negative speed_scale is not a third case — it stops the playhead rather than reversing it.)
Work down the list — each item silences audio on its own:
- The playback direction is backward. Reverse playback fires no audio at all, including the return leg of ping-pong and a negative
speed_scale. play_audiois off, or anaudio_backendis assigned and itsplay_audio()does not reach your audio stack. Assigning a backend always suppresses the built-in player.- The sound file did not load. Godot logs the path.
.wav/.oggimport asAudioStream; a format Godot does not import resolves tonulland is silently skipped. audio_volumeis 0, or the game's audio bus is muted.
Details in Audio Playback.
SpriteStudio must be installed on the machine you are working on, and .sspj must be associated with it — the button hands the file to the OS shell.
The link from .ssab back to .sspj lives as a relative path in .ssplayer_sources.cfg at the project root. If the .sspj moved, right-click the .ssab in the FileSystem dock and choose Reconvert; you are prompted for the new location, and every other file in the same directory is re-linked from that one answer.
Track .ssplayer_sources.cfg in version control so the whole team gets working buttons after a clone.
Select the node and use the SpriteStudio bottom panel — play from start / play from current / stop, plus a frame scrubber and loop and speed controls. Playback in the editor is driven from there, not from Autoplay.
- "GDExtension libraries are not supported by this engine version." — the stock Web templates cannot load GDExtension. Supply an engine template built with
dlink_enabled=yesand enable Extensions Support in the export preset, or use the custom module build, which needs neither. See Exporting Your Project → Web. - The page loads but the animation never appears — the runtime is built with WebAssembly SIMD and does not run on browsers without it. Treat SIMD as a distribution requirement.
- COOP/COEP headers are not needed: the Web build is single-threaded (
nothread) on purpose, so a plain static server is enough.
- Limitations & Scope — the constraints that are expected behavior rather than bugs.
- Shared Limitations — the ones that apply to every official player.
- Report an issue — include the Godot version, the build variant (GDExtension / custom module), the platform, and the Output panel text.