spritecook-use-assets-in-godot

SpriteCook アセットを Godot で使う

SpriteCook の既存アセットを Godot に移す際に、このスキルを使用してください。安全なダウンロードとアセットマニフェストの作成には、spritecook-workflow-essentials と組み合わせてください。アニメーションを先に生成する必要がある場合に限り、spritecook-animate-assets と組み合わせてください。

まずは手動の方法を優先してください。ほとんどのエージェントは、SpriteCook のスプライトシートから Godot のアニメーションリソースを直接作成できます。そのほうが自由度が高く、MCP サーバーでの追加作業も避けられます。SpriteCook にファイル一式をパッケージ化して返してほしいとユーザーが希望する場合は、次に MCP のエクスポートエンドポイントを使用してください。

方法を選ぶ

1. Godot での手動セットアップ（推奨）： SpriteCook のアニメーションスプライトシートとメタデータを使用して、Godot の SpriteFrames リソースと AnimatedSprite2D ノードを自分で作成します。
2. MCP によるパッケージ化エクスポート： export_godot_character_package を呼び出して、事前構築済みのテキストファイルとアセットのダウンロードを取得し、返されたマニフェストを実体化します。

AnimatedSprite2D の手動セットアップ

エージェントが SpriteCook のアニメーション出力をダウンロード済みの場合、アニメーションアセット ID が明示されている場合、またはスプライトシートの URL とフレームメタデータにアクセスできる場合は、この方法を使用してください。目的は、スプライトシートを Godot のアニメーションコンポーネントとして使用できるようにすることだけです。ユーザーから明示的に依頼されない限り、ゲームプレイ、コントローラー、プレイグラウンドシーン、完全なデモレベルは作成しないでください。

アニメーションごとに必要なもの：

• PNG スプライトシートの URL またはローカルファイル。
• idle、walk、attack、jump、fall、hurt、death などのアニメーション名。
• フレーム幅、フレーム高、フレーム数、fps。
• ループ動作。移動や待機のアニメーションはループさせます。通常、attack、hurt、death はループさせません。

重要：元のソースアセットのサイズではなく、出力スプライトシートのフレームサイズを使用してください。SpriteCook が余白を追加するため、詳細なアニメーションではフレームが大きくなる場合があります。たとえば、512x512 のソースから 640x640 のフレームが生成されることがあります。

ファイル構成

既存の Godot プロジェクト内に新しいパッケージを作成する場合は、専用のフォルダーを使用し、ユーザーの既存シーンを上書きしないようにしてください。

SpriteCook/
  assets/
    player_idle.png
    player_walk.png
    player_attack.png
    player_frames.tres

ユーザーがすでにシーンを持っている場合は、AnimatedSprite2D ノードとその sprite_frames 参照のみを追加または更新してください。

SpriteFrames を作成する

各スプライトシートを Texture2D の ext_resource として参照し、フレームごとに AtlasTexture の sub_resource を作成する .tres の SpriteFrames リソースを作成してください。

各フレーム i には、次を使用してください。

region = Rect2(i * frame_width, 0, frame_width, frame_height)

リソースの構成は次のとおりです。

[gd_resource type="SpriteFrames" load_steps=<resource_count> format=3]

[ext_resource type="Texture2D" path="res://SpriteCook/assets/player_idle.png" id="idle_sheet"]

[sub_resource type="AtlasTexture" id="AtlasTexture_idle_0"]
atlas = ExtResource("idle_sheet")
region = Rect2(0, 0, 64, 64)

[resource]
animations = [{
"frames": [{"duration": 1.0, "texture": SubResource("AtlasTexture_idle_0")}],
"loop": true,
"name": &"idle",
"speed": 8.0
}]

フレーム 0 だけでなく、すべてのフレームを生成してください。複数のアニメーションがある場合は、各アニメーションオブジェクトを animations 配列に追加してください。speed には SpriteCook の animation_fps を設定してください。

AnimatedSprite2D を追加する

対象のシーンに AnimatedSprite2D ノードを追加してください。対象のシーンがない場合は、アニメーションノードだけを含む最小限のシーンを作成してください。

[gd_scene load_steps=2 format=3]

[ext_resource type="SpriteFrames" path="res://SpriteCook/assets/player_frames.tres" id="frames"]

[node name="AnimatedSprite2D" type="AnimatedSprite2D"]
sprite_frames = ExtResource("frames")
animation = &"idle"
autoplay = "idle"

ユーザーのシーンにキャラクター／プレイヤーノードがすでにある場合は、AnimatedSprite2D を子として追加し、ゲームプレイのロジックには手を加えないでください。

手動での検証

• .tres 内のすべてのスプライトシートのパスが res:// 以下に存在することを確認します。
• 横向きのシートでは、frame_count * frame_width == spritesheet_width を確認します。
• 対象シーンに AnimatedSprite2D が含まれ、SpriteFrames リソースを参照していることを確認します。
• Godot 4.x でプロジェクトを開き、ext_resource の不足に関する警告がないことを確認します。
• Godot で AnimatedSprite2D のアニメーションをプレビューし、フレームの切り出しと再生を確認します。

MCP パッケージエクスポート

SpriteCook に完全なパッケージマニフェストを返してもらいたい場合、またはキャラクターアニメーションの完了済み run_id があり、プリセットから状態を推定すると便利な場合は、この方法を使用します。エンドポイントを使用する場合も、ユーザーがデモシーンを求めていない限り、返される SpriteFrames／AnimatedSprite のセットアップに重点を置いてください。

export_godot_character_package を呼び出します。

パラメーター	型	デフォルト	説明
run_id	string	null	完了済みのキャラクターアニメーション実行 ID。利用可能な場合はこれを優先してください。SpriteCook がプリセットからアニメーション状態を推定できます
animation_asset_ids	string[]	null	実行 ID が利用できない場合に指定する、明示的なアニメーションアセット ID
character_name	string	null	エクスポートのメタデータに使用する任意の名前
state_hints_by_asset_id	object	null	アセット ID からアニメーション状態への任意のマッピング

有効な状態ヒントは、Idle、Walk、Run、Jump、Fall、IdleDown、IdleUp、IdleRight、WalkDown、WalkUp、WalkRight、RunDown、RunUp、RunRight、Attack、Hurt、Death です。

ツールは以下を返します。

• text_files：各 { path, content } をそのまま書き込みます。
• asset_downloads：署名付きの各 url から、指定された path にダウンロードします。
• main_scene：Godot がリソースをインポートした後に開く、または実行するシーンです。
• package_kind：プレイ可能なセットアップの場合は character、単一のアニメーションの場合は animation_preview です。

MCP サーバーがファイルをローカルに書き込んだと想定しないでください。エージェントが、返されたファイルをユーザーの Godot プロジェクト内に作成する必要があります。

引数の例：

{
  "animation_asset_ids": ["idle-id", "walk-id", "attack-id"],
  "character_name": "Player",
  "state_hints_by_asset_id": {
    "idle-id": "Idle",
    "walk-id": "Walk",
    "attack-id": "Attack"
  }
}

パッケージを実体化した後は、手動の方法と同じ検証チェックリストを使用してください。