unreal-editor-automation

Unreal 5.8 Editor Automation

---
name: unreal-editor-automation
description: Design, implement, run, and debug safe Unreal Editor automation for Unreal Engine 5.8. Use for Editor Utility Widgets, Editor Utility Blueprints, Scripted Actions, Call in Editor, Scriptable Tools, Python Editor scripting, editor subsystems, asset import or batch mutation, commandlets, CI, Data Validation, Automation Tests, Functional Tests, transactions, source control, or the experimental Unreal MCP server and AI-driven editor tools.
---

# Unreal 5.8 Editor Automation

## Select the automation surface

Read [`references/selector-architecture.md`](references/selector-architecture.md).

- Use a **Scripted Action** for a contextual operation on selected assets or actors.
- Use an **Editor Utility Widget** for a persistent dockable UI and human-reviewed batch work.
- Use **Call in Editor** for an action attached to a placed Actor that also has runtime use.
- Use a **Scriptable Tool** for modal viewport interaction with accept/cancel semantics.
- Use **Python** for text-based pipelines, cross-DCC integration, and repeatable batches.
- Use a **commandlet** for unattended/headless work and CI.
- Use **Data Validation** for asset invariants, not as a general behavior-test framework.
- Use **Automation/Functional Tests** for code, system, map, gameplay, and regression checks.
- Use **Unreal MCP** only for bounded AI tool calls in 5.8; it is Experimental.

## Execute safely

1. Define selection/input scope, mutation set, source-control behavior, undo boundary,
   save policy, cancellation, logs, and validation before writing the tool.
2. Separate discovery and planning from mutation. Produce a dry-run report for destructive,
   bulk, or difficult-to-reverse work.
3. Use editor APIs for assets and packages. Never move, rename, or delete `.uasset` files
   with generic filesystem operations.
4. Use `get_editor_property`/`set_editor_property` when scripting reflected editor data so
   editor change notifications run.
5. Wrap only genuinely undoable changes in a transaction. Import, save, source-control,
   and many package operations are not made reversible by a transaction.
6. Mark changed objects/packages dirty, save deliberately, and report every failure.
7. Make reruns idempotent or detect prior output. Test on a disposable subset before the
   full content tree.
8. Run validation/tests and inspect the actual diff before submission.

Load the task reference:

- UI/Blueprint tools: [`references/editor-utilities-blueprint.md`](references/editor-utilities-blueprint.md)
- Python execution/APIs: [`references/python-workflows.md`](references/python-workflows.md)
- mutation guardrails: [`references/safe-asset-mutation.md`](references/safe-asset-mutation.md)
- command line/CI: [`references/commandlets-headless-ci.md`](references/commandlets-headless-ci.md)
- Data Validation: [`references/data-validation.md`](references/data-validation.md)
- test frameworks: [`references/automation-tests.md`](references/automation-tests.md)
- Unreal MCP: [`references/unreal-mcp.md`](references/unreal-mcp.md)
- concrete tools: [`references/patterns.md`](references/patterns.md)
- recovery: [`references/debugging-recovery.md`](references/debugging-recovery.md)

## Required answer format

Return:

1. **Automation surface** and maturity status.
2. **Inputs, selection filters, preconditions, and dry-run output**.
3. **Ordered API/node/command sequence** with editor/runtime boundaries.
4. **Transaction, source-control, save, cancellation, and idempotency policy**.
5. **Validation/test procedure**, logs, exit criteria, and expected diff.
6. **Failure recovery** and any operation that cannot be undone.

Do not invent nodes, APIs, command-line flags, defaults, or MCP tools. Inspect the enabled
5.8 API/tool schema when exact availability matters.

## Hard rules

- Never operate directly on `.uasset`/`.umap` files with `os`, `shutil`, or shell moves.
- Never run a bulk mutation before a scoped dry run or disposable-copy test.
- Never assume a transaction makes import, save, delete, or source-control work reversible.
- Never autosave unrelated dirty packages.
- Never suppress per-asset failures and still report success.
- Never run Python as gameplay code; UE 5.8's embedded Python is editor-only.
- Never expose Unreal MCP beyond loopback; it has no authentication layer.
- Never issue overlapping Unreal MCP tool calls; the server serializes them on the game thread.
- Never let an AI infer permission for destructive or project-wide mutations.

