From 51ec330a32e772218f8940090c321dec973f09e8 Mon Sep 17 00:00:00 2001 From: Naruto TAKAHASHI Date: Sun, 6 Sep 2026 16:37:50 +0900 Subject: [PATCH] docs: what the converter emits, and how to get it into a build The Unity player grew a page for this; Godot needs one for the opposite reason. Unity's references are GUIDs, so its editor tracks them correctly by construction. Here a `.ssab` reaches its textures, its `sound/` audio and the `.ssab` an Instance part plays by building a res:// path against its own directory at runtime, and SSABResource reports no dependency list -- so the editor filesystem's dependency cache for a `.ssab` is empty. That is invisible until it bites. "Export selected scenes (and dependencies)" collects by walking those deps, so it ships the `.ssab` a scene references and leaves the images, the audio and the Instance target behind. Playback does not stop on a texture that failed to resolve; the parts are drawn untextured. The export succeeds, the app launches, and only the artwork is missing. The default "Export all resources in the project" takes every file and is unaffected, which is why nobody has hit this yet. The warning is on the new page and repeated at the top of the export page, where the mode is chosen. The rest is what a reader has to work out by inspection today: which files land in the output folder and what each one holds; that no material and no shader is generated into the project, the shaders being built into the native library; that a reconvert rewrites the binaries in place, so an image's `.import` -- and its UID -- survives, and that a collision dialog appears only when the output already belongs to a different `.sspj`; and that `.pck` resolution works across packs because the pack carries its own `.remap` files. The `.sspj` / `.ss*e` side is player-agnostic and lives in the portal, which this links to rather than restating. Also correct the English CLI page: the converter writes `/`, not `_ssab/`, and it writes the referenced textures and audio there too -- which is the whole reason the folder has to be copied as a unit. --- docs/en/index.md | 1 + docs/en/workflow/export.md | 4 + docs/en/workflow/generated_assets.md | 158 +++++++++++++++++++++++ docs/en/workflow/import.md | 5 +- docs/en/workflow/usage_asset_pipeline.md | 3 + docs/ja/index.md | 1 + docs/ja/workflow/export.md | 4 + docs/ja/workflow/generated_assets.md | 158 +++++++++++++++++++++++ docs/ja/workflow/import.md | 3 + docs/ja/workflow/usage_asset_pipeline.md | 3 + mkdocs.ja.yml | 1 + mkdocs.yml | 1 + 12 files changed, 341 insertions(+), 1 deletion(-) create mode 100644 docs/en/workflow/generated_assets.md create mode 100644 docs/ja/workflow/generated_assets.md 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/