scenario-sprite-animation

シナリオスプライトアニメーション

概要

汎用画像モデルに「スプライトシート、歩行サイクル、8フレーム」というプロンプトをそのまま入力すると、1枚の画像が返ってきます。一方、指示への忠実度が高い画像モデルにグリッド仕様を記述すると、シートが返ってきます（下の単一シートの行）。フレームシーケンスの生成には、スプライトのサイズだけでなく、タスクに必要な制御に応じて選んだルートを使用します。詳細は関連スキルを参照してください。scenario-video（動画モデルの系統）、scenario-consistency と scenario-model-training（一連のアクションを通じた同一キャラクター）、scenario-game-assets（静止画、ピクセルの補正、アップスケーリング。セルに1キャラクターのフレームを並べたシートはここで扱います）、scenario-refine-loop（要件を満たすまで反復）。接続とコアループについては、scenario スキルを参照してください。ここで名前を挙げた関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。ユーザーが不在の場合は、ツールのスキーマに基づいて進め、不足していることを明示してください。

クイックリファレンス

必要なもの	ルート
ピクセルアートのサイクルやVFX、スタイルを固定したキャンバス	専用にトレーニングされたアニメーションモデル（ユーザー自身の言葉でスプライトアニメーションの要件を伝えて recommend を実行し、非推奨ではない候補を選択）：GIFプレビュー、同じシードでスプライトシートを再実行、スライス
正確なグリッド、指定したフレーム数、スクリプト化されたビート	高い指示追従性を備えた汎用画像モデル（ユーザー自身の言葉でグリッド仕様を伝えて recommend を実行し、専用モデルの候補に対して ask_user が提示されることを想定）：model_run を1回実行、スライス、タイルごとにスナップ、組み立て
静止画からシームレスなループを作成	最初と最後のフレームを指定できる動画モデル（ループの要件を指定して recommend を実行）：両端に同じ平坦化済み静止画を配置し、動きを明示したプロンプトを使用、抽出、継ぎ目を確認
指定した時点のポーズ	キーフレーム動画モデル（キーフレームを固定する要件を指定して recommend を実行）：ポーズの静止画をフレームインデックスまたはタイムスタンプに割り当て、抽出
このスプライトを大きく、またはスタイルを変えてアニメーション化	平坦化済み静止画を使った画像から動画への生成。スプライトアニメーションのスタイルに基づき、動きのビートをスクリプト化したプロンプトを使用。scenario-video に従ってモデルを選択
1つのキャラクターで一連のアクションを作成	scenario-consistency に従ってターンアラウンドを作成し、参照画像から動画を生成。各アクションで参照画像と設定を再利用
1つのキャラクター、複数の向き、サイクル一式、1枚のシート	ユーザーのアートからポーズシートまたはターンアラウンドを作成し、向きとサイクルごとに最初と最後のフレームを指定した画像から動画へのクリップを1つずつ生成。付属のサイクルスクリプトでローカルに仕上げます（方向別サイクル）
フレームをシートに、シートをフレームに	model_run 経由のツールモデル：model_scenario-video-to-image-seq、model_scenario-grid-maker、model_scenario-image-slicer、model_scenario-image-seq-to-video（固定されたファーストパーティ ID：各ツールは Scenario の各ステップに対応する唯一の決定論的ツールです）

