Skip to main content

Device Runs

A phone has no shader compiler, and a material shader has far too many permutations to compile them all ahead of time. The export therefore compiles a fixed set of permutations, and the game reports every permutation it needed but did not find. A device run builds the game, plays it on a connected phone for a set time, and collects those reports together with frame statistics, pipeline compiles, the battery temperature and crash lines. One click adds what was missing to the project, and the next build compiles it.

The Device Run Window​

Open it with Device Run... under Device & deployment on the Android app tab, or export with Install after build and Run after install ticked (Build, Install & Run), which opens it and starts a run.

ControlDescription
DeviceThe phone to run on.
Play for30, 45 or 60 seconds.
Keep the driver cacheOff (default): every run starts with an empty driver pipeline cache, like a player's first launch. On: the run reuses the caches earlier runs saved.
Run on device / Run againStarts a run. Cancel Run stops after the current stage.

The run goes through the stages Compile C++ plugin, Transform assets, Stage data, Compile shaders, Build APK, Install, Play on device and Collect results. It uses the active asset profile, which must be an Android profile.

Results​

TabContents
SummaryTiles for average fps, worst frame, pipeline stalls, missing permutations, battery °C, start → end and crash lines, a frame time graph, and a banner that says what to do next.
Missing permutationsThe shader permutations that drew with the fallback shader, grouped by shader. Add N and compile puts them into Editor/ShaderPermutations-Android.txt.
New pipelinesPipelines that compiled on first use while the game ran, which show up as hitches. Add N to the prewarm list puts them into Editor/PipelineList-Android.txt.
LogThe device log of the run, filterable by All, Errors, Warnings and Info and by text.

A run that ends with Clean run: no missing permutations, no pipeline compiled on first use. is ready to ship. The last run is saved to Editor/DeviceRun-Android.json, and the Preflight column of Build & Export reads it (Not run on a device yet, N shader permutations missing, Shader permutations).

Frame statistics and the driver cache reset need a debuggable (Development) build. A Shipping APK still runs, but the run has no frame rate.

Shader Permutation Lists​

Every Android export compiles:

  • the permutations of every staged shader (Base, the project and every package) for the forward, depth-only and G-buffer passes with normal shading quality, medium shadows, lit shading and no MSAA,
  • the permutations of the project's materials,
  • plus every entry of Editor/ShaderPermutations-Android.txt.

When the game needs a permutation that is not in the APK, it logs one line and draws with an empty shader instead of stopping:

PL_MISSING_PERMUTATION|Shaders/Materials/DefaultMaterial.plShader|BLEND_MODE=BLEND_MODE_OPAQUE;RENDER_PASS=...

The Device Run window collects these lines for you. Repeat runs, covering the levels and effects of the game, until no new permutations appear. Commit the list with the project. It is the project's Android shader manifest.

To add permutations from a session you played by hand, copy the PL_MISSING_PERMUTATION lines of the device log into the list, one per line. The export passes the list to the ShaderCompiler with -materiallist, which ignores any text before the marker, so lines copied from raw logcat output work:

adb logcat -d | findstr PL_MISSING_PERMUTATION >> Editor/ShaderPermutations-Android.txt

Pipeline Prewarm List​

Creating a GPU pipeline the first time can take long enough to cause a visible hitch. Development builds log a PL_PIPELINE| line for every pipeline they create. Entries of Editor/PipelineList-Android.txt ship as RuntimeConfigs/PipelineList-Android.txt, and the game creates those pipelines in the background at startup. The driver's pipeline cache is kept across launches on the device, so later launches start faster.

Exporting from the Command Line​

The EditorProcessor runs Build & Export, including a device run, without the editor window:

EditorProcessor -project <project> -exportProject Android -exportTarget D:/Exports/MyGame -androidRun 45 -androidRecordLists
OptionDefaultDescription
-exportProject <profile>The asset profile to export, for example Android.
-exportTarget <folder>The folder that is emptied and exported into.
-exportConfigurationDevelopmentDevelopment, Debug or Shipping.
-androidArchitectureARM64The ABI of the package.
-androidDevice <serial>The adb serial of the device. Without it, adb picks its only device.
-androidInstalloffInstalls the package on the device.
-androidRun <seconds>0Installs the package, plays the game for this many seconds (less when it exits) and writes the results to Editor/DeviceRun-Android.json. 0 does not run it.
-androidKeepDriverCacheoffWith -androidRun: keeps the pipeline caches that earlier runs saved on the device.
-androidRecordListsoffWith -androidRun: adds the missing shader permutations and new pipelines of the run to the project's Android lists.

The process returns exit code 6 when the export fails. The package format, signing and other app settings come from the project's Editor/AndroidApp.ddl.

Troubleshooting​

ProblemCause and fix
The active asset profile is not an Android profilePick the Android card in Build & Export first; the run exports with the active profile.
Objects render black or invisible on the phoneTheir shader permutations are missing. Run on the device and add the missing permutations.
The app stopped after N s with crash linesThe game crashed. Open Show log for the native crash lines (Fatal signal ...).
The run shows no frame rateThe APK is a Shipping build, which is not debuggable. Use Development for device runs.

See Also​