メインコンテンツまでスキップ

CLI クイックスタート

Resprite CLI は、保存済みの .resprite プロジェクトを単一 PNG、連番画像、グリッド形式のスプライトシートに書き出します。プロジェクト情報の取得、JSON 設定、バッチ書き出しにも対応し、素材の書き出しをビルドに組み込めます。

CLI は実験的な機能で、Resprite の macOS・Windows・Linux x86_64 パッケージに同梱されています。--version は CLI のバージョンを返します。アプリのバージョンは「About」で確認してください。

ターミナルのコマンドを設定する​

ヘルプ ▸ コマンドラインツール ▸ PATH に追加を選び、ターミナルアプリを閉じて開き直します。登録は現在のユーザーに適用され、その後はアプリのパスを指定せずに resprite-cli を実行できます。

  • macOS / Linux：Bash、Zsh、Fish の自動設定に対応しています。
  • Windows：既存の項目を残したまま、インストール先の cli をユーザー PATH に追加します。管理者権限は不要です。新しいターミナルにも古い PATH が残る場合は、サインアウトして再度サインインしてください。
  • Linux AppImage：登録したコマンドは元の AppImage を呼び出し、--cli を自動で付けます。AppImage は固定した場所に置いてください。

PATH を設定しない場合は、フルパスでの呼び出し例を使えます。

はじめての書き出しの準備​

  1. 自分のプロジェクトフォルダーに hero.resprite を保存します。
  2. PATH の設定後、そのフォルダーで新しいターミナルを開きます。ヘルプ ▸ コマンドラインツールから完全なコマンドをコピーすることもできます。
  3. 出力先の親フォルダーが存在し、初回は hero.png が存在しないことを確認して実行します。
resprite-cli export image "hero.resprite" --output "hero.png" --frame 0

この相対パスでは、元のプロジェクトと同じ場所に hero.png が作られます。PATH 未登録の場合は、下の OS 別フルパス例を使ってください。

CLI が読み取るのはディスクに保存済みの内容だけです。元のプロジェクトや、エディターのドキュメント・フレーム・選択範囲は変更しません。フレーム番号は 0 始まりです。どの OS でも利用可能なグラフィックス環境が必要ですが、実行中にエディターのウィンドウは表示されません。

OS 別のフルパス呼び出し​

パッケージには Apple Silicon（arm64）と Intel（x86_64）用が含まれます。個別の macOS バージョンやハードウェアとの互換性は、引き続き確認が必要です。GPU のない CI や非対話型のサービスセッションでは未検証です。

cli='/Applications/Resprite.app/Contents/MacOS/resprite-cli'
"$cli" export image "$HOME/Game Projects/hero.resprite" \
  --output "$HOME/Game Projects/hero.png" --frame 0

実行ファイルだけをコピーせず、.app 全体を保持してください。"$cli" --help で構文、"$cli" --version で CLI のバージョンを確認できます。

成功すると、元のプロジェクトと同じフォルダーに hero.png が生成されます。表示レイヤーを合成し、透明度を保持します。ターミナルには JSON 結果も出力されます。次回 PNG を置き換えるには、書き出しコマンドの末尾に --overwrite を追加します。アニメーションの出力フォルダーには別の上書き規則があります。

パスと以降の例について​

アプリの移動や名前変更後は、ヘルプ ▸ コマンドラインツール ▸ 登録を修復を使います。アンインストールや別のインストールへの切り替え前には登録を解除してください。登録は競合するコマンドや別の有効なインストールを上書きせず、解除はこの機能で追加した項目だけを削除します。手動で設定した PATH は引き続き自分で管理します。

プロジェクト、出力、自作スクリプトは自分のプロジェクトフォルダーに置いてください。インストール先の内容は更新時に置き換えられたり、アンインストールで削除されたりします。フルパスを使うスクリプトでは、アプリ移動後にパスを更新してください。

コマンドラインの相対パスはターミナルの現在のフォルダー、JSON 設定内の相対パスは設定ファイルのあるフォルダーを基準にします。空白を含むパスは引用符で囲みます。

以降のガイドの resprite-cli は、PATH 登録後にそのまま実行できます。フルパスの例で $cli を設定した場合は、次のように置き換えてください。

環境呼び出し方
macOS / Linux AppDir"$cli" ...
Windows PowerShell& $cli ...
Linux AppImage"$cli" --cli ...

ヘルプからは、同梱の OS 別・アニメーション・ビルド連携ガイドをオフラインで開くこともできます。フォルダーで表示から Markdown ファイルを探し、読むアプリを選べます。

トラブルシューティング​

画像が生成されない場合は終了コードと stderr を確認し、元のプロジェクトが保存済みか、出力先の親フォルダーが存在して書き込み可能か、必要な上書きを許可しているかを確認します。リンクされた出力先は拒否されます。ファイルの使用中や権限の制限でも失敗することがあります。結果と終了コードも参照してください。

1 回の呼び出しはバッチ内の全ジョブを含めて最大 120 秒です。タイムアウトや強制終了の後は、生成済みの出力を確認してから再試行してください。システムの一時フォルダーに resprite_cli_*、出力先の親フォルダーに .resprite_cli_* が残る場合があります。すべての CLI ジョブが停止するまで、ロックファイルの削除や関連フォルダーの整理をしないでください。

macOS が起動をブロックした場合は、システムのメッセージを保存してサポートに連絡してください。確認スクリプトで起動許可を付与したり、システムの制限を解除したりすることはできません。

macOS のインストールを確認する
/bin/bash '/Applications/Resprite.app/Contents/Helpers/RespriteCLI.app/Contents/Resources/verify_macos_installation.sh'

必要に応じてインストール先を置き換えます。スクリプトは macOS 標準ツールと同梱サンプルを使い、開発ツールの追加は不要です。インストールファイルや自分のプロジェクトは変更しません。report.txt のパスを表示し、サンプル出力と stdout/stderr を残すため、サポートへの診断情報として使えます。