See [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Select the automation surface

Read [`references/selector-architecture.md`](/unreal/unreal-editor-automation/selector-architecture/).

- Use a **Scripted Action** for a contextual operation on selected assets or actors.
- Use an **Editor Utility Widget** for a persistent dockable UI and human-reviewed batch work.
- Use **Call in Editor** for an action attached to a placed Actor that also has runtime use.
- Use a **Scriptable Tool** for modal viewport interaction with accept/cancel semantics.
- Use **Python** for text-based pipelines, cross-DCC integration, and repeatable batches.
- Use a **commandlet** for unattended/headless work and CI.
- Use **Data Validation** for asset invariants, not as a general behavior-test framework.
- Use **Automation/Functional Tests** for code, system, map, gameplay, and regression checks.
- Use **Unreal MCP** only for bounded AI tool calls in 5.8; it is Experimental.

## Execute safely

1. Define selection/input scope, mutation set, source-control behavior, undo boundary,
   save policy, cancellation, logs, and validation before writing the tool.
2. Separate discovery and planning from mutation. Produce a dry-run report for destructive,
   bulk, or difficult-to-reverse work.
3. Use editor APIs for assets and packages. Never move, rename, or delete `.uasset` files
   with generic filesystem operations.
4. Use `get_editor_property`/`set_editor_property` when scripting reflected editor data so
   editor change notifications run.
5. Wrap only genuinely undoable changes in a transaction. Import, save, source-control,
   and many package operations are not made reversible by a transaction.
6. Mark changed objects/packages dirty, save deliberately, and report every failure.
7. Make reruns idempotent or detect prior output. Test on a disposable subset before the
   full content tree.
8. Run validation/tests and inspect the actual diff before submission.

Load the task reference:

- UI/Blueprint tools: [`references/editor-utilities-blueprint.md`](/unreal/unreal-editor-automation/editor-utilities-blueprint/)
- Python execution/APIs: [`references/python-workflows.md`](/unreal/unreal-editor-automation/python-workflows/)
- mutation guardrails: [`references/safe-asset-mutation.md`](/unreal/unreal-editor-automation/safe-asset-mutation/)
- command line/CI: [`references/commandlets-headless-ci.md`](/unreal/unreal-editor-automation/commandlets-headless-ci/)
- Data Validation: [`references/data-validation.md`](/unreal/unreal-editor-automation/data-validation/)
- test frameworks: [`references/automation-tests.md`](/unreal/unreal-editor-automation/automation-tests/)
- Unreal MCP: [`references/unreal-mcp.md`](/unreal/unreal-editor-automation/unreal-mcp/)
- concrete tools: [`references/patterns.md`](/unreal/unreal-editor-automation/patterns/)
- recovery: [`references/debugging-recovery.md`](/unreal/unreal-editor-automation/debugging-recovery/)

## Required answer format

Return:

1. **Automation surface** and maturity status.
2. **Inputs, selection filters, preconditions, and dry-run output**.
3. **Ordered API/node/command sequence** with editor/runtime boundaries.
4. **Transaction, source-control, save, cancellation, and idempotency policy**.
5. **Validation/test procedure**, logs, exit criteria, and expected diff.
6. **Failure recovery** and any operation that cannot be undone.

Do not invent nodes, APIs, command-line flags, defaults, or MCP tools. Inspect the enabled
5.8 API/tool schema when exact availability matters.

## Hard rules

- Never operate directly on `.uasset`/`.umap` files with `os`, `shutil`, or shell moves.
- Never run a bulk mutation before a scoped dry run or disposable-copy test.
- Never assume a transaction makes import, save, delete, or source-control work reversible.
- Never autosave unrelated dirty packages.
- Never suppress per-asset failures and still report success.
- Never run Python as gameplay code; UE 5.8's embedded Python is editor-only.
- Never expose Unreal MCP beyond loopback; it has no authentication layer.
- Never issue overlapping Unreal MCP tool calls; the server serializes them on the game thread.
- Never let an AI infer permission for destructive or project-wide mutations.

See [`references/sources.md`](/unreal/unreal-editor-automation/sources/) for the UE 5.8 source trail.

unreal 5.8 editor automation design, implement, run, and debug safe unreal editor automation for unreal engine 5.8. use for editor utility widgets, editor utility blueprints, scripted actions, call in editor, scriptable tools, python editor scripting, editor subsystems, asset import or batch mutation, commandlets, ci, data validation, automation tests, functional tests, transactions, source control, or the experimental unreal mcp server and ai-driven editor tools. automation and functional tests automation and functional tests select the test level - low-level test: pure code with minimal engine environment. - automation unit/feature test: api or system behavior using unreal services. - automation spec: behavior-driven organization and latent/asynchronous steps. - functional test: actor-based gameplay/map scenario, blueprint-friendly. - screenshot comparison: controlled rendering regression. - content stress test: loading/compiling broad content to find crashes or invalid assets. the automation framework is c++-based and relies on engine systems, so epic does not recommend it for truly pure unit testing; use low-level tests for that boundary. test design 1. put tests in a project/plugin test module with deliberate build availability. 2. give names a stable hierarchy such as project.system.behavior. 3. create and tear down all state the test owns. 4. use latent commands/spec continuations for async engine work; do not block the game thread. 5. assert observable outcomes and include diagnostic context. 6. isolate files, maps, network roles, random seeds, and timing. only mark a test smoke when it satisfies epic's speed promise: intended to run at every startup and complete within one second. do not label slow map/content tests smoke. run and report interactive: enable required test plugins, then use tools > test automation. command line: text -execcmds="automation runtest project.system;quit" -reportexportpath="<output path>" the report path produces json with related html files. fail ci for failed tests, missing reports, engine crashes, or timeouts. functional tests place/configure a functional test actor in a dedicated deterministic test map. begin only after required actors/assets are ready; call the framework's success/failure completion path on every branch. keep test-only content out of production cook/chunks unless the target execution needs it. commandlets and headless ci commandlets and headless ci choose headless execution use unrealeditor-cmd.exe for commandlets and unattended automation. quote the .uproject and output paths. capture stdout/stderr, process exit code, engine version, project revision, and report artifacts. verified 5.8 examples: text unrealeditor-cmd.exe project.uproject -run=datavalidation unrealeditor-cmd.exe project.uproject -run=pythonscript -script="c:\path\job.py" unrealeditor-cmd.exe project.uproject \ -execcmds="automation runtest project.suite;quit" \ -reportexportpath="c:\reports\automation" use -executepythonscript="..." instead when the job needs the full editor and default startup level loaded. the python commandlet does not load a level automatically; load the required level explicitly through leveleditorsubsystem. ci contract each job must define: - required plugins and build target; - isolated workspace and writable derived data/intermediate/saved paths; - timeout and hung-process policy; - exact success/failure exit conditions; - machine-readable report location; - artifact retention for logs, screenshots, and diffs. never parse only a “completed” log line. fail when the process exits nonzero, the report is absent or malformed, tests fail, validation errors occur, or the expected output count differs. high-risk commandlets resavepackages, redirector cleanup, mass import, and migration rewrite many packages. run on a clean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect the resulting diff. epic's documented redirector cleanup example uses resavepackages with -fixupredirects; source-control flags can automatically check out files, so do not add them without deliberate authorization. determinism sort inputs, avoid current selection/editor ui state, seed random operations, use stable output paths, and make retries idempotent. record the command line with secrets removed. data validation automation data validation automation choose the validator - override uobject::isdatavalid when the rule belongs to a custom asset/class and may need private or protected data. - derive ueditorvalidatorbase when a validator should cover existing engine classes, several classes, or project-wide policy. for ueditorvalidatorbase, implement canvalidateasset narrowly and call assetpasses or assetfails on every validateloadedasset execution path. make messages actionable. c++ and blueprint validators are discovered at editor startup. python validators must register with ueditorvalidatorsubsystem.addvalidator. the command-line data validation path runs c++ rules by default; do not assume editor-registered blueprint/python rules ran in ci without proving the configured extension. run surfaces - one/many assets: asset actions > validate assets. - assets plus dependencies: validate assets and dependencies. - folder: validate assets in folder. - project: tools > validate data. - ci: unrealeditor-cmd.exe project.uproject -run=datavalidation. design rules use fast local validators on save. put slow global uniqueness, dependency-cycle, budget, and cross-asset relationship checks in an explicit full-project/ci stage. an error message should contain: text asset path | field/rule | received value | expected condition | repair action distinguish invalid from not validated. unsupported assets should be skipped explicitly, not reported as passed. treat warnings and errors according to a documented build policy. validate the validator create fixtures that should pass, warn, and fail. confirm interactive save, content browser, project-wide validation, and commandlet behavior. a validator that only runs in one surface is not yet a reliable gate. debugging and recovery debugging and recovery symptom routing | symptom | check first | |---|---| | blueprint editor node missing | editor-only parent/module, plugin enabled, restart required | | scripted action absent | correct utility base, call in editor, supported classes, compiled/saved | | python class/function absent | ue 5.8 api, plugin/module enabled, reflected exposure, editor restart | | python commandlet sees no actors | no level auto-loaded; load intended level explicitly | | property changed but ui/derived state stale | used direct assignment instead of seteditorproperty/setter | | undo does nothing | operation is not undoable or object was not transaction-aware | | asset exists but did not save | package not dirty, wrong package selected, save failed/read-only | | automation passes locally only | selection/ui dependence, race, machine path, missing plugin/report | | mcp cannot connect | server status, loopback endpoint/port, client launched from config root | | mcp new tool missing | toolset enabled/schema discovery, live coding limitation, restart | | editor freezes during batch | work on game thread, no progress/cancel, scope too broad | partial failure recovery stop on the first failure when continuing could compound damage. preserve: - ordered operation log; - objects changed before failure; - packages saved versus only dirty; - source-control state; - validation/test output; - whether transaction undo is available. if all changes are undoable and unsaved, perform and verify undo. otherwise use source control or the prepared backup to restore named packages. do not improvise filesystem replacement while the editor has packages loaded. after recovery, restart/reload as needed, requery objects from the editor rather than trusting stale python references, run validation, and inspect the diff before retrying. tool hardening checklist - rerun on already-processed content. - cancel halfway through. - inject a read-only asset and one invalid input. - test zero, one, and many candidates. - test name/path collisions. - test unrelated dirty packages. - test headless mode without selection or an open level. - test packaged/cook impact when runtime content changes. blueprint editor utilities blueprint editor utilities scripted actions create content browser > editor utilities > editor utility blueprint and choose: - assetactionutility for selected content browser assets; - actoractionutility for selected level actors. expose a function/custom event with call in editor. restrict supported classes so the action appears only for valid targets. validate dynamic inputs; the editor checks input types, not whether a value is present or sensible. editor utility widgets use an editor utility widget when users need filters, preview, progress, warnings, and explicit apply/cancel controls. create it under editor utilities > editor utility widget and run it as an editor tab. recommended flow: 1. collect selection/path/filter inputs. 2. scan and display the candidate set. 3. show planned changes and non-undoable consequences. 4. require explicit apply for mutations. 5. provide progress/cancel for long batches. 6. validate and display a per-object result table. editor utility widgets and editor scripting utilities are documented as beta in 5.8. call in editor and startup objects use call in editor for functions/events on a placed actor when the same graph must be usable at runtime or needs level context. an editor-only base class exposes more editor apis but is not included in packaged applications. startup objects instantiate when a project opens and invoke their startup event. keep startup work fast, idempotent, and limited to registration/listeners. do not perform bulk asset mutation at editor startup. the startup-object workflow is beta in 5.8. scriptable tools use a scriptable tool for modal viewport editing. its managed lifecycle, shutdown before save or pie, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct viewport interaction than a non-modal widget. the system is beta in 5.8. editor-only boundary place editor tool code and dependencies in editor-only blueprints/modules/plugins. prevent runtime assets from hard-referencing editor utility classes. test a shipping cook for accidental editor-only references. concrete automation patterns concrete automation patterns safe batch property editor text input: folder, class, predicate, property, proposed value discover: asset registry / editor subsystem plan: old -> new table, invalid objects, count, dirty/source-control state apply: one named transaction for undoable edits save: only successfully changed packages selected by policy verify: reload/requery property, data validation, diff reject unknown property names, incompatible types, root-wide accidental scope, and an empty filter that broadens selection. naming validator and fixer keep validation and mutation separate. validator reports naming failures without changing data. fixer computes collision-free target paths, shows referencers and redirector consequences, then uses asset tools rename apis. never use filesystem rename. deterministic import pipeline 1. parse a versioned manifest. 2. validate source existence, destination paths, factories/options, and collisions. 3. import into staging using assetimporttask/asset tools. 4. apply editor properties and build derived data where required. 5. run validators and representative opens/compiles. 6. promote/rename through unreal apis. 7. save intended packages and emit a manifest of results. editor utility widget wrapper the widget owns filters, preview, progress, cancel, and user confirmation. a reusable service owns discovery/mutation. the widget never embeds the only implementation of a production pipeline. ci data gate run data validation, then project automation tests, then a representative cook. persist reports and engine logs. treat missing reports, timeouts, partial processing, and unexpected dirty/output counts as failures. bounded mcp tool expose a typed operation with a narrow path root and dryrun=true default. the plan returns candidate object paths and requested changes. apply requires explicit confirmation token/request, runs serially, validates, saves only its packages, and returns structured results. do not expose an unrestricted “execute editor command” tool to compensate for missing schema. python editor workflows python editor workflows enable and version enable python editor script plugin and usually editor scripting utilities, then restart. unreal 5.8 embeds python 3.11.8. epic labels python editor scripting experimental. python is available only in the editor—not pie, standalone game, or cooked executables. put project modules in content/python; initunreal.py in a configured python path runs when the editor detects it. keep automatic initialization lightweight. execution selector - output log python mode: exploration and one-line inspection. - file > execute python script: manual repeatable script. - -executepythonscript="path": full editor, startup level loaded, then script. - -run=pythonscript -script="path": faster commandlet/headless path; levels are not loaded automatically. - startup scripts: run after the default startup level loads. epic warns against putting py ... inside startup -execcmd; it can execute before the editor environment is ready. api pattern python import unreal assets = unreal.geteditorsubsystem(unreal.editorassetsubsystem) actors = unreal.geteditorsubsystem(unreal.editoractorsubsystem) inspect the generated 5.8 python api for the exact subsystem/method available in the enabled plugins. the reflected unreal module changes with plugins and project c++ exposure. use geteditorproperty() and seteditorproperty() for reflected editor fields. the setter triggers pre/post-edit behavior that direct python attribute assignment may skip. batch shape implement discover -> plan -> apply -> save -> validate -> report. take explicit paths/filters as arguments; do not depend on current selection in unattended jobs. return a nonzero process status or raise on hard failure so ci cannot misread a partial batch as success. use unreal.scopedslowtask for long interactive batches and honor cancellation. use structured logs with object path, operation, status, and diagnostic. safe asset mutation safe asset mutation preflight before changing anything: 1. resolve the exact project, level, folders, classes, and object count. 2. refuse empty, root-wide, or unexpected scope unless explicitly authorized. 3. record existing dirty packages and exclude them from implicit saves. 4. check source-control/read-only state. 5. produce a dry-run list and collision/dependency warnings. 6. define backup/revert strategy for non-undoable operations. asset operations use unreal's asset tools, editor asset apis/subsystems, factories, import tasks, and rename data. never use generic filesystem apis on .uasset or .umap; doing so can break internal package references and redirector handling. for property changes: 1. use editor property accessors or native setters. 2. call the appropriate modify()/transaction-aware path where required. 3. mark affected packages dirty. 4. save only the intended packages. 5. requery/reload and verify the serialized result. transactions group undoable object edits in one named unreal.scopededitortransaction or blueprint/c++ transaction. transactions cover only operations the editor itself supports as undoable. import, save, source-control actions, and some asset operations remain irreversible even inside a scope. do not confuse canceling a transaction record with reverting partial object mutations. on error, explicitly undo/restore when the api supports it; otherwise stop, report the changed set, and use source control/backup recovery. rename/delete/import - check destination collisions before rename. - fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders. - find referencers before deletion and require explicit confirmation for nonempty dependency sets. - import to a staging path, validate, then promote when feasible. - make generated names deterministic so reruns update or skip instead of duplicating assets. completion proof report planned, changed, skipped, failed, saved, and still-dirty objects separately. run data validation, dependency checks, and the relevant automation test. inspect source-control diff and open a representative changed asset before claiming completion. automation surface selector automation surface selector | task shape | choose | notes | |---|---|---| | right-click selected assets/actors | scripted action | assetactionutility or actoractionutility; beta | | reusable dockable ui with controls/progress | editor utility widget | umg-based; beta | | action on one placed actor, possibly shared with runtime | call in editor | avoid editor-only nodes in runtime-capable classes | | interactive viewport manipulation | scriptable tool | modal, accept/cancel lifecycle; beta | | cross-tool pipeline or large scripted batch | python | editor-only; experimental in 5.8 | | deterministic editor extension/api | c++ editor module/plugin | best for stable shared tooling and native tests | | headless repeatable batch | commandlet or command-line python | prefer for ci; prove exit code and report output | | asset correctness | data validation | isdatavalid/ueditorvalidatorbase | | code/system behavior | automation test | c++ framework, specs, low-level tests as appropriate | | gameplay/map behavior | functional test | actor-based test in a level | | ai invokes bounded editor functions | unreal mcp | experimental 5.8 server; schema-driven tools | architecture split every nontrivial tool into: text ui / command / mcp adapter -> validated request -> discovery and dry-run plan -> mutation service -> save/source-control boundary -> validation and structured report keep domain logic out of widget graphs and mcp transport handlers. a shared c++/blueprint library or python module should make the same operation callable from ui, ci, or tests without duplicating behavior. escalation rule use the least powerful surface that fits. a one-selection rename does not need a global startup object; a ci validator does not need a dockable ui; an ai tool should expose one typed intent, not a general “execute arbitrary python” endpoint. ue 5.8 primary sources ue 5.8 primary sources verified against epic games documentation for unreal engine 5.8 on 2026-07-19. - scripting and automating the unreal editor - scripting the unreal editor using blueprints - editor utility widgets - scripted actions - calling blueprints in the editor - running blueprints at editor startup - scriptable tools system - scripting the unreal editor using python - unreal python 5.8 api - data validation - automation test framework - run automation tests - functional testing - asset redirectors - unreal mcp - unreal engine 5.8 release notes maturity labels recorded from epic's 5.8 pages: - unreal mcp: experimental. - python editor scripting/api: experimental. - editor utility widgets, scripted actions, editor scripting utilities, startup blueprint objects, and scriptable tools: beta where their feature pages state it. unreal mcp in ue 5.8 unreal mcp in ue 5.8 status and boundary unreal mcp is new and experimental in unreal engine 5.8. its engine/plugin identifier is modelcontextprotocol; the plugin browser name is unreal mcp. features, apis, and data formats may change. tool implementations come from toolset plugins; epic's overview identifies alltoolsets as the plugin used to enable the supplied tools. use mcp for small typed editor operations, inspection, and test invocation. do not expose arbitrary python/shell execution as a general tool. setup facts 1. enable unreal mcp and restart. 2. in editor preferences > general > model context protocol, use auto start or start on demand: text modelcontextprotocol.startserver 8000 3. default endpoint: http://127.0.0.1:8000/mcp. 4. generate a supported client config from the editor console, for example: text modelcontextprotocol.generateclientconfig codex generate from the project/workspace root expected by the client. epic notes that json configs are merged, while the codex cli toml configuration is write-once and will not overwrite an existing file; inspect and reconcile stale configuration deliberately. connection and execution guardrails - keep the listener loopback-only. there is no authentication layer and epic says it is unsafe beyond the local machine. - do not issue overlapping tool calls. mcp synchronizes external requests by running invocations serially on the game thread. - time-bound expensive work and return progress/job ids instead of monopolizing the game thread. - discover the current tool schema. default tool-search mode advertises listtoolsets, describetoolset, and calltool rather than every tool eagerly. - validate all paths, classes, object counts, enums, and ranges inside the unreal tool even when the mcp schema also validates types. ai mutation contract for tools that change content: 1. separate inspect/plan from apply. 2. return exact affected objects and irreversible consequences in the plan. 3. require explicit user authorization for delete, overwrite, project-wide, source-control, or difficult-to-reverse operations. 4. enforce scope server-side; never trust the model to preserve a path boundary. 5. use unreal transactions/editor apis where applicable. 6. save only named packages after successful validation. 7. return structured changed/skipped/failed results and validation evidence. prefer narrow tools such as setlightintensity(actorpath, value) over generic property or script executors. make calls idempotent where possible and include a dry-run flag for batch tools. known 5.8 limitations - http and server-sent events are supported; stdio and websocket are not. - shipping toolsets do not advertise mcp resources or prompts. - the toolset registry adapter is editor-only; runtime-hosted tools require direct registration. - live coding does not propagate new tool ufunction declarations; restart the editor.

Automation and Functional Tests

# Automation and Functional Tests

## Select the test level

- **Low-Level Test**: pure code with minimal engine environment.
- **Automation unit/feature test**: API or system behavior using Unreal services.
- **Automation Spec**: behavior-driven organization and latent/asynchronous steps.
- **Functional Test**: Actor-based gameplay/map scenario, Blueprint-friendly.
- **Screenshot Comparison**: controlled rendering regression.
- **Content stress test**: loading/compiling broad content to find crashes or invalid assets.

The Automation Framework is C++-based and relies on engine systems, so Epic does not recommend
it for truly pure unit testing; use Low-Level Tests for that boundary.

## Test design

1. Put tests in a project/plugin test module with deliberate build availability.
2. Give names a stable hierarchy such as `Project.System.Behavior`.
3. Create and tear down all state the test owns.
4. Use latent commands/spec continuations for async engine work; do not block the game thread.
5. Assert observable outcomes and include diagnostic context.
6. Isolate files, maps, network roles, random seeds, and timing.

Only mark a test **Smoke** when it satisfies Epic's speed promise: intended to run at every
startup and complete within one second. Do not label slow map/content tests Smoke.

## Run and report

Interactive: enable required test plugins, then use **Tools > Test Automation**.

Command line:

```text
-ExecCmds="Automation RunTest Project.System;Quit"
-ReportExportPath="<output path>"
```

The report path produces JSON with related HTML files. Fail CI for failed tests, missing reports,
engine crashes, or timeouts.

## Functional Tests

Place/configure a Functional Test Actor in a dedicated deterministic test map. Begin only after
required actors/assets are ready; call the framework's success/failure completion path on every
branch. Keep test-only content out of production cook/chunks unless the target execution needs it.

Commandlets and headless CI

# Commandlets and headless CI

## Choose headless execution

Use `UnrealEditor-Cmd.exe` for commandlets and unattended automation. Quote the `.uproject` and
output paths. Capture stdout/stderr, process exit code, engine version, project revision, and
report artifacts.

Verified 5.8 examples:

```text
UnrealEditor-Cmd.exe Project.uproject -run=DataValidation

UnrealEditor-Cmd.exe Project.uproject -run=pythonscript -script="C:\Path\job.py"

UnrealEditor-Cmd.exe Project.uproject \
  -ExecCmds="Automation RunTest Project.Suite;Quit" \
  -ReportExportPath="C:\Reports\Automation"
```

Use `-ExecutePythonScript="..."` instead when the job needs the full editor and default startup
level loaded. The Python commandlet does not load a level automatically; load the required level
explicitly through `LevelEditorSubsystem`.

## CI contract

Each job must define:

- required plugins and build target;
- isolated workspace and writable Derived Data/Intermediate/Saved paths;
- timeout and hung-process policy;
- exact success/failure exit conditions;
- machine-readable report location;
- artifact retention for logs, screenshots, and diffs.

Never parse only a “completed” log line. Fail when the process exits nonzero, the report is absent
or malformed, tests fail, validation errors occur, or the expected output count differs.

## High-risk commandlets

`ResavePackages`, redirector cleanup, mass import, and migration rewrite many packages. Run on a
clean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect
the resulting diff. Epic's documented redirector cleanup example uses `ResavePackages` with
`-fixupredirects`; source-control flags can automatically check out files, so do not add them
without deliberate authorization.

## Determinism

Sort inputs, avoid current selection/editor UI state, seed random operations, use stable output
paths, and make retries idempotent. Record the command line with secrets removed.

Data Validation automation

# Data Validation automation

## Choose the validator

- Override `UObject::IsDataValid` when the rule belongs to a custom asset/class and may need
  private or protected data.
- Derive `UEditorValidatorBase` when a validator should cover existing engine classes, several
  classes, or project-wide policy.

For `UEditorValidatorBase`, implement `CanValidateAsset` narrowly and call `AssetPasses` or
`AssetFails` on every `ValidateLoadedAsset` execution path. Make messages actionable.

C++ and Blueprint validators are discovered at editor startup. Python validators must register
with `UEditorValidatorSubsystem.AddValidator`. The command-line Data Validation path runs C++
rules by default; do not assume editor-registered Blueprint/Python rules ran in CI without proving
the configured extension.

## Run surfaces

- One/many assets: **Asset Actions > Validate Assets**.
- Assets plus dependencies: **Validate Assets and Dependencies**.
- Folder: **Validate Assets in Folder**.
- Project: **Tools > Validate Data**.
- CI: `UnrealEditor-Cmd.exe Project.uproject -run=DataValidation`.

## Design rules

Use fast local validators on save. Put slow global uniqueness, dependency-cycle, budget, and
cross-asset relationship checks in an explicit full-project/CI stage.

An error message should contain:

```text
asset path | field/rule | received value | expected condition | repair action
```

Distinguish **Invalid** from **Not Validated**. Unsupported assets should be skipped explicitly,
not reported as passed. Treat warnings and errors according to a documented build policy.

## Validate the validator

Create fixtures that should pass, warn, and fail. Confirm interactive save, Content Browser,
project-wide validation, and commandlet behavior. A validator that only runs in one surface is
not yet a reliable gate.

Debugging and recovery

# Debugging and recovery

## Symptom routing

| Symptom | Check first |
|---|---|
| Blueprint editor node missing | Editor-only parent/module, plugin enabled, restart required |
| Scripted Action absent | Correct utility base, Call in Editor, Supported Classes, compiled/saved |
| Python class/function absent | UE 5.8 API, plugin/module enabled, reflected exposure, editor restart |
| Python commandlet sees no actors | No level auto-loaded; load intended level explicitly |
| Property changed but UI/derived state stale | Used direct assignment instead of `set_editor_property`/setter |
| Undo does nothing | Operation is not undoable or object was not transaction-aware |
| Asset exists but did not save | Package not dirty, wrong package selected, save failed/read-only |
| Automation passes locally only | Selection/UI dependence, race, machine path, missing plugin/report |
| MCP cannot connect | Server status, loopback endpoint/port, client launched from config root |
| MCP new tool missing | Toolset enabled/schema discovery, Live Coding limitation, restart |
| Editor freezes during batch | Work on game thread, no progress/cancel, scope too broad |

## Partial failure recovery

Stop on the first failure when continuing could compound damage. Preserve:

- ordered operation log;
- objects changed before failure;
- packages saved versus only dirty;
- source-control state;
- validation/test output;
- whether transaction undo is available.

If all changes are undoable and unsaved, perform and verify undo. Otherwise use source control or
the prepared backup to restore named packages. Do not improvise filesystem replacement while the
editor has packages loaded.

After recovery, restart/reload as needed, requery objects from the editor rather than trusting
stale Python references, run validation, and inspect the diff before retrying.

## Tool hardening checklist

- Rerun on already-processed content.
- Cancel halfway through.
- Inject a read-only asset and one invalid input.
- Test zero, one, and many candidates.
- Test name/path collisions.
- Test unrelated dirty packages.
- Test headless mode without selection or an open level.
- Test packaged/cook impact when runtime content changes.

Blueprint editor utilities

# Blueprint editor utilities

## Scripted Actions

Create **Content Browser > Editor Utilities > Editor Utility Blueprint** and choose:

- `AssetActionUtility` for selected Content Browser assets;
- `ActorActionUtility` for selected Level actors.

Expose a function/custom event with **Call in Editor**. Restrict **Supported Classes** so the
action appears only for valid targets. Validate dynamic inputs; the editor checks input types,
not whether a value is present or sensible.

## Editor Utility Widgets

Use an Editor Utility Widget when users need filters, preview, progress, warnings, and explicit
apply/cancel controls. Create it under **Editor Utilities > Editor Utility Widget** and run it as
an editor tab.

Recommended flow:

1. Collect selection/path/filter inputs.
2. Scan and display the candidate set.
3. Show planned changes and non-undoable consequences.
4. Require explicit **Apply** for mutations.
5. Provide progress/cancel for long batches.
6. Validate and display a per-object result table.

Editor Utility Widgets and Editor Scripting Utilities are documented as Beta in 5.8.

## Call in Editor and startup objects

Use **Call in Editor** for functions/events on a placed Actor when the same graph must be usable
at runtime or needs level context. An editor-only base class exposes more editor APIs but is not
included in packaged applications.

Startup Objects instantiate when a project opens and invoke their startup event. Keep startup
work fast, idempotent, and limited to registration/listeners. Do not perform bulk asset mutation
at editor startup. The startup-object workflow is Beta in 5.8.

## Scriptable Tools

Use a Scriptable Tool for modal viewport editing. Its managed lifecycle, shutdown before save or
PIE, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct
viewport interaction than a non-modal widget. The system is Beta in 5.8.

## Editor-only boundary

Place editor tool code and dependencies in editor-only Blueprints/modules/plugins. Prevent
runtime assets from hard-referencing editor utility classes. Test a Shipping cook for accidental
editor-only references.

Concrete automation patterns

# Concrete automation patterns

## Safe batch property editor

```text
Input: folder, class, predicate, property, proposed value
Discover: Asset Registry / editor subsystem
Plan: old -> new table, invalid objects, count, dirty/source-control state
Apply: one named transaction for undoable edits
Save: only successfully changed packages selected by policy
Verify: reload/requery property, Data Validation, diff
```

Reject unknown property names, incompatible types, root-wide accidental scope, and an empty filter
that broadens selection.

## Naming validator and fixer

Keep validation and mutation separate. Validator reports naming failures without changing data.
Fixer computes collision-free target paths, shows referencers and redirector consequences, then
uses Asset Tools rename APIs. Never use filesystem rename.

## Deterministic import pipeline

1. Parse a versioned manifest.
2. Validate source existence, destination paths, factories/options, and collisions.
3. Import into staging using `AssetImportTask`/Asset Tools.
4. Apply editor properties and build derived data where required.
5. Run validators and representative opens/compiles.
6. Promote/rename through Unreal APIs.
7. Save intended packages and emit a manifest of results.

## Editor Utility Widget wrapper

The widget owns filters, preview, progress, cancel, and user confirmation. A reusable service owns
discovery/mutation. The widget never embeds the only implementation of a production pipeline.

## CI data gate

Run Data Validation, then project automation tests, then a representative cook. Persist reports
and engine logs. Treat missing reports, timeouts, partial processing, and unexpected dirty/output
counts as failures.

## Bounded MCP tool

Expose a typed operation with a narrow path root and `dry_run=true` default. The plan returns
candidate object paths and requested changes. Apply requires explicit confirmation token/request,
runs serially, validates, saves only its packages, and returns structured results. Do not expose
an unrestricted “execute editor command” tool to compensate for missing schema.

Python editor workflows

# Python editor workflows

## Enable and version

Enable **Python Editor Script Plugin** and usually **Editor Scripting Utilities**, then restart.
Unreal 5.8 embeds Python 3.11.8. Epic labels Python Editor scripting Experimental.

Python is available only in the editor—not PIE, Standalone Game, or cooked executables. Put
project modules in `Content/Python`; `init_unreal.py` in a configured Python path runs when the
editor detects it. Keep automatic initialization lightweight.

## Execution selector

- Output Log Python mode: exploration and one-line inspection.
- **File > Execute Python Script**: manual repeatable script.
- `-ExecutePythonScript="path"`: full editor, startup level loaded, then script.
- `-run=pythonscript -script="path"`: faster commandlet/headless path; levels are not loaded
  automatically.
- Startup Scripts: run after the default startup level loads.

Epic warns against putting `py ...` inside startup `-ExecCmd`; it can execute before the editor
environment is ready.

## API pattern

```python
import unreal

assets = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
```

Inspect the generated 5.8 Python API for the exact subsystem/method available in the enabled
plugins. The reflected `unreal` module changes with plugins and project C++ exposure.

Use `get_editor_property()` and `set_editor_property()` for reflected editor fields. The setter
triggers pre/post-edit behavior that direct Python attribute assignment may skip.

## Batch shape

Implement `discover -> plan -> apply -> save -> validate -> report`. Take explicit paths/filters
as arguments; do not depend on current selection in unattended jobs. Return a nonzero process
status or raise on hard failure so CI cannot misread a partial batch as success.

Use `unreal.ScopedSlowTask` for long interactive batches and honor cancellation. Use structured
logs with object path, operation, status, and diagnostic.

Safe asset mutation

# Safe asset mutation

## Preflight

Before changing anything:

1. Resolve the exact project, level, folders, classes, and object count.
2. Refuse empty, root-wide, or unexpected scope unless explicitly authorized.
3. Record existing dirty packages and exclude them from implicit saves.
4. Check source-control/read-only state.
5. Produce a dry-run list and collision/dependency warnings.
6. Define backup/revert strategy for non-undoable operations.

## Asset operations

Use Unreal's Asset Tools, Editor Asset APIs/subsystems, factories, import tasks, and rename data.
Never use generic filesystem APIs on `.uasset` or `.umap`; doing so can break internal package
references and redirector handling.

For property changes:

1. Use editor property accessors or native setters.
2. Call the appropriate `Modify()`/transaction-aware path where required.
3. Mark affected packages dirty.
4. Save only the intended packages.
5. Requery/reload and verify the serialized result.

## Transactions

Group undoable object edits in one named `unreal.ScopedEditorTransaction` or Blueprint/C++
transaction. Transactions cover only operations the editor itself supports as undoable. Import,
save, source-control actions, and some asset operations remain irreversible even inside a scope.

Do not confuse canceling a transaction record with reverting partial object mutations. On error,
explicitly undo/restore when the API supports it; otherwise stop, report the changed set, and use
source control/backup recovery.

## Rename/delete/import

- Check destination collisions before rename.
- Fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders.
- Find referencers before deletion and require explicit confirmation for nonempty dependency sets.
- Import to a staging path, validate, then promote when feasible.
- Make generated names deterministic so reruns update or skip instead of duplicating assets.

## Completion proof

Report planned, changed, skipped, failed, saved, and still-dirty objects separately. Run Data
Validation, dependency checks, and the relevant automation test. Inspect source-control diff and
open a representative changed asset before claiming completion.

Automation surface selector

# Automation surface selector

| Task shape | Choose | Notes |
|---|---|---|
| Right-click selected assets/actors | Scripted Action | `AssetActionUtility` or `ActorActionUtility`; Beta |
| Reusable dockable UI with controls/progress | Editor Utility Widget | UMG-based; Beta |
| Action on one placed Actor, possibly shared with runtime | `Call in Editor` | Avoid editor-only nodes in runtime-capable classes |
| Interactive viewport manipulation | Scriptable Tool | Modal, accept/cancel lifecycle; Beta |
| Cross-tool pipeline or large scripted batch | Python | Editor-only; Experimental in 5.8 |
| Deterministic editor extension/API | C++ editor module/plugin | Best for stable shared tooling and native tests |
| Headless repeatable batch | Commandlet or command-line Python | Prefer for CI; prove exit code and report output |
| Asset correctness | Data Validation | `IsDataValid`/`UEditorValidatorBase` |
| Code/system behavior | Automation Test | C++ framework, specs, low-level tests as appropriate |
| Gameplay/map behavior | Functional Test | Actor-based test in a level |
| AI invokes bounded editor functions | Unreal MCP | Experimental 5.8 server; schema-driven tools |

## Architecture

Split every nontrivial tool into:

```text
UI / command / MCP adapter
  -> validated request
  -> discovery and dry-run plan
  -> mutation service
  -> save/source-control boundary
  -> validation and structured report
```

Keep domain logic out of widget graphs and MCP transport handlers. A shared C++/Blueprint
library or Python module should make the same operation callable from UI, CI, or tests without
duplicating behavior.

## Escalation rule

Use the least powerful surface that fits. A one-selection rename does not need a global startup
object; a CI validator does not need a dockable UI; an AI tool should expose one typed intent,
not a general “execute arbitrary Python” endpoint.

UE 5.8 primary sources

# UE 5.8 primary sources

Verified against Epic Games documentation for Unreal Engine 5.8 on 2026-07-19.

- [Scripting and Automating the Unreal Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-and-automating-the-unreal-editor)
- [Scripting the Unreal Editor using Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-blueprints)
- [Editor Utility Widgets](https://dev.epicgames.com/documentation/en-us/unreal-engine/editor-utility-widgets-in-unreal-engine)
- [Scripted Actions](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripted-actions-in-unreal-engine)
- [Calling Blueprints in the Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/calling-blueprints-in-the-unreal-editor)
- [Running Blueprints at Editor Startup](https://dev.epicgames.com/documentation/en-us/unreal-engine/running-blueprints-at-unreal-editor-startup)
- [Scriptable Tools System](https://dev.epicgames.com/documentation/en-us/unreal-engine/scriptable-tools-system-in-unreal-engine)
- [Scripting the Unreal Editor Using Python](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python)
- [Unreal Python 5.8 API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/?application_version=5.8)
- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)
- [Automation Test Framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-test-framework-in-unreal-engine)
- [Run Automation Tests](https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine)
- [Functional Testing](https://dev.epicgames.com/documentation/en-us/unreal-engine/functional-testing-in-unreal-engine)
- [Asset Redirectors](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-redirectors-in-unreal-engine)
- [Unreal MCP](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-mcp-in-unreal-editor)
- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)

Maturity labels recorded from Epic's 5.8 pages:

- Unreal MCP: Experimental.
- Python Editor scripting/API: Experimental.
- Editor Utility Widgets, Scripted Actions, Editor Scripting Utilities, startup Blueprint
  objects, and Scriptable Tools: Beta where their feature pages state it.

Unreal MCP in UE 5.8

# Unreal MCP in UE 5.8

## Status and boundary

Unreal MCP is new and **Experimental** in Unreal Engine 5.8. Its engine/plugin identifier is
`ModelContextProtocol`; the Plugin Browser name is **Unreal MCP**. Features, APIs, and data formats
may change. Tool implementations come from toolset plugins; Epic's overview identifies
**AllToolsets** as the plugin used to enable the supplied tools.

Use MCP for small typed editor operations, inspection, and test invocation. Do not expose
arbitrary Python/shell execution as a general tool.

## Setup facts

1. Enable **Unreal MCP** and restart.
2. In **Editor Preferences > General > Model Context Protocol**, use Auto Start or start on demand:

```text
ModelContextProtocol.StartServer 8000
```

3. Default endpoint: `http://127.0.0.1:8000/mcp`.
4. Generate a supported client config from the editor console, for example:

```text
ModelContextProtocol.GenerateClientConfig Codex
```

Generate from the project/workspace root expected by the client. Epic notes that JSON configs are
merged, while the Codex CLI TOML configuration is write-once and will not overwrite an existing
file; inspect and reconcile stale configuration deliberately.

## Connection and execution guardrails

- Keep the listener loopback-only. There is no authentication layer and Epic says it is unsafe
  beyond the local machine.
- Do not issue overlapping tool calls. MCP synchronizes external requests by running invocations
  serially on the game thread.
- Time-bound expensive work and return progress/job IDs instead of monopolizing the game thread.
- Discover the current tool schema. Default tool-search mode advertises `list_toolsets`,
  `describe_toolset`, and `call_tool` rather than every tool eagerly.
- Validate all paths, classes, object counts, enums, and ranges inside the Unreal tool even when
  the MCP schema also validates types.

## AI mutation contract

For tools that change content:

1. Separate `inspect/plan` from `apply`.
2. Return exact affected objects and irreversible consequences in the plan.
3. Require explicit user authorization for delete, overwrite, project-wide, source-control, or
   difficult-to-reverse operations.
4. Enforce scope server-side; never trust the model to preserve a path boundary.
5. Use Unreal transactions/editor APIs where applicable.
6. Save only named packages after successful validation.
7. Return structured changed/skipped/failed results and validation evidence.

Prefer narrow tools such as `set_light_intensity(actor_path, value)` over generic property or
script executors. Make calls idempotent where possible and include a dry-run flag for batch tools.

## Known 5.8 limitations

- HTTP and Server-Sent Events are supported; `stdio` and WebSocket are not.
- Shipping toolsets do not advertise MCP Resources or Prompts.
- The Toolset Registry adapter is editor-only; runtime-hosted tools require direct registration.
- Live Coding does not propagate new tool `UFUNCTION` declarations; restart the editor.