Skip to main content
Version: Next (dev)

EditorProcessor

EditorProcessor is the editor without a user interface. It opens a project and runs one job: transforming assets, resaving asset documents, building the project's C++ code, running project checks, or exporting the project. Use it in build scripts and on build machines.

The editor also starts EditorProcessor itself, as the background asset processors. You don't need to do anything for that.

Running a job​

Every job needs -project with the path to the project folder. For example:

EditorProcessor -project "D:/Projects/MyGame" -transform Default
JobOptions
Transform assets-transform <profile> transforms every asset that is not up to date for the given asset profile. With -assets, only the listed assets and their dependencies. Before transforming, the project's C++ code is built if it is out of date.
Resave asset documents-resave opens, saves and closes every asset document, which migrates it to the latest document version. With -assets, only the listed assets.
Build C++ code-compile generates and compiles the project's C++ project.
Run project checks-checks <file.json> runs the project checks of the project's Checks folder and writes the results as JSON.
Export the project-exportProject <profile> -exportTarget <folder> runs the editor's Build & Export.

Options​

OptionDescription
-project <folder>The project folder.
-transform <profile>Transforms the assets for this asset profile, for example -transform Default.
-resaveResaves asset documents.
-assets <list>Semicolon-separated asset paths or GUIDs. With -transform, transforms only these assets and their dependencies. With -resave, resaves only these assets. It needs one of the two. An asset that is not found is logged and sets return code 1, the others are still processed.
-compileGenerates and compiles the project's C++ code.
-checks <file>Runs the project checks and writes the results as JSON to this file.
-checkFiles <list>With -checks: semicolon-separated changed files. Only the checks that apply to them run, as when submitting.
-checkFilesList <file>Like -checkFiles, but a text file with one path per line, for lists too long for a command line.
-exportData <folder>With -transform: after transforming, empties this folder and exports the project's data for that profile into it, as the Build & Export dialog does before packaging.
-exportProject <profile>Runs Build & Export for this platform profile into -exportTarget: the C++ plugin, the asset transform, the data export and, for Android, the shader cache and the APK. It runs its own transform, so it can't be combined with -transform.
-exportTarget <folder>The folder that -exportProject empties and exports into.
-exportConfiguration <name>The runtime configuration of -exportProject: Development (default), Debug or Shipping.
-priority <level>Process priority: Normal (default), BelowNormal or Idle. The engine process it starts gets the same priority. Use BelowNormal to keep a workstation usable while a script transforms assets.
-outputDir <folder>Where log files and crash dumps go.
-profilingSaves performance profiling data into the output folder when the job is done.
-readOnlyOpens the project without taking its lock. Use it for jobs that only read. See One Editor per Project.

Android exports have further options (-androidArchitecture, -androidDevice, -androidInstall, -androidRun, -androidKeepDriverCache, -androidRecordLists). Run EditorProcessor -help for the full list with descriptions.

Examples​

Resave only two assets, for example after changing their document format:

EditorProcessor -project "D:/Projects/MyGame" -resave -assets "Textures/Brick.plTextureAsset;{ 1c47ee4c-0379-4280-85f5-b8cda61941d2 }"

Transform everything for the Default profile at a low priority:

EditorProcessor -project "D:/Projects/MyGame" -transform Default -priority BelowNormal

Projects open in the editor​

EditorProcessor obeys the project lock like the editor does. Jobs that write, such as -transform, -resave or -exportProject, need the project for themselves: if an editor has it open, EditorProcessor logs The project '...' is open in another editor and exits with return code 2. Close the editor first.

-checks only reads, so it runs next to an editor that has the project open, for example from a version control submit hook.

Return codes​

CodeMeaning
0Success.
1An error, for example an invalid combination of options, an asset that was not found, or an asset that failed to transform. Details are in the log.
2The project could not be opened, for example because another editor has it open.
3The project's C++ code could not be built.
4-checks: a blocking check failed.
5-exportData: the export failed.
6-exportProject: the export failed.

Editor command-line options for automation​

These options are for the editor itself (PlasmaEditor), for example when you run it on a machine without a user:

OptionDescription
-nostartupdialogsSkips the dialogs at startup, such as the recovery dialog. Autosave snapshots stay, so the question comes back at the next normal start.
-unattendedFor an editor nobody sits at, for example a remote machine used through Editor Link. No popup opens: message boxes answer with the choice that changes nothing (No, Cancel, otherwise their default) and editor dialogs are cancelled. Each is logged, so a linked editor sees it in the host's log.
-editorUiCaptureDir <folder>Saves a PNG of every editor window to this folder, at most every two seconds per window, and also the images the engine renders into each viewport (view-<id>.png). Files are written to a temporary name first and then renamed, so a script that reads the folder never sees a half-written image. Useful for checking the editor UI in automated tests.
-readOnlyOpens the project read-only. See One Editor per Project.
-safeSafe mode: the editor does not load the previous project and documents.

See Also​