index.md

🕹️ SpriteStudioPlayer for Godot

This develop branch is a work-in-progress version.
The stable version can be obtained from the main branch or from Releases.
No warranty or support is provided for this branch, and we cannot respond to feature requests or bug reports.
Interfaces may change without notice.

A plugin for playing back animations created with SpriteStudio inside Godot Engine. Animation playback uses libssruntime provided by SpriteStudio-SDK.

!!! tip "No SpriteStudio data of your own yet?" The official sample data works as-is — that page is Japanese only, but the downloads themselves are language-neutral. Ringo is a good character sample, and Particle is a good one if you want effects.

Table of Contents

• Setup
  • Installation
  • Build Guide
• Workflow
  • Basic Usage
  • Integration with AnimationPlayer
  • Asset Import and Editor Integration (start here for the initial .sspj import)
  • Scripting and Events
  • Audio Playback
  • Exporting Your Project
  • Generated Assets and Packs (dependencies, export modes, .pck)
• Advanced Topics
  • CLI Conversion and Automation
  • Performance Tuning and Advanced Settings
• API Reference
  • SpriteStudioPlayer2D
  • Resource Classes
• Troubleshooting
• Limitations & Scope
• Migration from v1.x
• License
  • License
  • Third-Party Notices

Key Features

This plugin brings SpriteStudio's full expressive power to Godot Engine.

• Broad Feature Support: Supports nearly all SpriteStudio features — bone hierarchies, mesh & deformations, and high-performance particle effects — with a few exceptions noted in Limitations & Scope.
• Seamless Integration and a Powerful Asset Pipeline: In addition to easy drag-and-drop importing via the built-in "SS Import Dock", you can open SpriteStudio directly from the Inspector and reconvert with a single click. For details, see Asset Import and Editor Integration.
• Dynamic Customization (CellMap Overrides): Easily swap textures at runtime to implement character equipment changes or color variations.
• Signals & Events: Receive "User Data" and "Signals" from your animation timeline directly as Godot Signals, allowing frame-perfect triggers for game logic. Every event says which part fired it.
• Audio That Just Plays: Audio parts sound through Godot with no setup — in the editor preview too. Adjust the volume, take it over through the audio signal, or route every sound to your own audio middleware with a backend resource.
• Per-Part Effects: The thirteen SpriteStudio add-on shaders (sepia, outline, HSB, blur, pixelate, wave, noise and more) are reproduced natively — assigned in SpriteStudio, nothing to wire up in Godot.
• Smooth Slow-Motion: Built-in sub-frame interpolation ensures buttery-smooth playback even on high-refresh-rate displays or during slow-motion effects.
• High Performance & Low Memory: Backed by libssruntime's SIMD optimizations and zero-parse overhead binary formats (.ssab), it renders massive amounts of characters efficiently, even on mobile targets.

Overview

The diagram below shows how data flows through the plugin from authored assets to in-game playback.

graph LR
    SS[" .sspj / Images<br>(Source Assets) "]

    subgraph Convert ["Conversion Process"]
        DOCK[[" SS Import Dock<br>(Built-in Editor) "]]
        CLI[[" ssconverter-cli<br>(CLI Tool) "]]
    end

    subgraph Godot ["Godot Runtime (res://)"]
        BIN[" .ssab / .ssqb "]
        NODE[[ SpriteStudioPlayer2D ]]
        RT(" libssruntime ")
    end

    SS -- "Drag & Drop" --> DOCK
    SS -- "CI/CD or Manual" --> CLI
    DOCK -. "Auto-generate" .-> BIN
    CLI -. "Generate" .-> BIN
    
    BIN -- "Assign in Inspector" --> NODE
    NODE -. "High-speed playback" .-> RT
    NODE -- "Render" --> RENDER{{" Screen "}}

    classDef generated stroke-dasharray: 5 5;
    class BIN generated;

Loading

Supported Versions

• Godot Engine: 4.7 branch
• godot-cpp: master branch

Note

GDExtension is officially supported starting from Godot 4.7.

Build and execution have been verified on Windows / macOS.

Samples

Sample projects based on SDK test projects are available under the examples/ folder in the repository.

• Ringo — Basic quickstart test for Ringo
• Scripting — GDScript example for controlling animations and signals
• Override_Ringo — Attribute/material override example
• overall — Comprehensive functional test (Custom Module)
• overall_gdextension — Comprehensive functional test (GDExtension)

Related Repositories

• SpriteStudio Docs — the documentation portal for the SDK and its official players.
• SpriteStudio-SDK — the SDK itself, providing libssruntime / libssconverter.
• SSConverterGUI — a standalone desktop GUI for converting .sspj without a player.

Migration

For instructions on migrating from versions prior to v1.x, please refer to the Migration Guide.

License

See License.

For third-party library licenses (such as FlatBuffers and SpriteStudio-SDK dependencies), see Third-Party Notices.