spritecook-animate-assets

SpriteCook のアニメーションアセット

アニメーションのワークフローでは、このスキルを使用してください。クレジット、マニフェスト、安全なダウンロード、共有のデフォルト設定には、spritecook-workflow-essentials と組み合わせてください。

必要条件： SpriteCook MCP サーバーに接続されている必要があります。接続されていない場合は、接続が必要であることを説明し、許可されている場合はホストの標準の接続フローを使用してください。アート作業の一環として、ソフトウェアをインストールしたり認証設定を変更したりしないでください。

ツール

アニメーションの前に、元画像の輪郭と透明度を確認してください。必要に応じて、保持されたアルファソースからエッジピクセルを復元するために spritecook-polish-sprites を使用し、その後、調整済みのアセット ID をアニメーション化します。完成したアニメーションのエッジのちらつきを確認してください。調整ワークフローでは、対応するアニメーションの全フレームにわたって、同じしきい値を比較できます。

animate_game_art

既存の SpriteCook アセットを、短いピクセルアートアニメーションまたは精細なアニメーションにします。このツールはジョブをすぐに返します。リクエストを開いたままにせず、返された poll.tool と poll.arguments に従ってください。

パラメーター	型	デフォルト	説明
asset_id	string（必須）	-	アニメーション化する既存の SpriteCook アセット ID
prompt	string（必須）	-	時間の経過に伴う正確な動きを記述します。auto_enhance_prompt=true の場合、「Idle」や「Attack」のような簡単なプロンプトを使用できます
auto_enhance_prompt	bool	true	元のアセットを確認し、短いプロンプトをより詳細なアニメーションプロンプトに拡張します
edge_margin	int	6	アニメーションのフレーミング前に追加される間隔です。ピクセルアートは地面の線として下端に接するため、余白は左右と上に追加されます
vertical_align	string	null	ピクセルアート専用です。飛行、浮遊、跳ねる被写体には "center" を指定すると、edge_margin によって下側にも余白ができます。地面の線を維持する場合は省略します
pixel	bool	null	モードの任意の上書き設定です。省略すると、SpriteCook がアセットからモードを推定します
model	string	モードのデフォルト	pixel-engine-v1.1、frame-engine-v1.1、または pixel-engine-v1.5 です。v1.1 のデフォルトを使用する場合は省略します
output_frames	int	8	v1.1 では偶数を使用します（ピクセルアートは 2～16、精細なアニメーションは 2～24）。v1.5 では 3～16 の整数フレームを指定できます
output_format	string	"webp"	"webp"、"gif"、または "spritesheet"
negative_prompt	string	null	動きや内容に関する任意の除外指定です。pixel-engine-v1.5 ではサポートされていないため、指定しないでください
matte_color	string	"#808080"	透明度の処理前に使用する、16 進数のマットカラーです
removebg	string	"Basic"	"None"、"Basic"、または "Pro" です。Pro ではフレームごとにコストが追加されます
colors	int	24	ピクセルパレットのサイズです。出力に適用されます。pixel=true の場合のみ有効です

アニメーションの作成には約 1～5 分かかります。ツールのスキーマに wait_seconds が記載されている場合のみ、上限を設けて指定してください。それ以外の場合は、適切な間隔を空けて check_job_status を呼び出してください。animate_game_art は project_id を受け取りません。必要に応じて、assign_assets_to_project で結果を移動してください。

開始フレームの準備

アニメーションモデルは入力画像をアニメーション化します。この画像を開始フレームとして扱ってください。要求された動きの開始時に必要となるポーズ、状態、向きが、すでに画像に表れている必要があります。動きのプロンプトや auto_enhance_prompt では、適切な元画像の準備を代替できません。

• アニメーション化する前に元画像を確認してください。開始時のポーズが動きに合っている場合は、その画像を再利用します。
• 要求された状態に別のポーズが必要な場合は、まず edit_asset_id を指定した generate_game_art でポーズを準備するか、reference_asset_id を指定して、確立済みのキャラクターを基に生成してください。キャラクターのデザイン、パレット、プロポーション、アートスタイルを維持してください。
• 準備した静止画を確認してから、返された asset_id を animate_game_art に渡してください。

例：眠るループと眠りに落ちる動きの違い

同じキャラクターの動きが異なる場合に、開始フレームを選ぶ方法を以下に示します。

• 眠るループの場合は、まず同じキャラクターが横たわるか、丸くなって目を閉じている静止画を作成します。その寝姿勢を保ったまま、穏やかな呼吸をアニメーションにします。このループの入力に、立っている起きた状態の待機スプライトは使わないでください。
• 眠りに落ちる動きへの遷移の場合は、横たわって目を閉じる動きが依頼内容に含まれるため、起きた状態の開始ポーズが適切な場合があります。最終状態ではなく、動作の始まりに合った素材を選んでください。

