use-unity-editor

像在Unity编辑器中一样读取和编辑场景和预制件。没有这个技能,您无法在Unity编辑器中执行任何操作。

📖 中文导读:像在Unity编辑器中一样读取和编辑场景和预制件。没有这个技能,您无法在Unity编辑器中执行任何操作。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: use-unity-editor description: "Interact with the Unity editor, including: reading and editing scenes and prefabs; focusing the Unity editor window; reading the Unity console; screenshotting the editor; and starting play mode. You can't do anything in the Unity editor without this skill."

Use Highrise Studio's Unity Editor

Highrise Studio is built on Unity, and uses a variant of the Unity editor to edit scenes and prefabs. This guide covers:

  • How you can read and edit scenes and prefabs as a user would in the Unity editor
  • How to focus the Unity editor window to trigger pending changes
  • How to trigger a Lua rebuild to generate wrapper code for new Lua scripts
  • How to read the Unity console to check for errors and warnings
  • How to start and stop play mode to test your changes
  • How to capture a screenshot of the Unity editor's Game view to visually inspect the current state of the game

Important information

Reading the scene

Highrise Studio serializes the active scene to a JSON file for easier understanding. You can find the JSON file at Temp/Highrise/Serializer/active_scene.json. The JSON file should be up-to-date with the scene's current state.

The JSON file contains the scene's entire Game Object hierarchy. There will be a single top-level object called "SceneRoot", whose children are the root Game Objects in the scene. The JSON file is structured as follows:

{
  "referenceId": "a GUID that uniquely identifies this Game Object within the scene. Not persistent across editor reloads.",
  "objectProperties": {
    "name": "the name of the game object, as it appears in the hierarchy.",
    "activeSelf": "whether the Game Object is enabled.",
    "tag": "the Game Object's tag.",
    "parentGameObject": "the GUID of the parent Game Object, or null if this is a root Game Object.",
    "prefabPath": "the path to the prefab that this Game Object is an instance of, or null if this is not an instance of a prefab."
  },
  "components": [
    {
      "componentType": "the type of the component (e.g., UnityEngine.Transform)",
      "referenceId": "a GUID that uniquely identifies this component within the scene. Not persistent across editor reloads.",
      "componentProperties": {
        "PROPERTY_NAME (e.g., position)": {
          "propertyName": "the name of the property (e.g., position, rotation, scale, etc.), matching the PROPERTY_NAME key.",
          "type": "the type of the property (e.g., UnityEngine.Vector3, String, etc. If the type is an enum, the full name of the enum will be used, followed by a list of the possible values in parentheses.)",
          "value": "the value of the property."
        }
      }
    }
  ],
  "children": [
    {
      // An object of the same format as the root object; may have children of its own nested within it.
    }
  ]
}

Here are some important property value formats:

{
  "type": "UnityEngine.Vector2",
  "value": {"x": 1.0, "y": 2.0}
}
{
  "type": "UnityEngine.Vector3",
  "value": {"x": 1.0, "y": 2.0, "z": 3.0}
}
{
  "type": "UnityEngine.Vector4" | "UnityEngine.Quaternion",
  "value": {"x": 1.0, "y": 2.0, "z": 3.0, "w": 4.0}
}
{
  "type": "GameObject" | "a component type (e.g., Transform), when a property refers to a component",
  "value": "the GUID of the referenced Game Object or Component OR if the field refers to a prefab asset, a path to the prefab asset with the prefix 'prefab:' (e.g., 'prefab:Assets/Prefabs/MyPrefab.prefab')."
}

Reading the prefabs

Highrise Studio serializes all prefabs in the Assets directory to JSON files for easier understanding. You can find the JSON files in Temp/Highrise/Serializer/, under the name of the prefab file (e.g., Assets/Prefabs/MyPrefab.prefab.json). Each JSON file is structured the same as the active scene file, and the prefabs can be edited using the same editing instructions as the scene. You should make edits to the prefabs using the reference IDs in this file; only use the prefab:PATH format as the value of a property that refers to a prefab asset.

Editing the scene or a prefab

