unity-editor

Remote control Unity Editor via CLI using unityctl. Use when working with Unity projects to enter/exit play mode, compile scripts, view console logs, load scenes, run tests, capture screenshots, or execute C# code for debugging. Activate when user mentions Unity, play mode, compilation, or needs to interact with a running Unity Editor.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 12, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a powerful CLI-based interface to remote control the Unity Editor using unityctl. It streamlines game development workflows by enabling automated script compilation, play mode management, real-time log monitoring, and the execution of arbitrary C# code for advanced debugging and scene manipulation directly through the AI agent.

Use Cases

  • Automated Compilation & Testing: Trigger asset refreshes and run Unity tests (Edit/Play mode) directly from the chat interface to maintain code integrity and catch errors early.
  • Advanced Debugging: Execute custom C# snippets via Roslyn to inspect live GameObjects, check component values, or modify the game state in real-time without manual editor interaction.
  • Editor Lifecycle Management: Remotely launch or stop the Unity Editor, switch between scenes, and toggle Play Mode to speed up iterative development cycles.
  • Visual Verification & Logging: Capture high-quality screenshots of the current editor view and monitor console logs with stack traces to diagnose runtime issues efficiently.
nameunity-editor
descriptionRemote control Unity Editor via CLI using unityctl. Use when working with Unity projects to launch/stop editor, enter/exit play mode, compile scripts, view logs, load scenes, run tests, capture screenshots, or execute C# code for debugging. Activate when user mentions Unity, play mode, compilation, or needs to interact with a running Unity Editor.

unityctl - Unity Editor Remote Control

Control a running Unity Editor from the command line without batch mode.

Instructions

Setup (Required First)

  1. Start the bridge daemon: unityctl bridge start
  2. Launch Unity: unityctl editor run or manually open the project in Unity Editor
  3. Verify connection: unityctl status

Refresh Assets After Script Changes

After modifying C# scripts, refresh assets to compile:

unityctl asset refresh

Returns compilation errors directly in the output (non-zero exit code on failure). Fix errors and re-run until compilation succeeds before entering play mode.

Common Commands

Status & Bridge:

unityctl status           # Check Unity running, bridge, and connection status
unityctl bridge start     # Start bridge daemon (runs in background)
unityctl bridge stop      # Stop bridge

Editor Lifecycle:

unityctl editor run         # Launch Unity Editor (auto-detects version)
unityctl editor stop        # Stop running Unity Editor

Play Mode:

unityctl play enter       # Enter play mode
unityctl play exit        # Exit play mode

Logs:

unityctl logs                 # Show all logs since last clear (auto-clears on play enter and compile)
unityctl logs -n 50           # Limit to last 50 entries
unityctl logs --stack         # Show stack traces for log entries
unityctl logs --full          # Show full history (ignore clear boundary)

Scenes:

unityctl scene list                            # List scenes
unityctl scene load Assets/Scenes/Main.unity   # Load scene

Testing:

unityctl test run                    # Run edit mode tests
unityctl test run --mode playmode    # Play mode tests

Screenshots:

unityctl screenshot capture          # Capture screenshot

Script Execution (Debugging Power Tool)

Execute arbitrary C# in the running editor via Roslyn. Invaluable for debugging and automation.

// tmp/get-version.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        return Application.version;
    }
}
unityctl script execute -f tmp/get-version.cs

You can also execute code directly with -c:

unityctl script execute -c "using UnityEngine; public class Script { public static object Main() { return Application.version; } }"

Scripts must define a class with a public static object Main() method. The return value is JSON-serialized.

Getting Help

unityctl --help              # List all commands
unityctl <command> --help    # Command-specific help

Examples

Workflow: Edit script, compile, and test:

# After editing C# files...
unityctl asset refresh       # Returns compilation errors if any
unityctl play enter
unityctl logs                # Check runtime logs (shows all since play enter)
unityctl play exit

Debug: Find all GameObjects in scene:

// tmp/find-objects.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        return GameObject.FindObjectsOfType<GameObject>().Length;
    }
}
unityctl script execute -f tmp/find-objects.cs

Debug: Inspect Player position:

// tmp/find-player.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        var go = GameObject.Find("Player");
        return go?.transform.position.ToString() ?? "not found";
    }
}
unityctl script execute -f tmp/find-player.cs

Debug: Log message to Unity console:

// tmp/log-message.cs
using UnityEngine;

public class Script
{
    public static object Main()
    {
        Debug.Log("Hello from CLI");
        return "logged";
    }
}
unityctl script execute -f tmp/log-message.cs

Best Practices

  • Run unityctl status to check overall project status before running commands
  • Always run unityctl asset refresh after modifying C# files before entering play mode
  • For script execution, write scripts to tmp/<scriptname>.cs and execute with -f

Troubleshooting

Run unityctl status first to diagnose issues.

Problem Solution
Bridge not responding unityctl bridge stop then unityctl bridge start
Editor not connected to newly started bridge Normal, editor plugin uses exponential backoff, up to 30 seconds
Connection lost after compile Normal - domain reload. Auto-reconnects.
"Project not found" Run unityctl setup or unityctl config set project-path <path>
Editor not found Use --unity-path to specify Unity executable