10 KiB
10 KiB
Unity Editor Toolkit - GameObject & Hierarchy Commands
Complete reference for GameObject manipulation and hierarchy query commands.
Last Updated: 2025-01-13
cd && node .unity-websocket/uw go find
Find GameObject by name or hierarchical path.
Usage:
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:
# 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 && node .unity-websocket/uw go create
Create new GameObject.
Usage:
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:
# 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 && node .unity-websocket/uw go destroy
Destroy GameObject.
Usage:
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:
# 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 && node .unity-websocket/uw go set-active
Set GameObject active state.
Usage:
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:
# 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 && node .unity-websocket/uw go set-parent
Set or remove parent of GameObject.
Usage:
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:
# 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 && node .unity-websocket/uw go get-parent
Get parent information of GameObject.
Usage:
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:
# 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 && node .unity-websocket/uw go get-children
Get children of GameObject.
Usage:
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:
# 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 && node .unity-websocket/uw hierarchy
Query Unity GameObject hierarchy with tree visualization.
Usage:
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:
# 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:
# 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:
# Longer timeout for complex operations
cd <unity-project-root> && node .unity-websocket/uw hierarchy --timeout 60000
Error Handling
Commands return appropriate exit codes:
0: Success1: Error (connection failed, command failed, invalid parameters, etc.)
Check error messages for details on failures.
See Also:
- QUICKSTART.md - Quick setup and first commands
- COMMANDS.md - Complete command roadmap
- API_COMPATIBILITY.md - Unity version compatibility
- TEST_GUIDE.md - Unity C# server testing guide