Unity Editor Operations Skill

Overview

This skill enables Unity Editor operations through JSON commands. Commands are sent via send_message.py to Unity Command Server and executed immediately with results returned.

Architecture:

Claude Code (this side - Agent)
  ↓ JSON command
send_message.py (WebSocket client)
  ↓ ws://127.0.0.1:8766
Unity Command Server (simple executor)
  ↓
CommandExecutor
  ↓
Unity Editor Operations
  ↓ JSON result
send_message.py
  ↓
Claude Code (receives result)

Quick Start

1. Open Unity Command Server

In Unity Editor: Tools > ClaudeAgent > Unity Command Server

2. Send Command

python .claude/skills/unity-editor-operations/send_message.py '{"operation":"create_primitive","params":{"type":"sphere","name":"MySphere","color":"red"}}'

3. Check Result

✓ Connected to ws://127.0.0.1:8766/
📤 Sending: {"operation":"create_primitive",...}
⏳ Waiting for response (timeout: 10s)...

✓ Command executed successfully
   Time: 2025-11-25 18:00:00

send_message.py Usage

Located at: .claude/skills/unity-editor-operations/send_message.py

python send_message.py '<json_command>'

Features:

• WebSocket connection to Unity Command Server
• 10 second timeout
• JSON result parsing and display
• Exit code: 0 (success) / 1 (failure)

Response Format:

{
  "success": true,
  "result": { ... },
  "timestamp": "2025-11-25 12:00:00"
}

JSON Command Format

{
  "operation": "operation_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Common Parameters

Space Parameters

Several operations support position_space, rotation_space, and scale_space parameters:

Parameter	Values	Default
position_space	"local" / "world"	"world" if no parent, "local" if parent specified
rotation_space	"local" / "world"	"world" if no parent, "local" if parent specified
scale_space	"local" / "world"	"world" if no parent, "local" if parent specified

Applies to: create_primitive, create_empty, create_line, instantiate_prefab, create_terrain

Result messages show which space was used: Created sphere: MySphere (position: world, scale: local)

Supported Operations (60 total)

Looking up operation details: Use Grep "### operation_name" File.md -A 25 to retrieve only the specific operation section instead of reading the entire file. This reduces token consumption.

GameObject Operations

Operation	Description
create_primitive	Create sphere, cube, etc. ※VGM: markers only
create_empty	Create empty GameObject
delete_gameobject	Delete by path/name
set_active	Set active state
tag	Get/set tag (unified)
create_tag	Create new tag in project
delete_tag	Delete custom tag from project
find_gameobject	Find and return info
set_name	Rename
set_parent	Set parent-child relationship
duplicate_gameobject	Duplicate
look_at	Orient towards target
create_line	Create line between two points

Transform Operations

Operation	Description
transform	Get/set position, rotation, scale (unified)

Component Operations

Operation	Description
add_component	Add component
remove_component	Remove component
get_component	Get component info
set_component_property	Set property value
get_components	List all components
set_object_reference	Set GameObject/Component reference

Material Operations

Operation	Description
material	Get/set material properties (unified)
create_material	Create new material

Scene Operations

Operation	Description
open_scene	Open scene
save_scene	Save scene
create_scene	Create new scene
get_scene_hierarchy	Get hierarchy structure
get_active_scene	Get active scene info

Asset Operations

Operation	Description
create_asset	Create text asset
delete_asset	Delete asset
get_asset	Get asset info
import_asset	Re-import asset
refresh_assets	Refresh AssetDatabase
copy_asset	Copy asset
import_package	Import .unitypackage file
list_assets	List assets in folder

Prefab Operations

Operation	Description
create_prefab	Create from GameObject
instantiate_prefab	Instantiate into scene
open_prefab	Open in edit mode
save_prefab	Save prefab

Debugging Operations

Operation	Description
logs	Get console logs (unified: all, errors, statistics)
clear_logs	Clear console logs

Light Operations

Operation	Description
create_light	Create light
light	Get/set light properties (unified)

Camera Operations

Operation	Description
create_camera	Create camera
camera	Get/set camera properties (unified)

Screenshot Operations

Operation	Description
capture_scene_view	Capture scene screenshot

UI Operations

Operation	Description
create_canvas	Create canvas
create_ui	Create UI elements (button, text, image, panel, inputfield, scrollview)
ui	Get/set UI properties (unified)

Editor Operations

Operation	Description
execute_menu_item	Execute menu item
get_editor_state	Get editor state
get_selection	Get selected objects
set_selection	Select object
playmode	Play mode control (play/stop/pause/resume)

Animator Operations

Operation	Description
create_animator_controller	Create AnimatorController asset
create_animator_element	Create state/layer/parameter/transition/blend_tree
delete_animator_element	Delete state/layer/parameter/transition
animator_element	Get/set state/layer/parameter/blend_tree properties
animator	Runtime parameter value get/set

Terrain Operations

Operation	Description
create_terrain	Create terrain
add_terrain_layer	Add texture layer
terrain_height	Get/set/paint terrain height (unified)
terrain_texture	Fill/paint terrain texture (unified)

ProBuilder Operations

Operation	Description
create_probuilder_shape	Create procedural 3D mesh (stair, door, curved_stair, arch, pipe, cone, prism)

Visual Guide Modeling Operations

Operation	Description
create_fitted	Create geometry fitted to vertex positions ※VGM: geometry

Batch Operations (Meta-Operation)

Execute multiple commands in a single request for better performance. This is not a new Unity operation, but a wrapper to execute existing 59 operations in batch.

Batch Format

{
  "operation": "batch",
  "params": {
    "commands": [
      {"operation": "create_primitive", "params": {"type": "sphere", "name": "Ball", "color": "red"}},
      {"operation": "transform", "params": {"path": "Ball", "position": [0, 2, 0]}},
      {"operation": "create_light", "params": {"type": "point", "color": "yellow"}}
    ]
  }
}

Batch Features

Feature	Description
Max commands	20 per batch
Execution order	Sequential (array order)
Error handling	Stops on first error, remaining cancelled
Undo	All commands in one Undo group (single Ctrl+Z)
Nested batch	Not allowed

Batch Response

{
  "success": true,
  "results": [
    {"index": 0, "success": true, "result": "Created sphere: Ball"},
    {"index": 1, "success": true, "result": "Set Ball position to (0,2,0)"},
    {"index": 2, "success": true, "result": "Created point light"}
  ],
  "summary": {
    "total": 3,
    "succeeded": 3,
    "failed": 0,
    "cancelled": 0
  }
}

Batch Error Response

When a command fails, remaining commands are cancelled:

{
  "success": false,
  "results": [
    {"index": 0, "success": true, "result": "Created sphere: Ball"},
    {"index": 1, "success": false, "error": "GameObject not found: MissingObj"},
    {"index": 2, "success": false, "error": "Cancelled: previous command failed"}
  ],
  "summary": {
    "total": 3,
    "succeeded": 1,
    "failed": 1,
    "cancelled": 1
  }
}

When to Use Batch

• Creating multiple related objects
• Setting up a scene with multiple elements
• Any operation requiring 3+ sequential commands
• Performance-critical operations (reduces window activation overhead)

Best Practices

Script Generation: Local File Creation

For C# scripts, create files locally using Claude Code's Write tool instead of WebSocket commands.

This approach is recommended because:

• Faster execution: No WebSocket round-trip required
• Easier debugging: Scripts can be read/modified directly
• No JSON escaping: Avoid complex string escaping issues
• Full IDE support: Syntax highlighting and IntelliSense during creation

Workflow:

1. Create the .cs file locally using Write tool at Assets/YourFolder/YourScript.cs
2. Call refresh_assets to make Unity detect the new file:

   python send_message.py '{"operation":"refresh_assets","params":{}}'
   

3. Unity will automatically compile the script
4. Use logs with filter: "errors" to check for compilation errors if needed

Example script structure:

using UnityEngine;

public class MyBehavior : MonoBehaviour
{
    void Update()
    {
        // Your code here
    }
}

Always Verify Scene State

Before and after operations, use get_scene_hierarchy to confirm the current state:

# Check scene before operations
python send_message.py '{"operation":"get_scene_hierarchy","params":{"max_depth":2}}'

# Perform operations...

# Verify changes after operations
python send_message.py '{"operation":"get_scene_hierarchy","params":{}}'

Why this matters:

• Same-named objects may exist at different hierarchy levels
• Batch delete may miss objects (e.g., root Cube0 vs Cubes/Cube0)
• Confirms all intended changes were applied

Recommended Workflow

1. Get scene state - Understand current hierarchy before changes
2. Plan operations - Identify exact paths for objects to modify
3. Execute commands - Use batch for multiple related operations
4. Verify results - Check scene hierarchy to confirm changes
5. Clean up - Delete any unintended objects

Examples

# Create object
python send_message.py '{"operation":"create_primitive","params":{"type":"sphere","name":"Ball","color":"red","position":[0,1,0]}}'

# Query scene
python send_message.py '{"operation":"get_scene_hierarchy","params":{"max_depth":3}}'

# Modify object
python send_message.py '{"operation":"transform","params":{"path":"Ball","position":[5,0,0],"rotation":[0,45,0]}}'

# Batch operations (max 20 commands)
python send_message.py '{"operation":"batch","params":{"commands":[
  {"operation":"create_primitive","params":{"type":"cube","name":"Floor","scale":[10,0.1,10]}},
  {"operation":"create_primitive","params":{"type":"sphere","name":"Ball","color":"red","position":[0,1,0]}}
]}}'

