edit-scene

Guide for creating and editing Unity scene files in Unity projects.

Rules

• Do not directly Edit or Write .unity or .prefab files. Instead, write an editor script under Assets/UnityCodingSkills/Editor/ and execute it in Unity to create or update the scene or prefab — those carry GameObject/Prefab-instance structure that is unsafe to author by hand.
• Editor scripts must always end with EditorSceneManager.SaveScene (or PrefabUtility.SaveAsPrefabAsset for prefabs). Treat "no dirty scenes/assets at script exit" as a hard postcondition.
  • Scene: EditorSceneManager.SaveScene(scene, path) (new) or EditorSceneManager.SaveScene(scene) (existing). The return value is true on success.
  • Prefab: PrefabUtility.SaveAsPrefabAsset(go, path). When editing via LoadPrefabContents, always pair with SaveAsPrefabAsset → UnloadPrefabContents.
  • When the script also creates side-effect assets (Materials, ScriptableObjects, etc.), call AssetDatabase.SaveAssets() after the per-object saves to flush pending writes.
• Before running an editor script, check if the editor is in Play Mode using the unity_play_control tool. If it is, stop it first — Play Mode may skip recompilation, leaving stale code active.
• After modifying code, confirm compilation success using the get_unity_compilation_result tool before running.
• To determine which assembly an editor script belongs to, run ${CLAUDE_SKILL_DIR}/scripts/resolve-assembly.sh <cs-file-path>. It walks up directories to find the nearest .asmdef; if none is found, it falls back to Assembly-CSharp-Editor (path contains /Editor/) or Assembly-CSharp.
• Prefer the run_method_in_unity tool (MCP Server Extension for Unity) for execution. Define a public static method in the script (applying [MenuItem("Tools/...")] is optional) and invoke it directly via run_method_in_unity. Only fall back to execute_run_configuration or other alternatives when run_method_in_unity is unavailable.
• Delete the editor script (and its .meta) immediately after a successful run — do not leave it for manual removal. Delete both from the filesystem after the run returns; never have the script delete itself — AssetDatabase.DeleteAsset on its own file triggers a domain reload mid-call (see the Troubleshooting resource below).
  • Treat a run as successful only when the response carries no "type": "Error" entry in logs. success: true alone means only that the method was invoked, not that it completed without throwing.
  • Confirm the change landed: git diff for an existing scene/prefab; for a newly created one (untracked, so no diff) confirm the file exists and its saved hierarchy matches the intent.
  • If the run failed, or the change did not fully land, keep the script until a fix succeeds — don't delete a script you may still need to correct and re-run.
  • The same applies when a fallback runner (execute_run_configuration, etc.) was used instead of run_method_in_unity.
• For uGUI buttons and text, use the legacy variants (UnityEngine.UI.Button / UnityEngine.UI.Text). Do not use TextMeshPro unless the user explicitly requests it.
• Apply context-menu-equivalent defaults when creating uGUI components (see Resources below).
• Give every GameObject the user operates (buttons, toggles, input fields, etc.) a name that makes its hierarchy path unique within the scene/prefab. Otherwise, automated tests cannot identify the GameObject.