Initial commit

2025-11-29 18:19:28 +08:00
commit 1da7b24c8e
254 changed files with 43797 additions and 0 deletions
--- a/skills/references/COMMANDS_GAMEOBJECT_HIERARCHY.md
+++ b/skills/references/COMMANDS_GAMEOBJECT_HIERARCHY.md
@@ -0,0 +1,383 @@
+# Unity Editor Toolkit - GameObject & Hierarchy Commands
+
+Complete reference for GameObject manipulation and hierarchy query commands.
+
+**Last Updated**: 2025-01-13
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go find
+
+Find GameObject by name or hierarchical path.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go find <name> [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path (e.g., "Player" or "Environment/Trees/Oak")
+```
+
+**Options:**
+```
+-c, --with-components  Include component list in output
+--with-children        Include children hierarchy
+--full                 Include all details (components + children)
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Find GameObject by name
+cd <unity-project-root> && node .unity-websocket/uw go find "Player"
+
+# Find with full hierarchy path
+cd <unity-project-root> && node .unity-websocket/uw go find "Environment/Terrain/Trees"
+
+# Include component information
+cd <unity-project-root> && node .unity-websocket/uw go find "Player" --with-components
+
+# Get all details in JSON format
+cd <unity-project-root> && node .unity-websocket/uw go find "Enemy" --full --json
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go create
+
+Create new GameObject.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go create <name> [options]
+```
+
+**Arguments:**
+```
+<name>                 Name for the new GameObject
+```
+
+**Options:**
+```
+-p, --parent <parent>  Parent GameObject name or path
+--primitive <type>     Create primitive: cube, sphere, cylinder, capsule, plane, quad
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Create empty GameObject
+cd <unity-project-root> && node .unity-websocket/uw go create "NewObject"
+
+# Create with parent
+cd <unity-project-root> && node .unity-websocket/uw go create "Child" --parent "Parent"
+
+# Create primitive
+cd <unity-project-root> && node .unity-websocket/uw go create "MyCube" --primitive cube
+
+# Create nested object
+cd <unity-project-root> && node .unity-websocket/uw go create "Enemy" --parent "Enemies/Group1"
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go destroy
+
+Destroy GameObject.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go destroy <name> [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path to destroy
+```
+
+**Options:**
+```
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Destroy GameObject
+cd <unity-project-root> && node .unity-websocket/uw go destroy "OldObject"
+
+# Destroy nested GameObject
+cd <unity-project-root> && node .unity-websocket/uw go destroy "Enemies/Enemy1"
+
+# Get JSON response
+cd <unity-project-root> && node .unity-websocket/uw go destroy "Temp" --json
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go set-active
+
+Set GameObject active state.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go set-active <name> <active> [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path
+<active>               Active state: true or false
+```
+
+**Options:**
+```
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Activate GameObject
+cd <unity-project-root> && node .unity-websocket/uw go set-active "Player" true
+
+# Deactivate GameObject
+cd <unity-project-root> && node .unity-websocket/uw go set-active "Enemy" false
+
+# Set nested GameObject state
+cd <unity-project-root> && node .unity-websocket/uw go set-active "UI/Menu/Settings" false
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go set-parent
+
+Set or remove parent of GameObject.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go set-parent <name> [parent] [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path
+[parent]               Parent GameObject name (omit to remove parent)
+```
+
+**Options:**
+```
+--world-position-stays <bool>  Keep world position (default: true)
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Set parent (attach "Weapon" to "Player")
+cd <unity-project-root> && node .unity-websocket/uw go set-parent "Weapon" "Player"
+
+# Remove parent (detach to root)
+cd <unity-project-root> && node .unity-websocket/uw go set-parent "Weapon"
+
+# Set parent without keeping world position
+cd <unity-project-root> && node .unity-websocket/uw go set-parent "Child" "Parent" --world-position-stays false
+
+# Reparent nested object
+cd <unity-project-root> && node .unity-websocket/uw go set-parent "UI/Menu" "Canvas"
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go get-parent
+
+Get parent information of GameObject.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go get-parent <name> [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path
+```
+
+**Options:**
+```
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Get parent info
+cd <unity-project-root> && node .unity-websocket/uw go get-parent "Weapon"
+
+# Check if object has parent
+cd <unity-project-root> && node .unity-websocket/uw go get-parent "Player" --json
+
+# Get parent of nested object
+cd <unity-project-root> && node .unity-websocket/uw go get-parent "Enemies/Enemy1"
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw go get-children
+
+Get children of GameObject.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw go get-children <name> [options]
+```
+
+**Arguments:**
+```
+<name>                 GameObject name or path
+```
+
+**Options:**
+```
+-r, --recursive        Get all descendants (not just direct children)
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Get direct children
+cd <unity-project-root> && node .unity-websocket/uw go get-children "Player"
+
+# Get all descendants recursively
+cd <unity-project-root> && node .unity-websocket/uw go get-children "Player" --recursive
+
+# Get children with JSON output
+cd <unity-project-root> && node .unity-websocket/uw go get-children "Canvas" --json
+
+# Count nested objects
+cd <unity-project-root> && node .unity-websocket/uw go get-children "Environment" --recursive --json
+```
+
+---
+
+## cd <unity-project-root> && node .unity-websocket/uw hierarchy
+
+Query Unity GameObject hierarchy with tree visualization.
+
+**Usage:**
+```bash
+cd <unity-project-root> && node .unity-websocket/uw hierarchy [options]
+```
+
+**Options:**
+```
+-r, --root-only        Show only root GameObjects (no children)
+-i, --include-inactive Include inactive GameObjects in output
+-a, --active-only      Show only active GameObjects (opposite of -i)
+-d, --depth <n>        Limit hierarchy depth (e.g., 2 for 2 levels)
+-f, --filter <name>    Filter GameObjects by name (case-insensitive)
+-c, --with-components  Include component information for each GameObject
+--json                 Output in JSON format
+--timeout <ms>         Connection timeout in milliseconds (default: 30000)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# View full hierarchy
+cd <unity-project-root> && node .unity-websocket/uw hierarchy
+
+# Show only root GameObjects
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --root-only
+
+# Limit depth to 2 levels
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --depth 2
+
+# Filter by name
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --filter "enemy"
+
+# Show only active GameObjects with components
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --active-only --with-components
+
+# Get JSON output
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --json
+```
+
+---
+
+## Global Options
+
+All commands support these global options:
+
+```
+-V, --version          Output the version number
+-v, --verbose          Enable verbose logging
+-p, --port <number>    Unity WebSocket port (overrides auto-detection)
+-h, --help             Display help for command
+```
+
+**Examples:**
+```bash
+# Check CLI version
+cd <unity-project-root> && node .unity-websocket/uw --version
+
+# Enable verbose logging
+cd <unity-project-root> && node .unity-websocket/uw --verbose hierarchy
+
+# Use specific port
+cd <unity-project-root> && node .unity-websocket/uw --port 9501 go find "Player"
+```
+
+---
+
+## Notes
+
+### Port Auto-Detection
+
+Unity Editor Toolkit CLI automatically detects the Unity WebSocket server port by reading `.unity-websocket/server-status.json` in the Unity project directory. You only need to specify `--port` if:
+- Running multiple Unity Editor instances
+- Server is using non-default port range
+
+### JSON Output
+
+All commands support `--json` flag for machine-readable output. Useful for:
+- CI/CD pipelines
+- Automation scripts
+- Integration with other tools
+
+### Timeout Configuration
+
+Default timeout is 30 seconds (30000ms). Increase for operations that may take longer:
+
+```bash
+# Longer timeout for complex operations
+cd <unity-project-root> && node .unity-websocket/uw hierarchy --timeout 60000
+```
+
+### Error Handling
+
+Commands return appropriate exit codes:
+- `0`: Success
+- `1`: Error (connection failed, command failed, invalid parameters, etc.)
+
+Check error messages for details on failures.
+
+---
+
+**See Also:**
+- [QUICKSTART.md](../../QUICKSTART.md) - Quick setup and first commands
+- [COMMANDS.md](./COMMANDS.md) - Complete command roadmap
+- [API_COMPATIBILITY.md](../../API_COMPATIBILITY.md) - Unity version compatibility
+- [TEST_GUIDE.md](../../TEST_GUIDE.md) - Unity C# server testing guide