用途
该技能用于把已有的 SpriteCook 资源迁移到 Godot 引擎中。当用户希望将 SpriteCook 的精灵表 PNG、动画资源或角色动画序列转换为 Godot 可用的动画组件时使用。它建议与 spritecook-workflow-essentials 配合以安全下载和资源清单,仅在动画仍需先生成时才与 spritecook-animate-assets 配合。
两条路径
技能提供两种方式,并优先推荐手动路径:
- 手动 Godot 设置(首选):使用 SpriteCook 动画精灵表加元数据,自行创建 Godot 的 SpriteFrames 资源和 AnimatedSprite2D 节点。多数智能体可直接完成,自由度更高,且避免额外的 MCP 服务器工作。
- MCP 打包导出:调用 export_godot_character_package 获取预构建的文本文件和资源下载,然后落地返回的清单。当用户希望 SpriteCook 返回打包好的文件集时使用。
手动 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
创建一个 .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):完成的角色动画 run 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 服务器已在本地写入文件。智能体必须在用户的 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"
}
}
落地包后,使用与手动路径相同的验证清单。
适用场景
- 将 SpriteCook 生成的精灵表或角色动画导入 Godot 4.x 项目。
- 需要为已有角色节点添加 AnimatedSprite2D 动画组件。
- 希望通过 MCP 端点获取打包好的 Godot 角色资源清单。
限制
- 不构建玩法、控制器、游乐场场景或完整演示关卡,除非用户明确要求。
- 使用输出精灵表的帧尺寸,而非原始源素材尺寸。
- 使用 MCP 导出时,智能体必须自行在项目中创建返回的文件,不能假设服务器已写入本地。
- 关于收费、价格、平台支持范围等具体信息,资料中暂未提供。