スキーマは契約です。選んだモデルの model_schema_get で確認してください。毎回のセッションで生成メンバーを再検出し、ハードコードしないでください（上記のツール ID は固定です）。各レーンのスキーマに関する注意事項では、ピクセルレーンの Retro Diffusion のキャンバス固定と returnSpritesheet のシードの組み合わせ、単一シートのスキーマ構造と料金、動画レーンの制御項目、アルファのルート、非推奨タグの読み方を説明しています：references/lane-schemas.md。 単一シートレーンでは、ピクセルレーンのネイティブピクセル、固定キャンバス、シードのペアリングの代わりに、指定どおりのグリッドを使用します。ピクセル風の見た目はエミュレートされるため、スナップ処理もこのレーンの一部です。 無人で実行する場合、タスクでは表の最初の2行から選択します。ブリーフに正確なグリッド、フレーム数、またはスクリプト化された動きが指定されていれば、specialty.model_idよりも、ランキングが最上位の汎用モデルが優先されます。when_general_betterには、まさにそうした要件が記載されています。仕様は、それを読み込むパイプライン向けに記述してください。スライサーの6x6以内の行数と列数（16フレームは4x4とし、2 by 8にはしません。これはローカルでの切り出しです）、グリッドで均等に割り切れるキャンバス、1つのスケール、カメラ、向き、地面の基準線、フレームごとの動きの範囲（最後のフレームは最初のフレームと一致）、ゆとりのある余白、ラベルなし、を指定します。GIFの作成に関する指示は含めないでください。画像モデルが返すのは静止画であり、ホールドとは、追加フレームでも同じポーズを維持することです。background列挙型では色を指定できないため、単色の背景はプロンプトの文言で指定します。既存のキャラクターは参照画像フィールドに渡します。seedがない場合、再実行すると別のキャラクターになるため、候補はサンプル数パラメーターで生成し、1枚のシートをスライス前に承認します。スライスする前に、納品されたシートを確認してください。セルの数、セルの端、異なるポーズの数を数えます。動きの範囲で終了状態を1つだけ指定すると、同じポーズを保持したフレームが返ることがあるためです。その後、スライスし、手順5に従って各ステップのタイル間の継ぎ目を確認し、タイル間で体の位置をそろえ、保持するすべてのタイルを同じ色数とシードでスナップし、スナップ後のタイルのサイズがすべて同じことを確認して、組み立てます。位置合わせはプロンプトではなく後処理です。行をまたいで体の位置がずれます（ある実行では、接地した足が最後の行で最初の行より87 px高くなっており、位置固定を指示する文言も、参照画像として渡したレイアウトテンプレートも、ずれを解消できませんでした）。各タイルの体のバウンディングボックスを測定し、何も切れないように広めのキャンバス上で同じ基準線と水平中央に合わせてから、配置し直したシートをupload_assetでアップロードし、スライスしてください。ローカルで編集したフレームはアセットにならないためです。

再利用可能なレイアウトについては、グリッドマニフェストと テンプレート使用ガイドを参照してください。アップロード済みアセットの解決と新しいバージョンの公開には、scenarioスキルの共有アセットのライフサイクルを使用します。アクセスできるものがない場合、メンテナーまたはローカルジオメトリを必要とするエージェントが実行するグリッドビルダーで、MCPにアップロードする選択済みプリセットを作成します。アニメーションは生成しません。どのプリセットよりも、ユーザーが指定したフレーム数とキャンバスを優先してください。テンプレートを使っても、上記の位置合わせ、端、ループの確認は省略できません。

複数の向き（アイソメトリックの斜め、横向き、またはトップダウン）で、歩行、走行、待機、攻撃の行を備えたキャラクターについては、方向別サイクルレーンに従ってください。ユーザー自身のアート、キー色の確認、反転と武器を持つ手、エンジンへのインポートを扱います。エージェントが実行する3つのスクリプトは、MCPの手順をレーン内に保ち、ローカルのジオメトリ処理のみを行います。cycle_prompts.pyは、検出したスキーマに対応付ける、モデルに依存しないリクエストを作成します。cycle_frames.pyは、どのようなアートからでも最初のフレームを作成します。cycle_sheets.pyは、キャラクターのクリップにキー処理、ループ検索、登録、ピクセル化を行ってシートにまとめます。作成したシートはupload_assetでアップロードします。 フレームのパイプラインは、個別の MCP ツールではなく、model_run で実行するツールモデルです。動画から画像シーケンスを抽出するツール（extractAllFrames、または frameInterval を指定して N フレームごとに抽出します。フレームの順序は前提とせず、以下のとおり必ず確認します）、グリッド作成ツール（images は最大 100 枚で、入力順を維持します。columns のデフォルトは 3、未指定時の rows は枚数から計算されます。そのため、2 行 8 列で受け取った場合、完成したフレームは columns: 8 です。backgroundColor には 16 進文字列、transparent、black、white を指定できます）、グリッド分割ツール（image に加え、xSubdivisions と ySubdivisions を指定します。それぞれ 1〜6 で、省略時のデフォルトは 2 なので、上限は 6×6 です。出力サイズのパラメーターはありません。タイルは行優先順で返されますが、セルと同じサイズとは限らないため、asset_get で 1 枚確認してください。タイルがリサイズされている場合や、シートが 6×6 を超える場合は、数えたグリッドに沿ってシートをローカルで切り分けます）、シーケンスから動画を組み立てるツール（model_scenario-image-seq-to-video。名前として記載できる程度に安定したファーストパーティの ID です。fps は 1〜120、loopCount、pingpong、outputFormat には gif または mp4 を指定します）、ピクセルスナップツール（アートのグリッドを再検出し、指定した色数に量子化します。クリーンアップ処理で使える唯一のパレット制御です。タイルごとに課金されるため、セット全体の前に 1 枚試してください）です。GIF のフレーム遅延は 10 ms 単位に量子化されるため、100 を割り切れる fps（10、20、25）を組み立てツールに指定してください（8 fps では 125 ms、12 fps では 83 ms となり、どちらも単位に合いません）。そうしないと、継続時間を保つためにタイミングが再調整され、フレームが複製されます。生成後にタイミングを調整する手段は fps だけなので、フレーム数を事前に計画し、返されたフレーム数を数えてください。差分計算、継ぎ目の計算、エッジの読み取り、ウィンドウ検索などの分析はローカルで問題ありません。これらにはディスク上のピクセルデータが必要です。

