docs.unity3d.com
Search Results for

    Show / Hide Table of Contents

    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.fullScreenMode to Windowed and bundles a PlayerResolutionSettings asset 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_API scripting 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:

    1. Creates a back-buffer RenderTexture. Its resolution comes from a PlayerResolutionSettings asset loaded from Resources. If that asset is missing it falls back to 640x480 and logs a warning.
    2. Registers the texture as the default back-buffer surface via CloudGraphics.SetDefaultBackbufferSurface (skipped when UNITY_STANDALONE_LINUX_API is defined).
    3. Installs a custom PlayerLoopSystem that inserts a render step after PostLateUpdate.FinishFrameRendering. Each frame this step iterates Camera.allCameras, calling Render() first on cameras that have a targetTexture and 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.

    Additional resources

    • Image capture reference
    • Capture synthetic images
    • Known issues
    In This Article
    Back to top
    Copyright © 2026 Unity Technologies — Trademarks and terms of use
    • Legal
    • Privacy Policy
    • Cookie Policy
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)