Do not modify the active_scene.json or .prefab.json file directly; this will not do anything. Instead, you will submit a queue of changes to be applied to the scene in a file you will create called Temp/Highrise/Serializer/edit.json. The file consists of an array of objects. Each object is required to have an editType key, which will determine how to interpret the change and what other keys to expect in the object. The following are the possible edit types:

  • delete: Remove a GameObject or Component from the scene. Requires the following key:
    • referenceIdToDelete: The GUID of the GameObject or Component to delete.
  • createGameObject: Add a new GameObject to the scene. Requires the following keys:
    • referenceIdOfParentGameObject: The GUID of the parent Game Object to create the new Game Object under.
    • nameOfGameObjectToCreate: The name of the new Game Object.
    • referenceIdOfGameObjectToCreate: A GUID that you generate that will be assigned to the new Game Object.
    • prefabPathForGameObjectToCreate: The (optional) path to a prefab. If provided, the new Game Object will be instantiated from the prefab. If not provided, an empty Game Object will be created.
  • addComponent: Add a new Component to a Game Object. Requires the following keys:
    • referenceIdOfGameObjectToAddComponent: The GUID of the Game Object to add the new Component to.
    • componentTypeToAdd: The type of the Component to add (e.g., UnityEngine.Transform), chosen from the list of available component types in Temp/Highrise/Serializer/all_component_types.json.
    • referenceIdOfComponentToAdd: A GUID that you generate that will be assigned to the new Component.
  • setProperty: Set the value of a property on a GameObject or Component. Requires the following keys:
    • referenceIdOfObjectWithPropertyToSet: The GUID of the GameObject or Component to set the property on.
    • nameOfPropertyToSet: The name of the property to set (e.g., position, tag, etc.). This should already exist in the JSON file; do not invent a new property.
    • newPropertyValue: The value of the property to set.
  • saveObjectAsPrefab: Save a Game Object as a prefab file for future use. Requires the following keys:
    • referenceIdOfObjectToSaveAsPrefab: The GUID of the GameObject to save as a prefab.
    • pathToSavePrefabAs: The path to save the prefab as. This should be a relative path from the project root and should not already exist.

You can enqueue multiple edits in a single file, but create the file and write all edits to it in a single transaction. The edits will be applied in the order they are enqueued.

Adding components to Game Objects

When you want to add a component to a Game Object, you will need to know the full name of the type of the component you want to add. You can find the list of available component types in Temp/Highrise/Serializer/all_component_types.json. You do not know this list in advance; you will need to read the file to find it. all_component_types.json is structured as follows:

[
  {
    "fullName": "the full name of the component type (e.g., UnityEngine.Transform)",
    "properties": {
      "PROPERTY_NAME (e.g., position)": {
        "propertyName": "the name of the property (e.g., position, rotation, scale, etc.), matching the PROPERTY_NAME key.",
        "type": "the type of the property (e.g., UnityEngine.Vector3, String, etc. If the type is an enum, the full name of the enum will be used, followed by a list of the possible values in parentheses.)"
      }
    }
  }
]

If you want to create a Game Object or Component and then set properties on it, you can do this using multiple edits in a single edit.json file. After the createGameObject or addComponent edit, you can add the setProperty edit for the new object using the reference ID you generated for referenceIdOfGameObjectToCreate or referenceIdOfComponentToAdd.

Adding Lua script components to Game Objects

When you have a built-in or project-specific Lua script that you want to add to a Game Object, you will create a component as normal following the steps above. The only point to keep in mind is that the componentTypeToAdd key will be the name of the script with the prefix Highrise.Lua.Generated (e.g., Highrise.Lua.Generated.MyScript). Properties on these components will generally be prefixed with m_ (e.g., m_MyProperty).

If you just created the Lua script, do not attempt to add it to a Game Object yet, as the generated code will not exist yet. Ask the user to switch over to the Unity editor first so that the code can be compiled; then, the component can be added to the Game Object.

Adding UI components and making them visible

UI components are added by attaching a Lua script component to a Game Object in the scene, like any other component. The UXML and USS will be pulled in automatically at runtime. To make a UI component visible, you must also set the _uiOutput property on the component to either "World" (rendering the UI within the world space), "AboveChat" (rendering the UI above the chat), or "Hud" (above everything, like a heads-up display).

Focusing the Unity editor

To bring the Unity editor window to the foreground:

On macOS, create a .focus file in the project root:

touch .focus

On Windows, run the PowerShell script from the plugin resources:

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/skills/use-unity-editor/resources/focus-unity.ps1"

This is useful when you need Unity to process pending changes (such as after writing to edit.json) or when you want to ensure the user's attention is directed to the editor. On macOS, the Serializer scripts include a trigger that monitors for the .focus file and focuses the Unity window when detected. On Windows, the PowerShell script directly brings the Unity window to the foreground (Windows doesn't allow background processes to bring windows to the foreground, so the .focus file trigger won't work).

Toggling play mode

You can toggle Unity's play mode by creating a .play file in the project root directory. The Serializer scripts include a EditorTriggers that monitors for this file:

  • When the .play file is detected, Unity will start play mode if it's not running, or stop play mode if it is currently running.
  • Before starting play mode, Lua scripts are automatically rebuilt (via Highrise/Lua/Rebuild All).
  • The .play file is automatically deleted after being processed.
  • There is a 10-second cooldown between triggers to prevent accidental rapid toggling.
  • On macOS, the Unity window will be brought to the foreground when play mode starts. On Windows, you should focus the window manually first (see "Focusing the Unity editor" above).

