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:

Create the .cs file locally using Write tool at Assets/YourFolder/YourScript.cs

Call refresh_assets to make Unity detect the new file:

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

Unity will automatically compile the script
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

Get scene state - Understand current hierarchy before changes
Plan operations - Identify exact paths for objects to modify
Execute commands - Use batch for multiple related operations
Verify results - Check scene hierarchy to confirm changes
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

Open Unity Editor
Open: Tools > ClaudeAgent > Unity Command Server
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:

Wait a moment (1-2 seconds) after refresh_assets before sending the next command
If connection fails, retry the command once
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.

unity-editor-operations

Unity Editor Operations Skill

Overview