godot-resource-workflow

name	Godot Resource Workflow
version	1.0.0
description	提供完整的Godot资源文件（.tres）管理能力，支持资源创建、修改、批量处理和依赖关系管理，优化资源工作流

Godot 资源工作流程技能

本技能为Godot开发者提供完整的资源文件管理能力，支持.tres资源的创建、修改、批量处理、依赖解析和资源优化，构建高效的资源工作流。

触发条件

• 需要创建或修改资源文件（.tres, .res）
• 提及"资源管理"、"资源依赖"、"批量导入资源"
• 需要分析资源依赖关系或解决资源冲突
• 需要批量处理资源（如批量修改材质、纹理设置）
• 需要导入外部资源或优化现有资源

核心功能

1. 资源文件创建与管理

支持创建和编辑各种Godot资源类型：

• StandardMaterial3D / ShaderMaterial
• Texture2D / Texture3D / TextureArray
• Mesh 资源（ArrayMesh, PrimitiveMesh）
• Script 资源（GDScript）
• Scene 资源（PackedScene）
• Audio 资源（AudioStream）

2. 资源依赖关系管理

自动分析和处理资源间的依赖关系：

• 材质依赖纹理和Shader
• Script依赖其他脚本（继承）
• Scene依赖子场景和资源
• 依赖关系可视化
• 循环依赖检测和修复

3. 批量资源处理

支持批量操作多个资源：

• 批量修改资源属性
• 批量转换资源格式
• 批量重命名和整理
• 批量导入和导出

4. 资源优化与压缩

提供资源优化建议和实施：

• 纹理压缩（VRAM压缩、ETC2、S3TC）
• 网格优化（LOD、批量合并）
• 音频优化（压缩格式、比特率）
• 资源文件大小优化

执行步骤

创建资源文件

1. 规划资源类型

   • 确定需要的资源类型
   • 设计资源属性（PBR材质、纹理分辨率等）
   • 考虑性能影响（移动端vs桌面端）

2. 准备资源素材

   • 纹理图片（PNG, JPG, WebP）
   • 3D模型文件（GLTF, FBX, OBJ）
   • 音频文件（WAV, MP3, OGG）
   • Shader代码（.gdshader）

3. 执行资源创建

   • 使用 Godot 编辑器或 MCP 工具创建资源
   • 配置资源属性
   • 设置资源导入参数

4. 验证和测试

   • 在场景中测试资源
   • 检查视觉/音频效果
   • 验证性能

批量处理资源

1. 选择目标资源

   • 确定资源路径或通配符模式
   • 筛选符合条件的资源

2. 定义处理操作

   • 确定要执行的操作（修改属性、转换格式等）
   • 准备操作参数

3. 执行批量处理

   • 遍历所有目标资源
   • 应用操作
   • 记录处理结果

4. 验证结果

   • 检查处理后的资源
   • 验证项目仍然能正常运行

代码示例

示例 1: 创建标准材质资源

# 创建 StandardMaterial3D 资源
claude godot create_resource --project_path="/mnt/d/godot-projects/my-game" \
  --resource_type="StandardMaterial3D" \
  --resource_path="res://materials/ground.tres" \
  --properties='{
    "albedo_color": "Color(0.2, 0.5, 0.2, 1)",
    "metallic": 0.0,
    "roughness": 0.8
  }'

示例 2: 批量修改材质纹理

# 将所有材质的纹理过滤模式改为 Nearest
claude godot batch_update_resources --resource_pattern="res://materials/*.tres" \
  --property="texture_filter" \
  --value="BaseMaterial3D.TEXTURE_FILTER_NEAREST"

示例 3: 分析资源依赖关系

# 分析场景的资源依赖
claude godot analyze_dependencies --resource_path="res://scenes/main_level.tscn"

# 输出：列出所有依赖的纹理、材质、脚本等资源

示例 4: 批量导入纹理并设置参数

# 批量导入纹理并设置为重复模式
claude godot batch_import_textures --source_dir="assets/textures/tiles" \
  --import_to="res://textures/tiles" \
  --import_flags='{
    "repeat": true,
    "filter": false,
    "compress": "VRAM_COMPRESSED"
  }'

示例 5: 创建 ShaderMaterial 并应用Shader