フレームの順序は前提とせず、必ず確認してください。抽出されたフレームはすべて同じ createdAt を持ち、metadata にインデックスがないため、順序を示す情報はジョブ行の assetIds にしかありませんが、このリストは時間順でない状態で返されることがあります（執筆時点で確認済みの不具合です）。ストライド計算、分割、組み立てを行う前に、返された順序のまま ID をグリッド作成ツールに渡し、コンタクトシートをクリップの無料の firstFrame と lastFrame（asset_get）、および動きと照らし合わせてください。連続性を損なうフレームは順序が誤っています。以降は、修正した順序を独自の ID リストとして保持してください。リスト表示、タイムスタンプ、search から順序を再構築してはいけません。

例：静止画からシームレスなアイドルループを作成する

1. まず専用のコレクションを作成し（collection_create、ツールカタログ）、保持する各出力ができ次第、collection_add_assets（collection_id、asset_ids）で追加します。まだスチルがない場合は、最初に1枚生成して承認を得ます。スチルは後続のすべての工程の基準となるため、アニメーション化する前に、被写体にとって重要なディテールがブリーフに沿っているか確認し、ループとは別枠で予算を確保します（references/lane-schemas.md）。キャラクターを単色の背景に配置し（ローカルで編集しても構いません。参照画像と同様に、動画入力では透明度が失われる前提で進めます）、upload_assetでアップロードします。レーンと予算をユーザーに確認してください。無人で進める場合はタスクの指示に従い、指示がなければ要件に合う最安のレーンを選び、課金対象の実行前には毎回dry_runを行います。
2. ユーザー自身の言葉でループ要件を指定してrecommendを実行し、非推奨ではない候補を優先してからmodel_schema_getを実行します。使用するパラメーターはスキーマで決まります。durationとfpsの列挙値、staticなどのカメラ固定設定、音声の切り替え、対応している場合はネイティブのループフラグが含まれます。ネイティブのループフラグを使う場合、終了フレームのアンカーは置き換えられます。両方を同時に送信しないでください（dry_runでは受け付けられても、実行時に失敗する組み合わせがあります）。
3. 最初と最後のフレームに同じスチルを指定し、動きを明示したプロンプト（「重心を移し、マントが揺れる。キャラクターはその場にとどまる」など）を添えてmodel_runを実行します。ジョブの実行中は、pending_job_idsを指定してjobs_waitを再度呼び出します。
4. スプライトにアルファチャンネルが必要な場合、動画レーンからは出力されない前提で、背景除去の工程分の予算を確保します。まとめて処理する前に、ダウンロードした1フレームでアルファが保持されていることを確認してください。インライン表示ではアルファが合成で失われます。また、透明を指定してもアルファチャンネルのないコンテナーで返されることがあります（references/lane-schemas.md）。動画から画像シーケンスへのツールでフレームを抽出し、まずフレーム順を確認します（上記参照）。ストライドを計算する前に、実際に何が出力されたかを確認してください（リクエストが常に守られるとは限りません）。asset_getはproperties.duration、frameRate、nbFrames、width、heightを返します。計算に必要な出力済みフレーム数はnbFramesなので、これらを読み取り、レコードの残りの項目には手を加えないでください。作成時点で抽出ツールが公開していたのはextractAllFramesとframeIntervalだけです。model_schema_getで再確認してください。開始オフセット、終了位置、範囲を指定する機能はありません。不均一な選択（トリミングした区間、オフセットからのストライド、手動で選んだ部分集合）を行う場合は、extractAllFrames: trueで抽出してからアセットIDで絞り込みます。frameIntervalで指定できない区間があっても、それを理由にプラットフォームを離れる必要はありません。フレーム数の計算：抽出フレーム数 ＝ 出力済みフレーム数 ÷ frameInterval。両端のフレームを含みます。スキーマでfpsを指定できる場合は、スプライトのフレームレート（8〜12 fps。通常、1サイクルは8〜16フレーム）で生成するほうが、生成後に間引くより適しています。
5. シームは目視ではなく、シーケンス内の動きと比較して確認します。シームがループとして自然に見えるかどうかは、もともとのフレームの動きの大きさによって決まります。連続するフレーム間の平均絶対ピクセル差分（動きの基準値）と、シーム部分の差分を計算します。ループする区間全体ではなく、その区間の基準値以下にシームの差分が収まれば、ループが閉じています。シーンループ全体では、ステップごとの差分が桁違いに変動することがあるためです。ほぼ静止した待機モーションなら、最初と最後のフレームをasset_displayで表示するだけで十分です。ホップ、歩行、攻撃などの移動を伴うモーションでは、目視だけでは明らかに破綻したループを見逃します。シームの差が大きい場合、まず再実行しないでください。画像から動画を生成するモデルは入力スチルを基に再レンダリングするため、フレーム0は後続のどのフレームとも大きく異なることがよくあります（0から1への差分が大きいのが兆候です）。フレーム0をアンカーにしたループは、再実行しても直りません。フレーム0を除外し、モデル自身のレンダリング内で開始・終了フレームの組み合わせを探し、実際の動きが残る範囲で最も自然につながる区間を選びます。動きがある範囲にトリミングしてください。動作より長いdurationを指定すると静止した末尾が残り、ストライドは出力全体の長さではなく、動きのある区間を基準にします。区間を探しても解決しない場合に限り、再実行を検討します。スキーマにseedがあれば新しい値を使い、なければ動きの表現を変えます。無人で進める場合は再実行を1回までとし、その後は問題を報告して停止します。
6. 仕上げてパッケージ化します。ピクセルアート向けの出力にはピクセルグリッドへのスナップ処理が必要ですが、この処理にも落とし穴があり、場合によっては適切ではありません（references/lane-schemas.md）。グリッドメーカーでシートを作成し、ブリーフで不透明な背景が指定されている場合はその色を、それ以外の場合はtransparentの背景を指定します。シーケンスから動画への変換でGIFとしてプレビューします。アセンブラーには背景パラメーターがないため、納品用GIFでは、すでに背景上に配置された不透明なフレームを使用します。フレームはformat="png"、プレビューはformat="gif"を指定してasset_downloadします。動画アセットではformatを省略してください。mp4は受け付けられません。

