chore: move the example ssab deploy script to scripts/deploy-examples

AGENTS.md

@@ -38,6 +38,7 @@ A Godot Engine integration for SpriteStudio 7, providing a C++ `SpriteStudioPlay
 | Build Custom Module | `./scripts/build.sh` (POSIX) / `.\scripts\build.ps1` (Win) |
 | Setup (Source SDK) | `./scripts/build-runtime.sh` (POSIX) / `.\scripts\build-runtime.ps1` (Win) |
 | Setup (Prebuilt SDK) | `./scripts/download-sdk.sh` (POSIX) / `.\scripts\download-sdk.ps1` (Win) |
+| Deploy Example Assets | `./scripts/deploy-examples.sh` (POSIX) / `.\scripts\deploy-examples.ps1` (Win) |
 | Format C++ Code | `clang-format -i ss_player/*.{cpp,h}` (if available) |
 
 *Note: Setup (Source SDK) is recommended for developers using the submodule. Setup (Prebuilt SDK) is intended for CI or release-only environments.*

docs/en/setup/build.md

@@ -498,6 +498,24 @@ When `.fbs` files in SpriteStudio-SDK have changed, regenerate the headers under
 .\scripts\generate-runtime-code.ps1
 ```
 
+### Deploying the sample project assets
+
+The sample projects under `examples/` load `.ssab` assets converted from the SpriteStudio-SDK test projects. Regenerate them whenever an `ssab_generated/` directory is missing or the SDK version has changed. Each sample carries a `.ssplayer_sources.cfg` pointing at the source `.sspj`, so opening it in the Godot Editor regenerates the assets through the import dock; the script below does the same thing headlessly.
+
+**macOS / Linux**
+
+```sh
+./scripts/deploy-examples.sh
+```
+
+**Windows (PowerShell)**
+
+```powershell
+.\scripts\deploy-examples.ps1
+```
+
+> The `examples/dev_*` projects are excluded: they are developer-only scratch projects, so both their sources config and `ssab_generated/` are gitignored and set up by hand in the editor.
+
 ### SpriteStudio-SDK internal documentation
 
 Once the submodule is initialized, internal runtime specifications and porting notes are available at:

docs/ja/setup/build.md

@@ -493,6 +493,24 @@ SpriteStudio-SDK の `.fbs` を変更した場合は、以下で `ss_player/form
 .\scripts\generate-runtime-code.ps1
 ```
 
+### サンプルプロジェクトのアセット生成
+
+`examples/` 配下のサンプルは SpriteStudio-SDK のテストプロジェクトから変換した `.ssab` を読み込みます。`ssab_generated/` が無い場合や SDK のバージョンを更新した場合は再生成してください。各サンプルには変換元 `.sspj` を指す `.ssplayer_sources.cfg` があるため Godot エディタで開けばインポートドックが再生成しますが、以下のスクリプトはそれをエディタなしで実行します。
+
+**macOS / Linux**
+
+```sh
+./scripts/deploy-examples.sh
+```
+
+**Windows (PowerShell)**
+
+```powershell
+.\scripts\deploy-examples.ps1
+```
+
+> `examples/dev_*` は対象外です。開発者用のプロジェクトのため sources 設定と `ssab_generated/` の双方が gitignore されており、エディタ上で手動設定する運用です。
+
 ### SpriteStudio-SDK 内部ドキュメント
 
 サブモジュール初期化済みであれば、ランタイムの内部仕様や移植時の注意点は以下を参照できます。

scripts/deploy-examples.ps1

@@ -0,0 +1,74 @@
+#!/usr/bin/env pwsh
+#
+# Convert the SpriteStudio-SDK bundled test projects (tests/overall, tests/Ringo)
+# into the .ssab assets the sample projects under examples/ load.
+#
+# Each sample project also carries a .ssplayer_sources.cfg pointing at the same
+# .sspj, so opening it in the Godot Editor regenerates the same output through the
+# import dock. This script is the headless equivalent -- ssab_generated/ is not
+# tracked in git, so use it to populate the samples without launching the editor.
+#
+# The dev_* sample projects are intentionally excluded: their sources config is
+# gitignored and set up by hand in the editor.
+#
+# Requires the SpriteStudio-SDK submodule and a Rust toolchain (ssconverter-cli is
+# built from source; the prebuilt SDK packages only ship libssconverter).
+$ErrorActionPreference = "Stop"
+
+$baseDirectory = Split-Path -Parent $PSCommandPath
+$rootDirectory = Split-Path -Parent $baseDirectory
+
+$SDK_DIR = Join-Path $rootDirectory "ss_player/SpriteStudio-SDK"
+$SDK_TESTS_DIR = Join-Path $SDK_DIR "tests"
+$SDK_CLI_DIR = Join-Path $SDK_DIR "cli"
+$EXAMPLES_DIR = Join-Path $rootDirectory "examples"
+$APP = Split-Path -Leaf $PSCommandPath
+
+if (!(Test-Path (Join-Path $SDK_CLI_DIR "Cargo.toml"))) {
+    Write-Error "${APP}: SpriteStudio-SDK submodule is not initialized ($SDK_DIR)`n${APP}: run 'git submodule update --init --recursive' first"
+}
+
+if (!(Get-Command cargo -ErrorAction SilentlyContinue)) {
+    Write-Error "${APP}: cargo not found (a Rust toolchain is required to build ssconverter-cli)"
+}
+
+# Build ssconverter-cli
+Write-Host "Building ssconverter-cli (debug)..."
+pushd $SDK_CLI_DIR
+& cargo build
+if ($LASTEXITCODE -ne 0) {
+    popd
+    Write-Error "${APP}: cargo build failed ($LASTEXITCODE)"
+}
+popd
+$CONVERTER = Join-Path $SDK_DIR "target/debug/ssconverter-cli.exe"
+
+# "<SDK tests subdir>|<examples subdir>" -- one entry per destination sample
+# project. Output goes to <examples subdir>/ssab_generated/<SDK tests subdir>/,
+# matching the layout the editor's source sync produces.
+$DEPLOYMENTS = @(
+    "overall|overall"
+    "overall|overall_gdextension"
+    "Ringo|Ringo"
+    "Ringo|Override_Ringo"
+    "Ringo|Scripting"
+)
+
+foreach ($ENTRY in $DEPLOYMENTS) {
+    $TEST, $DEST = $ENTRY -split "\|"
+    $SSPJ_PATH = Join-Path $SDK_TESTS_DIR "$TEST/$TEST.sspj"
+    $OUTPUT_DIR = Join-Path $EXAMPLES_DIR "$DEST/ssab_generated/$TEST"
+
+    if (!(Test-Path $SSPJ_PATH)) {
+        Write-Error "${APP}: $SSPJ_PATH not found"
+    }
+
+    Write-Host "Updating SSAB for $TEST in $OUTPUT_DIR..."
+    mkdir -Force $OUTPUT_DIR > $null
+    & $CONVERTER "$SSPJ_PATH" -o "$OUTPUT_DIR"
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "${APP}: ssconverter-cli failed for $TEST ($LASTEXITCODE)"
+    }
+}
+
+Write-Host "Done!"

scripts/deploy-examples.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+#
+# Convert the SpriteStudio-SDK bundled test projects (tests/overall, tests/Ringo)
+# into the .ssab assets the sample projects under examples/ load.
+#
+# Each sample project also carries a .ssplayer_sources.cfg pointing at the same
+# .sspj, so opening it in the Godot Editor regenerates the same output through the
+# import dock. This script is the headless equivalent -- ssab_generated/ is not
+# tracked in git, so use it to populate the samples without launching the editor.
+#
+# The dev_* sample projects are intentionally excluded: their sources config is
+# gitignored and set up by hand in the editor.
+#
+# Requires the SpriteStudio-SDK submodule and a Rust toolchain (ssconverter-cli is
+# built from source; the prebuilt SDK packages only ship libssconverter).
+set -euo pipefail
+
+BASEDIR=$(dirname $0)
+BASEDIR=$(cd $BASEDIR && pwd -P)
+ROOTDIR=${BASEDIR}/..
+ROOTDIR=$(cd $ROOTDIR && pwd -P)
+
+SDK_DIR="${ROOTDIR}/ss_player/SpriteStudio-SDK"
+SDK_TESTS_DIR="${SDK_DIR}/tests"
+SDK_CLI_DIR="${SDK_DIR}/cli"
+EXAMPLES_DIR="${ROOTDIR}/examples"
+APP=$(basename $0)
+
+if [ ! -f "${SDK_CLI_DIR}/Cargo.toml" ]; then
+    echo "${APP}: SpriteStudio-SDK submodule is not initialized (${SDK_DIR})" >&2
+    echo "${APP}: run 'git submodule update --init --recursive' first" >&2
+    exit 1
+fi
+
+if ! command -v cargo > /dev/null; then
+    echo "${APP}: cargo not found (a Rust toolchain is required to build ssconverter-cli)" >&2
+    exit 1
+fi
+
+# Build ssconverter-cli
+echo "Building ssconverter-cli (debug)..."
+pushd "${SDK_CLI_DIR}" > /dev/null
+cargo build
+popd > /dev/null
+CONVERTER="${SDK_DIR}/target/debug/ssconverter-cli"
+
+# "<SDK tests subdir>|<examples subdir>" -- one entry per destination sample
+# project. Output goes to <examples subdir>/ssab_generated/<SDK tests subdir>/,
+# matching the layout the editor's source sync produces.
+DEPLOYMENTS=(
+    "overall|overall"
+    "overall|overall_gdextension"
+    "Ringo|Ringo"
+    "Ringo|Override_Ringo"
+    "Ringo|Scripting"
+)
+
+for ENTRY in "${DEPLOYMENTS[@]}"; do
+    TEST="${ENTRY%%|*}"
+    DEST="${ENTRY##*|}"
+    SSPJ_PATH="${SDK_TESTS_DIR}/${TEST}/${TEST}.sspj"
+    OUTPUT_DIR="${EXAMPLES_DIR}/${DEST}/ssab_generated/${TEST}"
+
+    if [ ! -f "${SSPJ_PATH}" ]; then
+        echo "${APP}: ${SSPJ_PATH} not found" >&2
+        exit 1
+    fi
+
+    echo "Updating SSAB for ${TEST} in ${OUTPUT_DIR}..."
+    mkdir -p "${OUTPUT_DIR}"
+    "${CONVERTER}" "${SSPJ_PATH}" -o "${OUTPUT_DIR}"
+done
+
+echo "Done!"