ue5-headless

name	ue5-headless
description	A formalized capability framework for executing Unreal Engine 5 in Headless mode for rendering and server logic operations.
tags	["unreal engine","ue5","headless","rendering","server","automation"]
author	Antigravity

🎮 UE5 Headless Execution Skill

This skill defines the operational parameters, constraints, and execution commands required to run Unreal Engine 5 completely headlessly via the command line.

Core Directives

1. Hardware Targeting (Windows Host): The local Linux environment lacks the necessary VRAM. You MUST deploy UE5 headless rendering and heavy logic operations via SSH to the Windows host (jbspc-1) to utilize its 64GB RAM and 12GB VRAM GPU.
2. No Editor GUI: Never attempt to launch the Unreal Editor GUI headlessly. You must strictly invoke UE5 using command line arguments to bypass the rendering interface or boot entirely null-RHI for servers.
3. Deterministic Output: Headless pipelines must output hard artifacts (e.g., a .mp4 video, a .png sequence, or server logs) to verify execution success.
4. EULA Compliance (CRITICAL):
   • You may autonomously render "Linear Media" (video/images) royalty-free limitlessly.
   • Do NOT distribute, package, or export the UnrealEditor binaries within a public Docker container. Containerized headless pipelines must remain strictly internal.

Execution Syntax

1. Headless Offscreen Rendering (Requires GPU)

Use this command to autonomously render a pre-configured sequence or synthetic data without a physical monitor.

# General Syntax for Offscreen Linux/Vulkan Rendering
<Path_to_UnrealEditor> <Path_to_Project.uproject> -ExecutePythonScript="<Path_To_Script.py>" -RenderOffscreen -NoUI -Log

Note: Depending on the OS, -RenderOffscreen might require -d3d12 (Windows) or -vulkan (Linux).

2. Dedicated Server (No GPU / Null RHI)

Use this command to spin up a game server instance that runs physics and logic but completely disables the hardware rendering interface.

<Path_to_ServerExecutable.exe> -log -port=7777 -server -nullrhi -NoUI

AI Agent Integration (Python Pipelines)

To control UE5 headlessly as an AI agent, the optimal architecture is to pass a Python script into the engine using -ExecutePythonScript. The pipeline follows this pattern:

1. Agent writes automation_script.py containing unreal API commands to load a map, adjust lighting, and trigger a Sequencer render.
2. Agent invokes UE5 command line with the script and -RenderOffscreen.
3. Agent parses -Log output to detect completion or Python API errors.

Recommended Project Settings for Autonomy

To ensure smooth headless execution, ensure the target .uproject has the following enabled:

• PythonScriptPlugin
• SequencerScripting
• MovieRenderPipeline

Error Handling

• Crash on Launch / Context Errors: If the headless launch fails, verify the node actually has Vulkan/D3D12 drivers installed. Headless rendering still physically requires GPU rendering hooks even if there is no physical screen.
• Plugin Load Errors: Many UI-centric plugins explicitly crash when IsHeadless() returns true. Only enable strictly necessary plugins in the .uproject file.