Run simulations headlessly
Configure Simulation Pro to render and capture data on displayless Linux compute nodes.
Headless simulation lets you render cameras and sensors on Linux compute nodes that have no display device, which is how Simulation Pro scales batch simulation and synthetic-data generation across cloud and CI machines. The subsystem lives in Runtime/Capture/ and is driven by HeadlessCustomPlayerLoop, together with the capture pipeline (CaptureCamera, BatchReadback) already documented in Image capture reference.
Why headless
Cloud and CI nodes typically run without an attached monitor or window server. In that environment Unity cannot present frames to a screen, so a normal player would never drive camera rendering. Headless simulation replaces frame presentation with an off-screen RenderTexture back-buffer, allowing many workers to render and capture data in parallel with no display.
The headless build target
Headless behavior activates on the LinuxHeadlessSimulation build target. This target was previously named CloudRendering; the code still supports both names for compatibility:
// Runtime/Sensors/Core/RenderPipelineUtils.cs
UnityEditor.BuildTarget.LinuxHeadlessSimulation => OperatingSystemFamily.Linux,
// CloudRendering was renamed to LinuxHeadlessSimulation in 2021.3.9
UnityEditor.BuildTarget.CloudRendering => OperatingSystemFamily.Linux,
Headless-specific code is guarded by the PLATFORM_CLOUD_RENDERING and PLATFORM_LINUXHEADLESSSIMULATION platform defines. PreBuildStep (Editor/Capture/Core/PreBuildStep.cs) runs automatically on every build and:
- Sets
PlayerSettings.fullScreenModetoWindowedand bundles aPlayerResolutionSettingsasset from the project's default screen width/height, regardless of build target.
When you build for the headless target specifically, it additionally:
- Imports the IL2CPP cross-compilation toolchain package for your editor host (Windows, macOS, or Linux).
- Adds the
UNITY_STANDALONE_LINUX_APIscripting define.
Note
You select the build target and configure the graphics API yourself. If you build a plain StandaloneLinux64 player instead, PreBuildStep.CheckUSimRunCompatibility warns that you need a Linux player, and that Vulkan requires the CloudRendering (headless) build target. The supported graphics APIs checked at build time are OpenGLES3, OpenGLCore, and Vulkan.
How rendering works without a display
On a headless build, HeadlessCustomPlayerLoop runs at RuntimeInitializeLoadType.AfterSceneLoad and:
- Creates a back-buffer
RenderTexture. Its resolution comes from aPlayerResolutionSettingsasset loaded fromResources. If that asset is missing it falls back to640x480and logs a warning. - Registers the texture as the default back-buffer surface via
CloudGraphics.SetDefaultBackbufferSurface(skipped whenUNITY_STANDALONE_LINUX_APIis defined). - Installs a custom
PlayerLoopSystemthat inserts a render step afterPostLateUpdate.FinishFrameRendering. Each frame this step iteratesCamera.allCameras, callingRender()first on cameras that have atargetTextureand then on those without one, skipping disabled cameras, and finally resets the render target.
This is fully automatic on the headless target so you don't call HeadlessCustomPlayerLoop yourself.
Note
The source loads the resolution asset from Resources/PlayerResolutionSettings. PreBuildStep generates this asset at build time from the player's default screen dimensions, so set your intended resolution in Player Settings.
Batch GPU readback for throughput
Because captured frames are read back from the GPU, throughput matters when many workers run at scale. Setting CaptureOptions.useBatchReadback = true routes readbacks through BatchReadback instead of issuing them individually:
CaptureOptions.useBatchReadback = true;
BatchReadback.Instance.BatchSize = 100; // default is 50
BatchReadback accumulates requests until BatchSize is reached, then flushes them as a group, using AsyncGPUReadback when supported and a synchronous pixel read otherwise. The pending batch is also flushed on shutdown. The CameraGrab convenience component exposes Batch Readback and Batch Size fields in its Inspector that set these values on Start.
Note
WaitForEndOfFrame never fires in batch mode because there is no frame presentation. Manager.LateUpdate accounts for this by draining its end-of-frame action queue directly when Application.isBatchMode is true, and by calling AsyncGPUReadback.WaitAllRequests() on shutdown so in-flight readbacks complete before the process quits.
Graphics API constraints
| Constraint | Detail |
|---|---|
| Graphics API | Non-OpenGL APIs are required for HDRP/URP sensor rendering; RenderPipelineUtils.IsPlatformSupported rejects OpenGL and directs Linux/Windows to Vulkan (Metal on macOS). |
| Ray-traced LiDAR | Requires Vulkan and is supported on Linux and Windows only (macOS is not supported), per the package Known issues. |
| Vulkan headless surface | The ray-tracing Vulkan engine references the VK_EXT_headless_surface extension (Runtime/Sensors/Sensors/RayTracingService/VulkanEngine/VulkanStringConstants.cs). |
Note
Refer to Unity's Command line arguments reference for the flags (such as -batchmode or -nographics) needed to launch a headless player. Simulation Pro does not add any headless-specific launch flags.