unity-editor-toolkit

Purpose

Unity Editor Toolkit enables comprehensive Unity Editor automation and control from Claude Code. It provides:

• Extensive Command Coverage: 500+ commands spanning 25 Unity Editor categories
• Real-time Communication: Instant bidirectional WebSocket connection (JSON-RPC 2.0)
• SQLite Database Integration: Real-time GameObject synchronization with GUID-based persistence
  • GUID-based Identification: Persistent GameObject tracking across Unity sessions
  • Multi-scene Support: Synchronize all loaded scenes simultaneously (1s interval)
  • Command Pattern: Undo/Redo support for database operations
  • Auto Migration: Automatic schema migration system
  • Batch Operations: Efficient bulk inserts, updates, and deletes (500 objects/batch)
• Menu Execution: Run Unity Editor menu items programmatically (Window, Assets, Edit, GameObject menus)
• ScriptableObject Management: Complete CRUD operations with array/list support and all field types
  • Array/List Operations: Add, remove, get, clear elements with nested access (items[0].name)
  • All Field Types: Integer, Float, String, Boolean, Vector*, Color, Quaternion, Bounds, AnimationCurve, ObjectReference, and more
  • Nested Property Traversal: Access deeply nested fields with dot notation and array indices
• Deep Editor Integration: GameObject/hierarchy, transforms, components, scenes, materials, prefabs, animation, physics, lighting, build pipeline, and more
• Security First: Multi-layer defense against injection attacks (SQL, command, JSON, path traversal) and unauthorized access
• Production Ready: Cross-platform support with robust error handling and logging

Always run scripts with --help first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

---

📚 문서 우선 원칙 (필수)

⚠️ CRITICAL: Unity Editor Toolkit skill을 사용할 때는 반드시 다음 순서를 따르세요:

1️⃣ Reference 문서 확인 (필수)

명령어를 사용하기 전에 반드시 skills/references/ 폴더의 해당 문서를 읽으세요:

• COMMANDS.md - 모든 명령어의 카테고리 및 개요
• Category-specific docs - 사용할 명령어의 카테고리 문서:
  • Component Commands - comp list/add/remove/enable/disable/get/set/inspect/move-up/move-down/copy
  • GameObject Commands - go find/create/destroy/set-active/set-parent/get-parent/get-children
  • Transform Commands - tf get/set-position/set-rotation/set-scale
  • Scene Commands - scene current/list/load/new/save/unload/set-active
  • Console Commands - console logs/clear
  • EditorPrefs Commands - prefs get/set/delete/list/clear/import
  • Other Categories - 추가 명령어 카테고리

2️⃣ --help 실행

# 모든 명령어 확인
cd <unity-project-root> && node .unity-websocket/uw --help

# 특정 명령어의 옵션 확인
cd <unity-project-root> && node .unity-websocket/uw <command> --help

3️⃣ 예제 실행

reference 문서의 Examples 섹션을 참고하여 명령어를 실행하세요.

4️⃣ 소스 코드 읽기 (최후의 수단)

• reference 문서와 --help만으로는 해결 안 될 때만 소스 코드를 읽으세요
• 소스 코드는 컨텍스트 윈도우를 많이 차지하므로 가능하면 피하세요

이 순서를 무시하면:

• ❌ 명령어 사용법을 잘못 이해할 수 있음
• ❌ 옵션을 놓쳐서 원하지 않는 결과가 나올 수 있음
• ❌ 컨텍스트 윈도우를 낭비할 수 있음

---

When to Use

Use Unity Editor Toolkit when you need to:

1. Automate Unity Editor Tasks

   • Create and manipulate GameObjects, components, and hierarchies
   • Configure scenes, materials, and rendering settings
   • Control animation, physics, and particle systems
   • Manage assets, prefabs, and build pipelines

2. Real-time Unity Testing

   • Monitor console logs and errors during development
   • Query GameObject states and component properties
   • Test scene configurations and gameplay logic
   • Debug rendering, physics, or animation issues

3. Batch Operations

   • Create multiple GameObjects with specific configurations
   • Apply material/shader changes across multiple objects
   • Setup scene hierarchies from specifications
   • Automate repetitive Editor tasks

4. Menu and Editor Automation

   • Execute Unity Editor menu items programmatically (menu run "Window/General/Console")
   • Open editor windows and tools via command line
   • Automate asset refresh, reimport, and build operations
   • Query available menu items with wildcard filtering

5. ScriptableObject Management

   • Create and configure ScriptableObject assets programmatically
   • Read and modify all field types (Vector, Color, Quaternion, AnimationCurve, etc.)
   • Manipulate arrays/lists with full CRUD operations
   • Access nested properties with array index notation (items[0].stats.health)
   • Query ScriptableObject types and inspect asset metadata

