CLI コマンドと形式のリファレンス
CLI の構文、JSON フィールド、制限を調べるためのページです。実行パスと対象バージョンはクイックスタートを参照してください。次の構文では resprite-cli を省略形として使います。山括弧は置き換える値、角括弧は省略可能な引数を示します。括弧そのものは入力しません。
コマンド構文
resprite-cli --help
resprite-cli --version
resprite-cli inspect <file.resprite>
resprite-cli export image <file.resprite> --output <file.png> [--frame N] [--overwrite] [--dry-run]
resprite-cli export frames <file.resprite> --output <directory> [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export sheet <file.resprite> --output <directory> [--columns N] [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export --config <file.json> [--dry-run]
resprite-cli batch --config <file.json> [--dry-run]
コマンドオプション
| オプション | 意味と既定値 |
|---|---|
--output PATH | 直接書き出す場合に必須の出力先。親フォルダーが必要 |
--frame N | image のみ。0 始まりの非負整数、既定値は 0 |
--columns N | sheet のみ。正の整数、既定値は 8 |
--clip-id ID | frames / sheet のみ。inspect で取得したクリップ先頭フレームの ID。省略時はタイムライン全体 |
--split-layers | frames / sheet のみ。エディターのグループ規則に従って表示レイヤーを分割。省略時は合成 |
--overwrite | 上書きを許可。省略時は既存の出力を拒否。アニメーションの出力先は正常な CLI 生成物に限る |
--dry-run | 出力を公開せず検証と計画の取得を行う。直接書き出し、設定による書き出し、バッチで利用可能 |
--config PATH | schema 1 の JSON を読む。export は 1 ジョブ、batch は 1–100 ジョブ |
--help / --version | コマンドヘルプ / CLI 実装のバージョンをテキストで返す |
不明、重複、またはそのモードで使えないオプションは拒否されます。--config と併用できる追加オプションは --dry-run だけです。書き出し設定の変更は JSON で行います。コマンドラインの相対パスは現在の作業フォルダーが基準です。空白を含むパスは引用符で囲んでください。dry-run でも、既存の出力には明示的な上書き許可が必要です。
設定形式
ルートオブジェクトには schemaVersion と jobs だけを指定し、バージョンは整数の 1 にします。不明なフィールド、型違い、選択したモードで使えないオプションは拒否されます。文字列は真偽値や数値へ暗黙に変換されません。設定ファイルはスクリプトの実行、ワイルドカードの展開、エディター設定の読み取りを行いません。
| ジョブのフィールド | 対象と既定値 |
|---|---|
mode、source、output | 必須の空でない文字列。mode は image / frames / sheet、入力は .resprite |
overwrite | 全モード。真偽値、既定値は false |
frame | image。0 始まりの非負整数、既定値は 0。出力の拡張子は .png |
columns | sheet。正の整数、既定値は 8 |
clipId | frames / sheet。inspect の clips[].id から取得する空でない文字列 |
splitLayers | frames / sheet。真偽値、既定値は false |
完全な設定例は設定とバッチ書き出しにあります。JSON の相対パスは設定ファイルのあるフォルダーが基準です。
プロジェクト情報の取得
フレームやレイヤーの確認、クリップ ID の取得には次を実行します。
resprite-cli inspect hero.resprite
プロジェクトの構造を JSON で返し、ソースの変更や出力の作成は行いません。プロジェクトの画像は読み込むため、利用可能なグラフィックス環境が必要です。画像の欠落やドキュメントの破損は入力エラーになります。
次は clips の 1 項目の例です。id を --clip-id に渡すとそのクリップを選択できます。同名のクリップも ID で区別します。
{
"id": "frame-walk-start",
"name": "Walk",
"firstFrame": 0,
"lastFrame": 1,
"direction": "Forward",
"playbackFrames": [0, 1]
}
結果と終了コード
プロセス API では実行ファイルのパスと引数配列を別々に渡します。stdout は UTF-8 です。情報取得、書き出し、dry-run、正常に完了したバッチは 1 つの JSON オブジェクトを返し、--help と --version はテキストを返します。診断は stderr に出力され、エンジンのログが混ざる場合があります。JSON 解析前にストリームを結合せず、stderr が空であることを成功条件にしないでください。
| 終了コード | 意味と対処 |
|---|---|
| 0 | 成功。stdout の結果を読む |
| 2 | 引数、設定、出力計画のエラー。オプションを修正する |
| 3 | 入力ファイルまたはドキュメントのエラー。ソースと設定ファイルを確認する |
| 4 | 出力パス、上書き、使用中、書き込みのエラー。出力先と権限を確認する |
| 5 | レンダリングまたはエンコードの失敗。stderr を保存する |
| 6 | バッチ内に失敗したジョブがある。stdout の各項目を読む |
| 70 | 内部エラー、起動失敗、タイムアウト。診断を保存し、生成済みの出力を確認する |
単一ジョブの失敗やバッチ開始前のエラーでは stdout は空です。正常に完了したバッチは終了コード 6 でも集計を返します。内部エラーは直ちに中断し、タイムアウトや強制終了では出力があっても最終報告がない場合があります。バッチ失敗時の処理を参照してください。
すべての成功結果には schemaVersion: 1、status: ok、cliVersion が含まれます。バッチ集計もこれらのフィールドを持ちますが、失敗項目がある場合の status は error です。
| 結果の種類 | 主なフィールド |
|---|---|
| 単一画像 | 絶対パスの source と output、frame、width、height |
| アニメーション | source、output、mode、manifest、imageCount、regionCount |
| 情報取得 | action: inspect、絶対パスの source、sourceSha256、canvas、frameRate、durationScale、frames、layers、clips、limits |
| 単一画像の dry-run | action: plan、dryRun: true、mode: image、ソースと出力先、フレーム番号、サイズ、ソースのダイジェスト、totalPixels、出力先の files |
| アニメーションの dry-run | action: plan、dryRun: true、ソースと出力先、mode、manifest の出力先、画像数・領域数、totalPixels、warnings、imagePathPattern、plan |
| バッチ集計 | action: batch、dryRun、succeeded、failed、results。各項目には index、exitCode と、書き出し・dry-run の結果または失敗情報 |
inspect の frames は index、安定した id、durationUnits、durationMs を返します。layers は元の順序の index、id、name、parentId、kind、自身の visible / opacity、親グループの影響を含む renderVisible、グループを 1 単位として書き出す splitAsUnit を返します。clips は上の例のフィールドを持ち、playbackFrames には再生方向が反映済みです。表示時間はアニメーションマニフェストの規則に従います。
sourceSha256 は実際に読み取ったソースの内容のダイジェストです。アニメーションの dry-run では plan.source.sha256 に格納されます。plan は画像サイズ、領域、トラック、アニメーションを含み、実際の分割単位は plan.tracks で確認できます。公開される画像パスは builds/<buildId>/<image.path> です。dry-run は画像を描画しないため、画像の SHA-256 や buildId は返しません。plan を公開済みのマニフェストとして使わないでください。
アニメーションマニフェスト
manifest.json の schemaVersion は 1 です。
| フィールド | 意味 |
|---|---|
schemaVersion / cliVersion / mode | マニフェスト形式のバージョン、CLI のバージョン、書き出しモード（frames / sheet） |
kind / buildId | 固定識別子 resprite-animation-export とビルド内容のダイジェスト。元の値を保持する |
source | 元のプロジェクトのファイル名 name と実際に読んだ内容の sha256。絶対パスは含まない |
canvas / frameRate / durationScale | 元のキャンバスサイズ、FPS、表示時間の倍率スケール（1000） |
images | マニフェストのフォルダーからの相対 path（区切りは /）、サイズ、sha256 |
regions | 画像インデックス、レイヤー単位、ソースフレーム番号、安定したフレーム ID、矩形座標とサイズ、durationUnits、durationMs |
tracks | レイヤー単位とソースフレーム順の領域インデックス。layerIds: null は表示レイヤー全体の合成、配列はその単位に含まれるレイヤー ID |
animations | クリップ ID、元の名前、方向、各トラックの再生領域インデックス。クリップがない場合は id: null、名前 timeline のアニメーション |
クリップ ID は先頭フレームの ID で、--clip-id に使用できます。自動生成の timeline には選択可能なクリップ ID がありません。クリップに属さないフレームも最上位の tracks に残ります。
正確な表示時間は durationUnits × 1000 / (durationScale × frameRate) ミリ秒で、現在は durationUnits / frameRate に相当します。OS 間で PNG のバイト列のダイジェストが一致する保証はありません。
読み込み手順と説明付きの抜粋は出力した素材の読み込みを参照してください。マニフェストには整合性情報が含まれるため、手動で編集しないでください。
制限
| 項目 | 現在の制限 |
|---|---|
| 入力 | 保存済みの .resprite のみ。未保存の編集は読み取らない |
| 設定 | 最大 1 MiB、1–100 ジョブ |
| 出力サイズ | 各画像の各辺は最大 16,384 ピクセル、1 ジョブの合計は最大 16,777,216 出力ピクセル。単一画像も対象 |
| 出力数 | 1 ジョブあたり最大 100,000 画像 |
| 実行時間 | バッチ全体を含め、1 回の呼び出しは最大 120 秒 |
出力上限を超えると、描画前に終了コード 2 で失敗します。情報取得は出力ピクセルの上限の対象外です。トリミング、拡大縮小、任意のフレーム範囲、名前によるレイヤー選択、密に配置するアトラス、差分ビルド、watch モードには対応していません。古いビルドは自動削除されません。更新と整理も確認してください。