diff --git a/docs/en/index.md b/docs/en/index.md index 534e2f6..9e5236f 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -26,6 +26,7 @@ Animation playback uses `libssruntime` provided by [SpriteStudio-SDK](https://gi - [Scripting and Events](workflow/usage_scripting.md) - [Audio Playback](workflow/audio.md) - [Exporting Your Project](workflow/export.md) + - [Generated Assets and Packs](workflow/generated_assets.md) (dependencies, export modes, `.pck`) - **Advanced Topics** - [CLI Conversion and Automation](workflow/import.md) - [Performance Tuning and Advanced Settings](workflow/tips.md) diff --git a/docs/en/workflow/export.md b/docs/en/workflow/export.md index c8980bb..7f288c0 100644 --- a/docs/en/workflow/export.md +++ b/docs/en/workflow/export.md @@ -2,6 +2,10 @@ Once your scene plays correctly in the editor, you export it like any other Godot project (**Project → Export…**). SpriteStudioPlayer runs in exported builds on every Godot target. There are only a few plugin-specific points to know. +> [!IMPORTANT] +> **Some export modes drop the generated assets.** +> A `.ssab` reads its images, audio and Instance targets by *resolving paths at runtime*, so they never appear in the Godot editor's dependency graph. A dependency-based mode such as "Export selected scenes (and dependencies)" leaves them out, producing a build that **launches but shows no artwork**. See [Generated Assets and Packs](generated_assets.md#choosing-an-export-mode) for the details and the fix. + ## General - **GDExtension variant** — the native library lives in your project's `addons/spritestudio/bin/`, and Godot bundles it into the export automatically. Desktop targets need nothing extra. diff --git a/docs/en/workflow/generated_assets.md b/docs/en/workflow/generated_assets.md new file mode 100644 index 0000000..31e7f18 --- /dev/null +++ b/docs/en/workflow/generated_assets.md @@ -0,0 +1,158 @@ +# 📦 Generated Assets, Exporting and Downloadable Packs + +[← Back to documentation index](../index.md) + +Converting a `.sspj` produces several files in the output folder. This page covers what you need in order to decide **how much of that has to travel together** when you export or ship a `.pck`: how the files depend on each other, **why the Godot editor cannot see those dependencies**, and what a reconvert overwrites and what it leaves alone. + +For the import procedure itself see [Asset Import and Editor Integration](usage_asset_pipeline.md); for per-target export settings see [Exporting Your Project](export.md). + +--- + +## How the SpriteStudio files map to the output + +If you are handed a `.sspj` and asked to take it from there in Godot, the first thing to know is **which SpriteStudio file becomes which converted file**. The roles of `.sspj` / `.ssae` / `.ssce` / `.ssqe` and how they map are the same for every Player, so they are documented in the portal. + +> [!NOTE] +> [SpriteStudio Docs: Asset Conversion — How a project's files map to the output](https://cri-middleware.github.io/SpriteStudio-Docs/overview/conversion/#how-a-projects-files-map-to-the-output) +> +> Two points matter here: **one `.ssae` becomes one `.ssab`**, and **cell positions are baked from the `.ssce` into the `.ssab`**. The latter decides whether you can swap the image on its own, below. + +### What you did in SpriteStudio, and what that updates + +| What you did in SpriteStudio | Output that changes | When shipping | +|---|---|---| +| Repainted the artwork only (cells untouched) | The `.png` alone | Shipping the pack that holds the images is enough | +| Added, moved or resized cells, or changed the image size (the `.ssce` changed) | The `.png` **and** the `.ssab` | **Ship both together.** Shipping one alone makes the artwork shift | +| Edited an animation (`.ssae`) | The corresponding `.ssab` | The pack containing that `.ssab` | +| Added an anime pack | One more `.ssab` | Make sure the new file is included in a pack | +| Edited a sequence (`.ssqe`) | The `.ssqb` | Nothing in the game changes today | + +--- + +## What gets generated + +Converting one `.sspj` creates a `/` folder under the output folder (default: `res://ssab_generated`), laid out like this. + +```text +res://ssab_generated/overall/ +├── Basic.ssab ← one per anime pack +├── Effect.ssab +├── Instance.ssab +├── … +├── sequence.ssqb ← one per .ssqe +├── common.png ← atlas images +├── common_2.png +├── box_00_00.png +├── font/ +│ └── RoundedMPlus_0.png ← subfolders are preserved +└── sound/ + ├── test.mp3 + └── WAV_16khz_mono_256kbps_s16.wav +``` + +| File | Produced from | Godot representation | What it holds | +|---|---|---|---| +| `.ssab` | One file per `.ssae` | `SSABResource` | Animations (keyframes), part structure, **the cell map (the source rectangle, pivot and original image size on the atlas)**, effect definitions, user data / signals, referenced texture names, sound references | +| `.ssqb` | One file per `.ssqe` | `SSQBResource` | The animation playback order (sequence). Playback is not yet supported ([Limitations and Scope](../limitations.md)) | +| `.png` and so on | The images referenced by the `.sspj` | `Texture2D` (Godot writes an `.import` and converts to `.ctex`) | The artwork itself (the atlas image) | +| `sound/