6. Database-Driven Workflows

   • Persistent GameObject tracking across Unity sessions with GUID-based identification
   • Real-time synchronization of all loaded scenes to SQLite database
   • Analytics and querying of GameObject hierarchies and properties
   • Undo/Redo support for database operations via Command Pattern
   • Efficient batch operations (500 objects/batch) for large scene management

7. CI/CD Integration

   • Automated builds with platform-specific settings
   • Test Runner integration for unit/integration tests
   • Asset validation and integrity checks
   • Build pipeline automation

Prerequisites

Unity Project Setup

1. Install Unity Editor Toolkit Server Package

   • Via Unity Package Manager (Git URL or local path)
   • Requires Unity 2020.3 or higher
   • Package location: skills/assets/unity-package

2. Configure WebSocket Server

   • Open Unity menu: Tools > Unity Editor Toolkit > Server Window
   • Plugin scripts path auto-detected from ~/.claude/plugins/...
   • Click "Install CLI" to build WebSocket server (one-time setup)
   • Server starts automatically when Unity Editor opens

3. Database Setup (Optional)

   • In the Server window, switch to "Database" tab
   • Click "Connect" to initialize SQLite database
   • Database file location: {ProjectRoot}/.unity-websocket/unity-editor.db
   • Click "Start Sync" to enable real-time GameObject synchronization (1s interval)
   • GUID Components: GameObjects are automatically tagged with persistent GUIDs
   • Multi-scene: All loaded scenes are synchronized automatically
   • Analytics: View sync stats, database health, and Undo/Redo history

4. Server Status

   • Port: Auto-assigned from range 9500-9600
   • Status file: {ProjectRoot}/.unity-websocket/server-status.json
   • CLI automatically detects correct port from this file

5. Dependencies

   • websocket-sharp (install via package installation scripts)
   • Newtonsoft.Json (Unity's built-in version)
   • Cysharp.UniTask (for async/await database operations)
   • SQLite-net (embedded SQLite database)

Claude Code Plugin

The Unity Editor Toolkit plugin provides CLI commands for Unity Editor control.

Core Workflow

1. Connection

Unity Editor Toolkit CLI automatically:

• Detects Unity project via .unity-websocket/server-status.json
• Reads port information from status file (9500-9600 range)
• Connects to WebSocket server if Unity Editor is running

2. Execute Commands

⚠️ Before executing ANY command, check the reference documentation for your command category (see "📚 문서 우선 원칙" section above).

Unity Editor Toolkit provides 86+ commands across 15 categories. All commands run from the Unity project root:

cd <unity-project-root> && node .unity-websocket/uw <command> [options]

Available Categories (Implemented):

#	Category	Commands	Reference
1	Connection & Status	1	COMMANDS_CONNECTION_STATUS.md
2	GameObject & Hierarchy	8	COMMANDS_GAMEOBJECT_HIERARCHY.md
3	Transform	4	COMMANDS_TRANSFORM.md
4	Component ✨	10	COMMANDS_COMPONENT.md
5	Scene Management	7	COMMANDS_SCENE.md
6	Asset Database & Editor	3	COMMANDS_EDITOR.md
7	Console & Logging	2	COMMANDS_CONSOLE.md
8	EditorPrefs Management	6	COMMANDS_PREFS.md
9	Wait Commands	4	COMMANDS_WAIT.md
10	Chain Commands	2	COMMANDS_CHAIN.md
11	Menu Execution	2	COMMANDS_MENU.md
12	Asset Management	9	COMMANDS_ASSET.md
13	Prefab	12	COMMANDS_PREFAB.md
14	Material	9	COMMANDS_MATERIAL.md
15	Shader	7	COMMANDS_SHADER.md

Usage:

cd <unity-project-root> && node .unity-websocket/uw <command> [options]

Required: Check Documentation

# 1. 먼저 명령어 카테고리의 reference 문서를 읽으세요
# 예: Component 명령어 사용 → skills/references/COMMANDS_COMPONENT.md 읽기

# 2. --help로 명령어 옵션 확인
cd <unity-project-root> && node .unity-websocket/uw --help
cd <unity-project-root> && node .unity-websocket/uw <command> --help

# 3. reference 문서의 예제를 참고하여 실행

📖 Complete Documentation by Category

Required Reading: Before using any command, read the Category-specific reference document:

• 🔴 MUST READ FIRST - COMMANDS.md - Overview and command ro

---

Content truncated.