Server Information

Item	Value
URL	ws://127.0.0.1:8766
Protocol	WebSocket + JSON
Timeout	10 seconds
Unity Window	Tools > ClaudeAgent > Unity Command Server

Troubleshooting

Connection Refused

1. Open Unity Editor
2. Open: Tools > ClaudeAgent > Unity Command Server
3. Verify status is "Running" (green)

Timeout (10s)

• Check Unity Console for errors
• Command may be taking too long
• Restart Command Server

Command Failed

• Check operation name (case-sensitive)
• Verify parameter names
• See category-specific .md files for details
• Errors are returned as-is (no fallback)

Unknown Parameter Warning

If you use an invalid or misspelled parameter name, the command will still execute but include a warning:

Created sphere: MySphere
[WARNING] Unknown parameters ignored: positon, colr

This helps identify typos (e.g., positon instead of position) without failing the command. The warning appears after the result message.

Connection Lost After refresh_assets

The refresh_assets operation may cause a temporary WebSocket disconnection:

Symptoms:

• Commands immediately after refresh_assets fail with connection errors
• Server status shows "Reconnecting..."

Cause: AssetDatabase.Refresh() can trigger a domain reload when new scripts are detected, which restarts the Unity Command Server.

Solution:

1. Wait a moment (1-2 seconds) after refresh_assets before sending the next command
2. If connection fails, retry the command once
3. The server automatically restarts after domain reload - no manual restart needed

Note: This behavior only occurs when refresh_assets detects new or modified scripts that require recompilation. Asset-only changes (textures, prefabs, etc.) do not trigger domain reload.