よくある間違い

• 何も指定せずに最初と最後のフレームを同一にすること：それではループではなく静止を求めることになります。動きを明示する必要があります。
• 移動するエフェクトを、余白や文言でセル内に収めようとすること：セルの端を越えたものは消えます。余白は埋められ、そこも越えてしまい、収めるよう指示すると投げる動作が打ち消されます。出力される端の帯が空に見えるフレームを維持してください。切り離された飛翔体は、それ自体が独立したスプライトです。
• すべてのモデルに seed があると思い込むこと：多くの動画スキーマや、忠実度の高いいくつかの画像スキーマには seed がありません。そのため、そこでの再現性は実行ごとではなく、アセット単位です。
• 補間フィルターに頼ること：カタログには存在せず、タイミングを調整する手段は fps です。ピクセル画像ではない画像をピクセル化するのと、ピクセルアートを整えるのは別の作業です。カタログには、前者用のピクセル化ツール（グリッドサイズ、パレット）と、後者用のスナッパーがあり、どちらも search で見つけられます（target: "models"、public: true、filters tags: ["tool"]、query: "pixel" を指定すると両方が返され、説明で見分けられます）。
• ピクセルフレームに写真用アップスケーラーを使うこと：テクスチャが勝手に作られてしまいます。scenario-game-assets にある、ピクセルを保持する方法を使ってください。
• シートをステップ処理せずに納品すること：フレームごとのステップ処理では新しい ID が返され、順序は渡したリストにしか残らないため、フレームと出力の対応関係を記録してください（一覧やタイムスタンプから作り直してはいけません）。その後、納品前にシートとプレビューを照合してください。
• フレームがすでにディスク上にあるからといって、納品物をローカルで組み立てること：分析ではクリップがダウンロードされ、ローカルでの組み立てが簡単に見えても、フレームはアセットにならず、コレクションには他の誰もアクセスできないシートだけが残ります。
• ピンポン再生やループのフラグを確認せずに設定すること：ダウンロードした GIF を確認し、それに合わせてアセンブラーを設定してください。
• すべてのフレーム、方向、クリップを一度に起動すること：チームの同時実行上限（scenario スキルの parallel-custom-jobs 行）を超えると、429 エラーで起動が拒否され、ジョブは作成されません。また、一部の動画レーンでは一斉起動が受け付けられた後、失敗して返金されたジョブとして戻ってくることがあります（方向性サイクル）。いずれの場合も、複数回に分けて起動し、拒否または失敗した項目は次の回で再実行してください。取りこぼしてはいけません。
• モデレーションでブロックされた後、攻撃の内容を弱めること：フィルターはプロバイダーのものなので、まず scenario-moderation に従って別の汎用画像モデルを試してください。グリッド仕様は変更しません。動作の説明を書き換えると、そのレーンが重視するものが失われます。