/yaml-editing

name: unity-yaml-editing
description: Last-resort guidance for safely hand-editing Unity YAML

YAML Editing - Safe Hand-Edit Rules

When to use

• Hand-editing YAML when REST cannot reach
• Fixing m_Script GUIDs or broken fileID references
• Fixing .meta files or merge conflicts

Advisory module. This is operational guidance for directly editing Unity serialized YAML text when the REST skills (and the Editor itself) cannot do the job. Hand-editing YAML is the **last resort**, not a shortcut.

When to use / When not to use

**Prefer REST first.** For normal object/asset work, use the REST skills — they keep serialization valid for you:

• GameObjects / components → `gameobject_*`
• Prefabs → `prefab_*`
• ScriptableObjects → `scriptableobject_*`
• Scenes → `scene_*`
• Importers → `importer_*`
• Graphics / rendering → `graphics_*`

**Only hand-edit YAML when REST cannot reach**, i.e. one of:

1. **Compile failure** — a script fails to compile, so the Editor cannot deserialize the component. Editor/REST APIs are unavailable; the only level left is the YAML text. 2. **.meta files** — no REST skill touches `.meta`; GUID and importer fields live only in text. 3. **Hidden ProjectSettings fields** — many `ProjectSettings/*.asset` fields have no public API or REST surface. 4. **Merge conflicts** — REST runs sequentially and cannot perform a 3-way merge of `.unity` / `.prefab`.

If none of these apply, stop and use REST. Do **not** hand-edit YAML for convenience.

Core Concepts

• **Object block / anchor**: every serialized object is a block headed by `--- !u!<classID> &<fileID>`. `<classID>` is the Unity type id (e.g. `1` = GameObject, `4` = Transform, `114` = MonoBehaviour). `<fileID>` is the object's anchor, unique **within this file**.
• **GUID vs fileID**:
• **GUID** = asset-level identity, a 32-char hex string, stored in the asset's `.meta`. Identifies the whole asset (a script, prefab, texture, ...).
• **fileID** = sub-object identity inside a file (a specific component, the specific MonoBehaviour script class, ...).
• **Serialized reference**: a cross-object/asset reference is `{fileID: N, guid: H, type: T}`. `guid` is omitted for same-file references (`{fileID: N}`).
• **`m_Script`**: a MonoBehaviour points at its script via `m_Script: {fileID: 11500000, guid: <scriptGUID>, type: 3}`. `fileID: 11500000` is the conventional MonoScript fileID; `guid` is the `.cs` file's GUID from its `.meta`; `type: 3` means the reference targets an asset on disk. A wrong `guid`/`fileID` here is exactly what produces a "missing script / missing component".

Coverage Scenarios

1. Reference / fileID repair

**When**: a script was renamed or moved, so a prefab/scene `m_Script` `guid`/`fileID` no longer resolves; or a compile failure left a component as Missing and you must locate, delete, or re-point it at the YAML level (the Editor cannot deserialize a broken component, so REST/Editor API is unavailable).

**How**: read the script's current GUID from its `.cs.meta`. In the prefab/scene, find the offending `m_Script: {fileID: 11500000, guid: ..., type: 3}` and set `guid` to the correct value (keep `fileID: 11500000`, `type: 3`). To delete a Missing component, remove its whole `--- !u!114 &<fileID>` block **and** the matching `{component: {fileID: <fileID>}}` entry under the owner GameObject's `m_Component` list — leaving one without the other corrupts the file.

**Danger**: deleting the object block but not its `m_Component` reference (or vice versa) breaks the GameObject; changing a `fileID` that other objects reference orphans those references.

2. .meta / GUID safety

**When**: a `.meta` GUID looks like a pseudo-random GUID and risks third-party collision, or you must edit an importer field that REST does not expose.

**How**: for pseudo-GUID detection and the uuid4 repair flow, **reuse `/metacheck`** — it documents 5 pseudo-GUID heuristics (consecutive hex runs, interleaved increment, repeated chars, literal `abcdef`, wrong length), the uuid4 regeneration step, and the `ValidationSkills.cs.meta` collision lesson. Do not re-derive that here. Generate replacement GUIDs with `python -c "import uuid; print(uuid.uuid4().hex)"`, never by hand.

**Danger**: changing a GUID without updating every reference. **Before changing any GUID, grep the whole project** for that GUID (`.asset` / `.prefab` / `.unity` / `.meta`) and update every reference point in the same change. Run `/metacheck` for a full GUID health audit before/after.

3. ProjectSettings patch

**When**: you need a `ProjectSettings/*.asset` field (YAML) that REST does not expose — e.g. a specific physics layer / collision matrix entry, or a hidden `QualitySettings` value.

**How**: git-back up (or confirm a clean tree) first, locate the exact field by key, change only its value, then let Unity reload and re-serialize to validate. Confirm the change round-trips (Unity rewriting the file the same way) rather than reverting or reformatting it.

**Danger**: editing collision-matrix or enum-backed fields by guessing the encoding can silently break settings; always verify Unity accepts the value on reload.

4. Merge conflict assistance

**When**: a `.unity` / `.prefab` has Git conflict markers and you must resolve them.

**How**: Unity YAML is line-mergeable because each object is an independent `--- !u!<classID> &<fileID>` block. Resolve per-block: for a block changed on only one side, take that side; for the same block changed on both sides, do a true 3-way merge of the conflicting fields. After resolving, ensure every `fileID`/`guid` referenced still has a defining block.

**Danger**: blindly accepting one side (`--theirs`/`--ours`) drops objects added on the other side or leaves dangling references. Never resolve by deleting whole conflict regions without checking the `fileID` references inside them.

Hard Rules

• **Back up first**: confirm a clean git tree (or commit/stash) before any YAML edit, so you can diff