spritecook-use-assets-in-godot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SpriteCook Use Assets In Godot

在Godot中使用SpriteCook资源

Use this skill when moving existing SpriteCook assets into Godot. Pair it with

spritecook-workflow-essentials

for safe downloads and asset manifests. Pair it with

spritecook-animate-assets

only when animations still need to be generated first.

Prefer the manual path first: most agents can create the Godot animation resource directly from SpriteCook spritesheets, which gives more freedom and avoids extra MCP server work. Use the MCP export endpoint second when the user wants SpriteCook to return a packaged set of files.

当你需要将现有SpriteCook资源迁移到Godot时使用本技能。搭配

spritecook-workflow-essentials

可实现安全下载和资源清单管理。仅当仍需生成动画时，才搭配

spritecook-animate-assets

使用。

优先选择手动流程：大多数Agent可以直接从SpriteCook精灵表创建Godot动画资源，这种方式自由度更高，还能避免额外的MCP服务器工作。当用户希望SpriteCook返回打包好的文件集时，再选择MCP导出端点。

Choose A Path

选择流程

Manual Godot setup, preferred: Use SpriteCook animation spritesheets plus metadata to create a Godot
```
SpriteFrames
```
resource and an
```
AnimatedSprite2D
```
node yourself.
MCP packaged export: Call
```
export_godot_character_package
```
to get prebuilt text files and asset downloads, then materialize the returned manifest.

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

Manual AnimatedSprite2D Setup

手动设置AnimatedSprite2D

Use this path when the agent has downloaded SpriteCook animation outputs, has explicit animation asset IDs, or can access spritesheet URLs and frame metadata. The goal is only to make the spritesheets usable as a Godot animation component, not to build gameplay, controllers, playground scenes, or complete demo levels unless the user explicitly asks for those.

Required per animation:

PNG spritesheet URL or local file.
Animation name such as
```
idle
```
,
```
walk
```
,
```
attack
```
,
```
jump
```
,
```
fall
```
,
```
hurt
```
, or
```
death
```
.
Frame width, frame height, frame count, and fps.
Loop behavior. Loop locomotion/idles; usually do not loop
```
attack
```
,
```
hurt
```
, or
```
death
```
.

Important: use the output spritesheet frame size, not the original source asset size. Detailed animations may return larger frames because SpriteCook adds margin, for example a 512x512 source can produce 640x640 frames.

当Agent已下载SpriteCook动画输出文件、拥有明确的动画资源ID，或能访问精灵表URL和帧元数据时，使用本流程。目标仅为让精灵表可作为Godot动画组件使用，除非用户明确要求，否则无需构建游戏玩法、控制器、测试场景或完整演示关卡。

每个动画所需信息：

PNG精灵表URL或本地文件。
动画名称，例如
```
idle
```
（ idle）、
```
walk
```
（行走）、
```
attack
```
（攻击）、
```
jump
```
（跳跃）、
```
fall
```
（下落）、
```
hurt
```
（受击）或
```
death
```
（死亡）。
帧宽、帧高、帧数和帧率（fps）。
循环行为。移动/idle动画需循环；通常
```
attack
```
、
```
hurt
```
或
```
death
```
动画不循环。

重要提示：使用输出精灵表的帧尺寸，而非原始资源尺寸。细节丰富的动画可能会返回更大的帧，因为SpriteCook会添加边距，例如512x512的原始资源可能生成640x640的帧。

File Layout

文件结构

For a new package inside an existing Godot project, use a contained folder and avoid overwriting the user's existing scenes:

text

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

If the user already has a scene, add or update only the

AnimatedSprite2D

node and its

sprite_frames

reference.

在现有Godot项目中新建包时，使用独立文件夹，避免覆盖用户现有场景：

text

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

如果用户已有场景，仅添加或更新

AnimatedSprite2D

节点及其

sprite_frames

引用。

Create SpriteFrames

创建SpriteFrames

Create a

.tres

SpriteFrames

resource that references each spritesheet as a

Texture2D

ext_resource and creates one

AtlasTexture

sub_resource per frame.

For each frame

, use:

gdresource

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

The resource shape is:

gdresource

[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
}]

Generate all frames, not only frame 0. If there are multiple animations, append each animation object to the

animations

array. Set

speed

to the SpriteCook

animation_fps

创建一个

.tres

格式的

SpriteFrames

资源，将每个精灵表作为

Texture2D

外部资源引用，并为每一帧创建一个

AtlasTexture

子资源。

对于第

帧，使用：

gdresource

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

资源结构如下：

gdresource

[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

值。

Add AnimatedSprite2D

添加AnimatedSprite2D

Add an

AnimatedSprite2D

node to the target scene, or create a minimal scene containing only the animation node when no target scene exists:

gdscene

[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"

If the user's scene already has a character/player node, attach the

AnimatedSprite2D

as a child and leave gameplay logic alone.

将

AnimatedSprite2D

节点添加到目标场景；如果没有目标场景，则创建一个仅包含该动画节点的最小场景：

gdscene

[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

作为子节点附加，不要改动游戏玩法逻辑。

Manual Verification

手动验证

Confirm every spritesheet path in
```
.tres
```
exists under
```
res://
```
.

Confirm

frame_count * frame_width == spritesheet_width

for horizontal sheets.

Confirm the target scene contains an
```
AnimatedSprite2D
```
and references the SpriteFrames resource.
Open the project in Godot 4.x and check for missing ext_resource warnings.
Preview the
```
AnimatedSprite2D
```
animations in Godot and verify frame slicing/playback.

确认
```
.tres
```
文件中的所有精灵表路径在
```
res://
```
下存在。
确认对于水平精灵表，
```
帧数 * 帧宽 == 精灵表宽度
```
。
确认目标场景包含
```
AnimatedSprite2D
```
节点并引用了SpriteFrames资源。
在Godot 4.x中打开项目，检查是否有缺失外部资源的警告。
在Godot中预览
```
AnimatedSprite2D
```
动画，验证帧切片和播放效果。

MCP Packaged Export

MCP打包导出

Use this path when the user wants SpriteCook to return a complete package manifest, or when a completed character animation

run_id

is available and state inference from presets is useful. Even when using the endpoint, focus on the returned SpriteFrames/AnimatedSprite setup unless the user asks for demo scenes.

Call

export_godot_character_package

Parameter	Type	Default	Description
`run_id`	string	null	Completed character animation run ID. Prefer this when available because SpriteCook can infer animation states from presets
`animation_asset_ids`	string[]	null	Explicit animation asset IDs when no run ID is available
`character_name`	string	null	Optional name used in export metadata
`state_hints_by_asset_id`	object	null	Optional mapping from asset ID to animation state

Valid state hints include

Idle

Walk

Run

Jump

Fall

IdleDown

IdleUp

IdleRight

WalkDown

WalkUp

WalkRight

RunDown

RunUp

RunRight

Attack

Hurt

, and

Death

The tool returns:

```
text_files
```
: write each
```
{ path, content }
```
exactly.
```
asset_downloads
```
: download each signed
```
url
```
to its
```
path
```
.
```
main_scene
```
: scene to open or run after Godot imports resources.
```
package_kind
```
:
```
character
```
for a playable setup, or
```
animation_preview
```
for a single animation.

Do not assume the MCP server wrote files locally. The agent must create the returned files in the user's Godot project.

Example arguments:

json

{
  "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"
  }
}

After materializing the package, use the same verification checklist as the manual path.

当用户希望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项目中创建返回的文件。

示例参数：

json

{
  "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"
  }
}

生成包后，使用与手动流程相同的验证清单进行检查。