spritecook-use-assets-in-godot

在 Godot 中使用 SpriteCook 资源

将现有 SpriteCook 资源移入 Godot 时使用此技能。搭配 spritecook-workflow-essentials 使用，以确保下载安全并处理资源清单。仅当仍需先生成动画时，才搭配 spritecook-animate-assets 使用。

优先采用手动方式：大多数 Agent 都可以直接根据 SpriteCook 精灵表创建 Godot 动画资源，这样更灵活，也能避免额外的 MCP 服务工作。仅当用户希望 SpriteCook 返回打包好的文件集时，才使用 MCP 导出端点。

选择一种方式

1. 手动设置 Godot，推荐： 使用 SpriteCook 动画精灵表及其元数据，自行创建 Godot SpriteFrames 资源和 AnimatedSprite2D 节点。
2. MCP 打包导出： 调用 export_godot_character_package 获取预构建文本文件和资源下载，然后根据返回的清单生成文件。

手动设置 AnimatedSprite2D

当 Agent 已下载 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

创建一个 .tres SpriteFrames 资源，将每个精灵表作为 Texture2D ext_resource 引用，并为每一帧创建一个 AtlasTexture sub_resource。

对于每一帧 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	没有 run_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 服务已在本地写入文件。Agent 必须在用户的 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"
  }
}

生成包文件后，使用与手动路径相同的验证清单。