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.
| Control | Description |
|---|---|
| Device | The phone to run on. |
| Play for | 30, 45 or 60 seconds. |
| Keep the driver cache | Off (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 again | Starts 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
| Tab | Contents |
|---|---|
| Summary | Tiles 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 permutations | The shader permutations that drew with the fallback shader, grouped by shader. Add N and compile puts them into Editor/ShaderPermutations-Android.txt. |
| New pipelines | Pipelines 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. |
| Log | The 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
| Option | Default | Description |
|---|---|---|
-exportProject <profile> | The asset profile to export, for example Android. | |
-exportTarget <folder> | The folder that is emptied and exported into. | |
-exportConfiguration | Development | Development, Debug or Shipping. |
-androidArchitecture | ARM64 | The ABI of the package. |
-androidDevice <serial> | The adb serial of the device. Without it, adb picks its only device. | |
-androidInstall | off | Installs the package on the device. |
-androidRun <seconds> | 0 | Installs 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. |
-androidKeepDriverCache | off | With -androidRun: keeps the pipeline caches that earlier runs saved on the device. |
-androidRecordLists | off | With -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
| Problem | Cause and fix |
|---|---|
| The active asset profile is not an Android profile | Pick the Android card in Build & Export first; the run exports with the active profile. |
| Objects render black or invisible on the phone | Their shader permutations are missing. Run on the device and add the missing permutations. |
| The app stopped after N s with crash lines | The game crashed. Open Show log for the native crash lines (Fatal signal ...). |
| The run shows no frame rate | The APK is a Shipping build, which is not debuggable. Use Development for device runs. |