Lesson 2 · Unity

Drive Unity from CLI and MCP

Direct answer: For builds, tests, and CI, use Unity’s official Editor command line: -batchmode -quit -projectPath -executeMethod -logFile. For a live Editor that an agent can poke, add a community MCP package or a thin HTTP CLI. Those are not Unity Technologies products.

Official CLI first

Unity documents the Editor arguments in the Editor command line arguments reference. The pattern they show is:

unity.exe -batchmode -quit -executeMethod MyClass.MyMethod

A game project usually needs the path and a log you can read after the agent finishes:

# macOS
"/Applications/Unity/Hub/Editor/6000.0.0f1/Unity.app/Contents/MacOS/Unity" \
  -batchmode -nographics -quit \
  -projectPath "/Users/you/Games/Arena" \
  -executeMethod BuildScript.BuildWebGL \
  -logFile "/tmp/unity-build.log"

# Windows
"C:\Program Files\Unity\Hub\Editor\6000.0.0f1\Editor\Unity.exe" ^
  -batchmode -nographics -quit ^
  -projectPath "C:\Projects\Arena" ^
  -executeMethod BuildScript.BuildWebGL ^
  -logFile "C:\Logs\unity-build.log"

-batchmode runs without the interactive loop. -nographics skips a GPU so CI machines still work. -quit exits when the method returns. -executeMethod must be a static method Unity can find after scripts compile. If compile fails, Unity may never reach your method — read the log, do not retry blindly.

// Assets/Editor/BuildScript.cs
using UnityEditor;
public static class BuildScript {
    public static void BuildWebGL() {
        BuildPipeline.BuildPlayer(
            new[] { "Assets/Scenes/Main.unity" },
            "Builds/WebGL",
            BuildTarget.WebGL,
            BuildOptions.None
        );
    }
}

When the Editor must stay open

Batch mode cannot click Play, move a cube you are looking at, or read the current Hierarchy the way a human does. That is the MCP / live-CLI job. Three maintained community options as of 2026-08-13:

Coplay’s quickstart is: add the package, open Window → MCP for Unity → Configure All Detected Clients, then prompt Create a cube at the origin and add a Rigidbody. IvanMurzak’s pitch is the same loop plus “any C# method may be turned into a tool by a single line.” The thin CLI exists because some people do not want Python, uv, or a second protocol — the Editor already listens on HTTP.

Unity also throttles the Editor when the window is unfocused. The unity-cli README’s practical fix is Edit → Preferences → General → Interaction Mode → No Throttling if background commands feel stuck.

Agent rules that keep the project alive

1. First prompt: list open scenes and GameObjects. No creates, no deletes, no Play Mode.
2. Pin the Unity version in the command. Do not let the agent guess Hub’s latest Editor.
3. One live connection. Do not run Coplay MCP and unity-cli against the same Editor until you know they do not fight over play mode.
4. Treat script edits as git work. An agent that rewrites Update() can compile-lock the Editor.
5. After Play Mode, stop Play Mode. A forgotten Play session blocks batch builds.

First inspect only.
Then: create an empty GameObject named Agent_Probe at the origin.
Do not enter Play Mode. Do not import packages. Commit nothing.

Try the command rehearsal

This tab cannot launch Unity. It walks the same order you should demand from an agent: status → inspect → one named object → batch build. Copy the command that appears and run it on your machine.

$ unity-cli status
# demo only — no Editor attached

How this connects to InstantGames

Most InstantGames titles are HTML5. Unity still matters when you need a WebGL export, a 3D prototype, or a build you can drop beside a Canvas game. Keep rules in code you can read. Use the agent for scene chores and CI glue, not as the source of gameplay.