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

CLI 設定とバッチ書き出し

JSON 設定を使うと、同じ書き出しを繰り返したり、複数のプロジェクトをビルドに組み込んだりできます。このページの resprite-cli は省略形です。クイックスタートで呼び出し方を設定し、macOS / Linux AppDir では "$cli"、Windows PowerShell では & $cli、Linux AppImage では "$cli" --cli に置き換えてください。

設定ファイルの作成​

次を build.json として、保存済みの hero.resprite、enemy.resprite と同じフォルダーに保存します。プロジェクト名は必要に応じて置き換え、不要なジョブは jobs から削除してください。初回は 3 つの出力先が存在しない状態で実行します。

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "batch-hero.png", "frame": 0},
    {"mode": "frames", "source": "hero.resprite", "output": "batch-hero-frames"},
    {"mode": "sheet", "source": "enemy.resprite", "output": "batch-enemy-sheet", "columns": 8, "splitLayers": true}
  ]
}

設定内の相対パスは設定ファイルのあるフォルダーが基準で、ターミナルの現在のフォルダーには依存しません。コマンドラインに直接指定する相対パスは、ターミナルの現在のフォルダーが基準です。出力先の親フォルダーは事前に作成します。

出力計画の確認と実行​

ターミナルで build.json のあるフォルダーに移動し、設定と出力計画を確認してから書き出します。

resprite-cli batch --config build.json --dry-run
resprite-cli batch --config build.json

dry-run が成功しても出力は生成されません。実際の書き出しが成功すると、batch-hero.png、batch-hero-frames/manifest.json、batch-enemy-sheet/manifest.json が生成されます。後の 2 つは各マニフェストから画像パスを取得します。出力した素材の読み込みを参照してください。

再実行する前に、置き換えたい出力のジョブへ "overwrite": true を追加します。image モードは PNG を置き換えます。連番画像とシートは、この CLI が作成した正常な素材フォルダーだけを更新できます。上書き規則を確認してください。dry-run でも既存の出力先には明示的な上書き許可が必要です。

設定を 1 ジョブだけで使う場合は、次を別の one-job.json としてプロジェクトの隣に保存します。

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "hero-single.png", "frame": 0}
  ]
}
resprite-cli export --config one-job.json --dry-run
resprite-cli export --config one-job.json

export --config は 1 ジョブだけを受け付けます。複数ジョブには batch を使ってください。設定ファイルを使う呼び出しに追加できるのは --dry-run だけです。他のオプションは JSON を編集し、コマンドラインでは上書きしません。

dry-run はプロジェクトを読み、引数、出力サイズの上限、パス、既存の出力先を確認します。PNG の描画や出力・出力ロックの作成は行いませんが、クイックスタートに記載した実行環境は必要です。dry-run の成功は、本実行時の書き込み権限、空き容量、レンダラーの動作を保証しません。 後から別のプロセスが出力先を使用する場合もあるため、本実行時に再確認します。

結果とエラーの処理​

プロセス API から呼ぶ場合は、実行ファイルのパスと引数配列を別々に渡します。 AppImage の CLI 引数配列は --cli で始めます。stdout は UTF-8 です。情報取得、書き出し、dry-run、正常に完了したバッチは 1 つの JSON オブジェクトを返し、--help と --version はテキストを返します。診断は stderr に出力され、エンジンのログが混ざる場合があります。JSON を解析する前に両ストリームを結合せず、stderr が空であることを成功条件にしないでください。

全終了コードと出力フィールドは結果と終了コードのリファレンスを参照してください。

単一ジョブの失敗やバッチ開始前のエラーでは stdout は空になり、stderr にエラーが出ます。バッチ開始前には全出力先を確認します。重複や包含関係、元のプロジェクトや設定ファイルの上書き・包含は禁止され、リンクや大文字・小文字違いの別名も確認します。この事前確認に失敗すると、どのジョブも実行しません。

確認後は設定順に 1 件ずつ実行します。引数、入力、出力、レンダリングのエラーはジョブごとに記録し、後続のジョブを続行します。内部エラーは直ちに中断します。成功したジョブの出力は保持され、バッチ全体のロールバックは行いません。

正常に終了したバッチは必ず JSON の集計結果を返します。全件成功は終了コード 0、1 件でも失敗した場合は全件失敗を含めて 6 です。次は単一画像の 2 ジョブのうち、2 件目が失敗した結果の抜粋です。バージョン、パス、成功項目の画像サイズを省略しています。

{
  "action": "batch",
  "dryRun": false,
  "status": "error",
  "succeeded": 1,
  "failed": 1,
  "results": [
    {"index": 0, "exitCode": 0, "status": "ok"},
    {"index": 1, "exitCode": 4, "status": "error",
     "mode": "image", "code": "output_exists", "message": "Output exists; use --overwrite to replace it."}
  ]
}

index は 0 始まりで jobs の順序に対応します。終了コード 6 の詳細は stdout の集計に含まれるため、stderr だけでは確認できません。

1 回の呼び出しはバッチ内の全ジョブを含めて最大 120 秒です。タイムアウトや強制終了では、一部の出力が完成していても最終集計がない場合があります。プロセスは失敗として扱い、出力を確認してから、置き換えが必要なものに上書き許可を付けて再試行します。大きなジョブ集合は複数のバッチに分けてください。