7.7 KiB
7.7 KiB
Unity Editor Toolkit - Scene Management Commands
Complete reference for scene management commands.
Last Updated: 2025-01-25 Commands: 7 commands
cd && node .unity-websocket/uw scene current
Get current active scene information.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene current [options]
Options:
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Get current scene info
cd <unity-project-root> && node .unity-websocket/uw scene current
# Get JSON output
cd <unity-project-root> && node .unity-websocket/uw scene current --json
cd && node .unity-websocket/uw scene list
List all loaded scenes.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene list [options]
Options:
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# List all scenes
cd <unity-project-root> && node .unity-websocket/uw scene list
# Get JSON output
cd <unity-project-root> && node .unity-websocket/uw scene list --json
cd && node .unity-websocket/uw scene load
Load scene by name or path.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene load <name> [options]
Arguments:
<name> Scene name or path (without .unity extension)
Options:
-a, --additive Load scene additively (don't unload current scenes)
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Load scene (replace current)
cd <unity-project-root> && node .unity-websocket/uw scene load "MainMenu"
# Load scene additively
cd <unity-project-root> && node .unity-websocket/uw scene load "UIOverlay" --additive
# Load scene by path
cd <unity-project-root> && node .unity-websocket/uw scene load "Assets/Scenes/Level1"
cd && node .unity-websocket/uw scene new
Create a new scene.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene new [options]
Options:
-e, --empty Create empty scene (no default camera/light)
-a, --additive Add new scene without replacing current scenes
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Create new scene with default objects (Main Camera, Directional Light)
cd <unity-project-root> && node .unity-websocket/uw scene new
# Create empty scene
cd <unity-project-root> && node .unity-websocket/uw scene new --empty
# Create new scene additively (keep current scenes)
cd <unity-project-root> && node .unity-websocket/uw scene new --additive
# Create empty scene additively
cd <unity-project-root> && node .unity-websocket/uw scene new -e -a
cd && node .unity-websocket/uw scene save
Save scene to disk.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene save [path] [options]
Arguments:
[path] Optional path for Save As (e.g., "Assets/Scenes/NewScene.unity")
Options:
-s, --scene <name> Specific scene name to save (default: active scene)
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Save active scene
cd <unity-project-root> && node .unity-websocket/uw scene save
# Save As - save to new location
cd <unity-project-root> && node .unity-websocket/uw scene save "Assets/Scenes/Level2.unity"
# Save specific scene (multi-scene editing)
cd <unity-project-root> && node .unity-websocket/uw scene save --scene "UIScene"
cd && node .unity-websocket/uw scene unload
Unload a scene from the editor.
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene unload <name> [options]
Arguments:
<name> Scene name or path to unload
Options:
-r, --remove Remove scene completely (default: just unload/close)
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Unload scene by name
cd <unity-project-root> && node .unity-websocket/uw scene unload "UIOverlay"
# Unload scene by path
cd <unity-project-root> && node .unity-websocket/uw scene unload "Assets/Scenes/Level1.unity"
# Remove scene completely
cd <unity-project-root> && node .unity-websocket/uw scene unload "TempScene" --remove
Note: Cannot unload the last remaining scene. At least one scene must always be loaded.
cd && node .unity-websocket/uw scene set-active
Set a scene as the active scene (for multi-scene editing).
Usage:
cd <unity-project-root> && node .unity-websocket/uw scene set-active <name> [options]
Arguments:
<name> Scene name or path to set as active
Options:
--json Output in JSON format
--timeout <ms> Connection timeout in milliseconds (default: 30000)
-h, --help Display help for command
Examples:
# Set active scene by name
cd <unity-project-root> && node .unity-websocket/uw scene set-active "MainScene"
# Set active scene by path
cd <unity-project-root> && node .unity-websocket/uw scene set-active "Assets/Scenes/Level1.unity"
Note: The target scene must be loaded before it can be set as active.
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 scene current
# Use specific port
cd <unity-project-root> && node .unity-websocket/uw --port 9501 scene load "Level1"
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 scene load "Level1" --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