例：待機中のウサギを「同じウサギが丸くなって眠り、目を閉じている。デザインとピクセルアートのスタイルは維持する」ように編集します。その静止画を確認してから、新しいアセットを「眠っているウサギは丸くなったまま目を閉じ、シームレスなループで穏やかに呼吸する」としてアニメーション化します。

例：連続する歩行サイクル

ループする歩行アニメーションでは、まず待機スプライトを編集するか参照し、同じキャラクターデザインと向きで歩行中のポーズにします。その静止画を確認してから、返されたアセット ID を使ってアニメーション化します。歩行の中間ポーズから始めると、最初のフレームも歩行動作の一部となり、サイクルが繰り返されるたびに不自然な立ち姿の待機ポーズに戻るのを防げます。立っている状態から歩き始める別個の遷移には、待機状態の素材が適している場合もあります。

静止画のプロンプト例：「同じキャラクターが歩行中の一歩を踏み出しており、片足を前に、もう片足を後ろに出し、腕は自然な歩行動作で振られている。元の向き、プロポーション、パレット、ピクセルアートのスタイルを維持する。」次に、「同じ向きと一定のリズムを保ち、開始時の歩幅をスムーズにつないで、停止したり立ち姿の待機ポーズに戻ったりせず、その場で連続して歩くサイクル」としてアニメーション化します。ループのつなぎ目を確認し、動きが途切れないことを確かめてください。

ワークフロー

1. ユーザーがすでに SpriteCook のアセットを持っている場合は、開始ポーズを確認します。そのポーズが依頼された動きに合う場合に限り、そのまま使用します。合わない場合は、上記の説明に沿って開始フレームを準備します。
2. ユーザーがローカルの画像ファイルパスしか持っていない場合は、spritecook-upload-assets を使って create_asset_upload を呼び出し、バイトデータをアップロードしてから finalize_asset_upload を呼び出します。
3. ユーザーが小さなデータ URL または生の base64 値を提供した場合は、最初に import_asset を呼び出し、返された asset_id を使用します。
4. アップロードまたはインポートした画像が開始フレームのガイダンスにも合っているか確認します。必要に応じて別のポーズを準備し、その準備した静止画の asset_id を animate_game_art で使用します。
5. モードを強制する必要がない限り、pixel は省略します。

アップロード／インポートの手順で、元画像を SpriteCook に取り込みます。これはアニメーション呼び出しそのものではありません。利用できる場合は、MCP アセットアップロードツールを使用してください。

一貫性のルール

• 動きが異なっても、確立したキャラクターデザインを一貫して維持します。
• 適切な開始ポーズを共有する動きには、同じ asset_id を再利用します。動きによって開始状態、ポーズ、または向きを変える必要がある場合は、参照または編集した静止画を準備し、その静止画を別途アニメーション化します。
• 元のキャラクターアセットを保持し、準備したポーズのアセット ID を再利用できるよう記録します。無関係なキャラクターを、参照せずに生成することは避けてください。

ソースのルール

• 小さなソースにはピクセルアニメーションが適しています。v1.1 のピクセルアニメーションで受け付けるアセットは最大 256x256、v1.5 のピクセルアニメーションでは最大 320x320 です。
• 256x256 から 2048x2048 までのアセットには、詳細アニメーションが適しています。
• 256x256 未満のソースを詳細モードに強制しないでください。
• ソースのアスペクト比は 1:2 から 2:1 の範囲である必要があります。
• デフォルトでは edge_margin=6 を維持します。これにより、ピクセルアートがキャンバスの端に寄りすぎるのを防げます。これは割合のため、非常に小さなスプライトでは 1、2 ピクセル分しか余白が増えません。ふたを開ける動きや大きな振りなど、外側に広がる動きには値を大きくしてください。飛ぶコウモリや跳ねるスライムのように地面から離れる対象には、vertical_align="center" を渡し、大きく伸びたり跳ねたりする動きでは edge_margin を大きくしてください。

エンジンの選択

• pixel-engine-v1.1（デフォルト）は、ループ、歩行サイクル、待機アニメーションに適しています。
• pixel-engine-v1.5は、正確な動きや珍しい動き、単独の被写体に適しています。また、背景が透明な単一のキャラクターや小道具では、より落ち着いた忠実な動きになりやすい傾向があります。
• 結果は被写体によって異なります。品質が重要な場合は、同じ静止画で両方のエンジンを試し、より良い方を選んでください。
• ガイド付きキャラクター実行（generate_character_animations）ではv1.1のみを使用します。v1.5では、同じ静止画に対してanimate_game_artを使い、それぞれの動きを個別にアニメーション化してください。

出力キャンバス

