godot-batch-operations skill

---
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: 批量移动所有敌人到指定位置

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

### 示例 2: 批量重命名节点

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

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

```bash
# 批量更新多个属性
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: 批量删除符合条件的节点

```bash
# 删除所有隐藏的节点
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 官方文档**: [场景与节点](https://docs.godotengine.org/zh-cn/stable/tutorials/scripting/nodes_and_scene_instances.html)
- **Godot MCP 工具集**: 使用 `claude godot --help` 查看所有可用工具
- **上下文控制最佳实践**: 当节点数量超过CURRENT/CHILD_COUNT_THRESHOLD时，Claude 自动批量控制