日本語 | English

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.

Note: The APIs and workflows described here are still under active development and may change without notice. No warranty or support is provided for this branch, and we cannot respond to feature requests or bug reports. A migration guide for v1.x users will be provided as a separate document.

A high-performance plugin for playing back animations created with OPTPiX SpriteStudio 7 inside Godot Engine. This plugin allows you to easily implement and play back raster-based 2D animations within your Godot projects.

Documentation

Comprehensive documentation is available in the docs/ folder:

• Documentation (English)
• ドキュメント (日本語)

Quick Links (English)

• Installation
• Importing Data
• Basic Usage
• Tips & Advanced
• Build Guide

Quick Start with GDExtension

We provide two Quick Starts: one for quickly checking the operation using a sample project, and another for setting up your own project.

1. Check Operation with Sample

1. Get Godot Engine: Download a 4.6-series editor from the official site.
2. Download GDExtension: Get the latest package from Releases and extract it.
3. Prepare Sample: Copy the extracted addons folder into the examples/Ringo folder of this repository.
4. Check: Open the examples/Ringo project in Godot Engine and open Ringo.tscn to immediately see the animation working.

2. Introduce to Your Project

1. Install: Copy the addons folder into your Godot project root.
2. Import: Drag & drop your .sspj onto the Godot editor to convert it to .ssab.
3. Play: Add a SpriteStudioPlayer2D node and assign the .ssab to its SSAB Resource property.

For more details, see the Installation Guide.

Overview

The following diagram shows the data flow from SpriteStudio source assets to Godot runtime.

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

    subgraph Godot ["Godot Project (res://)"]
        DOCK[[" SS Import Dock "]]
        BIN[" Generated .ssab "]
        NODE[[ SpriteStudioPlayer2D ]]
    end

    SS -- "Drag & Drop" --> DOCK
    DOCK -. "Auto-generate" .-> BIN
    BIN -- "Assign in Inspector" --> NODE
    NODE -- "Play" --> RENDER{{" Screen "}}

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

Loading

1. Source Assets: Animations are authored in SpriteStudio 7, producing .sspj (Project), .ssae (Animation), and .ssce (CellMap) files along with textures.
2. Conversion: To ensure high performance in Godot, source assets are converted into optimized binary formats (.ssab / .ssqb) using the SS Import Dock (built-in) or ssconverter-cli.
3. Godot Runtime: The generated binaries are loaded as SSABResource and played back via the SpriteStudioPlayer2D node, which utilizes libssruntime for efficient rendering.

Samples

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

• allAttributeV7 — Functional test for all attributes
• allPartsV7 — Functional test for all part types
• overall — Comprehensive functional test
• overall_gdextension — Comprehensive test for GDExtension
• ParticleEffect — Test for effect features
• Ringo — Test for Ringo
• dev_module — Development project for Module version
• dev_gdextension — Development project for GDExtension version

Related Repositories

• SpriteStudio7-SDK — The SDK itself, providing libssruntime / libssconverter

License

See LICENSE.txt.