CLI 画像とアニメーションの書き出し
保存済みの .resprite プロジェクトを、単一 PNG、PNG の連番画像、グリッド形式のスプライトシートに書き出します。アニメーションの出力には、画像と再生順を記述した manifest.json が含まれます。画像は元のキャンバスサイズ、透明背景、余白なし、1 倍で出力され、空白フレームも保持されます。
このページの resprite-cli は省略形です。クイックスタートで呼び出し方を設定し、macOS / Linux AppDir では "$cli"、Windows PowerShell では & $cli、Linux AppImage では "$cli" --cli に置き換えてください。ターミナルで、保存済みの hero.resprite があるフォルダーに移動してから実行します。CLI は独自のオプションを使い、エディターの書き出し設定は読み取りません。各例は別々の出力先を使います。初回は出力先が存在しない状態にし、親フォルダーは事前に作成してください。
単一フレームの書き出し
resprite-cli export image hero.resprite --output hero-still.png --frame 0
プロジェクトと同じフォルダーに hero-still.png が生成されます。表示レイヤーを合成し、透明度を保持します。フレーム番号は 0 始まりです。後でこの PNG を置き換えるには、同じコマンドに --overwrite を追加します。
連番画像の書き出し
resprite-cli export frames hero.resprite --output hero-frames
hero-frames/manifest.json にフレームと画像の対応が記録され、PNG はそのフォルダーの builds/ 以下に保存されます。各ソースフレームはレイヤーの書き出し単位ごとに 1 回だけ出力されます。逆再生や往復再生はマニフェストで表現し、PNG を複製しません。
グリッド形式のスプライトシートの書き出し
resprite-cli export sheet hero.resprite --output hero-sheet --columns 8
画像パスと各フレームの領域は hero-sheet/manifest.json から読み取ります。--columns は 1 行の列数を指定する正の整数で、既定値は 8 です。最終行の余った部分は透明になります。連番画像とは別の出力先なので、両方の例を試せます。
クリップの選択とレイヤー分割
resprite-cli inspect hero.resprite を実行し、結果の clips 配列から目的のクリップを探します。その id をコピーし、次の CLIP_ID を置き換えてください。
resprite-cli export sheet hero.resprite --output hero-clip --clip-id CLIP_ID --split-layers
--clip-idは 1 つのクリップを選択します。省略するとタイムライン全体を書き出します。inspectのclips[].idを使うため、同名のクリップも区別できます。指定した ID が見つからない場合は終了コード 2 になります。--split-layersはエディターのグループ分割規則に従って表示レイヤーを分割します。分割しない設定のグループは 1 つの書き出し単位となり、非表示レイヤーは含まれません。省略すると表示レイヤーをすべて合成します。--dry-runを追加すると、実際の分割単位と出力計画を確認できます。出力計画の確認と実行を参照してください。
出力した素材の読み込み
典型的な構成は次のとおりです。実際の画像名はマニフェストで確認します。
hero-sheet/
manifest.json
builds/
<buildId>/
sprite.png
プロセスが成功した後、manifest.json を一度読み、次の順でアニメーションを読み込みます。
animationsの項目と、その中のtracksの項目を 1 つ選びます。- そのトラックの
regionsのインデックス順に、最上位のregions配列から領域を取得します。 - 各領域の
imageインデックスでimagesの画像を取得し、pathをmanifest.jsonのあるフォルダーからの相対パスとして解決します。 - 画像内の
x/y/width/heightの矩形をdurationMsミリ秒表示し、次の領域に進みます。レイヤーを分割した場合、各トラックは 1 つの書き出し単位に対応します。
次はクリップのない単一フレームのプロジェクトからの抜粋です。読み取りの関係を示すため、バージョン・ソース・整合性フィールドを省略しています。<buildId> は実際に生成されるフォルダー名です。
{
"images": [
{"path": "builds/<buildId>/sprite.png", "width": 16, "height": 16}
],
"regions": [
{"image": 0, "layerUnit": 0, "sourceFrame": 0, "frameId": "frame-1",
"x": 0, "y": 0, "width": 16, "height": 16,
"durationUnits": 1000, "durationMs": 100}
],
"tracks": [{"layerUnit": 0, "layerIds": null, "regions": [0]}],
"animations": [
{"id": null, "name": "timeline", "direction": "Forward",
"tracks": [{"layerUnit": 0, "regions": [0]}]}
]
}
この例は 10 FPS です。領域 0 は画像 0 の左上から 16 × 16 ピクセルを取り出し、100 ミリ秒表示します。インデックスはすべて 0 始まり、座標の原点は画像の左上で、単位は出力ピクセルです。
animations[].tracks[].regions には正再生・逆再生・往復再生の順序が反映済みです。順に再生し、direction を再適用しないでください。durationMs は小数になる場合があります。フレームごとに丸めず、正確な時間を累積してずれを防ぎます。同じ領域を繰り返し参照する場合も、その領域の表示時間を使います。
更新と整理
初回の書き出しでは、出力フォルダーが存在せず、親フォルダーが存在する必要があります。元のプロジェクトは出力フォルダーの外に置いてください。上で生成したシートを更新するには、次を実行します。
resprite-cli export sheet hero.resprite --output hero-sheet --columns 8 --overwrite
--overwrite が更新できるのは、この CLI が作成し、マニフェストと現在の画像の整合性が保たれたフォルダーだけです。通常のフォルダーを置き換えたり、破損した出力を修復したりはできません。マニフェストには整合性情報が含まれ、手動編集には対応していません。変更は再度書き出して行います。
更新時は、古いマニフェストを読み取ったプログラムが読み込みを完了できるよう、古いビルドを保持します。古いビルドや中断後の残りは自動削除されないため、出力フォルダーの容量が増え続ける場合があります。画像は必ずマニフェストから読み込み、builds の走査やファイル名の推測はしないでください。
同じフォルダーへの同時書き出しはできません。output_busy / 終了コード 4 の場合は実行中のジョブが終わるまで待ちます。親フォルダーに残る .resprite_cli_lock_<digest> は正常なロックファイルで、存在するだけでは実行中とは限りません。すべての CLI ジョブが停止するまで、ロックファイルの削除や関連フォルダーの整理をしないでください。整理前には古いビルドを読み込むプログラムがないことも確認します。
タイムアウトや強制終了では、成功報告がなくても新しい素材が生成済みの場合があります。プロセスは失敗として扱い、マニフェストと素材を確認してから再試行を判断します。レンダリングの失敗によって古い素材がファイルごとに上書きされることはありませんが、停電からの復旧を保証するものではありません。