# 创建 ShaderMaterial 并关联 Shader
claude godot create_shader_material --project_path="/mnt/d/godot-project" \
  --material_path="res://materials/water.tres" \
  --shader_path="res://shaders/water.gdshader" \
  --shader_params='{
    "wave_speed": 1.5,
    "wave_height": 0.2,
    "color": "Vector3(0.1, 0.3, 0.8)"
  }'

最佳实践

✅ 应该做的

1. 使用一致的命名规范

   • 材质：material_材质名.tres
   • 纹理：tex_用途名.png
   • 脚本：class_类名.gd
   • 音频：sfx_音效名.wav, bgm_音乐名.ogg

2. 组织清晰的目录结构

   res://
   ├── materials/      # 材质资源
   ├── textures/       # 纹理图片
   ├── meshes/         # 3D模型
   ├── shaders/        # Shader文件
   ├── audio/          # 音频文件
   │   ├── sfx/        # 音效
   │   └── bgm/        # 背景音乐
   └── fonts/          # 字体
   

3. 合理使用资源继承

   • 创建基础材质，其他材质继承并覆盖
   • 基础脚本提供通用功能

4. 资源导入优化

   • 移动端：使用 VRAM 压缩，降低分辨率
   • 桌面端：可使用高分辨率，减少压缩
   • UI纹理：关闭过滤，使用精确尺寸

5. 定期清理未使用资源

   • 使用 Godot 的 "Find in Files" 检查资源引用
   • 删除未使用的旧资源

❌ 不应该做的

1. 避免在运行时创建大量资源

   • 运行时创建资源会导致性能问题
   • 应在编辑器中预创建资源

2. 不要将纹理保持为超大尺寸

   • 根据实际显示尺寸调整纹理大小
   • 2D精灵通常不需要 4K 纹理

3. 避免循环依赖

   • 材质 A 依赖材质 B，材质 B 又依赖材质 A
   • 使用基础材质打破循环

4. 不要使用绝对路径

   • 使用 res:// 相对路径
   • 避免跨项目引用

5. 不要提交导入缓存

   • .import/ 目录不应提交到版本控制
   • 只提交源文件（PNG, GDScript等）

性能优化技巧

纹理优化

• 使用 2 的幂次方尺寸（如 256x256, 512x512）
• 对于不需要透明的纹理，关闭 Alpha 通道
• 使用纹理图集（Atlas）减少Draw Call

音频优化

• 背景音乐使用 OGG Vorbis 格式
• 短音效使用 WAV（无压缩）
• 根据平台调整采样率（移动端 22kHz-44kHz）

3D模型优化

• 合并小物体减少Draw Call
• 使用LOD（Level of Detail）
• 合理使用遮挡剔除

常见问题

Q: 资源文件(.tres)丢失依赖怎么办？

A: 使用 Godot 编辑器的依赖查看器，手动重新指定路径，或使用 MCP 工具批量修复。

Q: 批量处理后游戏变慢了？

A: 检查纹理压缩设置，确保使用了合适的压缩格式。检查是否创建了过多小纹理，考虑使用图集。

Q: 如何找出未使用的资源？

A: 使用编辑器的查找功能搜索资源引用，或使用第三方工具分析项目。

Q: ShaderMaterial 修改后没有效果？

A: 确保 Shader 代码正确编译，检查 Shader 参数是否正确传递。使用 MCP 工具验证 Shader 参数类型。

MCP 工具集成

本技能与以下 Godot MCP 工具配合使用：

已支持的工具

• update_node_property - 将资源应用到节点
• get_node_properties - 检查节点当前资源
• create_node - 创建节点并附加资源
• create_material - 创建材质资源（需要开发支持）

计划开发的工具

基于本技能需求，需要在 Godot MCP 中添加：

• create_resource - 创建资源文件
• modify_resource - 修改资源属性
• analyze_dependencies - 分析资源依赖
• batch_modify_resources - 批量修改资源

Context7 集成

本技能与 Context7 MCP 集成，可自动获取：

• 最新 Godot 资源系统文档
• 材质参数说明和最佳实践
• 性能优化建议
• 版本兼容性信息

当需要创建特定资源的实现代码时，自动使用 Context7 获取最新 API 文档和示例。

版本控制

Git LFS 推荐配置

对于大型资源（纹理、音频、模型），建议使用 Git LFS：

# .gitattributes
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
*.gltf filter=lfs diff=lfs merge=lfs -text

.gitignore 配置

# Godot 4+ specific ignores
.import/
export.cfg
export_presets.cfg
.idea/
.vscode/