godot-batch-operations

name	Godot Batch Operations
version	1.0.0
description	提供批量操作Godot节点的能力，支持批量更新属性、重命名、删除和创建节点，大幅提升开发效率

Godot 批量操作技能

本技能为Godot开发者提供高效的批量节点操作能力，支持一次性对多个节点执行相同操作，大幅提升开发效率。

触发条件

• 需要对多个节点执行相同操作（如批量重命名、批量修改位置）
• 提及"批量"、"多个节点"、"一起修改"等关键词
• 需要对场景中所有特定类型的节点进行统一操作
• 需要进行大规模的节点结构重组

核心功能

1. 批量更新节点属性

一次性更新多个节点的相同属性，支持位置、旋转、缩放、可见性等所有节点属性。

2. 批量节点重命名

按照命名规则批量重命名节点，支持前缀、后缀、序号等多种命名模式。

3. 批量节点删除

根据条件批量删除节点，支持按类型、名称模式、层级关系等筛选条件。

4. 批量节点创建

基于模板批量创建节点，支持数组式批量生成和自动命名。

执行步骤

批量更新节点属性

1. 确定目标节点

   • 使用通配符或正则表达式匹配节点路径
   • 或指定父节点下的所有子节点
   • 或按节点类型筛选

2. 准备属性数据

   • 确定要更新的属性名称
   • 准备新的属性值
   • 对于复杂类型（如Vector2/3），准备完整的数据结构

3. 执行批量更新

   • 遍历所有匹配的节点
   • 使用 update_node_property 更新每个节点
   • 收集更新结果和错误信息

4. 验证结果

   • 检查更新成功的节点数量
   • 查看失败的节点和错误原因
   • 必要时回滚操作

批量重命名节点

1. 选择目标节点

   • 确定要重命名的节点范围
   • 支持通配符匹配节点名称

2. 定义命名规则

   • 新名称模板（如 "Enemy_001", "Enemy_002"）
   • 或使用前缀/后缀添加模式

3. 执行重命名

   • 批量应用命名规则
   • 处理命名冲突

4. 更新引用

   • 检查并更新脚本中的节点路径引用
   • 更新信号连接

代码示例

示例 1: 批量移动所有敌人到指定位置

# 更新所有以 "Enemy" 开头的节点的位置
claude godot update_node_property --node_path="/root/MainScene/Enemy*" \
  --property="position" --value="{\"x\": 100, \"y\": 200}"

示例 2: 批量重命名节点

# 将所有 "Item_" 开头的节点重命名为 "Collectible_001", "Collectible_002" 等
claude godot batch_rename_nodes --parent_path="/root/MainScene" \
  --pattern="Item_*" --new_pattern="Collectible_##"

示例 3: 批量修改多个属性

# 批量更新多个属性
claude godot batch_update_properties --node_paths='[
  "/root/MainScene/Player",
  "/root/MainScene/Enemy1",
  "/root/MainScene/Enemy2"
]' \
  --properties='{
    "modulate": "Color(1, 0, 0, 1)",
    "process_mode": "Node.PROCESS_MODE_INHERIT"
  }'

示例 4: 批量删除符合条件的节点

# 删除所有隐藏的节点
claude godot batch_delete_nodes --parent_path="/root/MainScene" \
  --condition="node.visible == false"

最佳实践

✅ 应该做的

1. 先测试后执行

   • 先在小范围测试批量操作
   • 确认效果符合预期后再大规模应用

2. 使用精确的选择器

   • 尽量使用具体的路径而非通配符
   • 避免误操作不相关的节点

3. 备份场景

   • 执行批量操作前先保存场景
   • 或使用版本控制进行备份

4. 分批处理

   • 对于大量节点（100+），分批处理避免卡顿
   • 每批处理50-100个节点

5. 记录操作

   • 记录批量操作的详细信息
   • 便于后续追踪和回滚

❌ 不应该做的

1. 避免在运行时修改

   • 批量操作应在编辑器模式下进行
   • 避免在游戏运行时执行批量操作

2. 不要忽略错误

   • 认真检查失败的节点和错误原因
   • 不要假设所有节点都更新成功

3. 避免复杂的条件嵌套

   • 不要创建过于复杂的筛选条件
   • 分多次简单操作比一次复杂操作更安全

4. 不要修改只读属性

   • 某些属性是只读的，尝试修改会导致错误
   • 提前了解属性的可写性

5. 避免循环引用

   • 批量操作时注意节点间的引用关系
   • 避免创建循环依赖

MCP 工具集成

本技能与以下 Godot MCP 工具深度集成：

• update_node_property - 更新单个节点属性
• get_node_properties - 获取节点属性
• list_nodes - 列出子节点
• create_node - 创建节点（批量创建时使用）

注意事项

性能考虑

• 批量操作1000+节点时可能卡顿，建议分批
• 复杂属性（如材质、脚本）更新较慢，需耐心等待

版本兼容性

• 本技能基于 Godot 4.5+ 开发
• 部分功能可能不兼容 Godot 3.x

错误处理

• 单个节点失败不会影响其他节点
• 操作完成后会返回详细的执行报告

相关资源

• Godot 官方文档: 场景与节点
• Godot MCP 工具集: 使用 claude godot --help 查看所有可用工具
• 上下文控制最佳实践: 当节点数量超过CURRENT/CHILD_COUNT_THRESHOLD时，Claude 自动批量控制