unreal-ai git:20261031.7b68c26A

Immutable. This exact content never changes and is served at /api/v1/blob/4e6ac7b6434abe0b.

---
name: unreal-ai
description: >-
  Domain skill - author and inspect Unreal Engine AI Blackboard data through
  runtime-gated Python editor APIs. Provides a typed capability preflight,
  bounded readback, and one minimal, transaction-backed key-authoring action.
  Behavior-tree graph, StateTree and EQS node editing are documented gaps and
  are not implemented here.
license: MIT
compatibility: Unreal Engine 5.0+, Python 3.7 syntax; runtime-gated, not native-qualified
allowed-tools: Bash Read Write
metadata:
  dcc-mcp:
    dcc: unreal
    version: "0.1.0"
    layer: domain
    stage: authoring
    search-hint: "unreal ai blackboard behavior tree key author inspect preflight state tree eqs"
    tags: "unreal, ai, blackboard, behavior-tree, key, authoring, preflight"
    tools: tools.yaml
---

# Unreal AI (Blackboard authoring)

An independently usable, runtime-gated Python route to the smallest high-value
AI authoring primitive: **AI Blackboard data**. It gates the exact engine
version, Python-exposed API symbols and adapter native bridge it needs before
touching the editor, then performs one minimal, undoable action with a real
reflected readback. It reuses the existing main-thread dispatcher and calls the
`DccMcpAutomationLibrary.get_enabled_plugin_names` C++ native bridge directly
for plugin enumeration (the same bridge `plugin_preflight.py` uses, but it does
not import that helper module); it adds no new discovery, threading or service
architecture.

## Capability matrix (evidence-based)

A missing same-named directory is not proof of missing support. The matrix
below distinguishes what this adapter already covers, what is partial, and the
real gaps, based on the current tool inventory and code evidence. See
[the full matrix](../../../../docs/unreal-ai-capability-matrix.md) for file and
version evidence.

| Capability | Status | Evidence / route |
| --- | --- | --- |
| AI Blackboard data | **supported (this slice)** | `unreal-ai`: preflight, inspect, author one typed key, transaction + readback |
| Behavior-tree graph nodes | **gap** | no Python-exposed graph node authoring; needs the plugin's C++ `DccMcpAutomationLibrary` typed bridge |
| StateTree | **gap** | no tool; needs the StateTree plugin and a C++ typed bridge, version-gated |
| EQS queries | **gap** | no tool; needs a C++ typed bridge; unqualified across engine versions |
| AI Perception config | **partial** | actor/component tools exist (`unreal-actors`) but there is no AI editor facade |
| Gameplay Tags registry | **partial** | config editing only, no typed tag-registry tool |
| Blueprint / Niagara / MetaSound / UMG / PCG | **supported** | existing domain skills; not re-created here |

The reference design's own evidence note concedes that many version/native AI
operations are untested. This skill does not treat that list as maturity: every
operation is gated at call time and fails closed with a typed reason and one
`next_action` when a host does not expose the required surface. Graph-level AI
authoring is intentionally left as a documented C++-bridge gap rather than a
shallow one-to-one C++-module-to-skill mapping.

## Workflow

1. Call `ai_capability_preflight` first. It is read-only and returns `ready`,
   the engine version, available/missing API symbols, enabled plugins, and one
   deterministic `next_action` (`proceed`, `update_adapter_plugin`, or
   `unsupported_engine_version`). Proceed only when `ready` is true.
2. Call `inspect_ai_blackboard` to read the asset's typed keys. A missing asset
   returns `exists=false` with `readback_verified=true`; an existing wrong-class asset is
   rejected, never overwritten.
3. Call `author_ai_blackboard_key` with `asset_path`, `key_name` and a `key_type`
   from the schema enum. It creates an empty Blackboard only when the path is
   free and `create_if_missing` is true, then adds one key inside a scoped editor
   transaction. It verifies the new key through a reflected readback **before**
   saving, and returns a receipt with `key_count_before`, `key_count_after`,
   `mutation_state` and `recovery_errors`.
4. Re-run `inspect_ai_blackboard` to confirm the key in a fresh readback.

## Preflight, errors, and undo/cancel

- Preflight gates: Unreal Engine `>= 5.0`, the seven required Python-exposed
  symbols **and** the editor methods the write path calls, plus the adapter's
  native plugin-enumeration bridge. A failed gate yields `ready=false` and one
  machine-readable `next_action`.
- Typed errors carry a `reason` such as `preflight_not_ready`,
  `unsupported_api`, `invalid_asset_path`, `invalid_key_name`,
  `unsupported_key_type`, `duplicate_key`, `wrong_asset_class`,
  `asset_load_failed`, `readback_mismatch`, `readback_type_mismatch`,
  `save_failed` and `limit_exceeded`.
- Undo/cancel: the mutation is wrapped in `ScopedEditorTransaction`. On any
  failure the error context carries `created` and `recovery_errors`. If this
  call created the asset, that asset is deleted (best effort) so a
  `rolled_back` result leaves no new empty asset behind; a failed deletion is
  recorded in `recovery_errors`. An existing asset is never overwritten, and
  an existing-but-unloadable asset fails closed with `asset_load_failed`. The
  observed key array is restored and the transaction cancelled. Cancellation
  is advisory for an operation already running in the editor - it does not
  interrupt the editor process.

## Limits and honest boundaries

- At most 128 keys, 96-character key names, and a 240-character `/Game` package
  path; exceeding a limit rejects the operation rather than truncating.
- Real result readback is reflected editor state in the current session. A
  successful `save` is **not** proof of disk persistence or editor-restart
  survival. `generation_verified` and `reopen_verified` stay false.
- Real Unreal Editor / commandlet and GUI/PIE acceptance are separate gates and
  are not claimed here. The bounded unit contracts live in
  `tests/test_ai_blackboard_authoring.py`; a host commandlet probe is sketched
  in `tests/ue_ai_blackboard_commandlet.py`.