To toggle play mode:

touch .play

After starting play mode, you should:

  1. Sleep for 15 seconds to allow Unity to import assets and enter play mode.
  2. Read Console.log to observe the running session output.
  3. Retry up to 3 times (15s intervals) if the console hasn't updated yet.

Note: Play mode (via .play) automatically triggers a Lua rebuild before starting, so you don't need to manually rebuild if you're about to enter play mode.

Triggering a Lua rebuild

Highrise Studio uses Lua scripts for game logic, which must be compiled into C# code before Unity can execute them. When you create or modify Lua scripts, Unity needs to rebuild them to generate the corresponding C# classes. Until this rebuild happens, any new scripts or changes won't be available in the editor (e.g., you won't be able to add a new Lua component to a Game Object).

To trigger a Lua rebuild, create a .rebuild file in the project root:

touch .rebuild

When the .rebuild file is detected:

  • On macOS, the Unity window will be brought to the foreground. On Windows, you should focus the window manually first (see "Focusing the Unity editor" above).
  • Lua scripts are rebuilt via Highrise/Lua/Rebuild All
  • The .rebuild file is automatically deleted after being processed

You should trigger a Lua rebuild when:

  • You've created a new Lua script and need to add it as a component to a Game Object
  • You've modified Lua script properties (fields) and need the changes reflected in the editor
  • You're seeing errors about missing Lua-generated types

After triggering a Lua rebuild, you should:

  1. Wait ~5-10 seconds for compilation.
  2. Check Packages/com.pz.studio.generated/Runtime/Highrise.Lua.Generated/ for the generated wrapper.
  3. If the generated wrapper is not found, check the console for errors before retrying.

Reading the Unity console

Highrise Studio captures Unity console output to a JSON file for debugging and error tracking. You can find the console log at Temp/Highrise/Serializer/console.json. The file contains the most recent 500 log entries and is updated every 0.5 seconds when new messages are logged.

The JSON file is structured as an array of log entries:

[
  {
    "message": "the log message text",
    "stackTrace": "the stack trace if available (often empty for simple logs)",
    "logType": "Log | Warning | Error | Assert | Exception",
    "timestamp": "2024-01-15 14:30:45.123"
  }
]

Use this to check for errors, warnings, or debug output when troubleshooting issues. For example, to see the most recent errors:

jq '[.[] | select(.logType == "Error" or .logType == "Exception")] | .[-5:]' Temp/Highrise/Serializer/console.json

Capturing a screenshot

To capture a screenshot of the Unity Game view, focus the window (see "Focusing the Unity editor" above) and then create a .screenshot file in the project root:

touch .screenshot

When the .screenshot file is detected:

  • On macOS, the Unity window will be brought to the foreground automatically. On Windows, you must focus the window manually first.
  • A screenshot of the Game view is captured and saved to Temp/Highrise/Serializer/screenshot.png
  • The .screenshot file is automatically deleted after being processed

This is useful for visually inspecting the current state of the game, debugging UI layouts, or verifying that changes appear correctly. The screenshot captures whatever is currently visible in the Game view, so ensure the Game view is showing what you want to capture.

Instructions for reading and editing

Add the following steps to your todo list:

  1. Check that Temp/Highrise/Serializer/active_scene.json exists and was modified within the past hour (use find Temp/Highrise/Serializer/active_scene.json -mmin -60 to verify). If it does not exist or is stale, follow these steps: a. Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-serializer.sh ${CLAUDE_PLUGIN_ROOT} to ensure the Serializer scripts are symlinked. b. Ask the user to turn on JSON serialization in the Unity toolbar, under Highrise > Studio.
  2. Use your tools (jq, grep, etc.) to read the relevant parts of the JSON file. For example, to list the names of the root Game Objects in the scene, you can use the following command: jq -r '.SceneRoot.children[].properties.name' Temp/Highrise/Serializer/active_scene.json. Do not make any changes to the JSON file.
  3. If needed, create the Temp/Highrise/Serializer/edit.json file and write the edits to it.
  4. After creating the edit.json file, focus the Unity editor (see "Focusing the Unity editor" above) to trigger it to process the pending changes.
  5. Check your work by doing some or all of the following, as needed: a. Check that the desired updates are reflected in active_scene.json. b. Capture a screenshot of the Unity editor to verify the changes (see "Capturing a screenshot" above). c. Enter play mode to test the changes (see "Toggling play mode" above).