• 出力フレームは通常、正方形で余白が付いています。正方形でないソースは正方形のフレームの中央に配置されます（180x320のソースからは320x320のフレームが返されます）。小さなスプライトは少し拡大縮小される場合があります。レスポンスにはオフセットが含まれません。
• アニメーションをシーンに戻したり、静止画と位置を合わせたりするには、ローカルでソースとフレーム0を照合してオフセットを見つけ、スケールも確認してください。
• フレームサイズはジョブによって異なります。共通の地面ラインを揃える必要があるセットでは、ローカルで共通のフレーム範囲を計算し、すべてのフレームを配置し直してください。
• フレーム数がoutput_framesと1つ異なる場合があります。ループの長さを決めつける前に、結果のメタデータからframe_countを読み取ってください。
• output_format="spritesheet"の場合も、sprite_urlはアニメーションWebPです。PNGのストリップはspriteheet_urlです。

品質チェック

• アニメーション化する前に静止画を整えてください。輪郭からはみ出たピクセル、パーツ間に残った背景、ノイズは、すべてのフレームに描き直されます。まずspritecook-polish-spritesを使ってください。
• 約32 px未満では輪郭がぼやけ、小さな目などの特徴がフレーム間でずれることがあります。そのサイズでは顔をシンプルに保ち、すべてのフレームを確認してください。
• 待機アニメーションではちらつきが起きることがあります。孤立したピクセルが1フレームだけ変わり、次のフレームで元に戻ります。auto_enhance_prompt=falseを設定した落ち着いたプロンプトにすると、全体的な動きを抑えられます。残った1フレームだけの変化は、前後のフレームでピクセルが一致している場合、そのピクセルを復元してローカルで修正してください。
• 「足は地面につけたままにする」「顔を変えない」など、動かさずに保つものを指定し、維持されたか確認してください。エンジンは常に指示を守るとは限りません。
• 光の周辺や足元に灰色や色の異なる点がないか、またループが途切れていないか（最後のフレームと最初のフレームを比較）を確認してください。

シーンの一部をアニメーション化する

シーン全体をアニメーション化すると、フレーム全体が描き直されます。空や石などの静止領域がフレーム間でずれ、ループもほとんどの場合つながりません。代わりに、動く部分だけをアニメーション化してください。

1. generate_game_art(edit_asset_id=<scene>, prompt="Remove the X ...")でシーンを編集し、きれいな背景プレートを作成します。
2. 元の画像と背景プレートの差分から、ローカルでXを切り抜きます。それをアップロードし、そのアセットだけをアニメーション化します。
3. オフセットを合わせて、フレームを背景プレートに合成し直します。

滝のように背景に属するエフェクトでは、removebg="None"とedge_margin=0を指定して背景プレートを切り抜き、動く領域をモーションマスクで再度ブレンドしてください。

プロンプトの作成

• プロンプトを書く前に、元画像のキャラクターを実際に確認してください。
• ピクセルアートの場合は、確認専用として、元画像を最近傍補間で約 1024x1024 に拡大してください。
• まず、目に見えるキャラクターの詳細を特定してください。シルエット、鎧、バイザー、武器、盾、ポーズ、向きなどです。
• 元画像で実際に見える詳細だけに言及してください。
• ラベルやキーワードの羅列ではなく、平易な文章で短い段落を1つ書いてください。
• 何がどのように動くのか、何が安定したままなのか、目に見える小道具や武器がどのように使われるのかを説明してください。
• 新しい装備やエフェクトを作り出すのではなく、既存のキャラクターに即した動きにしてください。
• auto_enhance_prompt=true でない限り、idle animation のような汎用的なプロンプトは避けてください。

アイドルアニメーションのプロンプト例： 紫色のタクティカル装備を身に着けた装甲兵が、安定した戦闘態勢で立ち、リズミカルな呼吸に合わせて上下にわずかに揺れます。黄色いバイザーが光を受け、ライフルが手の中でわずかに動きますが、高い警戒態勢を保っています。

攻撃アニメーションのプロンプト例： 紫色のタクティカル装備を身に着けた装甲兵がライフルを構えて数発撃ち、銃身の先端に黄色いマズルフラッシュが現れます。発砲のたびに体が反動で揺れますが、頭部とバイザーは前方を見据えたまま、射撃の間中、安定した戦闘態勢を保ちます。

auto_enhance_prompt=true の場合、SpriteCook が元のアセットを確認して自動的にプロンプトを補完できるため、Idle、Attack、Walk のようなシンプルなプロンプトも有効です。

check_job_status

animate_game_art の job_id を check_job_status で使用してください。成功したら、asset_id と正規の sprite_url を使用します。spritesheet_url は、レスポンスに含まれている場合にのみ使用してください。レスポンスに warning.code="asset_output_unavailable" が含まれている場合は、指定された warning.recovery のツール呼び出しを実行してください。