Working with Unity
Headless modes
The three ways a Unity editor can run in Satura Space, what each one gives up, and how to reveal the real editor window.
Long agent runs and balance grinds don't need pixels. Each Unity session runs in one of three modes, so you stream the game while you watch and drop rendering when nobody is.
The three modes
| Mode | What it does |
|---|---|
| Normal | The default. The editor window is hidden and the game streams into the app with mouse, keyboard and audio. The editor can be revealed. |
| Headless Graphics | Batch mode with a GPU. There's no editor window, but the view still renders and the panel still streams. |
| Headless NoGraphics | Runs -batchmode -nographics: no window, no rendering, no GPU work, one player. The lightest mode, for compiles, handles and logic. |
Trade-offs
In Headless NoGraphics, Update() ticks past 5,000 times a second instead of sixty, so a run that takes minutes finishes in seconds. The trade is that there's no picture:
- The Unity panel shows the editor's live log instead of the game.
- Screenshots, video and Tuner views fail at once with
NoGraphicsError. - You and the agent read handle results and tagged logs instead.
- Multiplayer needs Normal or Headless Graphics. NoGraphics is single-player.
- Reveal needs Normal mode, since the headless modes have no window.
To look at a NoGraphics session, switch it back to Normal.
Switching modes
It's the same editor session, so a mode switch needs no player build. A common loop is Normal to find the bug, NoGraphics to grind it, Normal to watch the fix.
Agents switch with unity.setMode(), which relaunches a running editor and waits for Edit Mode:
await unity.mode()
await unity.setMode('headless-nographics')Each scratchpad keeps its own mode, so one agent can grind in NoGraphics while another streams in Normal. A stopped project keeps its mode. Multiplayer clones have no mode: they're always hidden windows.
Reveal the editor
The hidden editor is a complete Unity with its windows suppressed at the OS level. Reveal shows them, so nothing relaunches, recompiles or waits on an import, Play Mode keeps running, and hot-reloaded code stays in the running session.
- The Editor button on the Unity panel opens the editor in its own window.
- The menu next to it adds Reveal Split 50/50: the editor takes the left half of the space your app window covers and the app moves to the right half.
- Hide Editor puts the app back at its old size, and the stream picks up again.
While revealed, the game plays in Unity's Game view and takes your input. Every window and every extension of your own tooling works as usual. Closing the editor window stops the player.
Tuner or Reveal
For a few Inspector values or a clip, the Tuner does it inside the app on the hidden editor. Reveal covers custom editor windows, the Animator graph and anything else the Tuner doesn't. A common use is mid-play: spot a bad collider, reveal, fix it in the Inspector, hide and keep playing.