SuperAPI AI 工具集

spritecook-use-assets-in-godot

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

该技能用于把已有的 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 导出时,智能体必须自行在项目中创建返回的文件,不能假设服务器已写入本地。
  • 关于收费、价格、平台支持范围等具体信息,资料中暂未提供。