---
name: aibridge-prefab-patch
description: Unity Prefab asset patch workflow for AIBridge. Use when modifying complex prefab assets with prefab patch operations, child or component creation, SerializedProperty writes, array edits, internal GameObject/component references, dry-run validation, or when deciding between prefab patch, inspector set_property, scene object commands, and direct Unity YAML fallback.
---

# AIBridge Prefab Patch

Use `prefab patch` for complex Prefab asset edits that need multiple operations in one load/save cycle. Use `inspector set_property` for a single simple serialized field, and `inspector set_properties` for small batched field edits. Use `gameobject`、`transform`、`inspector` for scene objects. If the requested Prefab/Scene/custom `.asset` operation is not supported by AIBridge, load `unity-yaml-editing` and follow its direct UnityYAML rules.

`$CLI` means the platform-appropriate AIBridge CLI invocation, usually `./.aibridge/cli/AIBridgeCLI.exe` on Windows.

## 参数选择

- Prefer `--ops <file>` for multi-step edits, nested JSON, arrays, references, or anything run from PowerShell.
- Use `--ops-json <json>` only for one or two very small operations.
- Put temporary operation files under `.aibridge/patch_ops/`.
- Always run `--dryRun true` before writing the prefab.

## 标准流程

1. Find the target prefab with `asset find/search --format paths`.
2. Inspect structure with `prefab get_hierarchy --prefabPath "<prefab>"`.
3. Create `.aibridge/patch_ops/<task>.json`.
4. Run dry-run:

```bash
$CLI prefab patch --prefabPath "Assets/Prefabs/Player.prefab" --ops ".aibridge/patch_ops/player_hp_patch.json" --dryRun true
```

5. If dry-run succeeds, run the same command without `--dryRun true`.
6. Re-check hierarchy/properties, then run `compile unity` and `get_logs --logType Error`.

## 操作示例

```json
[
  { "op": "ensure_child", "path": "Player/HP" },
  { "op": "ensure_component", "path": "Player/HP", "typeName": "Animator" },
  {
    "op": "set_property",
    "target": { "path": "Player/HP", "componentName": "Animator" },
    "propertyName": "m_Enabled",
    "value": true
  },
  {
    "op": "set_array",
    "target": { "path": "Player", "componentName": "YourComponent" },
    "propertyName": "items",
    "items": [
      { "key": "HP", "value": { "$gameObject": "Player/HP" } },
      {
        "key": "HPAnimator",
        "value": {
          "$component": { "path": "Player/HP", "typeName": "Animator" }
        }
      }
    ]
  }
]
```

## 支持的操作

- `ensure_child`: Ensure a GameObject path exists. Optional fields: `active`, `tag`, `layer`.
- `ensure_component`: Ensure a component exists on `path`. Use `typeName`.
- `set_property`: Set one SerializedProperty on a GameObject/component/asset target.
- `set_properties`: Set multiple SerializedProperties on one target.
- `set_array`: Replace an array property.
- `append_array`: Append items to an array property.
- `clear_array`: Clear an array property.

## 不支持时的处理

`prefab patch` currently does not cover every Unity serialized structure. Use `unity-yaml-editing` when the task needs unsupported operations such as:

- Scene `.unity` object creation or structure edits not exposed by scene/gameobject/transform/inspector commands.
- Prefab Variant override structures, nested modification records, or operations outside the listed patch ops.
- Creating a brand-new Prefab file from text serialization, including paired `.meta`, root object, child hierarchy, and component documents.
- Adding Prefab documents/components whose schema is not covered by patch ops, after copying the shape from the same Unity version/project.
- ScriptableObjectTable/custom `.asset` creation or structural edits that cannot be represented by Inspector SerializedProperty writes.
- Other text-serialized Unity assets (`.mat`, `.controller`, `.anim`, etc.) requiring direct document/fileID/GUID changes.

## 引用写法

Use these object reference values inside `value` or array items:

```json
{ "$gameObject": "Player/HP" }
{ "$component": { "path": "Player/HP", "typeName": "Animator" } }
{ "$asset": "Assets/Materials/HPMat.mat" }
{ "$guid": "asset-guid" }
null
```

## 注意事项

- Do not edit Prefab YAML directly unless no Unity/AIBridge API path exists; when required, use `unity-yaml-editing`.
- For direct YAML fallback, copy component schema from a same-project example, update every `GameObject.m_Component`, `Transform.m_Children`, `Transform.m_Father`, and component `m_GameObject` reference, then re-import and inspect.
- Paths are normalized against the prefab root; both `Root/Child` and `Child` can work when unambiguous.
- Duplicate child names under the same parent are ambiguous; use exact hierarchy paths.
- Duplicate components of the same type are ambiguous; use `componentIndex` when needed.
- Keep operation JSON under `.aibridge/patch_ops/`; do not put it under `Assets/` or commit it.

## References

- `references/prefab-reference.md`: generated CLI reference for general `prefab` commands.