From a1fa0d2b09dbbed53a4a52e52dd401dcca154a34 Mon Sep 17 00:00:00 2001 From: Naruto TAKAHASHI Date: Sat, 1 Aug 2026 13:01:39 +0900 Subject: [PATCH] chore: move the example ssab deploy script to scripts/deploy-examples Renames examples/update_ssabs.{sh,ps1} to scripts/deploy-examples.{sh,ps1}, matching the sibling players and this repository's own kebab-case scripts/ layout. Nothing referenced the old path. - Fail fast: set -euo pipefail on the shell side, $ErrorActionPreference and $LASTEXITCODE checks on the PowerShell side (native commands do not stop on their own). - Preflight the SDK submodule, cargo and the source .sspj with actionable messages instead of failing deep inside cargo. - Replace the per-project if branches with a flat deployment table. - Document it under "For SpriteStudio-SDK Developers" (en/ja) and add a row to the AGENTS.md verification table. --- AGENTS.md | 1 + docs/en/setup/build.md | 18 +++++++++ docs/ja/setup/build.md | 18 +++++++++ examples/update_ssabs.ps1 | 47 ----------------------- examples/update_ssabs.sh | 54 --------------------------- scripts/deploy-examples.ps1 | 74 +++++++++++++++++++++++++++++++++++++ scripts/deploy-examples.sh | 74 +++++++++++++++++++++++++++++++++++++ 7 files changed, 185 insertions(+), 101 deletions(-) delete mode 100644 examples/update_ssabs.ps1 delete mode 100755 examples/update_ssabs.sh create mode 100644 scripts/deploy-examples.ps1 create mode 100755 scripts/deploy-examples.sh diff --git a/AGENTS.md b/AGENTS.md index 90028e1..620ae84 100644 --- a/AGENTS.md +++ b/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.* diff --git a/docs/en/setup/build.md b/docs/en/setup/build.md index 7139222..fe4da55 100644 --- a/docs/en/setup/build.md +++ b/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: diff --git a/docs/ja/setup/build.md b/docs/ja/setup/build.md index 42eb840..5203d2c 100644 --- a/docs/ja/setup/build.md +++ b/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 内部ドキュメント サブモジュール初期化済みであれば、ランタイムの内部仕様や移植時の注意点は以下を参照できます。 diff --git a/examples/update_ssabs.ps1 b/examples/update_ssabs.ps1 deleted file mode 100644 index c826696..0000000 --- a/examples/update_ssabs.ps1 +++ /dev/null @@ -1,47 +0,0 @@ -# Base directories -$SDK_DIR = Resolve-Path (Join-Path $PSScriptRoot "../ss_player/SpriteStudio-SDK") -$SDK_TESTS_DIR = Join-Path $SDK_DIR "tests" -$SDK_CLI_DIR = Join-Path $SDK_DIR "cli" -$EXAMPLES_DIR = $PSScriptRoot - -# Build ssconverter-cli -Write-Host "Building ssconverter-cli (debug)..." -Push-Location $SDK_CLI_DIR -cargo build -$CONVERTER = Join-Path $SDK_DIR "target/debug/ssconverter-cli.exe" -Pop-Location - -# List of tests to update SSABs -$TESTS = @("overall", "Ringo") - -foreach ($TEST in $TESTS) { - $SSPJ_PATH = Join-Path $SDK_TESTS_DIR "$TEST/$TEST.sspj" - - # Standard project - $OUTPUT_DIR = Join-Path $EXAMPLES_DIR "$TEST/ssab_generated/$TEST" - Write-Host "Updating SSAB for $TEST in $OUTPUT_DIR..." - if (!(Test-Path $OUTPUT_DIR)) { New-Item -ItemType Directory -Path $OUTPUT_DIR } - & $CONVERTER "$SSPJ_PATH" -o "$OUTPUT_DIR" - - # overall project special handling for overall_gdextension - if ($TEST -eq "overall") { - $GD_OUTPUT_DIR = Join-Path $EXAMPLES_DIR "overall_gdextension/ssab_generated/overall" - Write-Host "Updating SSAB for $TEST in $GD_OUTPUT_DIR..." - if (!(Test-Path $GD_OUTPUT_DIR)) { New-Item -ItemType Directory -Path $GD_OUTPUT_DIR } - & $CONVERTER "$SSPJ_PATH" -o "$GD_OUTPUT_DIR" - } - - # Ringo is also converted into the Override_Ringo and Scripting demo projects - if ($TEST -eq "Ringo") { - $OR_OUTPUT_DIR = Join-Path $EXAMPLES_DIR "Override_Ringo/ssab_generated/Ringo" - Write-Host "Updating SSAB for $TEST in $OR_OUTPUT_DIR..." - if (!(Test-Path $OR_OUTPUT_DIR)) { New-Item -ItemType Directory -Path $OR_OUTPUT_DIR } - & $CONVERTER "$SSPJ_PATH" -o "$OR_OUTPUT_DIR" - - $SCR_OUTPUT_DIR = Join-Path $EXAMPLES_DIR "Scripting/ssab_generated/Ringo" - Write-Host "Updating SSAB for $TEST in $SCR_OUTPUT_DIR..." - if (!(Test-Path $SCR_OUTPUT_DIR)) { New-Item -ItemType Directory -Path $SCR_OUTPUT_DIR } - & $CONVERTER "$SSPJ_PATH" -o "$SCR_OUTPUT_DIR" - } -} -Write-Host "Done!" diff --git a/examples/update_ssabs.sh b/examples/update_ssabs.sh deleted file mode 100755 index 078d5e5..0000000 --- a/examples/update_ssabs.sh +++ /dev/null @@ -1,54 +0,0 @@ -#!/bin/bash -set -e - -# Base directories -# Script location is assumed to be in the 'examples' directory -SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" -SDK_DIR="${SCRIPT_DIR}/../ss_player/SpriteStudio-SDK" -SDK_TESTS_DIR="${SDK_DIR}/tests" -SDK_CLI_DIR="${SDK_DIR}/cli" -EXAMPLES_DIR="${SCRIPT_DIR}" - -# Build ssconverter-cli -echo "Building ssconverter-cli (debug)..." -cd "${SDK_CLI_DIR}" -cargo build -CONVERTER="${SDK_DIR}/target/debug/ssconverter-cli" -cd "${EXAMPLES_DIR}" - -# List of tests to update SSABs -# Note: overall is also converted into overall_gdextension -TESTS=("overall" "Ringo") - -for TEST in "${TESTS[@]}"; do - SSPJ_PATH="${SDK_TESTS_DIR}/${TEST}/${TEST}.sspj" - - # Standard project - OUTPUT_DIR="${EXAMPLES_DIR}/${TEST}/ssab_generated/${TEST}" - echo "Updating SSAB for ${TEST} in ${OUTPUT_DIR}..." - mkdir -p "${OUTPUT_DIR}" - "${CONVERTER}" "${SSPJ_PATH}" -o "${OUTPUT_DIR}" - - # overall project special handling for overall_gdextension - if [ "${TEST}" == "overall" ]; then - GD_OUTPUT_DIR="${EXAMPLES_DIR}/overall_gdextension/ssab_generated/overall" - echo "Updating SSAB for ${TEST} in ${GD_OUTPUT_DIR}..." - mkdir -p "${GD_OUTPUT_DIR}" - "${CONVERTER}" "${SSPJ_PATH}" -o "${GD_OUTPUT_DIR}" - fi - - # Ringo is also converted into the Override_Ringo and Scripting demo projects - if [ "${TEST}" == "Ringo" ]; then - OR_OUTPUT_DIR="${EXAMPLES_DIR}/Override_Ringo/ssab_generated/Ringo" - echo "Updating SSAB for ${TEST} in ${OR_OUTPUT_DIR}..." - mkdir -p "${OR_OUTPUT_DIR}" - "${CONVERTER}" "${SSPJ_PATH}" -o "${OR_OUTPUT_DIR}" - - SCR_OUTPUT_DIR="${EXAMPLES_DIR}/Scripting/ssab_generated/Ringo" - echo "Updating SSAB for ${TEST} in ${SCR_OUTPUT_DIR}..." - mkdir -p "${SCR_OUTPUT_DIR}" - "${CONVERTER}" "${SSPJ_PATH}" -o "${SCR_OUTPUT_DIR}" - fi -done - -echo "Done!" diff --git a/scripts/deploy-examples.ps1 b/scripts/deploy-examples.ps1 new file mode 100644 index 0000000..0c84a2f --- /dev/null +++ b/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" + +# "|" -- one entry per destination sample +# project. Output goes to /ssab_generated//, +# 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!" diff --git a/scripts/deploy-examples.sh b/scripts/deploy-examples.sh new file mode 100755 index 0000000..adb861a --- /dev/null +++ b/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" + +# "|" -- one entry per destination sample +# project. Output goes to /ssab_generated//, +# 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!"