#!/usr/bin/env python3
"""Thrixel -> Roblox asset sync.

One command gets every mesh under thrixel_assets/ into the open Studio place:

    python3 tools/roblox_helpers.py sync [--only Name ...] [--user-id N] > swap.luau

It uploads new or changed meshes to Open Cloud (content-hash cached, so re-runs
never re-upload), rewrites src/shared/AssetIds.luau, and prints one Luau chunk
to stdout (progress goes to stderr). Run that chunk through execute_luau
(datamodel_type "Edit"): it inserts missing models into ReplicatedStorage.Assets,
replaces stale ones, and sets the edit-time MeshPart properties clones inherit.
Idempotent end to end — re-running both steps is always safe.

Layout: one directory per asset, `thrixel_assets/<Name>/`. The directory name is
the asset's identity; inside it the newest .fbx wins, else the newest .glb.
Needs `roblox_api_key.txt` in the project root, and (first upload only) the
creator user id via --user-id or ROBLOX_USER_ID — get it with
`execute_luau: return game.CreatorId`.
"""

import json
import os
import re
import ssl
import sys
import time
import urllib.error
import urllib.request
import uuid
from hashlib import sha1
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
ASSET_DIR = ROOT / "thrixel_assets"
KEY_FILE = ROOT / "roblox_api_key.txt"
MANIFEST = ROOT / "assets" / "manifest.json"
OUT_LUAU = ROOT / "src" / "shared" / "AssetIds.luau"

API_CREATE = "https://apis.roblox.com/assets/v1/assets"
API_OP = "https://apis.roblox.com/assets/v1/operations/{}"
CONTENT_TYPES = {".glb": "model/gltf-binary", ".fbx": "model/fbx"}
MAX_BYTES = 20 * 1024 * 1024

_SSL = ssl.create_default_context()

LUAU_HEADER = """--!strict
-- AssetIds — GENERATED by tools/roblox_helpers.py sync. Do not edit by hand.
return {
"""

SWAP_TEMPLATE = """local InsertService = game:GetService("InsertService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local ASSETS = {
__ASSETS__
}

local folder = ReplicatedStorage:FindFirstChild("Assets")
if not folder then
\tfolder = Instance.new("Folder")
\tfolder.Name = "Assets"
\tfolder.Parent = ReplicatedStorage
end

local log = {}
for _, entry in ipairs(ASSETS) do
\tlocal name, id = entry[1], entry[2]
\tlocal existing = folder:FindFirstChild(name)
\tif existing and existing:GetAttribute("AssetId") == id then
\t\ttable.insert(log, name .. ": up to date")
\t\tcontinue
\tend
\tif existing then
\t\texisting:Destroy()
\tend
\tlocal ok, result = pcall(InsertService.LoadAsset, InsertService, id)
\tif not ok then
\t\ttable.insert(log, name .. ": FAILED " .. tostring(result):sub(1, 90))
\t\tcontinue
\tend
\t-- LoadAsset wraps the uploaded Model in a container Model; unwrap one level.
\tlocal inner = result:GetChildren()[1]
\tlocal model = if inner and inner:IsA("Model") then inner else result
\tmodel.Name = name
\tmodel:SetAttribute("AssetId", id)
\tlocal meshes = 0
\tfor _, d in ipairs(model:GetDescendants()) do
\t\tif d:IsA("MeshPart") then
\t\t\td.CollisionFidelity = Enum.CollisionFidelity.Box
\t\t\td.RenderFidelity = Enum.RenderFidelity.Automatic
\t\t\td.Anchored = true
\t\t\td.CanCollide = false
\t\t\td.CanTouch = false
\t\t\tmeshes += 1
\t\tend
\tend
\tmodel.Parent = folder
\tif model ~= result then
\t\tresult:Destroy()
\tend
\tlocal _, size = model:GetBoundingBox()
\ttable.insert(log, string.format("%s: swapped in, %d meshparts, bbox %.1f x %.1f x %.1f studs",
\t\tname, meshes, size.X, size.Y, size.Z))
end
table.insert(log, "Assets folder holds " .. #folder:GetChildren() .. " models.")
return table.concat(log, "\\n")
"""


def log(msg):
    """Print a progress line to stderr, keeping stdout clean for the Luau chunk."""
    print(msg, file=sys.stderr)


def api_key():
    """Return the Open Cloud API key from roblox_api_key.txt.

    Returns:
        The key as a stripped string. Exits with a message if the file is missing.
    """
    if not KEY_FILE.exists():
        sys.exit(f"No API key at {KEY_FILE}")
    return KEY_FILE.read_text().strip()


def load_manifest():
    """Return the upload cache from assets/manifest.json, or {} if absent."""
    return json.loads(MANIFEST.read_text()) if MANIFEST.exists() else {}


def save_manifest(manifest):
    """Write the upload cache back to assets/manifest.json."""
    MANIFEST.parent.mkdir(parents=True, exist_ok=True)
    MANIFEST.write_text(json.dumps(manifest, indent=2, sort_keys=True))


def find_mesh(directory):
    """Pick the mesh file to upload for one asset directory.

    FBX keeps part names and Architect flat colours; GLB keeps full PBR maps.
    Which format an asset uses is chosen by which file is in its directory.

    Args:
        directory: The `thrixel_assets/<Name>/` directory.

    Returns:
        The newest .fbx in the directory if any, else the newest .glb
        (searching subdirectories too), else None.
    """
    fbx = list(directory.glob("*.fbx"))
    if fbx:
        return max(fbx, key=lambda p: p.stat().st_mtime)
    glbs = list(directory.glob("*.glb")) or list(directory.rglob("*.glb"))
    return max(glbs, key=lambda p: p.stat().st_mtime) if glbs else None


def resolve_user_id(cli_value):
    """Resolve the creator user id for uploads.

    Checks, in order: the --user-id flag, the ROBLOX_USER_ID env var, and the
    `_userId` cached in the manifest. Whatever is found is cached back into the
    manifest so later runs need nothing.

    Args:
        cli_value: The --user-id argument, or None.

    Returns:
        The user id as a string. Exits with instructions if none is available.
    """
    manifest = load_manifest()
    uid = cli_value or os.environ.get("ROBLOX_USER_ID") or manifest.get("_userId")
    if not uid:
        sys.exit(
            "No creator user id. Get it via execute_luau (`return game.CreatorId`) "
            "and pass --user-id N (cached after the first run)."
        )
    if manifest.get("_userId") != str(uid):
        manifest["_userId"] = str(uid)
        save_manifest(manifest)
    return str(uid)


def _multipart(fields, file_field, path, ctype):
    boundary = f"----claude{uuid.uuid4().hex}"
    out = bytearray()
    for key, value in fields.items():
        out += f"--{boundary}\r\n".encode()
        out += f'Content-Disposition: form-data; name="{key}"\r\n\r\n'.encode()
        out += value.encode() + b"\r\n"
    out += f"--{boundary}\r\n".encode()
    out += (
        f'Content-Disposition: form-data; name="{file_field}"; '
        f'filename="{path.name}"\r\n'
    ).encode()
    out += f"Content-Type: {ctype}\r\n\r\n".encode()
    out += path.read_bytes() + b"\r\n"
    out += f"--{boundary}--\r\n".encode()
    return bytes(out), f"multipart/form-data; boundary={boundary}"


def _request(url, data=None, ctype=None, method="GET"):
    req = urllib.request.Request(url, data=data, method=method)
    req.add_header("x-api-key", api_key())
    if ctype:
        req.add_header("Content-Type", ctype)
    try:
        with urllib.request.urlopen(req, context=_SSL, timeout=180) as r:
            return json.loads(r.read().decode())
    except urllib.error.HTTPError as e:
        body = e.read().decode(errors="replace")
        raise RuntimeError(f"HTTP {e.code} from {url}\n{body}") from None


def upload(path, display_name, user_id):
    """Upload one mesh to Open Cloud and wait for the import to finish.

    Args:
        path: The .glb or .fbx file.
        display_name: Roblox-side display name for the asset.
        user_id: Creator user id for the upload's creationContext.

    Returns:
        The new asset id as a string.

    Raises:
        RuntimeError: On an unsupported extension, an API error, an import
            failure, or a poll timeout (10 minutes).
    """
    ctype = CONTENT_TYPES.get(path.suffix.lower())
    if not ctype:
        raise RuntimeError(f"Unsupported extension {path.suffix}")

    request_json = json.dumps(
        {
            "assetType": "Model",
            "displayName": display_name,
            "description": "Generated with Thrixel.",
            "creationContext": {"creator": {"userId": user_id}},
        }
    )
    body, content_type = _multipart({"request": request_json}, "fileContent", path, ctype)
    op = _request(API_CREATE, data=body, ctype=content_type, method="POST")
    op_id = op.get("operationId") or op.get("path", "").split("/")[-1]
    if not op_id:
        raise RuntimeError(f"No operation id in create response: {op}")

    deadline = time.time() + 600
    delay = 2.0
    while time.time() < deadline:
        time.sleep(delay)
        delay = min(delay * 1.3, 15.0)
        result = _request(API_OP.format(op_id))
        if not result.get("done"):
            continue
        if "response" in result:
            state = result["response"].get("moderationResult", {}).get("moderationState")
            if state and "approved" not in state.lower():
                log(f"  ! moderation state: {state}")
            return str(result["response"]["assetId"])
        raise RuntimeError(f"Upload failed: {json.dumps(result.get('error', result))}")
    raise RuntimeError(f"Timed out waiting for operation {op_id}")


def upload_cached(path, display_name, user_id):
    """Upload a mesh unless its exact bytes were uploaded before.

    The cache key is display name plus content hash, so a regenerated asset
    (same name, new bytes) is a real new upload while an unchanged file keeps
    the id it already had.

    Args:
        path: The mesh file.
        display_name: Roblox-side display name, also part of the cache key.
        user_id: Creator user id, used only when an upload actually happens.

    Returns:
        A (asset_id, cached) tuple; cached is True on a cache hit.
    """
    key = f"{display_name}:{sha1(path.read_bytes()).hexdigest()[:16]}"
    manifest = load_manifest()
    if key in manifest:
        return manifest[key]["assetId"], True
    asset_id = upload(path, display_name, user_id)
    manifest = load_manifest()
    manifest[key] = {
        "assetId": asset_id,
        "name": display_name,
        "file": str(path.relative_to(ROOT)) if ROOT in path.parents else str(path),
        "bytes": path.stat().st_size,
    }
    save_manifest(manifest)
    return asset_id, False


def read_asset_ids():
    """Parse src/shared/AssetIds.luau into a {name: asset_id} dict ({} if absent)."""
    if not OUT_LUAU.exists():
        return {}
    pairs = re.findall(
        r'^\s*(\w+)\s*=\s*"rbxassetid://(\d+)"', OUT_LUAU.read_text(), re.MULTILINE
    )
    return dict(pairs)


def write_asset_ids(results):
    """Write the {name: asset_id} table to src/shared/AssetIds.luau for Rojo."""
    lines = [LUAU_HEADER]
    for name in sorted(results):
        lines.append(f'\t{name} = "rbxassetid://{results[name]}",\n')
    lines.append("}\n")
    OUT_LUAU.parent.mkdir(parents=True, exist_ok=True)
    OUT_LUAU.write_text("".join(lines))


def emit_swap_luau(results):
    """Render the Studio-side swap chunk for execute_luau (Edit).

    The chunk is idempotent per asset: a model in ReplicatedStorage.Assets whose
    AssetId attribute matches is skipped; anything else is destroyed, reinserted
    via InsertService:LoadAsset, unwrapped, renamed, stamped with the attribute,
    and has its MeshParts prepared (Box collision, Automatic render fidelity,
    anchored, no collide/touch — all edit-time-only, inherited by clones).

    Args:
        results: {name: asset_id} for every asset in the game.

    Returns:
        The complete Luau source as a string.
    """
    rows = "\n".join(f'\t{{ "{n}", {results[n]} }},' for n in sorted(results))
    return SWAP_TEMPLATE.replace("__ASSETS__", rows)


def sync(only, user_id_arg):
    """Upload changed meshes, rewrite AssetIds.luau, print the swap chunk.

    Args:
        only: Set of asset names to (re)upload, or None for all. Assets outside
            the filter keep their existing ids from AssetIds.luau.
        user_id_arg: The --user-id value, or None. Only resolved if an upload
            actually happens.
    """
    if not ASSET_DIR.exists():
        sys.exit(f"No {ASSET_DIR}")
    dirs = sorted(d for d in ASSET_DIR.iterdir() if d.is_dir())
    if not dirs:
        sys.exit(f"No asset directories in {ASSET_DIR}")

    names = {d.name for d in dirs}
    results = {n: i for n, i in read_asset_ids().items() if n in names}
    uid = None
    problems = []

    for d in dirs:
        if only and d.name not in only:
            continue
        mesh = find_mesh(d)
        if not mesh:
            problems.append(f"{d.name}: no .fbx or .glb found")
            continue
        size = mesh.stat().st_size
        if size > MAX_BYTES:
            problems.append(
                f"{d.name}: {size / 1e6:.1f} MB exceeds the 20 MB Open Cloud limit "
                "— reduce triangles or drop texture_size"
            )
            continue
        display = f"{ROOT.name} {d.name}"
        key = f"{display}:{sha1(mesh.read_bytes()).hexdigest()[:16]}"
        if uid is None and key not in load_manifest():
            uid = resolve_user_id(user_id_arg)
        try:
            asset_id, cached = upload_cached(mesh, display, uid)
            results[d.name] = asset_id
            flag = "cached" if cached else f"uploaded {size / 1e6:.1f} MB"
            log(f"  {d.name:<16} {asset_id}  ({flag})")
        except Exception as exc:  # noqa: BLE001 - report and keep going
            problems.append(f"{d.name}: {exc}")

    write_asset_ids(results)
    log(f"Wrote {OUT_LUAU.relative_to(ROOT)} with {len(results)} assets.")
    print(emit_swap_luau(results))
    log("Swap chunk on stdout — run it through execute_luau (Edit).")

    if problems:
        log(f"{len(problems)} problem(s):")
        for p in problems:
            log(f"  ! {p}")
        sys.exit(1)


def main():
    """Parse arguments and dispatch. Only subcommand: sync."""
    import argparse

    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest="command", required=True)
    p_sync = sub.add_parser("sync", help="upload changed meshes and print the swap chunk")
    p_sync.add_argument("--only", nargs="+", metavar="NAME", help="limit to these assets")
    p_sync.add_argument("--user-id", help="creator user id (cached after first use)")
    args = parser.parse_args()
    sync(set(args.only) if args.only else None, args.user_id)


if __name__ == "__main__":
    main()

/**
 * Reference main.js. Every project's entry point does these seven things in this
 * order; copy it and change the system list.
 *
 * The order matters and each step is load-bearing — see the comments.
 */
import { Engine, boot, Input, configFromLocation, installShotApi, signalReady, prewarm } from '../lib/index.js';

import { RenderSystem } from './systems/render.js';
import { WorldSystem } from './systems/world.js';
import { PlayerSystem } from './systems/player.js';
import { FxSystem } from './systems/fx.js';
import { UiSystem } from './systems/ui.js';
import { SHOTS, clearState } from './shots.js';

// 1. Config comes from the URL, so every tool can drive the game with no UI.
const { config, capture, lockstep, shot } = configFromLocation();

const canvas = document.getElementById('game');
const input = new Input(canvas, { sensitivity: config.sensitivity });
const engine = new Engine({ canvas, config, input });

// 2. Registration order is irrelevant — the Registry topo-sorts on static deps.
//    That means adding a system never means working out where in a list it goes.
engine.add(RenderSystem).add(WorldSystem).add(PlayerSystem).add(FxSystem).add(UiSystem);

// 3. Boot with a visible failure. A black canvas with the error only in devtools
//    costs a whole capture cycle to diagnose.
await boot(engine);

// 4. Install the dev/capture API BEFORE prewarm, so the harness can already see
//    the shot list, and so capture mode's fixed shutter clock is in place before
//    anything steps the engine.
const shotApi = installShotApi(engine, { shots: SHOTS, capture, lockstep, clearState });

// 5. Compile every shader permutation while nothing is on screen yet. On by
//    default; `?prewarm=0` opts out, which is also how you A/B its pixel
//    neutrality with tools/baseline.mjs --query=prewarm=0.
window.__PREWARM__ = config.prewarm
  ? await prewarm(engine)
  : { ok: false, reason: 'disabled by ?prewarm=0' };
console.info('[boot] prewarm', window.__PREWARM__);

engine.start();

// 6. Apply the requested shot, then raise __READY__ after a fixed FRAME COUNT —
//    not a timeout. This is what makes boot duration irrelevant to output.
if (shot) window.__APPLY_SHOT__(shot);
await signalReady(shotApi, 3);

// 7. HMR must dispose, or every save leaks a scene's worth of GPU resources
//    until the context is lost and the page goes black mid-iteration.
if (import.meta.hot) import.meta.hot.dispose(() => engine.dispose());

/**
 * THE SHOT LIST. Write this on day one, before any art or feature work.
 *
 * A shot is a named, fixed framing that every review round re-captures. Its job
 * is to make iteration N comparable to iteration N+1 — if the framing drifts,
 * every critique is noise and you cannot tell improvement from camera luck.
 *
 * Cover the axes your game will be judged on, one shot per axis, and say in
 * `doc` what each shot is FOR. That sentence is what a reviewer reads, and it is
 * what stops them from critiquing the wrong thing.
 *
 * Aim for 8-12. Fewer and a whole class of defect has no witness; many more and
 * a review round costs too much to run often.
 */
export const SHOTS = {
  // --- establishing / art direction -------------------------------------
  hero: {
    pos: [0, 1.9, 18],
    look: [0, 1.4, -6],
    fov: 70,
    time: 16.5,
    doc: 'Wide establishing view — overall art direction, silhouette, composition.',
  },
  // --- close-range material quality (the most common failure) -----------
  detail: {
    pos: [3.1, 1.15, 4.5],
    look: [1.6, 0.95, 3.0],
    fov: 45,
    time: 16.5,
    doc: 'Close-up on a surface — texel density, normal detail, grime, edge wear.',
  },
  // --- lighting extremes ------------------------------------------------
  sunset: {
    pos: [3.0, 2.6, 16],
    look: [-2.0, 1.7, -8],
    fov: 65,
    time: 19.2,
    doc: 'Low sun — long shadows, scattering, bloom, exposure at the extremes.',
  },
  night: {
    pos: [0, 1.9, 18],
    look: [0, 1.4, -6],
    fov: 70,
    time: 1.5,
    doc: 'Night — artificial lights, exposure adaptation, shadow quality in the dark.',
  },
  // --- interior: bounce, AO, contact shadows ----------------------------
  interior: {
    pos: [-2.6, 1.7, 0.2],
    look: [-6.5, 1.4, 0.0],
    fov: 70,
    time: 16.5,
    doc: 'Enclosed space — ambient occlusion, bounce light, contact shadows.',
  },
  // --- transient FX. `apply` schedules the event to peak ON the captured
  //     frame, using opts.grabFrame — guessing does not work for a 50 ms flash.
  impacts: {
    pos: [3.0, 1.45, 1.4],
    look: [-1.4, 1.2, 0.65],
    fov: 60,
    time: 16.5,
    apply: (e, o) => e.ctx.peek('fx')?.debugBurst?.('wall', o),
    doc: 'Impact FX — decals, sparks, dust, light spill, debris.',
  },
  // --- UI over gameplay -------------------------------------------------
  hud: {
    pos: [0, 1.9, 18],
    look: [0, 1.4, -6],
    fov: 70,
    time: 16.5,
    apply: (e) => e.ctx.peek('ui')?.debugState?.('busy'),
    doc: 'Full HUD in its busiest state — layout, contrast, readability.',
  },
};

/**
 * Put transient gameplay state back to neutral. Called before every shot's own
 * apply(). Without this, the previous shot's looping debug state is still running
 * during the next one, and the next review round reports phantom regressions.
 */
export function clearState(engine) {
  engine.ctx.peek('fx')?.debugBurst?.('none');
  engine.ctx.peek('ui')?.debugState?.('clean');
}

/**
 * One place for tuning and quality. Subsystems read `ctx.config` instead of
 * hardcoding numbers, so the quality scaler, the capture harness and the
 * profiler can all drive the whole game from a single object.
 *
 * Rule: if a subsystem has a magic number that a reviewer might want to change,
 * it belongs here or in that subsystem's own exported constants — never inline
 * in the middle of an update().
 */

export const PHYSICS_HZ = 120;
export const FIXED_DT = 1 / PHYSICS_HZ;
/** Never simulate more than this many fixed steps in one frame. Without this a
 *  slow frame makes the next frame slower, forever (the "spiral of death"). */
export const MAX_SUBSTEPS = 8;
/** Longest frame delta the simulation will accept. A tab switch or a debugger
 *  pause otherwise teleports everything. */
export const MAX_FRAME_DT = 0.1;

/**
 * Quality presets. Every entry is a BUDGET or a FEATURE FLAG, never a
 * brightness/scale fudge — a preset must change cost, not art direction.
 * Subsystems must honour the budgets and must never exceed them.
 *
 * `maxPixelRatio` is the one that decides whether a phone can run the game at
 * all, and it is the easiest to get wrong because desktop hides it: a phone
 * reports devicePixelRatio 3, so an uncapped renderer draws roughly 3.5x the
 * pixels of a 1080p laptop on a fraction of the GPU. Resolution, not geometry,
 * is what costs the frames — see threejs.md, Performance doctrine.
 */
export const QUALITY_PRESETS = {
  low: {
    maxPixelRatio: 1.5,
    renderScale: 0.72,
    shadowMapSize: 1024,
    shadowDistance: 60,
    cascades: 2,
    postAa: false,
    ao: false,
    reflections: false,
    volumetrics: false,
    motionBlur: false,
    bloom: true,
    anisotropy: 4,
    particleBudget: 2000,
    decalBudget: 64,
    maxDynamicLights: 4,
  },
  medium: {
    maxPixelRatio: 2,
    renderScale: 0.85,
    shadowMapSize: 2048,
    shadowDistance: 90,
    cascades: 3,
    postAa: true,
    ao: true,
    reflections: false,
    volumetrics: true,
    motionBlur: true,
    bloom: true,
    anisotropy: 8,
    particleBudget: 6000,
    decalBudget: 128,
    maxDynamicLights: 8,
  },
  high: {
    maxPixelRatio: 2,
    renderScale: 1.0,
    shadowMapSize: 2048,
    shadowDistance: 140,
    cascades: 4,
    postAa: true,
    ao: true,
    reflections: true,
    volumetrics: true,
    motionBlur: true,
    bloom: true,
    anisotropy: 16,
    particleBudget: 12000,
    decalBudget: 256,
    maxDynamicLights: 12,
  },
  ultra: {
    maxPixelRatio: 2,
    renderScale: 1.0,
    shadowMapSize: 4096,
    shadowDistance: 200,
    cascades: 4,
    postAa: true,
    ao: true,
    reflections: true,
    volumetrics: true,
    motionBlur: true,
    bloom: true,
    anisotropy: 16,
    particleBudget: 24000,
    decalBudget: 512,
    maxDynamicLights: 16,
  },
};

export const DEFAULTS = {
  quality: 'high',
  fov: 70,
  exposure: 1.0,
  sensitivity: 0.0022,
  /** Set by the capture harness. Disables everything nondeterministic: seeds the
   *  RNG from a constant, freezes input, fixes the frame delta. */
  deterministic: false,
  /** Compile every shader permutation before the first frame. See lib/prewarm.js. */
  prewarm: true,
};

/**
 * Pick a starting preset for the device this is running on.
 *
 * Coarse on purpose. There is no reliable way to ask a browser how fast its GPU
 * is, and every attempt to infer it from the UA string ages badly, so this only
 * separates handheld from not: a phone or tablet starts at `low`, everything
 * else at `high`. A game that wants better should measure the first few seconds
 * of real frame time and call `config.setQuality()` — a running frame rate is
 * the only honest signal, and it is available to every game for free.
 */
export function autoQuality(fallback = 'high') {
  if (typeof matchMedia !== 'function') return fallback;
  const handheld = matchMedia('(hover: none) and (pointer: coarse)').matches;
  return handheld ? 'low' : fallback;
}

export function createConfig(overrides = {}) {
  const cfg = { ...DEFAULTS, ...overrides };
  const name = QUALITY_PRESETS[cfg.quality] ? cfg.quality : DEFAULTS.quality;
  cfg.quality = name;
  cfg.q = { ...QUALITY_PRESETS[name] };
  cfg.setQuality = (next) => {
    if (!QUALITY_PRESETS[next]) throw new Error(`unknown quality preset "${next}"`);
    cfg.quality = next;
    // Mutate in place: subsystems are allowed to hold a reference to cfg.q.
    Object.assign(cfg.q, QUALITY_PRESETS[next]);
  };
  return cfg;
}

/** Read config out of the URL, so every tool can drive the game without a UI:
 *  ?capture=1&lockstep=1&q=low&shot=hero&prewarm=0&seed=12345 */
export function configFromLocation(search = globalThis.location?.search ?? '') {
  const p = new URLSearchParams(search);
  const capture = p.get('capture') === '1';
  return {
    params: p,
    capture,
    lockstep: capture && p.get('lockstep') === '1',
    shot: p.get('shot') ?? null,
    config: createConfig({
      // No ?q= -> pick by device, so a phone opening a shared link is not
      // handed the desktop preset. Capture pins `high` instead: the pixel gate
      // compares runs against each other, and a preset that varies by machine
      // would make every diff meaningless.
      quality: p.get('q') ?? (capture ? DEFAULTS.quality : autoQuality()),
      deterministic: capture,
      prewarm: p.get('prewarm') !== '0',
      seed: p.get('seed') ? Number(p.get('seed')) >>> 0 : undefined,
    }),
  };
}

/**
 * Disposal. WebGL resources are not garbage collected — a geometry, material,
 * texture or render target you drop the last reference to stays on the GPU until
 * you call dispose(). Two symptoms in practice: VRAM climbing over a session,
 * and (with HMR) each reload leaking a whole scene's worth of textures until the
 * context is lost and the page goes black mid-iteration.
 *
 * Every subsystem's dispose() should be able to be written as:
 *   dispose() { disposeTree(this.root); this.root.parent?.remove(this.root); }
 */

/** Dispose one material and every texture it references. */
export function disposeMaterial(material) {
  if (!material) return 0;
  let n = 0;
  for (const key of Object.keys(material)) {
    const v = material[key];
    if (v && v.isTexture) {
      v.dispose();
      n++;
    }
  }
  // Uniforms of a ShaderMaterial / patched material hold textures too.
  const u = material.uniforms;
  if (u) {
    for (const k of Object.keys(u)) {
      const v = u[k]?.value;
      if (v && v.isTexture) {
        v.dispose();
        n++;
      }
    }
  }
  material.dispose();
  return n;
}

/**
 * Recursively dispose geometries, materials and textures under `root`.
 * Materials and geometries are deduped, because sharing them is the norm and
 * double-disposing a shared material in a partial teardown is a real crash.
 * Does NOT detach `root` from its parent — that is the caller's call.
 */
export function disposeTree(root, { removeChildren = true } = {}) {
  if (!root) return { geometries: 0, materials: 0, textures: 0 };
  const geos = new Set();
  const mats = new Set();
  root.traverse((o) => {
    if (o.geometry) geos.add(o.geometry);
    const m = o.material;
    if (Array.isArray(m)) for (const x of m) mats.add(x);
    else if (m) mats.add(m);
  });
  let textures = 0;
  for (const g of geos) g.dispose();
  for (const m of mats) textures += disposeMaterial(m);
  if (removeChildren) root.clear?.();
  return { geometries: geos.size, materials: mats.size, textures };
}

/** Dispose a list of render targets / textures / anything with .dispose(). */
export function disposeAll(...items) {
  for (const list of items) {
    for (const it of Array.isArray(list) ? list : [list]) it?.dispose?.();
  }
}

/**
 * Track what you create so dispose() cannot forget one. Cheap enough to use
 * everywhere, and it turns "did I dispose the 14 render targets" into one call.
 *
 *   this.own = new Owned();
 *   const rt = this.own.add(new THREE.WebGLRenderTarget(...));
 *   ...
 *   dispose() { this.own.disposeAll(); }
 */
export class Owned {
  #items = new Set();

  add(item) {
    if (item?.dispose) this.#items.add(item);
    return item;
  }

  addAll(...items) {
    for (const i of items.flat()) this.add(i);
    return items;
  }

  disposeAll() {
    let n = 0;
    for (const i of this.#items) {
      try {
        i.dispose();
        n++;
      } catch (err) {
        console.warn('[dispose] threw', err);
      }
    }
    this.#items.clear();
    return n;
  }

  get size() {
    return this.#items.size;
  }
}

import * as THREE from 'three';
import { Registry, EventBus } from './registry.js';
import { FIXED_DT, MAX_SUBSTEPS, MAX_FRAME_DT } from './config.js';
import { Rng } from './rng.js';

/**
 * The Engine owns the frame loop and the `ctx` object every subsystem receives.
 * It knows NOTHING about any subsystem — it only sequences them. Every
 * game-specific decision lives in a subsystem, which is what makes one owner
 * able to rewrite one directory without reading the rest.
 *
 * Frame order — deliberate, and worth keeping:
 *   1. input.beginFrame()      snapshot; gameplay never touches DOM events
 *   2. fixedUpdate(FIXED_DT)*N physics / deterministic simulation
 *   3. update(dt)              animation, cameras, decisions
 *   4. lateUpdate(dt)          anything that must observe FINAL transforms
 *   5. render                  the 'render' system draws
 *   6. input.endFrame()        clear per-frame edges
 *
 * `time.alpha` is the interpolation factor between the last two fixed steps.
 * Render transforms from interpolated state, or everything visibly ticks at the
 * physics rate instead of the display rate.
 */
export class Engine {
  constructor({ canvas, config, input = null }) {
    this.canvas = canvas;
    this.config = config;
    this.registry = new Registry();
    this.events = new EventBus();
    this.input = input;
    this.rng = new Rng(
      config.deterministic ? (config.seed ?? 0x5eed1234) : (config.seed ?? (Math.random() * 2 ** 32) >>> 0)
    );

    this.scene = new THREE.Scene();
    this.camera = new THREE.PerspectiveCamera(config.fov, 1, 0.05, 1200);
    // YXZ so yaw/pitch can be set directly without gimbal surprises.
    this.camera.rotation.order = 'YXZ';

    /**
     * A second scene+camera drawn after the world with a cleared depth buffer,
     * with its own near plane. Use it for anything held by / attached to the
     * viewer that must never clip into world geometry: a first-person weapon or
     * tool, a held item, a cockpit interior, a card in hand. Leave it empty and
     * the render system should skip the pass entirely.
     */
    this.overlayScene = new THREE.Scene();
    this.overlayCamera = new THREE.PerspectiveCamera(60, 1, 0.005, 12);

    this.time = {
      /** Scaled seconds since start. THE clock. Animate off this, never off
       *  performance.now() — see PITFALLS.md #1. */
      elapsed: 0,
      /** Unscaled seconds since start. For UI timers that ignore slow motion. */
      raw: 0,
      /** Last frame delta, scaled and clamped. */
      dt: 0,
      fixed: FIXED_DT,
      /** 0..1 between the last two fixed steps. */
      alpha: 0,
      scale: 1,
      /** Monotonic frame index. Phase noise/jitter off this, not off wall time. */
      frame: 0,
    };

    this.ctx = {
      engine: this,
      scene: this.scene,
      camera: this.camera,
      overlayScene: this.overlayScene,
      overlayCamera: this.overlayCamera,
      canvas,
      config,
      events: this.events,
      input: this.input,
      time: this.time,
      rng: this.rng,
      get: (id) => this.registry.get(id),
      peek: (id) => this.registry.peek(id),
      has: (id) => this.registry.has(id),
    };

    this._accum = 0;
    this._last = 0;
    this._running = false;
    this._onResize = () => this.resize();
  }

  add(SystemClass, opts) {
    this.registry.add(new SystemClass(opts));
    return this;
  }

  /** init() in dependency order. Logs anything slow, because boot time is a
   *  budget too and you want to know which system spent it. */
  async init() {
    const order = this.registry.resolve();
    this.bootMarks = [];
    for (const sys of order) {
      const t0 = performance.now();
      await sys.init?.(this.ctx);
      const ms = performance.now() - t0;
      this.bootMarks.push({ id: sys.constructor.id, ms: +ms.toFixed(1) });
      if (ms > 50) console.info(`[engine] ${sys.constructor.id} init ${ms.toFixed(0)}ms`);
    }
    this.input?.attach?.();
    addEventListener('resize', this._onResize);
    this.resize();
    return this;
  }

  resize() {
    const w = Math.max(1, this.canvas.clientWidth || innerWidth);
    const h = Math.max(1, this.canvas.clientHeight || innerHeight);
    this.camera.aspect = w / h;
    this.camera.updateProjectionMatrix();
    this.overlayCamera.aspect = w / h;
    this.overlayCamera.updateProjectionMatrix();
    for (const sys of this.registry.with('resize')) sys.resize(w, h, this.ctx);
    this.events.emit('resize', { width: w, height: h });
  }

  start() {
    if (this._running) return;
    this._running = true;
    this._last = performance.now();
    this._loop = this._loop.bind(this);
    requestAnimationFrame(this._loop);
  }

  stop() {
    this._running = false;
  }

  _loop(now) {
    if (!this._running) return;
    // Schedule first: an exception in step() must not kill the loop silently.
    requestAnimationFrame(this._loop);
    this.step(now);
  }

  /** Advance exactly one frame. Public so the capture harness can hand-pump
   *  frames (lib/shots.js lockstep mode) instead of racing rAF. */
  step(now = performance.now()) {
    const t = this.time;
    const rawDt = Math.min(MAX_FRAME_DT, Math.max(0, (now - this._last) / 1000));
    this._last = now;
    t.raw += rawDt;
    t.dt = rawDt * t.scale;
    t.elapsed += t.dt;
    t.frame++;

    this.input?.beginFrame?.();

    this._accum += t.dt;
    let steps = 0;
    const fixedSystems = this.registry.with('fixedUpdate');
    while (this._accum >= FIXED_DT && steps < MAX_SUBSTEPS) {
      for (const sys of fixedSystems) sys.fixedUpdate(FIXED_DT, this.ctx);
      this._accum -= FIXED_DT;
      steps++;
    }
    if (steps === MAX_SUBSTEPS) this._accum = 0; // shed the backlog, don't spiral
    t.alpha = this._accum / FIXED_DT;

    for (const sys of this.registry.with('update')) sys.update(t.dt, this.ctx);
    for (const sys of this.registry.with('lateUpdate')) sys.lateUpdate(t.dt, this.ctx);

    const renderSystem = this.registry.peek('render');
    if (typeof renderSystem?.render === 'function') renderSystem.render(this.ctx);

    this.input?.endFrame?.();
  }

  dispose() {
    this.stop();
    removeEventListener('resize', this._onResize);
    this.input?.detach?.();
    // Reverse dependency order: a system's dependencies outlive it.
    for (const sys of [...this.registry.ordered].reverse()) sys.dispose?.();
    this.events.clear();
  }
}

/**
 * Boot helper: does the five things every main.js needs and nothing else.
 * Shows the failure on screen — a black canvas with the error only in devtools
 * costs an agent a whole capture cycle to diagnose.
 */
export async function boot(engine, { onError } = {}) {
  try {
    await engine.init();
    return engine;
  } catch (err) {
    console.error('[boot] init failed', err);
    onError?.(err);
    document.body.insertAdjacentHTML(
      'beforeend',
      `<pre style="position:fixed;inset:0;padding:2rem;color:#f66;background:#000;
         font:12px/1.5 ui-monospace,monospace;overflow:auto;z-index:9999;white-space:pre-wrap"
       >BOOT FAILURE\n\n${String(err?.stack ?? err?.message ?? err)}</pre>`
    );
    throw err;
  }
}

/**
 * threejs-game-kit — reusable, genre-generic runtime pieces.
 *
 * Nothing here knows what your game is. Everything here exists because its
 * absence cost the reference project measurable time or measurable frame rate.
 * See ../threejs.md for how they fit together and ../PITFALLS.md for why each one
 * looks the way it does.
 */
export { Registry, EventBus } from './registry.js';
export { Engine, boot } from './engine.js';
export { Rng, hash3, noise3, fbm3 } from './rng.js';
export {
  PHYSICS_HZ, FIXED_DT, MAX_SUBSTEPS, MAX_FRAME_DT,
  QUALITY_PRESETS, DEFAULTS, createConfig, configFromLocation, autoQuality,
} from './config.js';
export { Input, DEFAULT_ACTIONS, isTouchDevice } from './input.js';
export { TouchControls } from './touchui.js';
export { installShotApi, signalReady } from './shots.js';
export { prewarm, compileMeshes } from './prewarm.js';
export { LightBallast, LightPool } from './lights.js';
export { scratch, Pool, InstanceRing, ParticleStore } from './pool.js';
export { disposeTree, disposeMaterial, disposeAll, Owned } from './dispose.js';
export { suite, stats } from './selftest.js';

/**
 * Input aggregation: keyboard, mouse, TOUCH, wheel — exposed as a stable
 * PER-FRAME SNAPSHOT so gameplay never touches a DOM event.
 *
 * Why a snapshot and not listeners in gameplay code:
 *  - a DOM event can fire twice between two frames, or zero times; gameplay that
 *    reads events directly behaves differently at different frame rates
 *  - a capture harness / demo bot can then DRIVE the game by writing into this
 *    object (see tools/smoke.mjs) and everything downstream — state machines,
 *    animation, AI reacting to the player — runs untouched. That is how you get
 *    a scripted playthrough that is really the game being played, rather than a
 *    canned camera path that proves nothing.
 *  - `frozen` gives the shot API one switch to take control away
 *
 * TOUCH FEEDS THE SAME SNAPSHOT, which is the whole design. A thumb on the left
 * of the screen resolves to the same `axis2()` a WASD key does, a drag on the
 * right resolves to the same `look`, and a bound on-screen button resolves to
 * the same `held('jump')`. So gameplay code has no touch branch anywhere: write
 * the game once against actions and it is playable on a phone. Games published
 * to thrixel.world get opened on phones far more often than on desktops, so this
 * is not an accessibility extra — it is most of the audience.
 *
 * Edge queries (`pressed`, `released`) are only valid during the frame the
 * transition happened. Read them in update(), never in fixedUpdate() — a fixed
 * step may run 0 or N times in a frame, so an edge is missed or double-counted.
 */

/** Coarse pointer + no hover = phone or tablet. Not UA sniffing: this asks the
 *  question that actually matters (can this person hover a mouse?) and it stays
 *  right on devices that did not exist when this was written. */
export const isTouchDevice = () =>
  typeof matchMedia === 'function' &&
  matchMedia('(hover: none) and (pointer: coarse)').matches;

/** Beyond this the thumb has slid too far for the press to have been a tap. */
const TAP_SLOP_PX = 12;
/** Longer than this and it was a look-drag or a hold, not a tap. */
const TAP_MS = 260;

export const DEFAULT_ACTIONS = {
  forward: ['KeyW', 'ArrowUp'],
  back: ['KeyS', 'ArrowDown'],
  left: ['KeyA', 'ArrowLeft'],
  right: ['KeyD', 'ArrowRight'],
  jump: ['Space'],
  crouch: ['ControlLeft', 'KeyC'],
  sprint: ['ShiftLeft'],
  use: ['KeyF', 'KeyE'],
  primary: ['Mouse0'],
  secondary: ['Mouse2'],
  reload: ['KeyR'],
  pause: ['Escape'],
};

export class Input {
  /**
   * @param {object} [opts]
   * @param {boolean} [opts.touch] enable the touch layer (default true; it costs
   *   nothing on a desktop because nothing dispatches touch pointers there)
   * @param {number} [opts.touchSensitivity] radians per pixel of thumb drag.
   *   Higher than the mouse figure on purpose: a thumb has perhaps a third of
   *   the travel of a mouse arm and has to cover the same 360 degrees.
   * @param {number} [opts.moveZoneWidth] fraction of the canvas width, measured
   *   from the left edge, that acts as the movement stick. The rest looks.
   * @param {string|null} [opts.tapAction] action fired by a tap in the look
   *   zone. Pass null for a game where a stray tap should not shoot.
   */
  constructor(canvas, {
    actions = DEFAULT_ACTIONS,
    sensitivity = 0.0022,
    pointerLock = true,
    touch = true,
    touchSensitivity = 0.0045,
    moveZoneWidth = 0.45,
    tapAction = 'primary',
  } = {}) {
    this.canvas = canvas;
    this.actions = actions;
    this.sensitivity = sensitivity;
    this.pointerLock = pointerLock;
    this.touchEnabled = touch;
    this.touchSensitivity = touchSensitivity;
    this.moveZoneWidth = moveZoneWidth;
    this.tapAction = tapAction;

    /**
     * True once this session has seen a real touch. Games read it to swap the
     * control hints ("WASD to move" -> nothing), to skip the click-to-lock
     * overlay, and to show on-screen controls. Deliberately NOT the same as
     * `isTouchDevice()`: a laptop with a touchscreen should keep its keyboard
     * hints until someone actually reaches out and touches the screen.
     */
    this.touchActive = false;
    /** Analog movement from the on-screen stick, each axis in [-1, 1]. Merged
     *  into axis2() alongside the keyboard, so gameplay reads one value. */
    this.move = { x: 0, y: 0 };
    this._stick = null;      // { id, ox, oy, x, y, radius }
    this._lookTouch = null;  // { id, x, y, t0, moved }
    this._touchLook = { x: 0, y: 0 };
    this._unbinds = new Map();

    this.down = new Set(); // codes held right now
    this._pressed = new Set(); // went down during this frame
    this._released = new Set(); // went up during this frame
    /**
     * An ORDERED queue of `{ code, down }`, not two sets. Two sets cannot
     * represent both of the things that legitimately happen inside one frame:
     *   - a fast TAP (down then up) must yield a press AND a release, not held
     *   - a RE-PRESS (up then down) must leave the key held
     * With sets you have to pick an order and one of those breaks. Processing all
     * downs before all ups silently swallowed the re-press, which is exactly what
     * a bot driving the game does when it releases the previous case's keys and
     * presses the next case's in the same frame — the key came out NOT held and
     * the run measured zero movement.
     */
    this._queue = [];

    /** Accumulated pointer delta for this frame, in radians after sensitivity. */
    this.look = { x: 0, y: 0 };
    this._rawLook = { x: 0, y: 0 };
    this.wheel = 0;
    this._rawWheel = 0;

    this.enabled = true;
    /** When true, every query reads as neutral. The shot API sets this. */
    this.frozen = false;
    this.locked = false;

    this._handlers = [];
  }

  attach() {
    const on = (target, type, fn, opts) => {
      target.addEventListener(type, fn, opts);
      this._handlers.push(() => target.removeEventListener(type, fn, opts));
    };

    on(window, 'keydown', (e) => {
      if (e.repeat) return;
      this._queue.push({ code: e.code, down: true });
      // Space scrolls, F5/Tab/etc. are the user's; only swallow what we bind.
      if (this._isBound(e.code)) e.preventDefault();
    });
    on(window, 'keyup', (e) => this._queue.push({ code: e.code, down: false }));
    on(window, 'blur', () => {
      // Without this, alt-tabbing while holding W leaves the player sprinting.
      for (const c of this.down) this._queue.push({ code: c, down: false });
      this._releaseAllTouches();
    });

    on(this.canvas, 'mousedown', (e) => {
      this._queue.push({ code: `Mouse${e.button}`, down: true });
      if (this.pointerLock && !this.locked) this.canvas.requestPointerLock?.();
    });
    on(window, 'mouseup', (e) => this._queue.push({ code: `Mouse${e.button}`, down: false }));
    on(this.canvas, 'contextmenu', (e) => e.preventDefault());
    on(window, 'mousemove', (e) => {
      if (this.pointerLock && !this.locked) return;
      this._rawLook.x += e.movementX ?? 0;
      this._rawLook.y += e.movementY ?? 0;
    });
    on(window, 'wheel', (e) => {
      this._rawWheel += Math.sign(e.deltaY);
    }, { passive: true });
    on(document, 'pointerlockchange', () => {
      this.locked = document.pointerLockElement === this.canvas;
    });

    if (this.touchEnabled) {
      // Pointer events, not touch events: one code path, and `pointerType`
      // separates a thumb from the mouse cleanly. The mouse listeners above are
      // left alone, so this adds a path rather than replacing one.
      //
      // `touch-action: none` is set here as well as in CSS on purpose. Without
      // it the browser claims the gesture as a scroll or a pinch after ~100ms
      // and pointermove simply stops arriving mid-drag — which presents as
      // "looking around works for a moment and then sticks", a bug that is very
      // hard to read from the game code.
      this.canvas.style.touchAction = 'none';
      on(this.canvas, 'pointerdown', (e) => {
        if (e.pointerType !== 'touch') return;
        e.preventDefault();
        this.touchActive = true;
        this.canvas.setPointerCapture?.(e.pointerId);
        const r = this.canvas.getBoundingClientRect();
        const inMoveZone = e.clientX - r.left < r.width * this.moveZoneWidth;
        if (inMoveZone && !this._stick) {
          // A FLOATING stick, centred wherever the thumb landed, not a fixed
          // circle the thumb has to find. On a phone the thumb cannot see what
          // it is covering, so a fixed stick means constant small corrections.
          this._stick = {
            id: e.pointerId,
            ox: e.clientX,
            oy: e.clientY,
            x: 0,
            y: 0,
            radius: Math.min(96, Math.max(46, Math.min(r.width, r.height) * 0.17)),
          };
        } else if (!this._lookTouch) {
          this._lookTouch = { id: e.pointerId, x: e.clientX, y: e.clientY, t0: performance.now(), moved: 0 };
        }
      });
      on(this.canvas, 'pointermove', (e) => {
        if (e.pointerType !== 'touch') return;
        e.preventDefault();
        const s = this._stick;
        if (s && s.id === e.pointerId) {
          const dx = e.clientX - s.ox;
          const dy = e.clientY - s.oy;
          const len = Math.hypot(dx, dy) || 1;
          const k = Math.min(1, len / s.radius) / len;
          s.x = dx * k;
          s.y = dy * k;
          return;
        }
        const l = this._lookTouch;
        if (l && l.id === e.pointerId) {
          const dx = e.clientX - l.x;
          const dy = e.clientY - l.y;
          l.moved += Math.hypot(dx, dy);
          l.x = e.clientX;
          l.y = e.clientY;
          this._touchLook.x += dx;
          this._touchLook.y += dy;
        }
      });
      const endTouch = (e) => {
        if (e.pointerType !== 'touch') return;
        if (this._stick?.id === e.pointerId) {
          this._stick = null;
          this.move.x = this.move.y = 0;
          return;
        }
        const l = this._lookTouch;
        if (l?.id !== e.pointerId) return;
        this._lookTouch = null;
        const tapped = e.type === 'pointerup'
          && l.moved < TAP_SLOP_PX
          && performance.now() - l.t0 < TAP_MS;
        // Down AND up in one frame is handled correctly by the ordered queue:
        // it yields a press edge and a release edge, and leaves nothing held.
        if (tapped && this.tapAction) {
          const code = this.actions[this.tapAction]?.[0];
          if (code) {
            this._queue.push({ code, down: true });
            this._queue.push({ code, down: false });
          }
        }
      };
      on(this.canvas, 'pointerup', endTouch);
      on(this.canvas, 'pointercancel', endTouch);
    }

    return this;
  }

  /**
   * Route an on-screen element to an action, for jump / fire / interact buttons.
   * Works for a mouse click too, so the same HUD is usable on a desktop.
   *
   *   input.bindButton(document.querySelector('[data-jump]'), 'jump')
   *
   * Returns an unbind function; `detach()` also releases every binding.
   */
  bindButton(el, action) {
    if (!el) return () => {};
    const code = this.actions[action]?.[0] ?? action;
    const down = (e) => {
      e.preventDefault();
      e.stopPropagation();          // never let the canvas also read this as a look-drag
      if (e.pointerType === 'touch') this.touchActive = true;
      el.setPointerCapture?.(e.pointerId);
      this._queue.push({ code, down: true });
    };
    // Release on up AND cancel AND lostpointercapture: a finger that slides off
    // a button and lifts elsewhere otherwise leaves the action held forever,
    // which reads as "the fire button got stuck".
    const up = (e) => {
      e.preventDefault();
      e.stopPropagation();
      this._queue.push({ code, down: false });
    };
    el.style.touchAction = 'none';
    el.addEventListener('pointerdown', down);
    el.addEventListener('pointerup', up);
    el.addEventListener('pointercancel', up);
    el.addEventListener('lostpointercapture', up);
    const off = () => {
      el.removeEventListener('pointerdown', down);
      el.removeEventListener('pointerup', up);
      el.removeEventListener('pointercancel', up);
      el.removeEventListener('lostpointercapture', up);
      this._unbinds.delete(el);
    };
    this._unbinds.set(el, off);
    return off;
  }

  /** Where the floating stick is and how far it is pushed, for anything drawing
   *  an indicator. Null when no thumb is down. Read-only view of private state. */
  get stickState() {
    const s = this._stick;
    return s && s.id !== -1 ? { originX: s.ox, originY: s.oy, x: s.x, y: s.y, radius: s.radius } : null;
  }

  _releaseAllTouches() {
    this._stick = null;
    this._lookTouch = null;
    this.move.x = this.move.y = 0;
    this._touchLook.x = this._touchLook.y = 0;
  }

  detach() {
    for (const off of this._handlers) off();
    this._handlers.length = 0;
    for (const off of [...this._unbinds.values()]) off();
    this._releaseAllTouches();
  }

  _isBound(code) {
    for (const codes of Object.values(this.actions)) if (codes.includes(code)) return true;
    return false;
  }

  /** Promote queued events into this frame's snapshot, in the order they arrived. */
  beginFrame() {
    this._pressed.clear();
    this._released.clear();
    if (this.enabled && !this.frozen) {
      for (const ev of this._queue) {
        if (ev.down) {
          if (!this.down.has(ev.code)) {
            this.down.add(ev.code);
            this._pressed.add(ev.code);
          }
        } else if (this.down.delete(ev.code)) {
          this._released.add(ev.code);
        }
      }
      // Mouse and thumb are summed, each at its own sensitivity: the two are
      // never in use at the same moment, and summing avoids a mode flag that
      // would have to be got right.
      this.look.x = this._rawLook.x * this.sensitivity + this._touchLook.x * this.touchSensitivity;
      this.look.y = this._rawLook.y * this.sensitivity + this._touchLook.y * this.touchSensitivity;
      this.wheel = this._rawWheel;
      const s = this._stick;
      // Deadzone: a thumb resting on the glass drifts a few pixels, and without
      // this the player slides very slowly forever while standing still.
      this.move.x = s && Math.hypot(s.x, s.y) > 0.12 ? s.x : 0;
      this.move.y = s && Math.hypot(s.x, s.y) > 0.12 ? s.y : 0;
    } else {
      this.down.clear();
      this.look.x = this.look.y = 0;
      this.wheel = 0;
      this.move.x = this.move.y = 0;
    }
    this._queue.length = 0;
    this._rawLook.x = this._rawLook.y = 0;
    this._touchLook.x = this._touchLook.y = 0;
    this._rawWheel = 0;
  }

  endFrame() {
    this._pressed.clear();
    this._released.clear();
  }

  /**
   * BOT / TEST DRIVING — feed a synthetic event exactly where a DOM event would
   * land, so `pressed()` and `released()` edges fire normally.
   *
   * Use this from tools (smoke test, profiler, demo recorder) instead of writing
   * into `down` directly: `down.add('Mouse0')` makes the key look HELD but never
   * generates a press edge, so anything gated on `pressed()` silently never
   * happens and the tool reports zero events for a game that works. That exact
   * mistake cost a debugging round here.
   */
  inject(code, isDown = true) {
    this._queue.push({ code, down: !!isDown });
    return this;
  }

  /** Feed raw pointer delta in pixels, pre-sensitivity — like a real mouse. */
  injectLook(dx, dy) {
    this._rawLook.x += dx;
    this._rawLook.y += dy;
    return this;
  }

  /**
   * Drive the movement stick directly, in stick space: x right, y DOWN-screen,
   * each in [-1, 1], so `injectStick(0, -1)` is full forward. For bots driving
   * a touch-only control scheme.
   *
   * It STAYS deflected until you call `injectStick(0, 0)` — there is no finger
   * to lift. A bot that forgets leaves the player walking into a wall for the
   * rest of the run, which measures as movement and reads as a pass.
   */
  injectStick(x, y) {
    this._stick = { id: -1, ox: 0, oy: 0, x, y, radius: 1 };
    this.touchActive = true;
    return this;
  }

  /** Take control for a bot: enabled, unfrozen, and pointer-lock not required. */
  takeControl() {
    this.enabled = true;
    this.frozen = false;
    this.pointerLock = false;
    return this;
  }

  /** Held. */
  held(action) {
    const codes = this.actions[action];
    if (!codes) return false;
    for (const c of codes) if (this.down.has(c)) return true;
    return false;
  }

  /** Went down this frame. */
  pressed(action) {
    const codes = this.actions[action];
    if (!codes) return false;
    for (const c of codes) if (this._pressed.has(c)) return true;
    return false;
  }

  /** Went up this frame. */
  released(action) {
    const codes = this.actions[action];
    if (!codes) return false;
    for (const c of codes) if (this._released.has(c)) return true;
    return false;
  }

  /**
   * Movement axis, in [-1, 1] per axis. Not normalised — the mover decides
   * whether diagonal movement is faster, which is a design choice.
   *
   * Keyboard contributes -1/0/1 and the touch stick contributes its analog
   * deflection; they are summed and clamped. That sum is why gameplay code
   * needs no touch branch: the same call is the whole control scheme on both a
   * keyboard and a thumb, and a half-deflected thumb walks instead of running.
   * Note the stick's screen-down Y is negated here, since forward is up-screen.
   */
  axis2(negX = 'left', posX = 'right', negY = 'back', posY = 'forward', out = { x: 0, y: 0 }) {
    const clamp = (v) => (v < -1 ? -1 : v > 1 ? 1 : v);
    out.x = clamp((this.held(posX) ? 1 : 0) - (this.held(negX) ? 1 : 0) + this.move.x);
    out.y = clamp((this.held(posY) ? 1 : 0) - (this.held(negY) ? 1 : 0) - this.move.y);
    return out;
  }
}

import * as THREE from 'three';

/**
 * THE POINT-LIGHT COUNT IS A SHADER PERMUTATION KEY.
 *
 * This is the single most expensive Three.js trap in the reference project, and
 * it is invisible in every profiler that reports a median frame time.
 *
 * three bakes the number of VISIBLE lights of each type into every material's
 * program cache key. So the moment a light's `visible` flips — which is exactly
 * what distance culling does — EVERY lit material in the scene recompiles.
 * Measured, walking one street with 17 practicals (12 bulbs at 13 m, 5 lamps at
 * 22 m), the visible count swept 9-8-7-6-5-4 and produced:
 *
 *   f15 +36 programs 636 ms · f32 +35 702 ms · f41 +35 699 ms
 *   f51 +35 programs 678 ms · f99 +33 698 ms
 *   -> 186 programs and ~3.5 s of stalls inside 900 frames of play
 *
 * Pre-compiling every possible count instead costs 9.5 s of boot (595 programs
 * for counts 0-16). Holding the count constant costs nothing.
 *
 * TWO FIXES, both exactly pixel-neutral:
 *   A. Drive `intensity` to 0 and leave `visible = true` (best for pooled FX
 *      lights you own).
 *   B. Park zero-intensity BALLAST lights and top the count up to a fixed slot
 *      budget every lateUpdate (best when you cannot control who culls).
 *
 * Why it cannot move a pixel: a light whose colour x intensity is exactly 0 adds
 * a float 0.0 to the irradiance accumulator. Not "almost nothing" — zero. It
 * only changes `numPointLights`, which is a permutation input and nothing else.
 * Measured cost of 20 live ballast slots: p05 frame time 15.7 -> 14.4 ms, i.e.
 * inside noise.
 */
export class LightBallast {
  /**
   * @param parent Object3D to hang the ballast off (your subsystem's root)
   * @param slots  the FIXED number of point-light slots the shader will see
   * @param extra  spare slots so a burst of real lights can't exceed the target
   */
  constructor(parent, slots, extra = 4) {
    this.slots = slots;
    this.lights = [];
    for (let i = 0; i < slots + extra; i++) {
      const l = new THREE.PointLight(0x000000, 0, 0.01, 2);
      l.name = `light_ballast_${i}`;
      l.castShadow = false;
      l.visible = false;
      l.userData.isBallast = true;
      // Far under the world so even the distance-attenuation term is 0.
      l.position.set(0, -1000, 0);
      parent.add(l);
      this.lights.push(l);
    }
  }

  /**
   * Call from lateUpdate — after every subsystem has finished moving lights and
   * the camera, and before render draws, so the count three sees is identical
   * every frame.
   *
   * `realVisible` is how many NON-ballast point lights will be visible when the
   * renderer draws. You usually have to PREDICT it rather than read
   * `light.visible`, because the renderer's own cull runs after lateUpdate. Being
   * off by one on the frame a light crosses its radius costs one recompile
   * instead of hundreds — and if you mirror the cull's own test you are exact.
   */
  update(realVisible) {
    const need = Math.max(0, this.slots - realVisible);
    for (let i = 0; i < this.lights.length; i++) this.lights[i].visible = i < need;
    return need;
  }

  dispose() {
    for (const l of this.lights) l.parent?.remove(l);
    this.lights.length = 0;
  }
}

/**
 * A fixed-size pool of dynamic lights (muzzle flash, explosion, spark, pickup
 * glow, spell). Never creates or destroys a light after init, and never sets
 * `visible = false` — it drives intensity to 0 instead, so the permutation key
 * never changes. This is fix (A) above.
 */
export class LightPool {
  constructor(parent, count, { color = 0xffffff, distance = 8, decay = 2, castShadow = false } = {}) {
    this.pool = [];
    this.cursor = 0;
    for (let i = 0; i < count; i++) {
      const l = new THREE.PointLight(color, 0, distance, decay);
      l.castShadow = castShadow;
      l.visible = true; // ALWAYS. intensity 0 is the off state.
      parent.add(l);
      this.pool.push({ light: l, until: -1, peak: 0, start: 0 });
    }
  }

  /** Flash light i at `intensity` for `life` seconds starting `now`. */
  flash(position, intensity, life, now, color = null) {
    const slot = this.pool[this.cursor++ % this.pool.length];
    slot.light.position.copy(position);
    if (color !== null) slot.light.color.set(color);
    slot.peak = intensity;
    slot.start = now;
    slot.until = now + life;
    return slot.light;
  }

  /** Call every frame with the engine clock. Allocation-free. */
  update(now) {
    let live = 0;
    for (const s of this.pool) {
      if (s.until < 0) continue;
      const t = (s.until - now) / Math.max(1e-6, s.until - s.start);
      if (t <= 0) {
        s.light.intensity = 0;
        s.until = -1;
        continue;
      }
      s.light.intensity = s.peak * t * t; // quadratic falloff reads as a flash
      live++;
    }
    return live;
  }

  dispose() {
    for (const s of this.pool) s.light.parent?.remove(s.light);
    this.pool.length = 0;
  }
}

import * as THREE from 'three';

/**
 * ALLOCATE NOTHING PER FRAME. A `new THREE.Vector3()` inside update() is a bug:
 * at 60 fps with a few hundred objects it is millions of short-lived objects a
 * minute, and the GC pause lands as a hitch you cannot attribute to anything.
 *
 * The three tools here cover ~all of it: scratch objects for math, a generic
 * pool for gameplay entities, and an instanced ring buffer for the FX-shaped
 * problem (spawn many, expire quietly, never exceed a budget).
 */

/**
 * Preallocated scratch. Create ONE of these per module at file scope, never per
 * call. Deliberately not a stack/allocator: a named field is greppable and a
 * reviewer can see aliasing bugs, whereas `scratch.get()` hides them.
 *
 *   const S = scratch(); // module scope
 *   ... S.v0.copy(a).sub(b);
 */
export function scratch() {
  return {
    v0: new THREE.Vector3(), v1: new THREE.Vector3(), v2: new THREE.Vector3(),
    v3: new THREE.Vector3(), v4: new THREE.Vector3(),
    q0: new THREE.Quaternion(), q1: new THREE.Quaternion(),
    m0: new THREE.Matrix4(), m1: new THREE.Matrix4(),
    n0: new THREE.Matrix3(),
    e0: new THREE.Euler(),
    c0: new THREE.Color(), c1: new THREE.Color(),
    box0: new THREE.Box3(), box1: new THREE.Box3(),
    sph0: new THREE.Sphere(),
    ray0: new THREE.Ray(),
    pl0: new THREE.Plane(),
  };
}

/**
 * Fixed-capacity object pool. `acquire()` returns null at capacity rather than
 * growing — a budget you can silently exceed is not a budget, and an unbounded
 * pool turns a spawn bug into an OOM instead of a visible cap.
 */
export class Pool {
  /**
   * @param capacity  hard cap, from ctx.config.q budgets
   * @param create    () => item, called `capacity` times at init and never again
   * @param reset     (item) => void, called on release
   */
  constructor(capacity, create, reset = null) {
    this.capacity = capacity;
    this.reset = reset;
    this.items = new Array(capacity);
    this.free = new Array(capacity);
    for (let i = 0; i < capacity; i++) {
      this.items[i] = create(i);
      this.free[i] = i;
    }
    this.freeCount = capacity;
    this.live = 0;
    this.rejected = 0; // surface this in your stats; a rising count is a bug
  }

  acquire() {
    if (this.freeCount === 0) {
      this.rejected++;
      return null;
    }
    const i = this.free[--this.freeCount];
    this.live++;
    const item = this.items[i];
    item.__poolIndex = i;
    return item;
  }

  release(item) {
    const i = item.__poolIndex;
    if (i === undefined || i < 0) return false;
    item.__poolIndex = -1;
    this.reset?.(item);
    this.free[this.freeCount++] = i;
    this.live--;
    return true;
  }

  /** Oldest-wins recycling: for FX where dropping a spawn looks worse than
   *  stealing the oldest one. */
  acquireOrRecycle(oldest) {
    return this.acquire() ?? (oldest ? (this.release(oldest), this.acquire()) : null);
  }
}

/**
 * InstancedMesh ring buffer. One draw call for up to `capacity` copies of one
 * geometry; spawning past capacity overwrites the oldest slot. This is how
 * decals, shells, debris, footprints, bullet holes and crowd props stay at one
 * draw call each.
 *
 * Two details that bite:
 *  - `instanceMatrix.needsUpdate = true` must be set after any write, but set it
 *    ONCE per frame, not per instance.
 *  - Set `frustumCulled = false` (or maintain real bounds): three culls the whole
 *    InstancedMesh against the geometry's bounding sphere at the mesh's origin,
 *    so a ring buffer spread across the level vanishes when the origin leaves the
 *    frustum.
 */
export class InstanceRing {
  constructor(geometry, material, capacity, { parent = null, colors = false } = {}) {
    this.capacity = capacity;
    this.mesh = new THREE.InstancedMesh(geometry, material, capacity);
    this.mesh.frustumCulled = false;
    this.mesh.count = 0;
    if (colors) {
      this.mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3).fill(1), 3);
    }
    this.cursor = 0;
    this._m = new THREE.Matrix4();
    this._zero = new THREE.Matrix4().makeScale(0, 0, 0);
    this._dirty = false;
    parent?.add(this.mesh);
  }

  /** Write one instance from position/quaternion/scale. Returns the slot index. */
  spawn(position, quaternion, scale) {
    const i = this.cursor;
    this.cursor = (this.cursor + 1) % this.capacity;
    if (this.mesh.count < this.capacity) this.mesh.count++;
    this._m.compose(position, quaternion, scale);
    this.mesh.setMatrixAt(i, this._m);
    this._dirty = true;
    return i;
  }

  /** Scale a slot to zero — the cheap way to hide one instance. */
  clear(i) {
    this.mesh.setMatrixAt(i, this._zero);
    this._dirty = true;
  }

  setColorAt(i, color) {
    this.mesh.setColorAt(i, color);
    if (this.mesh.instanceColor) this.mesh.instanceColor.needsUpdate = true;
  }

  /** Call once per frame, from lateUpdate. */
  flush() {
    if (!this._dirty) return;
    this.mesh.instanceMatrix.needsUpdate = true;
    this._dirty = false;
  }

  dispose() {
    this.mesh.parent?.remove(this.mesh);
    this.mesh.dispose();
  }
}

/**
 * Struct-of-arrays particle store. Typed arrays, no per-particle objects, no
 * allocation at spawn. Deliberately dumb: the point is that `spawn()` is a few
 * array writes so it can be called hundreds of times a frame.
 */
export class ParticleStore {
  constructor(capacity) {
    this.capacity = capacity;
    this.count = 0;
    this.pos = new Float32Array(capacity * 3);
    this.vel = new Float32Array(capacity * 3);
    this.age = new Float32Array(capacity);
    this.life = new Float32Array(capacity);
    this.size = new Float32Array(capacity);
    this.seed = new Float32Array(capacity);
  }

  spawn(px, py, pz, vx, vy, vz, life, size, seed) {
    if (this.count >= this.capacity) return -1;
    const i = this.count++;
    const j = i * 3;
    this.pos[j] = px; this.pos[j + 1] = py; this.pos[j + 2] = pz;
    this.vel[j] = vx; this.vel[j + 1] = vy; this.vel[j + 2] = vz;
    this.age[i] = 0;
    this.life[i] = life;
    this.size[i] = size;
    this.seed[i] = seed;
    return i;
  }

  /** Swap-with-last compaction: O(live), no holes, stable cost. */
  step(dt, gravity = -9.81, drag = 0) {
    const k = drag > 0 ? Math.exp(-drag * dt) : 1;
    for (let i = 0; i < this.count; ) {
      this.age[i] += dt;
      if (this.age[i] >= this.life[i]) {
        this._swapWithLast(i);
        continue;
      }
      const j = i * 3;
      this.vel[j] *= k;
      this.vel[j + 1] = this.vel[j + 1] * k + gravity * dt;
      this.vel[j + 2] *= k;
      this.pos[j] += this.vel[j] * dt;
      this.pos[j + 1] += this.vel[j + 1] * dt;
      this.pos[j + 2] += this.vel[j + 2] * dt;
      i++;
    }
    return this.count;
  }

  _swapWithLast(i) {
    const last = --this.count;
    if (i === last) return;
    const a = i * 3, b = last * 3;
    for (let c = 0; c < 3; c++) {
      this.pos[a + c] = this.pos[b + c];
      this.vel[a + c] = this.vel[b + c];
    }
    this.age[i] = this.age[last];
    this.life[i] = this.life[last];
    this.size[i] = this.size[last];
    this.seed[i] = this.seed[last];
  }
}

import * as THREE from 'three';

/**
 * SHADER PRE-WARM. If you build one thing from this kit besides the capture
 * harness, build this.
 *
 * WHY: three compiles a program the first time a given permutation — (material,
 * light counts, shadow, skinning, fog, instancing, colour space, tone mapping) —
 * is actually DRAWN. So the frame that first shows a spark, an enemy, a lamp
 * coming into range or a muzzle flash is also the frame that compiles its
 * shader. Measured on the reference project: 86-146 programs compiled during
 * play, up to 30 on a single frame, producing 700 ms - 3.9 SECOND stalls. That
 * is what players describe as "it freezes" — not a low frame rate.
 *
 * The fix is to force every permutation to compile up front, behind a loading
 * state, so the steady-state loop compiles nothing.
 *
 * THE CONTRACT — each subsystem implements:
 *
 *   async prewarmMaterials(ctx) -> { ok, compiled }
 *
 *   "Build and compile every material this subsystem can produce, WITHOUT
 *    spawning gameplay objects, drawing a gameplay frame, or touching the clock
 *    or the RNG."
 *
 * That wording is load-bearing. Pre-warm is only useful if it is *provably*
 * pixel-neutral, and it is only provable if it leaves no simulation residue. The
 * reference project measured up to 254/255 channel deltas from a pre-warm that
 * spawned transients "just to reach their shaders", because decals live in a
 * ring buffer and spawned actors had no despawn hook.
 *
 * Four traps, all measured, all of which silently make pre-warm useless:
 *
 *  1. A RENDER TARGET MUST BE BOUND WHILE COMPILING. three folds
 *     `outputColorSpace` and `toneMapping` into the program cache key and reads
 *     BOTH off the CURRENTLY BOUND target. Compile with the canvas bound and you
 *     get the srgb + tone-mapped variant; but the world is drawn into an HDR
 *     target needing srgb-linear + NoToneMapping. Measured: 25 of 47 pre-warmed
 *     programs were the unused canvas variant and the real ones still compiled
 *     during play. A 1x1 target is enough to get the right key.
 *  2. compileAsync(scene, camera) ONLY REACHES THE FORWARD LIT VARIANT. Not the
 *     shadow/depth pass, not an MRT prepass, not the post chain, not any
 *     override material. Those need the owning subsystem's own hook.
 *  3. PATCH BEFORE YOU COMPILE. If your renderer injects chunks via
 *     onBeforeCompile / material.needsUpdate after the fact, a program compiled
 *     first is thrown away and recompiled by the first real frame. Measured: 26
 *     of 144 live programs were unpatched duplicates — 18% of the compile budget
 *     spent on programs that never draw anything.
 *  4. ANYTHING WHOSE KEY DEPENDS ON THE VISIBLE LIGHT COUNT CANNOT BE WARMED
 *     HERE. The visible set is only settled inside the first rendered frame.
 *     Those systems must self-warm on frame 2 and be listed in `selfWarming`.
 *     (And the light count itself must then be held constant — see
 *     lib/lights.js.)
 */
export async function prewarm(engine, { selfWarming = ['fx'], renderFirst = true, onProgress = () => {} } = {}) {
  const t0 = performance.now();
  const render = engine.ctx.peek('render');
  const renderer = render?.renderer;
  if (!renderer) return { ok: false, reason: 'no renderer' };

  const programsBefore = renderer.info.programs?.length ?? 0;

  // Snapshot everything a hook could conceivably disturb. Any residue here is a
  // visual change, and a visual change makes the pixel gate report phantom
  // regressions for the rest of the project.
  const cam = engine.camera;
  const saved = { pos: cam.position.clone(), quat: cam.quaternion.clone(), fov: cam.fov };
  const savedTime = { ...engine.time };
  const savedRng = engine.rng.save();
  const savedAccum = engine._accum;

  const scratchRt = new THREE.WebGLRenderTarget(1, 1, { depthBuffer: false, stencilBuffer: false });
  const prevRt = renderer.getRenderTarget();
  const prevFace = renderer.getActiveCubeFace?.() ?? 0;
  const prevMip = renderer.getActiveMipmapLevel?.() ?? 0;

  const hookResults = {};
  try {
    // ---- pass 1: the forward lit variant of everything already in a scene ----
    renderer.setRenderTarget(scratchRt); // trap #1
    try {
      await renderer.compileAsync(engine.scene, engine.camera);
      if (engine.overlayScene.children.length) {
        await renderer.compileAsync(engine.overlayScene, engine.overlayCamera);
      }
    } catch {
      // Old three, or a driver without KHR_parallel_shader_compile.
      try {
        renderer.compile(engine.scene, engine.camera);
        if (engine.overlayScene.children.length) renderer.compile(engine.overlayScene, engine.overlayCamera);
      } catch {
        /* boot must proceed regardless */
      }
    } finally {
      renderer.setRenderTarget(prevRt, prevFace, prevMip);
    }
    onProgress(0.5);

    // ---- pass 2: the subsystem hooks ----------------------------------------
    // render goes FIRST when it patches materials (trap #3): a program compiled
    // off an unpatched material is discarded by the first frame that walks the
    // scene and re-injects.
    const skip = new Set(selfWarming);
    const hooks = [];
    if (renderFirst && typeof render?.prewarmMaterials === 'function') hooks.push(render);
    for (const sys of engine.registry.ordered) {
      if (sys === render) continue;
      if (skip.has(sys.constructor?.id)) continue;
      if (typeof sys.prewarmMaterials === 'function') hooks.push(sys);
    }

    let done = 0;
    for (const sys of hooks) {
      const id = sys.constructor?.id ?? '?';
      try {
        hookResults[id] = (await sys.prewarmMaterials(engine.ctx)) ?? { ok: true };
      } catch (err) {
        // An optional hook must NEVER be able to block boot. A failed pre-warm
        // just means the stutter comes back; a thrown one means a black screen.
        hookResults[id] = { ok: false, reason: String(err?.message ?? err) };
      }
      onProgress(0.5 + (0.5 * ++done) / Math.max(1, hooks.length));
    }
  } finally {
    cam.position.copy(saved.pos);
    cam.quaternion.copy(saved.quat);
    cam.fov = saved.fov;
    cam.updateProjectionMatrix();
    cam.updateMatrixWorld(true);
    Object.assign(engine.time, savedTime);
    engine.rng.load(savedRng);
    engine._accum = savedAccum;
    engine._last = performance.now();
    renderer.setRenderTarget(prevRt, prevFace, prevMip);
    scratchRt.dispose();
  }

  const programsAfter = renderer.info.programs?.length ?? 0;
  return {
    ok: true,
    hooks: hookResults,
    ms: Math.round(performance.now() - t0),
    programsBefore,
    programsAfter,
    compiled: programsAfter - programsBefore,
    parallel: !!renderer.getContext().getExtension('KHR_parallel_shader_compile'),
  };
}

/**
 * Helper for a subsystem's own prewarmMaterials(): compile these real meshes,
 * with a target bound, without adding them to any scene.
 *
 * Compile THE REAL MESHES, not stand-ins. `renderer.compile` walks
 * `scene.children` for materials and only uses the target scene for lights, fog
 * and environment — so borrowing the real meshes into a scratch scene (never
 * re-parenting: `parent` is untouched by pushing into `children`) is what
 * guarantees the cache key matches the real draw, down to InstancedMesh-ness and
 * the geometry's exact attribute set.
 *
 * @param renderer  THREE.WebGLRenderer
 * @param meshes    array of Object3D — the real ones
 * @param lightsFrom scene whose lights/fog/env define the permutation (usually ctx.scene)
 * @param camera    any camera
 */
export function compileMeshes(renderer, meshes, lightsFrom, camera) {
  if (!meshes.length) return 0;
  const before = renderer.info.programs?.length ?? 0;
  const scratchRt = new THREE.WebGLRenderTarget(1, 1, { depthBuffer: false, stencilBuffer: false });
  const prevRt = renderer.getRenderTarget();
  const prevFace = renderer.getActiveCubeFace?.() ?? 0;
  const prevMip = renderer.getActiveMipmapLevel?.() ?? 0;

  const holder = new THREE.Scene();
  holder.environment = lightsFrom?.environment ?? null;
  holder.fog = lightsFrom?.fog ?? null;
  // Borrow lights so the light-count part of the key matches.
  lightsFrom?.traverse?.((o) => {
    if (o.isLight) holder.children.push(o);
  });
  for (const m of meshes) holder.children.push(m);

  try {
    renderer.setRenderTarget(scratchRt);
    renderer.compile(holder, camera, lightsFrom ?? holder);
  } catch {
    /* never block boot */
  } finally {
    holder.children.length = 0;
    renderer.setRenderTarget(prevRt, prevFace, prevMip);
    scratchRt.dispose();
  }
  return (renderer.info.programs?.length ?? 0) - before;
}

/**
 * Subsystem registry + event bus. Genre-generic; nothing here knows about a game.
 *
 * CONTRACT — every subsystem is a class with:
 *   static id       : string, unique. Others reach it via ctx.get(id).
 *   static deps     : string[] of ids that must init() first.
 *   async init(ctx) : build resources. May await.
 *   fixedUpdate(h,ctx): fixed-rate, 0..N times per frame. Optional.
 *   update(dt,ctx)  : once per frame, before render. Optional.
 *   lateUpdate(dt,ctx): after every update(), before render. Optional.
 *   resize(w,h,ctx) : viewport changed. Optional.
 *   prewarmMaterials(ctx): compile every shader this system can produce. Optional.
 *   dispose()       : free GPU/CPU resources. Optional.
 *
 * Subsystems MUST NOT import each other. They go through ctx.get(id). That is
 * what keeps the dependency graph explicit and lets one owner work on one
 * directory without reading (or breaking) another's internals.
 */

export class Registry {
  #systems = new Map();
  #order = [];
  #cache = new Map();

  add(system) {
    const id = system.constructor.id;
    if (!id) throw new Error(`${system.constructor.name} is missing a static id`);
    if (this.#systems.has(id)) throw new Error(`duplicate subsystem id "${id}"`);
    this.#systems.set(id, system);
    this.#cache.clear();
    this.#order = [];
    return this;
  }

  /** Throwing lookup — use for a hard dependency. */
  get(id) {
    const s = this.#systems.get(id);
    if (!s) throw new Error(`subsystem "${id}" not registered`);
    return s;
  }

  /** Non-throwing lookup — use for an optional dependency, and in tools. */
  peek(id) {
    return this.#systems.get(id) ?? null;
  }

  has(id) {
    return this.#systems.has(id);
  }

  /** Topological sort over static deps. Throws on cycles and missing deps. */
  resolve() {
    const seen = new Map(); // id -> 0 visiting, 1 done
    const out = [];
    const visit = (id, from) => {
      const state = seen.get(id);
      if (state === 1) return;
      if (state === 0) throw new Error(`dependency cycle at "${id}" (via ${from})`);
      const sys = this.#systems.get(id);
      if (!sys) throw new Error(`"${from}" depends on unregistered subsystem "${id}"`);
      seen.set(id, 0);
      for (const d of sys.constructor.deps ?? []) visit(d, id);
      seen.set(id, 1);
      out.push(sys);
    };
    for (const id of this.#systems.keys()) visit(id, '<root>');
    this.#order = out;
    return out;
  }

  get ordered() {
    return this.#order.length ? this.#order : this.resolve();
  }

  /** Systems implementing `method`, in dependency order. Cached per method so the
   *  frame loop does no filtering. */
  with(method) {
    let list = this.#cache.get(method);
    if (!list) {
      list = this.ordered.filter((s) => typeof s[method] === 'function');
      this.#cache.set(method, list);
    }
    return list;
  }

  invalidate() {
    this.#cache.clear();
  }
}

/**
 * Minimal synchronous event bus. Handlers are copied before dispatch so a
 * handler may unsubscribe (or subscribe) during its own dispatch, and a throwing
 * handler cannot take down the frame — a single bad listener in one subsystem
 * would otherwise stop every later listener from running that frame.
 */
export class EventBus {
  #map = new Map();

  on(type, fn) {
    let set = this.#map.get(type);
    if (!set) this.#map.set(type, (set = new Set()));
    set.add(fn);
    return () => this.off(type, fn);
  }

  once(type, fn) {
    const off = this.on(type, (e) => {
      off();
      fn(e);
    });
    return off;
  }

  off(type, fn) {
    this.#map.get(type)?.delete(fn);
  }

  emit(type, payload) {
    const set = this.#map.get(type);
    if (!set || set.size === 0) return;
    for (const fn of [...set]) {
      try {
        fn(payload);
      } catch (err) {
        console.error(`[events] handler for "${type}" threw:`, err);
      }
    }
  }

  clear() {
    this.#map.clear();
  }
}

/**
 * Deterministic PRNG (xoshiro128**) with the sampling helpers a game actually
 * needs. ALL gameplay and visual randomness must run through this, never
 * Math.random(), or captures are not reproducible and the pixel gate
 * (tools/imagediff.mjs) is worthless.
 *
 * Use fork() to give each subsystem its own stream: two systems drawing from one
 * stream make each one's output depend on how many numbers the other consumed,
 * which turns an unrelated change into a visual diff.
 */
export class Rng {
  constructor(seed = 0x9e3779b9) {
    this.seed(seed);
  }

  seed(s) {
    // SplitMix32 to spread one 32-bit seed across the four state words.
    let z = s >>> 0;
    const next = () => {
      z = (z + 0x9e3779b9) >>> 0;
      let x = z;
      x = Math.imul(x ^ (x >>> 16), 0x21f0aaad);
      x = Math.imul(x ^ (x >>> 15), 0x735a2d97);
      return (x ^ (x >>> 15)) >>> 0;
    };
    this.s0 = next();
    this.s1 = next();
    this.s2 = next();
    this.s3 = next();
    this._spare = undefined;
    return this;
  }

  /** Uniform uint32. */
  u32() {
    const rot = (x, k) => ((x << k) | (x >>> (32 - k))) >>> 0;
    const result = Math.imul(rot(Math.imul(this.s1, 5) >>> 0, 7), 9) >>> 0;
    const t = (this.s1 << 9) >>> 0;
    this.s2 ^= this.s0;
    this.s3 ^= this.s1;
    this.s1 ^= this.s2;
    this.s0 ^= this.s3;
    this.s2 ^= t;
    this.s3 = rot(this.s3, 11);
    return result;
  }

  /** Uniform [0,1). */
  float() {
    return this.u32() / 4294967296;
  }

  /** Uniform [min,max). */
  range(min, max) {
    return min + (max - min) * this.float();
  }

  /** Uniform integer [min,max] inclusive. */
  int(min, max) {
    return min + (this.u32() % (max - min + 1));
  }

  /** Uniform [-1,1]. */
  signed() {
    return this.float() * 2 - 1;
  }

  bool(p = 0.5) {
    return this.float() < p;
  }

  /** Standard normal via Box–Muller; the pair's second sample is cached. */
  gauss() {
    if (this._spare !== undefined) {
      const v = this._spare;
      this._spare = undefined;
      return v;
    }
    let u = 0;
    while (u === 0) u = this.float();
    const r = Math.sqrt(-2 * Math.log(u));
    const th = 2 * Math.PI * this.float();
    this._spare = r * Math.sin(th);
    return r * Math.cos(th);
  }

  pick(arr) {
    return arr[this.u32() % arr.length];
  }

  /** In-place Fisher–Yates. */
  shuffle(arr) {
    for (let i = arr.length - 1; i > 0; i--) {
      const j = this.u32() % (i + 1);
      const t = arr[i];
      arr[i] = arr[j];
      arr[j] = t;
    }
    return arr;
  }

  /** Uniform point in the unit disc — spread cones, splash positions, emission. */
  disc(out = { x: 0, y: 0 }) {
    const r = Math.sqrt(this.float());
    const a = this.float() * Math.PI * 2;
    out.x = Math.cos(a) * r;
    out.y = Math.sin(a) * r;
    return out;
  }

  /** Uniform direction on the unit sphere. */
  sphere(out = { x: 0, y: 0, z: 0 }) {
    const z = this.signed();
    const a = this.float() * Math.PI * 2;
    const r = Math.sqrt(Math.max(0, 1 - z * z));
    out.x = Math.cos(a) * r;
    out.y = Math.sin(a) * r;
    out.z = z;
    return out;
  }

  /** Independent stream derived from this one. Give one to each subsystem. */
  fork() {
    return new Rng(this.u32());
  }

  /** Snapshot / restore — needed by anything that must be simulation-transparent
   *  (see lib/prewarm.js: it steps nothing, but hooks might). */
  save() {
    return { s0: this.s0, s1: this.s1, s2: this.s2, s3: this.s3, spare: this._spare };
  }

  load(s) {
    this.s0 = s.s0;
    this.s1 = s.s1;
    this.s2 = s.s2;
    this.s3 = s.s3;
    this._spare = s.spare;
    return this;
  }
}

/** Deterministic 2D/3D value hash — for "random-looking" detail that must be a
 *  pure function of position (dressing, per-instance variation, noise seeds). */
export function hash3(x, y, z) {
  let h = Math.imul(Math.round(x * 1013) ^ 0x27d4eb2d, 0x85ebca6b);
  h = Math.imul(h ^ Math.round(y * 1619), 0xc2b2ae35);
  h = Math.imul(h ^ Math.round(z * 31337), 0x27d4eb2f);
  h ^= h >>> 15;
  return (h >>> 0) / 4294967296;
}

const fade = (t) => t * t * (3 - 2 * t);
const lerp = (a, b, t) => a + (b - a) * t;

/** Smooth value noise, period 1 unit. Deterministic, allocation-free. */
export function noise3(x, y, z) {
  const xi = Math.floor(x), yi = Math.floor(y), zi = Math.floor(z);
  const xf = fade(x - xi), yf = fade(y - yi), zf = fade(z - zi);
  const c = (dx, dy, dz) => hash3(xi + dx, yi + dy, zi + dz);
  const x00 = lerp(c(0, 0, 0), c(1, 0, 0), xf);
  const x10 = lerp(c(0, 1, 0), c(1, 1, 0), xf);
  const x01 = lerp(c(0, 0, 1), c(1, 0, 1), xf);
  const x11 = lerp(c(0, 1, 1), c(1, 1, 1), xf);
  return lerp(lerp(x00, x10, yf), lerp(x01, x11, yf), zf);
}

/** Fractal sum of noise3. octaves>4 rarely pays for itself on CPU. */
export function fbm3(x, y, z, octaves = 4, lacunarity = 2, gain = 0.5) {
  let f = 1, a = 0.5, sum = 0, norm = 0;
  for (let i = 0; i < octaves; i++) {
    sum += a * noise3(x * f, y * f, z * f);
    norm += a;
    f *= lacunarity;
    a *= gain;
  }
  return sum / norm;
}

/**
 * A 40-line assert harness for subsystem self-tests. No dependencies, runs in
 * node and in the browser.
 *
 * WHY IT EXISTS: a screenshot cannot show that a capsule tunnelled through a
 * wall, that a ragdoll is gaining energy, that a nav path is unreachable, that a
 * synthesised sound is silent or clipping, or that a generated mesh has NaN
 * vertices. Those are exactly the failures that a visual critic will report as
 * something else ("the enemy looks wrong") and send you hunting in the wrong
 * subsystem.
 *
 * The pattern that paid off in the reference project: every non-visual subsystem
 * ships a `selftest` that prints a TABLE of measured-vs-expected, runnable as
 * `node src/<system>/selftest.mjs`. Measured numbers, not assertions that pass
 * silently — the table is the artifact you paste into a report, and a reviewer
 * can see a value drifting before it crosses a threshold.
 *
 *   const t = suite('physics');
 *   t.ok(hit !== null, 'ray hits the wall');
 *   t.near(speed, 4.57, 0.12, 'walk top speed', 'm/s');
 *   t.range(slide, 0.75, 0.95, 'slide duration', 's');
 *   process.exit(t.report());
 */
export function suite(name) {
  const rows = [];
  let failures = 0;

  const push = (pass, label, measured, expected, unit) => {
    rows.push({ pass, label, measured, expected, unit: unit ?? '' });
    if (!pass) failures++;
    return pass;
  };

  return {
    name,
    section(title) {
      rows.push({ section: title });
    },
    ok(cond, label, detail = '') {
      return push(!!cond, label, cond ? 'yes' : 'NO', detail || 'yes');
    },
    eq(got, want, label, unit) {
      return push(got === want, label, got, want, unit);
    },
    near(got, want, tol, label, unit) {
      return push(Number.isFinite(got) && Math.abs(got - want) <= tol, label, fmt(got), `${want} ±${tol}`, unit);
    },
    range(got, lo, hi, label, unit) {
      return push(Number.isFinite(got) && got >= lo && got <= hi, label, fmt(got), `${lo}..${hi}`, unit);
    },
    finite(arr, label) {
      let bad = 0;
      for (let i = 0; i < arr.length; i++) if (!Number.isFinite(arr[i])) bad++;
      return push(bad === 0, label, `${bad} non-finite`, '0 non-finite');
    },
    /** Report as a table. Returns the exit code: 0 = all pass. */
    report({ log = console.log } = {}) {
      const w = (s, n) => String(s).padEnd(n);
      log(`\n${name} — ${rows.filter((r) => r.pass === true).length}/${rows.filter((r) => 'pass' in r).length} pass`);
      log(w('TEST', 34) + w('MEASURED', 16) + w('EXPECTED', 18) + 'RESULT');
      for (const r of rows) {
        if (r.section) {
          log(`\n${r.section}`);
          continue;
        }
        log(w(r.label, 34) + w(r.measured + r.unit, 16) + w(r.expected + r.unit, 18) + (r.pass ? 'PASS' : 'FAIL'));
      }
      if (failures) log(`\n${failures} FAILURE${failures > 1 ? 'S' : ''}`);
      return failures ? 1 : 0;
    },
    get failures() {
      return failures;
    },
    rows,
  };
}

const fmt = (v) =>
  typeof v === 'number' ? (Math.abs(v) < 100 ? v.toFixed(3) : v.toFixed(1)) : String(v);

/**
 * Statistics for measuring feel and cost. `p(0.99)` is the number that matters
 * for frame time; a mean or median hides exactly the stalls players notice.
 */
export function stats(values) {
  const a = Float64Array.from(values).sort();
  const n = a.length;
  if (!n) return { n: 0 };
  let sum = 0;
  for (const v of a) sum += v;
  const p = (q) => a[Math.min(n - 1, Math.max(0, Math.floor(n * q)))];
  return {
    n,
    min: a[0],
    max: a[n - 1],
    mean: sum / n,
    p1: p(0.01), p50: p(0.5), p90: p(0.9), p95: p(0.95), p99: p(0.99),
    p: (q) => p(q),
  };
}

import * as THREE from 'three';

/**
 * THE CAPTURE / REVIEW API. This file is the single most valuable piece of the
 * kit: it is what makes a screenshot mean something.
 *
 * A "shot" is a named, reproducible framing of the game:
 *   { pos:[x,y,z], look:[x,y,z], fov?, doc, apply?(engine, opts) }
 *
 * Three separate things live here, in order of importance:
 *
 *  1. window.__APPLY_SHOT__(name, opts) — pose the camera, freeze input, force
 *     the gameplay state the shot is meant to show, and CLEAR the previous
 *     shot's state. Reviewers compare iteration N against iteration N+1 of the
 *     same framing; if the framing drifts, every critique is noise.
 *
 *  2. LOCKSTEP MODE (?capture=1&lockstep=1) — the engine stops scheduling its
 *     own frames; frames only happen inside window.__PUMP__(n). This is what
 *     makes captures bit-reproducible. See the long comment on __PUMP__.
 *
 *  3. A fixed 1/60 shutter clock in capture mode, so temporal accumulators
 *     (TAA jitter, exposure adaptation, any easing) converge identically.
 *
 * Nothing here ships in a gameplay build's critical path; it is dev API on
 * `window`. Keep it that way — tools must never import subsystem modules.
 */

/**
 * @param engine        the Engine
 * @param shots         { [name]: shot } — game-specific, you write these
 * @param capture       true when ?capture=1
 * @param lockstep      true when ?capture=1&lockstep=1
 * @param clearState    called before every shot's own apply(): put transient
 *                      gameplay state back to neutral. See the note below.
 * @param setTimeOfDay  (engine, hour) => void, applies `shot.time`. Defaults to
 *                      the first registered system that has a setTimeOfDay()
 *                      method. Do not assume a subsystem name here: the first
 *                      version of this file called ctx.peek('sky') and silently
 *                      did nothing in a project where `render` owned the sun —
 *                      so the day and night shots came out identical and the
 *                      night shot reviewed as "fine".
 */
export function installShotApi(
  engine,
  { shots = {}, capture = false, lockstep = false, clearState = null, setTimeOfDay = null } = {}
) {
  const applyTime =
    setTimeOfDay ??
    ((eng, hour) => {
      for (const sys of eng.registry.ordered) {
        if (typeof sys.setTimeOfDay === 'function') return sys.setTimeOfDay(hour);
      }
      console.warn('[shots] shot.time set but no system implements setTimeOfDay()');
      return null;
    });
  window.__SHOTS__ = shots;
  window.__ENGINE__ = engine;

  /**
   * `opts.grabFrame` is how many frames the harness will pump before the
   * shutter. A shot whose subject is a transient (a muzzle flash lives ~50 ms, a
   * hit spark less) needs it so it can schedule the event to peak ON the
   * captured frame instead of guessing.
   */
  window.__APPLY_SHOT__ = (name, opts = {}) => {
    const shot = shots[name];
    if (!shot) return { error: `unknown shot "${name}"`, available: Object.keys(shots) };

    // Freeze live input and take the camera away from whatever owns it.
    if (engine.input) {
      engine.input.frozen = true;
      engine.input.enabled = false;
    }
    engine.ctx.peek('player')?.setControlEnabled?.(false);

    const cam = engine.camera;
    cam.position.fromArray(shot.pos);
    cam.lookAt(new THREE.Vector3().fromArray(shot.look));
    if (shot.fov) {
      cam.fov = shot.fov;
      cam.updateProjectionMatrix();
    }
    cam.updateMatrixWorld(true);
    // Keep the player proxy under the camera so gameplay systems stay coherent
    // (audio listener position, AI perception, occlusion queries).
    engine.ctx.peek('player')?.teleport?.(cam.position, cam.rotation);

    /**
     * CLEAR FIRST, THEN APPLY. Shots are taken back to back in one session, so a
     * previous shot's *looping* debug state is still running: the muzzle shot's
     * scripted burst keeps emptying a magazine during the next shot, the impact
     * shot keeps walking rounds across a wall behind the HUD shot. Every one of
     * those is a phantom regression in the next review round.
     */
    clearState?.(engine);
    if (shot.time !== undefined) applyTime(engine, shot.time);
    shot.apply?.(engine, opts);

    engine.events.emit('shot:applied', { name, shot });
    return { applied: name, pos: shot.pos, fov: shot.fov ?? engine.config.fov };
  };

  if (capture) {
    if (engine.input) engine.input.frozen = true;
    /**
     * FIXED SHUTTER CLOCK. Assigning `_last = fake` before each step forces
     * rawDt to be EXACTLY 1000/60 on every frame INCLUDING THE FIRST, whatever
     * else stamped `_last` with a real clock (Engine.start and prewarm both do).
     * Without it, frame 1's dt is 0 when `_last` was stamped and 1/60 when it
     * was not — a boot-path-dependent one-frame difference that then lives in
     * every accumulator for the rest of the run.
     */
    let fake = 0;
    engine.step = ((orig) =>
      function () {
        this._last = fake;
        fake += 1000 / 60;
        return orig.call(this, fake);
      })(engine.step);
  }

  window.__RENDER_INFO__ = null;
  const snapInfo = () => {
    const r = engine.ctx.peek('render');
    const info = r?.renderer?.info;
    window.__RENDER_INFO__ = {
      frame: engine.time.frame,
      calls: info?.render.calls ?? 0,
      tris: info?.render.triangles ?? 0,
      programs: info?.programs?.length ?? 0,
      textures: info?.memory.textures ?? 0,
      geometries: info?.memory.geometries ?? 0,
      ms: engine.time.dt * 1000,
    };
  };

  /**
   * LOCKSTEP CAPTURE — the determinism fix. Read this before you "simplify" it.
   *
   * The problem: the engine's own rAF loop keeps stepping while the driver is
   * doing round trips — waitForFunction on __READY__, the evaluate that applies
   * the shot, the screenshot RPC itself. How many frames fit inside those round
   * trips is wall-clock dependent, so `time.frame` at the shutter drifts 10-20
   * frames run to run. EVERYTHING phase-locked to the absolute frame index —
   * TAA jitter, AO/reflection noise rotation (`frame % 64`), exposure
   * adaptation, the cadence of any scripted transient — therefore resolves
   * differently every run. That, not any subsystem clock read, is the usual
   * reason two identical runs differ, and the reason adding a slow boot step
   * looks like a visual change.
   *
   * The fix: in lockstep mode the engine NEVER schedules a frame. Frames happen
   * only inside __PUMP__(n), which advances exactly n. The frame index at the
   * shutter is then a constant on every run and every machine, and nothing at
   * all advances while the screenshot is being taken.
   */
  if (lockstep) {
    engine.start = function () {
      this._running = true;
    };
    window.__LOCKSTEP__ = true;

    /** Advance exactly `n` engine frames, one per rAF so each one is presented. */
    window.__PUMP__ = (n = 1) =>
      new Promise((resolve) => {
        let i = 0;
        const tick = () => {
          engine.step();
          snapInfo();
          if (++i >= n) resolve(engine.time.frame);
          else requestAnimationFrame(tick);
        };
        requestAnimationFrame(tick);
      });

    /** Yield `n` rAFs WITHOUT stepping, so the compositor has certainly picked
     *  up the last rendered frame before the shutter. Advances no state. */
    window.__PRESENT__ = (n = 2) =>
      new Promise((resolve) => {
        let i = 0;
        const tick = () => (++i >= n ? resolve(engine.time.frame) : requestAnimationFrame(tick));
        requestAnimationFrame(tick);
      });
  } else {
    window.__LOCKSTEP__ = false;
    // Free-running: the engine drives itself; __PUMP__ just waits out n frames.
    // Tools that measure real frame pacing (tools/profile.mjs) need this path.
    window.__PUMP__ = (n = 1) =>
      new Promise((resolve) => {
        let i = 0;
        const tick = () => (++i >= n ? resolve(engine.time.frame) : requestAnimationFrame(tick));
        requestAnimationFrame(tick);
      });
    window.__PRESENT__ = window.__PUMP__;
    const info = () => {
      snapInfo();
      requestAnimationFrame(info);
    };
    requestAnimationFrame(info);
  }

  return { pump: window.__PUMP__, present: window.__PRESENT__, lockstep: !!lockstep };
}

/**
 * Raise window.__READY__ after a fixed NUMBER OF FRAMES, not after a timeout and
 * not after a bare rAF race. The shot is then always applied at the same engine
 * frame no matter how long boot took in wall-clock terms — which is what lets
 * you add or remove an expensive boot step and still prove the pixels did not
 * move.
 */
// Told to whoever framed us, as well as set on window.
//
// window.__READY__ works for the capture harness, which drives this page from
// the same process. It cannot work for a host page: a published world is on
// its own registrable domain, so a parent frame is forbidden from reading any
// variable in here. A postMessage crosses that line by design, and it is the
// difference between a host that can hide its loading state at the exact
// frame the world starts drawing and one that has to guess.
//
// targetOrigin is '*' deliberately. There is nothing secret in the message,
// and the alternative is baking the host's origin into every published
// bundle - which would then be wrong for anyone who frames it elsewhere.
function post(message) {
  try {
    if (window.parent && window.parent !== window) {
      window.parent.postMessage({ source: 'thrixel-world', ...message }, '*');
    }
  } catch {
    // A sandbox that forbids it. The world still runs and nothing here is
    // load-bearing for play; the host falls back to its own signals.
  }
}

function announceReady() {
  window.__READY__ = true;
  post({ type: 'ready' });
  sendCover();
}

// A still of the world, taken by the world.
//
// Anything published through the skill already has artwork - playcheck runs
// the game, drives it for a couple of seconds and screenshots it into the
// bundle, which is a better picture than this one. This is for the bundle
// that arrived another way: somebody zipping their build by hand and
// uploading it, which skips playcheck and lands with no picture at all.
//
// Two things make it fiddly, and both are handled by retrying rather than by
// timing luck:
//
//  1. A WebGL canvas without preserveDrawingBuffer is EMPTY to toDataURL
//     unless it is read in the same frame it was drawn. Whether our rAF
//     lands after the engine's is not something a library can promise, so
//     this tries again next frame instead of assuming.
//  2. A frame taken the instant boot completes is often a loading screen, or
//     a scene whose models have not arrived. So it waits first.
//
// The blank check is what makes the retry safe: a uniform image is never
// sent, so the worst case is no cover rather than a grey rectangle stored as
// one.
const COVER_WAIT_MS = 2500;
const COVER_MAX_W = 1280;
const COVER_TRIES = 8;

function frameIfNotBlank(canvas) {
  const scale = Math.min(1, COVER_MAX_W / (canvas.width || COVER_MAX_W));
  const flat = document.createElement('canvas');
  flat.width = Math.max(1, Math.round(canvas.width * scale));
  flat.height = Math.max(1, Math.round(canvas.height * scale));
  const ctx = flat.getContext('2d');
  if (!ctx) return null;
  ctx.drawImage(canvas, 0, 0, flat.width, flat.height);

  // Sample a grid rather than every pixel: enough to tell a rendered scene
  // from a cleared buffer, cheap enough to run eight times.
  const { data } = ctx.getImageData(0, 0, flat.width, flat.height);
  let min = 255;
  let max = 0;
  for (let i = 0; i < data.length; i += 4 * 997) {
    const lum = (data[i] + data[i + 1] + data[i + 2]) / 3;
    if (lum < min) min = lum;
    if (lum > max) max = lum;
  }
  if (max - min < 8) return null;   // one flat colour: nothing was drawn
  return flat.toDataURL('image/jpeg', 0.75);
}

function sendCover() {
  const canvas = window.__ENGINE__?.canvas || document.querySelector('canvas');
  if (!canvas) return;
  let left = COVER_TRIES;
  const attempt = () => {
    let shot = null;
    try {
      shot = frameIfNotBlank(canvas);
    } catch {
      return;   // tainted or unreadable: not worth another try
    }
    if (shot) post({ type: 'cover', dataUrl: shot });
    else if (--left > 0) requestAnimationFrame(attempt);
  };
  setTimeout(() => requestAnimationFrame(attempt), COVER_WAIT_MS);
}

export async function signalReady(shotApi, bootFrames = 3) {
  if (shotApi.lockstep) {
    await shotApi.pump(bootFrames);
    announceReady();
    return;
  }
  let warm = 0;
  const probe = () => {
    if (++warm >= bootFrames) {
      announceReady();
      return;
    }
    requestAnimationFrame(probe);
  };
  requestAnimationFrame(probe);
}

/**
 * On-screen controls for phones: a floating stick indicator and a cluster of
 * action buttons, both wired into the same `Input` snapshot the keyboard feeds.
 *
 * Why this is in the kit rather than left to each game: touch INPUT without
 * touch UI is a game that is technically playable and looks broken. A player
 * who opens a shared link on a phone sees a 3D scene and no controls, tries a
 * tap, and leaves. The single most common mobile failure is not a dead input
 * layer, it is an invisible one.
 *
 * Two rules inherited from the capture harness:
 *  - This layer stays hidden until `input.touchActive`, so a headless capture
 *    (no touch events, ever) is pixel-identical to one taken before this file
 *    existed. `alwaysShow: true` is a debugging aid and WILL move pixels.
 *  - No CSS transitions or animations. Same reason as the HUD: they run on the
 *    browser's clock, not the engine's. Opacity is set, not eased.
 */

const BUTTON_PX = 68; // >= 44 is the accessibility floor; a thumb wants more

/** Standing back from the very edge: phone screens curve, and iOS reserves the
 *  bottom strip for the home indicator. `env(safe-area-inset-*)` needs
 *  `viewport-fit=cover` in the viewport meta tag to be non-zero. */
const EDGE = 'calc(22px + env(safe-area-inset-bottom, 0px))';

export class TouchControls {
  /**
   * @param {import('./input.js').Input} input
   * @param {object} [opts]
   * @param {HTMLElement} [opts.host] where to mount (default: #ui, else body)
   * @param {Array<{action: string, label: string}>} [opts.buttons] right-hand
   *   cluster, listed bottom-first. Keep it to three or fewer: every button is
   *   screen a thumb covers.
   * @param {boolean} [opts.stick] draw the floating stick indicator
   * @param {boolean} [opts.alwaysShow] show on desktop too (debugging only)
   */
  constructor(input, { host = null, buttons = [], stick = true, alwaysShow = false } = {}) {
    this.input = input;
    this.buttons = buttons;
    this.showStick = stick;
    this.alwaysShow = alwaysShow;
    this.host = host ?? document.getElementById('ui') ?? document.body;
    this.root = null;
    this._offs = [];
    this._visible = null;
  }

  attach() {
    const root = document.createElement('div');
    root.dataset.touchControls = '';
    // pointer-events: none on the layer, auto on the buttons — otherwise this
    // covers the canvas and swallows every look-drag.
    // `visibility:hidden`, not just `opacity:0`: an invisible button with
    // pointer-events still swallows clicks, so a desktop player would find a
    // dead zone in the bottom-right corner of the screen. Visibility removes
    // the subtree from hit-testing as well as from the picture.
    root.style.cssText =
      'position:fixed;inset:0;pointer-events:none;z-index:20;' +
      '-webkit-user-select:none;user-select:none;-webkit-tap-highlight-color:transparent;' +
      'opacity:0;visibility:hidden';

    if (this.showStick) {
      this.stickRing = document.createElement('div');
      this.stickRing.style.cssText =
        'position:absolute;left:0;top:0;border-radius:50%;border:2px solid rgba(255,255,255,.35);' +
        'background:rgba(255,255,255,.06);display:none';
      this.stickNub = document.createElement('div');
      this.stickNub.style.cssText =
        'position:absolute;left:0;top:0;width:52px;height:52px;margin:-26px 0 0 -26px;border-radius:50%;' +
        'background:rgba(255,255,255,.5);display:none';
      root.append(this.stickRing, this.stickNub);
    }

    const cluster = document.createElement('div');
    cluster.style.cssText =
      `position:absolute;right:calc(22px + env(safe-area-inset-right, 0px));bottom:${EDGE};` +
      'display:flex;flex-direction:column-reverse;gap:14px;align-items:center';
    for (const { action, label } of this.buttons) {
      const b = document.createElement('button');
      b.type = 'button';
      b.dataset.action = action;
      b.textContent = label;
      b.style.cssText =
        `width:${BUTTON_PX}px;height:${BUTTON_PX}px;border-radius:50%;pointer-events:auto;` +
        'border:2px solid rgba(255,255,255,.4);background:rgba(12,16,22,.45);color:#eef2f6;' +
        'font:600 13px/1 ui-sans-serif,system-ui,sans-serif;letter-spacing:.06em;' +
        '-webkit-tap-highlight-color:transparent;touch-action:none';
      this._offs.push(this.input.bindButton(b, action));
      cluster.appendChild(b);
    }
    root.appendChild(cluster);

    this.host.appendChild(root);
    this.root = root;
    return this;
  }

  /**
   * Call once per frame from your UI system's lateUpdate. Cheap: it writes to
   * the DOM only when something actually changed.
   */
  sync() {
    if (!this.root) return;
    const visible = this.alwaysShow || this.input.touchActive;
    if (visible !== this._visible) {
      this.root.style.opacity = visible ? '1' : '0';
      this.root.style.visibility = visible ? 'visible' : 'hidden';
      this._visible = visible;
    }
    if (!this.showStick) return;
    const s = visible ? this.input.stickState : null;
    if (!s) {
      if (this.stickRing.style.display !== 'none') {
        this.stickRing.style.display = 'none';
        this.stickNub.style.display = 'none';
      }
      return;
    }
    const d = s.radius * 2;
    this.stickRing.style.display = 'block';
    this.stickNub.style.display = 'block';
    this.stickRing.style.width = this.stickRing.style.height = `${d}px`;
    this.stickRing.style.transform =
      `translate(${s.originX - s.radius}px, ${s.originY - s.radius}px)`;
    this.stickNub.style.transform =
      `translate(${s.originX + s.x * s.radius}px, ${s.originY + s.y * s.radius}px)`;
  }

  dispose() {
    for (const off of this._offs) off();
    this._offs.length = 0;
    this.root?.remove();
    this.root = null;
  }
}

# <PROJECT> — engine contract

**Every owner must read this before writing code. It is the only coordination
mechanism.** Fill in the bracketed parts and delete this line.

Target: <one sentence naming the genre AND the quality bar, e.g. "a browser <genre>
whose visual and tactile quality stands next to <named reference>">. WebGL2 +
Three.js, <asset policy: e.g. meshes and textures should be generated using Thrixel
according to the guidelines in root SKILL.md. Sounds must be generated procedurally.>.

## Hard rules

1. **You own your directory. Never edit files outside it.** Another owner owns
   every other directory; your edit will be clobbered or will break them.
2. **Never import another subsystem's module.** Get it at runtime:
   `const fx = ctx.get('fx')`. This is what makes isolated work safe.
3. **No new runtime dependencies.** `three` only. No CDN fetches, no external
   images/audio/models except those made with Thrixel. Any assets made with Thrixel
   should be downloaded. The game must run fully offline, self-contained.
4. **No `Math.random()` in gameplay or visuals.** Use `ctx.rng` or a
   `ctx.rng.fork()` you keep. Capture reproducibility depends on it.
5. **No wall-clock time.** Animate off `ctx.time` (`elapsed`, `dt`, `frame`), never
   `performance.now()`, `Date.now()`, or a CSS animation. Instrumentation that only
   logs a duration is fine.
6. **Allocate nothing per frame.** Preallocate in `init()` and reuse. A
   `new THREE.Vector3()` inside `update()` is a bug.
7. **Dispose what you create.** Geometries, materials, textures and render targets
   are freed in `dispose()`.
8. **Respect the budgets in `ctx.config.q`.** Never exceed one; report rejections.
9. `npm run build` must pass, `node tools/smoke.mjs` must pass, and
   `node tools/capture.mjs` must produce a frame after your change. If you break
   the boot, nobody else can work.

## Subsystem interface

```js
export class MySystem {
  static id = 'mysystem';        // unique; how others reach you
  static deps = ['render'];      // ids that must init() before you

  async init(ctx) {}             // build resources; may await
  fixedUpdate(h, ctx) {}         // optional, fixed rate, deterministic simulation
  update(dt, ctx) {}             // optional, once per frame
  lateUpdate(dt, ctx) {}         // optional, after all update()
  resize(w, h, ctx) {}           // optional
  async prewarmMaterials(ctx) {} // optional: compile every material you can produce,
                                 // WITHOUT spawning objects, drawing a gameplay
                                 // frame, or touching the clock/RNG
  dispose() {}                   // optional
}
```

`ctx` provides: `scene`, `camera`, `overlayScene`, `overlayCamera`, `canvas`,
`config`, `events`, `input`, `time`, `rng`, `get(id)`, `peek(id)`, `has(id)`.

- `scene` / `camera` — the world. `overlayScene` / `overlayCamera` — anything
  attached to the viewer that must never clip into world geometry, drawn after the
  world with a cleared depth buffer.
- `time` — `{ elapsed, raw, dt, fixed, alpha, scale, frame }`. Use `alpha` to
  interpolate rendered transforms between fixed steps.
- `config.q` — the active quality preset. Honour every budget in it.

## Ownership map

| id | directory | owns |
|---|---|---|
| `render` | `src/render/` | the WebGLRenderer, all post-processing, shadows, the final composite |
| `<...>` | `src/<...>/` | <...> |

Shared, owned by the lead (do not edit): `src/core/`, `src/main.js`, `src/dev/`,
`tools/`, build config.

## Cross-subsystem events

Emit and listen via `ctx.events`. Payloads are plain objects. The canonical set:

| event | payload | emitted by |
|---|---|---|
| `<domain>:<verb>` | `{ ... }` | `<system>` |

For each event also state, where it could be ambiguous, **who acts on it**. The
reference project lost time to damage being applied twice because both the emitter
and the target's listener applied it.

If you need an event that is not listed, add a row here in the same commit.

## Shared vocabularies

Any string both sides of an event must agree on goes here — surface types, entity
classes, damage types, tile kinds, animation state names. Example:

`concrete`, `metal`, `wood`, `dirt`, `sand`, `glass`, `water`, `foliage`, `fabric`,
`flesh`, `rubber`, `plaster`

## Render integration

What `render` exposes to everyone else, and the rules for using it:

```js
const r = ctx.get('render');
r.renderer            // do not change its state outside a frame
r.screenSize          // { width, height } of the internal target
r.setTimeOfDay(hour)  // if the project has one
r.resetTemporal()     // drop temporal history — used by the capture harness
// r.registerPass(pass) / r.addLight(light) / r.depthTexture / ... as applicable
```

Per-object opt-outs, and the ONE flag that controls each (see PITFALLS C3):

```js
mesh.userData.noShadow  = true  // do not cast into the shadow pass
mesh.userData.noPrepass = true  // keep out of the depth/normal/velocity prepass
```

### Light-count stability

Anything registering distance-culled punctual lights must keep the **visible count
constant** — the count is a shader permutation key. Use `LightPool` (intensity 0,
`visible` stays true) or `LightBallast` (fixed slot budget topped up in
`lateUpdate`). See PITFALLS B2.

## Quality bar

Every visual subsystem is reviewed against <reference>. Non-negotiables:

- Unless a requested art style, **no flat or untextured surfaces.** 
  Albedo variation at more than one frequency, a normal map, roughness variation,
  and a detail layer visible at 0.5 m.
- **No uniform lighting.** Contact shadows, bounce, AO, and a clear key/fill/rim
  separation.
- **Physically plausible values.** Albedo 0.02-0.9, metals are 0 or 1, real-world
  light intensities, exposure-driven rather than multiplier-driven.
- **Every action has weight.** Recoil/impulse, camera shake, an audio transient, and
  a visual FX on every impact.

## Debug hooks (the capture harness depends on these)

Each subsystem exposes a hook the shot list can drive, so any state can be
captured on demand and cleared afterwards:

| system | hook | kinds |
|---|---|---|
| `fx` | `debugBurst(kind, opts)` | `'none'` must fully clear |
| `ai` | `debugStage(kind)` | `'none'` must despawn |
| `ui` | `debugState(mode)` | `'clean'` must reset |
| `<...>` | `<...>` | |

`opts.grabFrame` is how many frames the harness will pump before the shutter — use
it to land a transient's peak on the captured frame. Re-seed your RNG inside the
hook so a staged effect is identical regardless of what ran before it.

import * as THREE from 'three';
import { scratch, Owned, disposeTree, compileMeshes, Pool } from '../lib/index.js';

/** Module-scope scratch. Allocated once. Never inside a per-frame function. */
const S = scratch();

/**
 * <SYSTEM> — <one line: what it owns>.
 *
 * Copy this file, delete what you do not need, and keep the parts that are
 * commented as contract. Every hook here exists because a tool depends on it.
 */
export class TemplateSystem {
  /** Unique id. Others reach you with ctx.get('<id>') — never by import. */
  static id = 'template';
  /** Systems that must init() before you. Topo-sorted; order of add() is irrelevant. */
  static deps = ['render'];

  async init(ctx) {
    this.ctx = ctx;
    /** Everything disposable you create goes through this. */
    this.own = new Owned();
    /** Your OWN random stream, so your output does not depend on what another
     *  subsystem consumed from the shared one. */
    this.rng = ctx.rng.fork();

    this.root = new THREE.Group();
    this.root.name = TemplateSystem.id;
    ctx.scene.add(this.root);

    const q = ctx.config.q;
    // Fixed-capacity pool sized from the budget. Never grows; counts rejections.
    this.things = new Pool(
      q.particleBudget,
      () => ({ alive: false, position: new THREE.Vector3() }),
      (t) => {
        t.alive = false;
      }
    );

    // Listen; never reach into another subsystem to ask what happened.
    ctx.events.on('example:event', (e) => this.onExample(e));
  }

  onExample(e) {
    const t = this.things.acquire();
    if (!t) return; // at budget — dropping is correct, growing is not
    t.alive = true;
    t.position.copy(e.position);
  }

  /** Deterministic simulation. 0..N times per frame. Do NOT read input edges here. */
  fixedUpdate(h, ctx) {}

  /** Once per frame. Animation, decisions, anything reading input edges. */
  update(dt, ctx) {
    // Animate off the engine clock. NEVER performance.now(). See PITFALLS A3.
    const t = ctx.time.elapsed;
    S.v0.set(Math.sin(t), 0, Math.cos(t)); // scratch, no allocation
  }

  /** After every update(), before render: anything that must see final transforms
   *  (attachments, light-count stabilisation, instance buffer flushes). */
  lateUpdate(dt, ctx) {}

  resize(w, h, ctx) {}

  /**
   * CONTRACT: compile every material this subsystem can produce, WITHOUT spawning
   * gameplay objects, drawing a gameplay frame, or touching the clock or the RNG.
   * compileMeshes() binds a 1x1 render target first, which is what puts the right
   * colour space and tone mapping in the program cache key. See PITFALLS B3/B4.
   */
  async prewarmMaterials(ctx) {
    const meshes = [];
    this.root.traverse((o) => {
      if (o.isMesh) meshes.push(o);
    });
    return { ok: true, compiled: compileMeshes(ctx.get('render').renderer, meshes, ctx.scene, ctx.camera) };
  }

  /**
   * Debug hook for the shot list and the profiler. `kind === 'none'` must FULLY
   * clear — a looping effect that survives into the next shot produces phantom
   * regressions in the next review round (PITFALLS A6).
   *
   * `opts.grabFrame` is how many frames the harness pumps before the shutter; use
   * it to land a transient's peak on the captured frame. Re-seed the RNG so the
   * staged effect is identical regardless of what ran before it.
   */
  debugStage(kind, opts = {}) {
    this.rng.seed(0x51a6ed);
    if (kind === 'none' || !kind) {
      /* clear everything you staged */
      return { cleared: true };
    }
    return { staged: kind, peakAt: Math.max(4, Number(opts.grabFrame ?? 60) - 6) };
  }

  dispose() {
    disposeTree(this.root);
    this.root.parent?.remove(this.root);
    this.own.disposeAll();
  }
}

# Driving Unreal 5.8 headlessly and autonomously through the official MCP

Field notes from building a complete small game (a first-person fishkeeping scene) with zero
GUI steps, on a headless Linux box where the human watched through Pixel Streaming.
Use `-RenderOffscreen` for this interactive editor and omit `-Unattended`. The original
session used both flags, but a later UE 5.8.2 check found that `-Unattended` silently cancels
normal Save All requests. Reserve it for automated commandlets/tests. See
[the save recovery procedure](../setup.md#interactive-editing-and-saving). Entries are ordered
by how early in a session you meet them.

The companion client used throughout is `tools/uemcp.py` (see the "MCP without a client
restart" section). Snippets below use it as `uemcp.py call <Toolset> <tool> '<json>'`.

---

## 1. Configuring the project without a human

1. Edit the `.uproject` `Plugins` array yourself (`ModelContextProtocol`, `AllToolsets`, plus
   whatever the game needs - e.g. `Water`). Also enable them with `"Enabled": true`; the
   `PluginToolset.SetPluginEnabled` tool does not persist.
2. Put the MCP section (`bAutoStartServer=True`, port, path) in the project's
   `Config/DefaultEditorPerProjectUserSettings.ini` - not the `Saved/Config/...` per-user file,
   which the editor rewrites on exit and which lost our appended sections - and write
   `.mcp.json` next to the `.uproject`.
3. Before restarting, inspect dirty map and content packages and preserve user edits.
   Missing `LogEditorTransaction` / `LogFileHelpers` lines do not establish that nothing is
   unsaved. Follow [the save recovery procedure](../setup.md#interactive-editing-and-saving)
   if the current editor has `-Unattended`, and verify persistence before stopping it.
   Read `/proc/<pid>/cmdline` to retain the user's relevant launch flags, but remove
   `-Unattended` from an interactive editor's replacement command line. Stop the old process
   only after saving, wait for exit, then relaunch.

   Pass `-ModelContextProtocolStartServer` on the relaunch as well as the `.ini` setting.
   The server is up when the log says `Starting MCP server on port 8000` and
   `ss -ltnp | grep :8000` shows the editor listening. Boot takes 1-2 minutes.

## 2. MCP without a client restart

Claude Code (and most hosts) read `.mcp.json` at startup. If you enabled the server mid-session
the `unreal-mcp` tools will not be in your tool list until the host restarts, and restarting
throws away your context. Do not wait for that: the server speaks plain Streamable HTTP, so a
40-line stdlib client is enough. `tools/uemcp.py` does exactly that:

```sh
uemcp.py toolsets                                  # list_toolsets
uemcp.py sig editor_toolset.toolsets.actor.ActorTools   # one line per tool: name(arg:type) + doc
uemcp.py call EditorToolset.EditorAppToolset CaptureEditorImage '{}'   # images land in /tmp/uemcp_1.png
uemcp.py call <Toolset> <tool> @args.json          # big/quoted payloads from a file
```

Two details that matter: send `Accept: application/json, text/event-stream`, and echo the
`Mcp-Session-Id` header. `sig` exists because `describe_toolset` returns full JSON schemas
that run to hundreds of lines per toolset; dump every toolset's signatures once into a file and
grep it instead of re-describing.

Even with a live client, running MCP calls from a shell has two advantages: you can chain
dozens of calls in one command (they still execute serially), and you can pipe results into
Python for filtering.

## 3. Seeing the editor and the game

- **`EditorAppToolset.CaptureEditorImage` works headlessly** and returns the editor exactly as the
  Pixel Streaming viewer sees it (all panels included). Use it as your eyes; move the level
  camera first with `SetCameraTransform`. Read the PNG the client wrote.
- Earlier 5.8.0 testing found a stale `CaptureViewport` view. On 5.8.2, an explicit
  `captureTransform` plus `annotations:null` and `bShowUI:false` worked. Verify the returned
  camera and image; use `CaptureEditorImage` if the installed version still misbehaves.
- During Play-In-Editor the same capture shows the game viewport, so PIE screenshots need no
  Pixel Streaming client at all.
- The user may rearrange panels at any time (they did: one viewport became four). Re-take a
  screenshot before assuming where anything is on screen.

## 4. The editor goes idle without input - and the PIE world stops

This one cost the most time. With nobody moving the mouse, a headless editor with no realtime
viewport stops redrawing **and stops ticking the Play-In-Editor world after a handful of
frames**. The engine frame counter keeps advancing, `IsPIERunning` says true, and two
`CaptureEditorImage` calls five seconds apart are byte-identical. Consequences:

- `Delay`, `SetTimerByFunctionName`, `EventTick` in your Blueprints never fire.
- Movement components appear to work only because the human moved the mouse while watching.
- `bThrottleCPUWhenNotForeground=False` alone does NOT fix it.

What fixes it:

1. **Preferred for automated tests: start PIE in a floating window** -
   `StartPIE` with `playMode: "PlayMode_InEditorFloating"`. That window always ticks, and
   `CaptureEditorImage` still captures it (it is drawn on top of the editor).
2. Turn the level viewport's **Realtime** toggle on (the checkbox at the right end of the
   viewport toolbar). Clicking it through `SlateInspectorToolset.Click` works, but see §7 -
   the toolbar checkboxes are unlabeled and mirrored across panes, so only do this from a
   snapshot you have just read, one control at a time.
3. Persist for the next launch: `[/Script/UnrealEd.EditorPerformanceSettings]`
   `bDisableRealtimeViewportsInRemoteSessions=False` in `EditorPerProjectUserSettings.ini`
   (Pixel Streaming counts as a remote session, which is why viewports start non-realtime).

Detect the frozen state cheaply: place a test actor whose Tick moves it, capture twice a few
seconds apart, `cmp` the two PNGs.

## 5. Starting PIE

- `StartPIE` needs the full `options` block. **`startTransform` is not optional and not ignored**:
  the pawn spawns exactly there, so `(0,0,0)` puts it inside your floor and the spawn fails
  (`LogSpawn: Warning: SpawnActor failed because of collision`) - you then look at the world from
  the origin, underground. Pass the PlayerStart location (or wherever you want to test from).
  This is also how you "walk" the player to a spot for a screenshot: restart PIE with a
  different `startTransform`.
- **Key presses do reach the game once the PIE window has focus.** `SlateInspector.PressKey`
  goes to the focused Slate widget, so straight after `StartPIE` it is lost, and
  `Windows {"action":"select"}` is not enough. `Snapshot` the floating Preview window, `Click`
  any widget inside the viewport (a HUD text block works), then `PressKey {"key":"E"}`. Held
  movement and mouse look still cannot be driven this way. Two traps: when several actors have
  enabled input for the same key, only the last one enabled receives it, so test from a start
  point outside the radius of other interactables; and a click also captures the mouse, which
  is harmless for a test. When focus cannot be obtained, fall back to a temporary hook
  (`BeginPlay -> timer -> the function the key calls`) with a `PrintString ... :bPrintToLog true`
  marker, grep the log, and rebuild the graph without the hook.
- Verify game logic from the **log file on disk**, not `LogsToolset.GetLogEntries`: that tool
  returns the *oldest* matches up to `maxEntries`, so new lines are invisible once a pattern
  has matched before. `grep -a LogBlueprintUserMessages <Project>/Saved/Logs/<Project>.log | tail`
  is reliable and instant.

## 5b. Measuring what you cannot watch

An agent sees stills roughly 0.4 s apart, so flicker, jitter and physics blow-ups are invisible
unless you measure them.

- **Frame-burst difference.** Fixed `startTransform`, capture 6-8 frames back to back, compute
  the mean absolute pixel difference between frames over a crop that excludes HUD and window
  chrome. A pure-Python PNG decoder (zlib plus the five scanline filters) is enough; do not
  assume PIL or numpy exist.
- **Controls make the number mean something.** Run the same burst with the effect's amplitude
  at exactly 0 (noise floor from lighting and anti-aliasing) and with the animation speed scaled
  to near zero (anything left above the floor is per-frame instability, not motion). Change one
  thing per run. Console variables set through the Cmd box before `StartPIE` carry into the
  session, so anti-aliasing method or pre-pass mode can be A/B tested; restore them afterwards.
- **Alternating states.** Compare frame *i* with *i+1* and with *i+2*. Smooth motion gives
  `d(i,i+1) < d(i,i+2)`. If `d(i,i+1) > d(i,i+2)` the image is flipping between two states. An
  amplified difference image and a magnified side-by-side crop of two consecutive frames show
  what is flipping.
- **Encode hidden values as pixels.** A debug material whose emissive is `frac(Time * k)`, or a
  cube whose World Position Offset is the value under test, turns shader inputs into something
  a screenshot can read. Remove the debug actors afterwards.
- **Physics without input.** To check how props react to the character, spawn the pawn directly
  on top of them with `startTransform` and look at where they end up: nudged is fine, gone is not.
  `LogCharacterMovement: ... is stuck and failed to move` in the log means the pawn climbed onto
  a small prop.
- **Direction of travel.** Two frames a second apart from above: the displacement of a creature
  must point the same way as its head.
- Warnings that appear on screen during play are usually also in the log
  (`LogRenderer: Warning: [VSM] ...`). Count occurrences before and after a long PIE run rather
  than waiting to see one.

## 6. Building a whole level from scripts

`ProgrammaticToolset.execute_tool_script` is the workhorse: one call, dozens of tool
invocations, returns a dict. A small library pattern that paid off:

```python
def T(n,a): return execute_tool(n, json.dumps(a))
def setp(o,v): return T("editor_toolset.toolsets.object.ObjectTools.set_properties",{"instance":{"refPath":o},"values":json.dumps(v)})["returnValue"]
def by_label(lbl, cls="/Script/Engine.StaticMeshActor"):   # labels are the only stable handle you chose yourself
    for a in T("editor_toolset.toolsets.scene.SceneTools.find_actors",{"name":"","tag":"","collision_channels":[],"actor_type":{"refPath":cls}})["returnValue"]:
        if T("editor_toolset.toolsets.actor.ActorTools.get_label",{"actor":a})["returnValue"]==lbl: return a["refPath"]
def box(label,c,size_cm,mat,folder):        # architecture out of /Engine/BasicShapes/Cube
    a=T(ST+"add_to_scene_from_asset",{"asset_path":"/Engine/BasicShapes/Cube","name":label,"xform":xf(c,(0,0,0),(size_cm[0]/100,size_cm[1]/100,size_cm[2]/100))})["returnValue"]["refPath"]
    T(AT+"set_label",{"actor":{"refPath":a},"label":label}); T(ST+"set_actor_folder",{"actor":{"refPath":a},"folder_path":folder})
    setp(a+".StaticMeshComponent0",{"overrideMaterials":[{"refPath":mat}]})
    return a
```

Rules learned the hard way:

- **A failed call aborts the script, and only some of it rolls back.** Assets created before
  the failure persist (materials, blueprints) but the edits inside them may not. Never rerun
  a script blindly: make every script idempotent (`AssetTools.exists`, `list_variables`,
  `list_graphs` checks) and split independent work into separate scripts so one bad pin name
  does not cost the batch.
- `try/except` around `execute_tool` catches schema/argument errors (`input param X is
  required`) but NOT node-creation assertions from `write_graph_dsl` / `create_node`, and not
  `Parameter error: ... is not valid Object` - those kill the script. Existence checks must be
  made with calls that return normally (`find_assets`, `list_variables`, `list_graphs`).
- Property names in `set_properties` are **camelCase of the UPROPERTY** (`overrideMaterials`,
  `relativeLocation`, `bUnbound`, `fishTag` for a Blueprint variable `FishTag`). Enum values are
  the C++ short form (`BLEND_Translucent`, `TLM_SurfacePerPixelLighting`, `Hidden`). Object
  references are `{"refPath": ...}`. `list_properties` returns the JSON schema - use it when a
  struct shape is unclear (`layoutData` on a canvas slot, `settings` on a PostProcessVolume).
- **Read structs back.** On components of placed Blueprint actors only the first member of a
  vector or rotator is written, and nested `bodyInstance` fields are ignored (gotchas file,
  ObjectTools). Use actor-level transforms, or editor Python for component offsets and collision.
- Spawned actors get generated names; use the returned `refPath`, then `set_label`. Component
  paths are `<actor refPath>.<ComponentName>` (`.StaticMeshComponent0`, `.Mesh`, `.Orbit`).
  Light actors do not follow the pattern you expect: DirectionalLight's component is
  `LightComponent0`, fog is `HeightFogComponent0` - `get_components` first.
- `find_actors` and `find_assets` paginate at 20 silently on wide queries. Filter by class or
  folder, or loop.

## 7. Slate automation is a last resort

`SlateInspectorToolset` can click toolbar buttons and type into the status-bar `Cmd` box, and
`Snapshot` gives you refs. But toolbar checkboxes carry no labels, the same global setting is
mirrored into every viewport pane, and refs go stale when the user changes the layout. A
heuristic click on "all unchecked 24x24 checkboxes" flipped the user's snapping settings and
took several passes to undo. If you must click, click one ref you have just read, then
re-snapshot and confirm the effect. Prefer the non-UI route whenever one exists (floating PIE
instead of the realtime toggle; `ObjectTools.set_properties` on
`/Script/UnrealEd.Default__EditorPerformanceSettings` instead of Editor Preferences).

## 7b. Console commands and editor Python

The toolset has no console-command tool and its Python sandbox cannot `import unreal`. The way
in is the status-bar Cmd textbox via `SlateInspectorToolset.Type`, wrapped in
`tools/ue_console.sh` because the box duplicates the first character and only accepts every
other submit. Once it works you have all of `unreal.*`: `py unreal.EditorLoadingAndSavingUtils.
save_dirty_packages(True, True)` was how the World Partition actors finally got saved.

The helper wraps `py <source>` as Python source, so run a file with
`py exec(open('/abs/script.py').read())`, not `py "/abs/script.py"`. A pattern that scales: keep
one small editor-Python file per job that reads a JSON spec written by the shell (component
transforms, collision settings, light properties), log a unique marker at the end, and retry the
helper until the marker count in the log increases. Some settings classes are not exposed to
Python (`unreal.LevelEditorPlaySettings`); use `ConfigSettingsToolset` for those.

## 8. Level hygiene for an agent-made level

- Delete template geometry by class, keeping the sky sphere:
  `find_actors(actor_type=StaticMeshActor)` -> skip labels containing `SkySphere` -> `remove_from_scene`, loop until empty (20-result pages).
- Put everything in outliner folders (`set_actor_folder`) - your later `by_label` lookups and
  the human's Outliner both depend on it.
- `ObjectTools.set_properties` on a level actor does not mark it dirty, so its edits are not
  saved and vanish on the next reload. After property-only edits (instance arrays, materials on
  a component, variables on an instance) write the actor's transform back unchanged to dirty it.
- Save with `AssetTools.save_assets([...all /Game/<Yours> assets..., "/Game/Maps/Level"])`, then
  `tools/ue_console.sh 'py unreal.EditorLoadingAndSavingUtils.save_dirty_packages(True, True)'`
  - the level is World Partition and every actor is its own external package; saving the map
  alone leaves them unsaved, and `SceneTools.save_actor` cannot save never-saved actors. Confirm
  with the status bar reading "All Saved" (`Snapshot("sp1")`).
- Back up `Content/` to a tarball before the first mutating script. It is cheap and you will
  be glad of it the first time a script half-applies.

### Save All leaves an unsaved asset and edits revert on restart

Check the running editor's command line for `-Unattended`. In UE 5.8.2 this can cancel the
normal checkout-and-save path even when the files are writable. Use the direct Python save
and dirty-package checks in [setup.md](../setup.md#interactive-editing-and-saving) before
restarting without that flag. Treat this separately from property edits that never marked
an actor dirty, World Partition external packages, and changes made only in Play/Simulate.
Running without the flag also means import popups are no longer suppressed; see the same
setup section for closing the Message Log window that steals focus from the console helper.

## 8b. The editor can die under you

A Vulkan GPU crash (`FVulkanDynamicRHI.TerminateOnGPUCrash`, in a Nanite pass) took the editor
down once after ~6 hours, with no dialog. Everything had been saved minutes earlier, so nothing
was lost. Treat the "All Saved" check as a habit after every batch of edits, keep the relaunch
command line at hand (`/proc/<pid>/cmdline`), and expect the user to relaunch *without* your MCP
flag - which is why the auto-start setting must live in `Config/Default*.ini`. When the server
is not on :8000 after a relaunch, the only fix is another restart with the flag; there is no way
in through Slate without MCP.

# Performance and safe iteration in Unreal 5.8.2

Use these notes when improving an existing project, especially after someone has edited the
level manually. These are tested workflow patterns and version-specific observations, not
mandatory rendering settings or a level-design recipe.

## Preserve authored work

Save and back up the current map, content, config and source before a bulk pass. Check dirty
map **and** content packages. An old generation script may be repeatable while still erasing
new manual edits: review what it destroys/recreates before running it. Scope additive scripts
to explicitly owned actors/assets; rerunning them still overwrites manual edits to that scope.

`tools/ue_scene_audit.py` records the loaded editor world without changing it. It includes actor
and mesh-component transforms, material overrides, mesh bounds, instance counts, light shadows
and dirty packages. Optional instance hashes detect placement changes inside an ISM component.
Run outside PIE and keep separate before/after files:

```python
import sys
sys.path.insert(0, '/absolute/path/to/tools')
from ue_scene_audit import audit
audit('/absolute/path/before.json', instance_hashes=True)
```

After the change, save/reopen and capture `after.json`, then outside Unreal:

```sh
python3 tools/ue_compare_audits.py before.json after.json
```

The comparator reports additions and mesh swaps separately; removal or movement of existing
actors, component placement/count changes, and changed material overrides fail the preservation
check. It does not prove gameplay properties are unchanged. Instance hashes are exact; actor
and component transforms use a configurable absolute tolerance.

For mesh-only optimization, keep the original asset and import a replacement into a new folder.
Preserve component overrides when swapping meshes. Compare bounds and pivot origins: equal
actor transforms do not guarantee equal visible placement if the replacement pivot changed.
Check shape, material slots, collision and resting height from the normal player distance.

## Profile a controlled view

Record engine/build, hardware, viewport dimensions, camera, quality settings and warmup interval.
Use the actual game viewport size, not a screenshot's outer dimensions. Background builds,
shader compilation, CPU throttling, VSync and frame caps can confound a short capture.

CSV Profiler commands are case-sensitive on the tested build:

```text
csvprofile STARTFILE=Before
csvprofile FRAMES=1200
```

`STARTFILE` selects a filename; it does **not** start recording by itself. `FRAMES=N` starts a
bounded capture. `csvprofile START` / `csvprofile STOP` provide manual control. Files are under
the project's `Saved/Profiling/CSV`. Keep immutable baseline copies; an inspection callback
that replays a stale request after restart can overwrite a capture with the same name.

```sh
python3 tools/ue_csv_summary.py Before.csv After.csv --start 300 --stop 1100 --output timing.json
```

The helper ignores metadata/footer rows and reports mean, median, nearest-rank p95, min and max.
Default columns are `FrameTime`, `GPUTime`, `GameThreadTime`; inspect the CSV header and supply
`--columns` when names differ. Frame slice indices are zero-based and stop-exclusive.

Report CPU and GPU separately. A capped frame time may remain unchanged while GPU work falls.
Pixel Streaming's decoded FPS measures the video pipeline, not uncapped game performance.
One view on one GPU is not a minimum-hardware benchmark. Restore intentional frame caps after
testing. A successful cook also does not establish a successful standalone playthrough.

## Quality presets that remain usable

Use `UGameUserSettings` to apply scene resolution and scalability groups, with a clear low
preset and an in-game way back. Keep HUD/layout independent of 3D resolution. Save the preset
choice separately from gameplay saves and verify it after a fresh launch. Apply changes only
when the selected value changes; avoid writing settings every frame while dragging a slider.

Test a sequence such as high → low → middle, then an interior and an exterior. Check both
visual output and the effective CVars. Loading a preset from disk alone does not verify a UI.

**Version-specific observation:** stock Effects scalability in UE 5.8.2 changes
`r.SceneColorFormat` and material quality permutations, among other settings. On the tested
Linux/Vulkan setup, switching the full groups produced transient over-bright artifacts.
Keeping the Effects group stable while varying resolution, shadows, GI/reflections and other
measured settings avoided them in the tested sequence. This is a workaround, not a diagnosed
engine defect or a universal requirement to use High effects. Consult the installed
`Engine/Config/BaseScalability.ini` and reproduce on the target renderer before broad changes.

Lumen disabled by a lower GI group changes ambient/interior lighting; inspect that explicitly.
Do not lower texture quality so far that readable props or UI art become illegible merely to
make every group share one numeric level. Test the packaged build as well as PIE when feasible.

## Choose optimizations by repetition and screen size

- Prioritize repeated small props and distant vegetation before recognizable hero silhouettes.
  Inspect source counts, reduce in Thrixel, inspect again, then import into a separate folder.
  For multipart sources, **reduce before grouping** when the ungrouped job is available.
  If reduction fails or returns unchanged counts, check the original job instead of assuming
  success; keep submitted jobs recorded and do not resubmit merely because processing is slow.
- Instancing reduces repeated component/draw overhead, but many material slots still cost
  work. Grouping parts preserves slots. Measure the result rather than equating one mesh with
  one draw call.
- Nanite LOD0/render-data counts exposed by `get_num_triangles(0)` can describe fallback data.
  They are useful for an asset audit, not the triangles actually drawn in a frame. Keep source
  geometry counts and profiler measurements distinct.
- Cull small, low-importance props by distance. Limit unnecessary tiny-light and grass shadows
  while retaining the lights/shadows that make rooms readable. Use two-sided materials where
  back faces are visible, rather than enabling them on every closed opaque surface.
- When ticking distant actors less frequently, integrate movement and timers with elapsed
  time. Check transitions near the distance threshold and interactions with nearby actors.

### "[VSM] Non-Nanite Marking Job Queue overflow"

The on-screen warning (also `LogRenderer: Warning: [VSM] Non-Nanite Marking Job Queue overflow`
in the log) means non-Nanite shadow casters are touching too many Virtual Shadow Map pages.
Audit instead of guessing. In editor Python, walk every `StaticMeshComponent` and record
`static_mesh.nanite_settings.enabled`, `cast_shadow`, instance count and actor bounds; list the
entries that are non-Nanite **and** casting. In the tested level that left three kinds of mesh,
and the offender was the template's `SM_SkySphere`: shadow casting on, with bounds that cover
every page of every clipmap level. Set `castShadow` and `bCastDynamicShadow` false on sky domes,
water planes and glass. Non-Nanite grass that already has shadow casting off does not
contribute. The warning is intermittent (it tends to fire on frames that invalidate the shadow
cache), so compare log counts across a long PIE run before and after the change.

## Static procedural surfaces

For a mostly static ground pattern, baking tileable noise to a small texture and sampling it at
multiple world-space scales can be cheaper than evaluating shader Noise nodes. Keep the color
range restrained and inspect close ground, distant repetition, seams and shadowed areas.
World-space mapping is useful for differently scaled meshes; it does not require dense UVs.

Still provide explicit UV records/indices in generated OBJ files. The UE 5.8.2 Interchange OBJ
translator emitted `UVs.IsValidIndex(VertexData.UVIndex)` ensures for a UV-less reimport on the
tested path. Validate triangle winding independently for strips and grids; a downward path can
be correctly placed yet invisible. Reimport changed source geometry: an asset-exists check
must not silently keep an old terrain mesh.

Height-function values and a triangulated surface differ between vertices. Follow the mesh's
actual triangle interpolation, or trace only the intended surface, then check visually. Nanite
simplification can introduce further small differences; thin overlays need enough separation
to avoid clipping/flicker without looking suspended. Wider props on slopes may need grading
or foundations, not just a correct center height.

## Reliable inspection and scripting

`tools/ue_console.sh` targets the editor Cmd box and presses Escape: **do not use it to send
commands during PIE**. For PIE profiling, use a temporary editor-only callback that targets the
game world and calls `SystemLibrary.execute_console_command`, or another verified game-console
route. Give requests unique IDs, initialize without replaying stale commands, and unregister
the callback after testing. Keep inspection hooks out of packaged gameplay and user saves.

The console wrapper confirms Python completion/error with unique log markers. A Python error
returns failure without replaying partial mutations. A lost connection or missing acknowledgement
still requires inspecting the log/state before a manual retry. For ordinary console commands,
a logged dispatch confirms submission, not semantic success. Prefer a short `py exec(open(...).read())`
call over a long command, and pass the running editor's log explicitly.

Editor Python often exposes editable fields only through `set_editor_property`, even when a
similarly named direct attribute is absent. Examples include ComponentMask `r/g/b/a`, Multiply
`const_b`, and LinearInterpolate `const_alpha`. TextureSample's input pin is `UVs`, not
`Coordinates`; single unnamed inputs usually take `''`. Assert connection results before
building the rest of a material. `__file__` is not defined by `exec(open(...).read())`; pass a
tools/source directory explicitly or use the project directory instead.

For clean screenshots, a warmed-up PIE `HighResShot` captures the game viewport/HUD. For editor
inspection, UE 5.8.2 `CaptureViewport` worked with an explicit transform and `annotations:null`;
verify the image and returned camera because older builds had a stale-view defect. A full
`CaptureEditorImage` may include several windows and be resized, so it is not a trustworthy
source of game viewport dimensions.

When driving Pixel Streaming input, account for the video element's displayed rectangle,
source video resolution, letterboxing, window chrome and actual game viewport. Wait for and
assert the resulting game state; tool submission and one immediately sampled response can
precede delivery of the input event. A connected stream with zero video frames is inconclusive.


## Grounded characters and world maps that track authored geometry

For multipart procedural characters, the actor origin or torso bounds may not coincide with
the soles. Ground the complete visible body, including animated legs, at spawn and after
movement/pose updates. Restrict support queries to intended floor/path surfaces; unrestricted
traces can place people on furniture, roofs or each other. Check idle and walking poses,
interiors and surface transitions, and verify contact visually as well as numerically.

In-game world maps built from independent pixel coordinates can drift from the level. Mark the
actual footprint actors with runtime tags or explicit references, then project their geometry
and the player through one world-to-map transform. Preserve aspect ratio, rotation and north
orientation; use a numbered key when labels do not fit. Editor actor labels alone are unsuitable
as runtime identifiers in Shipping builds. A floor footprint only tracks edits to that floor:
keep a building's floor and shell together when moving the whole building.

Concurrent editor and commandlet launches can assign the editor a suffixed log such as
`Project_2.log`. Verify the active editor's actual log before console scripting. An inactive
log can hide a successful dispatch and provoke retries. A dedicated editor stdout/log file
also avoids this ambiguity. Finish acknowledgement-dependent calls before starting PIE: an
unfinished console helper may press Escape and stop the new play session.


In native Canvas drawing, `FCanvasTriangleItem` requires a valid texture for its textured draw
path even when vertices use solid colors. UE 5.8.2 asserts on a null texture. The higher-level
`UCanvas::K2_DrawTriangle(nullptr, Triangles)` supplies the engine's default white texture;
set each vertex color explicitly. Verify the panel by opening it in play, since compilation
cannot catch this render-time requirement.

Field manual for driving Unreal Engine 5.8 through MCP. Engine-level
gotchas, silent-fail edges, crash patterns, and the call sequences that
actually work — applicable regardless of which MCP server you're using
(Epic's official ModelContextProtocol plugin, custom servers, or anything
else). Auto-trigger when Unreal Engine MCP tools are detected in a session,
or when the user mentions Unreal Engine, UE5, Blueprints, Niagara,
MetaSound, materials, or any UE editor automation workflow. This skill
contains hard-won knowledge from real debugging sessions — most entries
trace back to an actual editor crash or hours-long faceplant. Ignoring it
when UE5 MCP tools are present will lead to wasted time hitting known dead
ends.

# ue5-mcp — Field manual for driving Unreal Engine 5 via MCP

Engine-level wisdom an LLM needs to drive UE5 through an MCP server without
faceplanting on UE's silent-fail edges. This skill is **server-agnostic**:
the gotchas, patterns, and identifiers documented here apply whether you're
connected to Epic's official `ModelContextProtocol` plugin (UE 5.8+) or any
other MCP server that exposes UE5 functionality.

What this skill *isn't*: a list of commands for any particular MCP server.
Each server publishes its own tool catalogue — ask the server with
`tools/list` for what it actually exposes. This skill covers what bites you
*after* you know the tool names.

---

## 1. Session checklist — read before you write

UE5 is a structured-asset editor. The agent that wins is the one that reads
state before mutating it.

1. **Always dump the asset before editing it.** Blueprint, material, Niagara
   system, widget, level — every MCP server worth its salt exposes a
   `dump_*` / `inspect_*` / `read_*` family. Use it. Editing a graph
   without first knowing what's there creates broken connections, duplicate
   nodes, and unrecoverable corruption faster than anything else.
2. **Discover before assuming.** Call `tools/list` once on connect, cache it,
   and use it to figure out which tools your server actually exposes.
   Different servers wrap UE5 differently; recipes from this manual that
   reference a generic capability (e.g., "dump the Blueprint graph") will
   map to different concrete tool names on different servers.
3. **Verify after mutating.** UE5 has too many silent-fail edges to trust a
   successful response. Read the property back. Compare to what you asked
   for. If they differ, re-examine.
4. **Save explicitly.** Most introspection tools serialize from disk. If
   your last mutation is in-memory only, the dump returns the pre-mutation
   state. Save the asset (or `SaveDirtyAssets`) before re-reading.

---

## 2. UE5 reflection gotchas

These bite agents regardless of which MCP server sits in front of them. Every
one has cost real debugging time.

### 2.1 PascalCase, not snake_case, for UPROPERTY writes

Setting a UPROPERTY via the Python binding's `set_editor_property("auto_possess_ai", ...)`
silently no-ops on many builds. UPROPERTY names are PascalCase at the
reflection layer: `AutoPossessAI`. Python's `unreal` module accepts
snake_case at the call site, but the underlying lookup is case-sensitive
against the PascalCase name. There is no error returned — the property
simply doesn't change.

**Detection pattern: round-trip verify.** After any UPROPERTY write, read the
property back and compare. Naive string compare misses normalization
(`EFoo::Bar` vs `Foo::Bar`, `(X=1,Y=2)` vs `(X=1.000000,Y=2.000000)`). The
robust pattern in native C++:

1. Allocate a scratch buffer aligned to `Property->GetMinAlignment()` and
   call `Property->InitializeValue(Scratch)`.
2. `Property->ImportText_Direct(RequestedValue, Scratch, Owner, PPF_None)`
   to canonicalize what was requested.
3. `Property->ExportTextItem_Direct(ExpectedText, Scratch, ...)` for the
   canonical form of "what we asked for."
4. Apply the write, then `Property->ExportTextItem_Direct(ActualText, ...)`
   for "what we got."
5. Compare `ExpectedText` to `ActualText`.

If they differ, the write didn't take — usually due to snake_case mismatch,
an enum-class qualifier issue, or a struct-text format the property doesn't
recognize.

### 2.2 Blueprint class path needs the `_C` suffix

`LoadObject<UClass>(nullptr, "/Game/Path/BP_Foo")` returns `nullptr`. The
Blueprint's generated class lives under a different name:
`/Game/Path/BP_Foo.BP_Foo_C`. `StaticLoadClass` expands this internally;
`LoadObject<UClass>` does not.

If an MCP tool returns "Class not found: /Game/Path/BP_Foo," that's almost
always the missing suffix. Retry with `<path>.<asset>_C`.

### 2.3 Async asset operations don't block

MetaHuman texture downloads, asset compilation, shader compilation,
derived-data builds, Niagara compile, package save — all async. An agent
that requests "download MetaHuman textures" and immediately reads the
character sees the *previous* texture state, not the new one.

**Patterns:**
- Poll the relevant `Is*Complete` predicate before continuing.
- Subscribe to the completion delegate if the subsystem exposes one
  (`FAssetCompilingManager::Get().GetPostCompilationDelegate()`, etc.).
- For MetaHuman: poll `IsTextureSourceRequestComplete(Character)` after
  `RequestTextureSources`.
- For asset save: don't immediately re-read the package file; let
  `UPackage::SavePackage` complete first.

### 2.4 Save before reading from disk

Many "dump" / "serialize" operations read the asset from its `.uasset`
package on disk. If the most recent edits are in-memory only, the dump
returns the pre-edit state. Save explicitly between mutate and read, or use
an in-memory-aware introspection path if the server provides one.

### 2.5 `PostEditChangeProperty` is required after direct property writes

`Property->CopyCompleteValue(Dest, Src)` writes the value but doesn't fire
`PostEditChangeProperty`. Any derived state set up by the object's
`PostEditChangeProperty` handler — preview meshes, generated thumbnails,
recompiles, dependent properties — won't update. Notify it manually:

```cpp
FPropertyChangedEvent ChangeEvent(Property, EPropertyChangeType::ValueSet);
Object->PostEditChangeProperty(ChangeEvent);
```

The Details panel will show the new value either way, but the object's
behaviour won't reflect it until the event fires.

### 2.6 Blueprint graph mutations need three steps, not one

To safely add a node to a `UEdGraph`:

1. Construct the node (`NewObject<UEdGraphNode>(Graph)`).
2. `Graph->Nodes.Add(NewNode)`.
3. `Graph->NotifyGraphChanged()`.

Single-call helpers in some bindings do step 1 only and leave the graph in
an inconsistent state — the node exists but the editor's pin-resolution +
compile pipeline doesn't see it. Symptoms: phantom "missing node" errors at
compile, broken connect operations, or nodes that vanish after editor
reload.

### 2.7 Enum-string resolution has three accepted forms

UENUM-defined enums store their entries as fully-qualified FName forms
like `EAutoExposureMethod::AEM_Manual`. `UEnum::GetValueByNameString`
matches the fully-qualified form, but bare short names (`AEM_Manual`) and
the Python-binding casing the `unreal` module exposes (`AEM_MANUAL` from
`unreal.EAutoExposureMethod.AEM_MANUAL`) silently miss — those are the
forms agents most naturally reach for, especially when copying values
out of `dump_post_process_settings` output or Python docs.

A 3-step resolver covers the common cases:

```cpp
int64 ResolveEnumValue(UEnum* Enum, const FString& Name)
{
    if (!Enum) return INDEX_NONE;
    int64 Val = Enum->GetValueByNameString(Name);            // EEnumType::ShortName
    if (Val != INDEX_NONE) return Val;
    Val = Enum->GetValueByName(FName(*Name));                // FName lookup
    if (Val != INDEX_NONE) return Val;
    const int32 N = Enum->NumEnums();                        // case-insensitive
    for (int32 i = 0; i < N; ++i)                            // suffix-after-::
    {
        FString EntryName = Enum->GetNameStringByIndex(i);
        int32 ColonPos = INDEX_NONE;
        if (EntryName.FindLastChar(TEXT(':'), ColonPos))
            EntryName = EntryName.RightChop(ColonPos + 1);
        if (EntryName.Equals(Name, ESearchCase::IgnoreCase))
            return Enum->GetValueByIndex(i);
    }
    return INDEX_NONE;
}
```

Affects every reflection-driven property setter that accepts enum-typed
JSON strings (`FEnumProperty`, `FByteProperty` whose `Enum` field is
populated, properties resolved via `StaticEnum<...>()`). The 1-step form
`Enum->GetValueByNameString(Name, EGetByNameFlags::CaseSensitive)` is
the most fragile — it rejects everything except the fully-qualified
form. The fallback chain trades a tiny scan cost (enums rarely have more
than a few dozen entries) for actually accepting the strings callers
pass in.

The same pattern applies on the agent side: when calling an MCP tool
that takes an enum-named string, prefer the C++ short form
(`AEM_Manual`) — it's accepted by every resolver that follows even
minimal best practice; the Python-binding uppercase form may not be.

**When resolution misses, list the valid values in the error.** Returning
`"unsupported type or value coercion failed"` and nothing else forces the
caller to grep engine source for the enum's entries. The same
`NumEnums()` / `GetNameStringByIndex()` iteration that backs the
case-insensitive fallback also gives you the discovery surface — trim
each entry to its short name (after the last `::`), skip the
auto-generated `_MAX` terminator, and join the rest into the error
string:

```cpp
TArray<FString> ValidNames;
const int32 N = Enum->NumEnums();
for (int32 i = 0; i < N; ++i)
{
    FString EntryName = Enum->GetNameStringByIndex(i);
    int32 ColonPos = INDEX_NONE;
    if (EntryName.FindLastChar(TEXT(':'), ColonPos))
        EntryName = EntryName.RightChop(ColonPos + 1);
    if (EntryName.EndsWith(TEXT("_MAX")))
        continue;
    ValidNames.Add(EntryName);
}
// "Could not apply 'X' (enum EAutoExposureMethod). Valid values:
//  AEM_Histogram, AEM_Basic, AEM_Manual. (Case-insensitive; C++ short
//  name, not Python display name.)"
```

The error message becomes self-documenting: any agent that calls the
tool with an invalid string immediately sees the valid set in the
response. No round-trip through engine source. This pairs naturally
with the resolver above — same iteration, same `_MAX` filter, used for
discovery instead of resolution.

### 2.8 Actor "properties" may live on the RootComponent, not the AActor

A reflection-driven property setter that only walks `Actor->GetClass()`
silently misses the properties that look actor-level in the editor but
are actually stored on the RootComponent (a SceneComponent). The
member-of-component set includes `Mobility`, `bHidden`, `bVisible`,
`RelativeLocation`, `RelativeRotation`, `RelativeScale3D`, `AreaClass`,
and the other SceneComponent transform/visibility fields.

The failure mode is hostile: the setter returns success-shaped (the
property *name* is real, and the JSON value coerced cleanly), the call
log shows `"property_name": "Mobility", "applied": true`, but a
follow-up read returns the old value. There's no error, no
deprecation warning, no typo suggestion — just a write that went into
the void because the writer aimed at the wrong UObject.

**Fix:** when the property isn't found on `Actor->GetClass()` and the
caller didn't pin a specific component, fall back to the RootComponent's
class:

```cpp
UClass* TargetClass = Actor->GetClass();
void*   TargetPtr   = Actor;

FProperty* Prop = TargetClass->FindPropertyByName(*PropertyName);
if (!Prop && Actor->GetRootComponent())
{
    USceneComponent* Root = Actor->GetRootComponent();
    if (FProperty* RootProp = Root->GetClass()->FindPropertyByName(*PropertyName))
    {
        Prop        = RootProp;
        TargetClass = Root->GetClass();
        TargetPtr   = Root;
    }
}
```

**Surface which container actually received the write in the response**
(`target_object: "Actor" | "<ComponentName>"`). Without that hint, a
caller debugging "why didn't the mobility change?" has no clue whether
the fallback fired or whether the original Actor-level write succeeded
on a same-named property. The silent-magic failure mode is worse than
the original wart — the call now appears to work but you can't tell
where the change landed.

The same pattern applies to other SceneComponent-resident sets — light
intensity / color on light components, mesh on StaticMeshComponent, etc.
Those usually have explicit component-targeting parameters in MCP
surfaces, so the silent-miss mode there is rarer, but the fallback is
the right default for any property setter accepting an actor name
without an explicit component scope.

### 2.9 A mutation without `Modify()` isn't "undoable but with one field missing" — it's not in the undo history at all

`FScopedTransaction` wraps a block of editor code as one undo step, but the
transaction only actually *contains* an object if that object's `Modify()`
was called before it changed. An empty transaction — every object in scope
mutated via a raw setter or direct `FProperty` write that skipped `Modify()`
— is discarded as transient rather than pushed onto the undo stack
(verified against UE 5.8's `EditorTransaction.cpp`). The failure mode isn't
"Ctrl+Z reverts everything except this one field" — it's "Ctrl+Z does
nothing at all for this entire edit," with no error and no indication
anything was skipped. A human editing the same property through the
Details panel gets a working undo step for free (the panel's property
handle calls `Modify()` for you); a tool that reaches past the UI and
writes the property directly does not, unless it calls `Modify()` itself.

**The rule: call `Modify()` on the object *before* the mutation, not
after** — it snapshots pre-mutation state, so calling it post-hoc records
nothing useful.

```cpp
// Wrong: SetMobility doesn't call Modify() itself, so this mutation
// never enters the transaction — Ctrl+Z after this silently does nothing.
RootComponent->SetMobility(EComponentMobility::Movable);

// Right:
RootComponent->Modify();
RootComponent->SetMobility(EComponentMobility::Movable);
```

For a transform-style write that touches both the actor and its root
component, `Modify()` both — matching whichever object's state the engine
actually reads back on undo:

```cpp
Actor->Modify();
Actor->GetRootComponent()->Modify();
Actor->SetActorTransform(NewTransform);
```

**Not every mutator needs this.** High-level engine entry points that are
themselves undo-aware self-record when a transaction is active — `UWorld::
SpawnActor` and `AActor::Destroy()` both record into `GUndo` automatically
(verified in engine source), so wrapping a spawn/destroy in an outer
`FScopedTransaction` needs no extra `Modify()` call. The gap is specifically
low-level setters (`SetMobility`, `SetIntensity`, a generic reflected
`FProperty` write via `ImportText_Direct` / `CopyCompleteValue`) that
mutate state directly without going through an undo-aware wrapper.

**If you're auditing an existing surface for this bug, look for "it built,
it ran, the response said success" as the tell** — this is not a crash or
an error-returning bug, so it never shows up in normal QA. The only way to
catch it is to explicitly test Ctrl+Z (or the transaction system's
equivalent) after every mutating call and confirm the *specific* property
you changed actually reverts — not just that undo doesn't crash.

---

## 3. UE5 stability — actions that crash the editor

These are crashes that hit any agent driving the editor, regardless of MCP
server. Worth knowing before you do them.

### 3.1 Don't delete or modify assets that other actors reference

Deleting (or transforming) a mesh asset while level actors reference it
triggers a `RegisteredElementType` assertion crash. The editor goes down
and any unsaved work in other windows is lost.

**Safe pattern:** before deleting, walk the asset dependency graph. Most
MCP servers expose this (`get_asset_references` or similar). If anything
depends on the asset, create a new replacement asset, swap actor references
to it, then delete the original.

### 3.2 Don't spawn-then-immediately-delete actors in quick succession

Same `RegisteredElementType` assertion. Spawn → delete → focus in rapid
succession (sub-frame timing) corrupts the actor registry. Add a small
delay or interleave with other operations.

### 3.3 Niagara assertions and MetaSound crashes wipe unsaved changes

When Niagara or MetaSound asserts during PIE, the editor reverts to the
last on-disk save. Custom nodes, in-memory tweaks, and uncompiled edits are
gone. **Save before every PIE test** for these subsystems. Pattern after a
crash: restart editor, dump the asset, recreate the lost nodes from the
dump.

### 3.4 MetaSound: scalar literal on an Audio-type pin

Setting a float (or other scalar) literal directly on a pin typed as
`Audio` crashes the editor at **runtime**, not at edit time. The edit
succeeds silently; the crash fires when PIE starts and the graph
evaluates. The stack signature is:

```
bExpectsNone [MetasoundDataFactory.h:395]
```

**Rule:** Audio-type pins expect audio buffer connections, not scalar
values. Don't pipe a Multiply (Audio) directly from a Constant; route it
through an Oscillator or noise source that produces an audio-rate buffer.

After this crash, all custom MetaSound nodes are wiped on next editor
launch — only `OnPlay`, `OnFinished`, and `Output` survive.

### 3.5 Editor sprite icons are not particles

Editor viewport screenshots include sprite icons for each component
(NiagaraComponent, AudioComponent, etc.). They look like particles but are
the editor's UI overlay, not the actual VFX. **Editor screenshots are not
reliable verification for live Niagara behavior.** Verify by:

1. Reading `is_active: true` off the Niagara actor after spawn.
2. Entering PIE and screenshotting the running game viewport.
3. Or using pixel streaming for real-time visual confirmation.

---

## 4. Identifier and path conventions

### 4.1 Actor labels are not stable identifiers

`a.get_actor_label()` returns the display string shown in the Outliner. Two
actors can share a label. The label is user-editable.

Use the actor's **full path** as the stable identifier:

```
/Game/Maps/Level.Level:PersistentLevel.BP_Character_C_0
```

Most MCP servers accept either, but the path is the only form that
survives renames and disambiguates duplicates.

### 4.2 Asset path forms

UE5 accepts three forms for an asset, and they mean different things:

| Form | Example | What it loads |
|---|---|---|
| Package name | `/Game/Foo/Bar` | The package (used by the asset registry) |
| Package.Asset | `/Game/Foo/Bar.Bar` | The primary asset within the package (`LoadObject<UObject>`) |
| Package.Asset_C | `/Game/Foo/Bar.Bar_C` | The generated class of a Blueprint (`LoadObject<UClass>`) |

If a tool returns a path-not-found error, check that the form matches what
the tool expects.

### 4.4 OBJ import mirrors Y (and applies no up-axis conversion)

The FBX/OBJ factory reads an `.obj` as Z-up but converts handedness by **negating Y**: a vertex
written `v x y z` lands at UE `(x, -y, z)`. X and Z are untouched, so a mesh that is symmetric in
Y looks perfectly correct and a mesh that is not comes in mirrored across the X axis - a terrain
whose hills should be north ends up with them south, while every flat area still sits where you
expect. Write `v x -y z` and flip the triangle winding when generating OBJ for Unreal, and probe a
few asymmetric points after import (trace down where nothing is overhead, compare with the
source). This bites any generated OBJ - terrain, water planes, collision proxies - not only
Thrixel assets, which normally arrive as FBX and are converted there instead (glTF Y-up -> UE
Z-up, glTF Z -> UE Y).

The same importer also **flips the V texture coordinate** (`vt u v` arrives as `(u, 1 - v)`).
That is invisible with an ordinary texture and wrong for any generated mesh that stores data in
UVs: a root-to-tip ramp used as a wind mask comes in upside down, so roots sway while tips stay
pinned, and a base-to-tip colour gradient inverts. Write `1 - v` in the exporter or put a
`OneMinus` after the V mask in the material, and confirm with a close-up.

### 4.3 Widget paths vs widget Blueprint paths

UMG-related tools usually take one of two parameters with similar names:

- `widget_blueprint_path` — path to the WidgetBlueprint asset on disk
  (`/Game/UI/WBP_HUD`)
- `widget_path` — the identifier of a widget *within* a tree, addressing a
  node inside the WidgetBlueprint's hierarchy

A "compile this widget" tool wants the Blueprint path. A "remove this
widget from its parent" tool wants the tree-internal path. Servers vary on
which they expose where — check input schemas before assuming.

---

## 5. UE5 subsystem gotchas

Engine-level facts about specific subsystems. These apply regardless of MCP
server — the underlying UE5 behavior is the same.

### 5.1 Lumen lighting — Movable mobility is mandatory

Lumen Global Illumination only considers lights with **Movable** mobility.
Static and Stationary lights contribute nothing to Lumen GI. Agents that
spawn a DirectionalLight default to Stationary and then complain that GI
isn't working — the fix is to set `Mobility` to `Movable` explicitly.

### 5.2 Blueprint instance override staleness

Level-placed Blueprint instances retain editor-modified component property
overrides even after the parent Blueprint changes. If you edit
`BP_Character` to change `Speed` from 600 to 800, instances of
`BP_Character` placed in the level keep their old override (whatever the
designer or a prior agent set on that specific instance).

**Pattern after any parent BP property change:** walk affected level
instances and either revert overrides to defaults or re-apply the new
value explicitly per instance. The "Reset to Defaults" right-click in the
Details panel does this for humans; for agents, set the property directly
on each instance.

### 5.3 Niagara: created-from-empty systems don't emit

Programmatically constructing a `UNiagaraSystem` from scratch produces a
system that compiles clean but never emits. The empty-system default state
isn't valid for emission (missing system spawn script wiring, missing
emitter mode, etc.).

**Working pattern:** start from a working template. UE ships
`/Niagara/DefaultAssets/DefaultSystem` which has a valid sprite emitter.
Most MCP servers expose an "asset duplicate" tool; use it to duplicate a
working system and then mutate the copy. Don't try to build emitters from
nothing.

### 5.4 Niagara: `script_usage` is part of the module identity

The same module name can appear in multiple script-usage stages:

- `system_spawn`, `system_update` — once per system frame
- `emitter_spawn`, `emitter_update` — once per emitter per frame
- `particle_spawn`, `particle_update` — once per particle

A module named `SpawnRate` typically lives in `emitter_update`. A module
named `Initialize Particle` lives in `particle_spawn`. When setting module
inputs, **always specify `script_usage`** — the same module name in
different stages is a different module instance, and the wrong stage
silently no-ops.

### 5.5 Niagara: user-facing inputs vs script pins

The Niagara stack panel shows "user-facing inputs" — the named tweakable
parameters per module. These are NOT the same as the underlying script's
function-call pins. An agent that reads script pins and assumes they're the
inputs will fail to set values.

**Discovery pattern:** ask for the module's input list before setting
anything. Servers usually expose this as `list_module_inputs` or
equivalent. The returned names are what `set_*_module_input` expects.

### 5.6 Niagara: dynamic input setting is broken in many versions

`set_niagara_dynamic_input` (or equivalent) typically fails with:

```
Failed to load random range script
```

This is a UE5 Niagara API gap, not an MCP-server bug. **Workarounds:** bake
the dynamic value to a constant before assignment, or compute the value in
Python and set the static input.

### 5.7 MetaSound: exact pin names matter

MetaSound pin names are case-sensitive and exact. `SuperOscillator` uses
`Frequency`, `Voices`, `Detune` — not `Base Frequency` or `Freq`. Always
dump the MetaSound's nodes (`dump_metasound_graph` or equivalent) before
setting pins to learn the exact names.

### 5.8 Materials: emissive bloom threshold

Emissive intensity must **exceed 1.0** to trigger bloom in the Post Process
pipeline. Values of 3–10 produce visibly bloomed emissive surfaces. An
emissive material with intensity 0.8 looks dim and self-lit but won't
bloom.

Additional requirement: Post Process Volume must have **Bloom enabled** in
its Effects settings. Default volumes have it on, but an agent that
explicitly disabled bloom for performance won't get emissive bloom either.

### 5.9 Materials: translucent particle materials need Unlit shading

Lit translucent materials require normal vectors. Niagara sprite particles
don't reliably provide normals (the orientation comes from the renderer,
not the geometry). Pattern for particle materials:

- `blend_mode = Translucent`
- `shading_model = Unlit`
- Emissive output, no base color routing

A lit translucent particle material renders as a black/featureless sprite
because the lighting calc has nothing to work with.

### 5.10 Materials: compilation lag

Creating or modifying a material kicks off shader compilation. Depending on
how many permutations the material has (number of materials in the project
using it, light counts, etc.), compilation takes seconds to minutes.
Visual output doesn't update until compilation completes.

**Pattern:** after a material edit, poll for compile completion before
judging visuals. Most servers expose a "get material errors" or "is asset
compiled" predicate; if not, screenshot after a fixed delay (10–30s for
moderately complex materials).

### 5.11 UMG widgets: `CreateWidget` needs an owning player context

A widget created without specifying an owning player context renders blank
at runtime. The widget Blueprint compiles, the instance spawns, and
`AddToViewport` accepts it — but nothing draws because the widget has no
World context to anchor in.

**Fix:** pass `GetPlayerController(0)` as the `Owner` argument to
`CreateWidget` (the Owner pin in the Blueprint node, or the `OwningPlayer`
parameter in the Python `unreal.CreateWidget` call).

### 5.12 In-world widget components need a `WidgetClass`

Adding a `WidgetComponent` to a Blueprint doesn't automatically associate
it with a Widget Blueprint. Set the `WidgetClass` property explicitly —
it's a `TSubclassOf<UUserWidget>` (an FClassProperty), so the value is the
generated class path (`/Game/UI/WBP_HUD.WBP_HUD_C`) or the asset path
(`/Game/UI/WBP_HUD`, which auto-expands).

Default draw mode is screen-space; for a 3D billboard, set the component's
`Space` to `World`.

### 5.13 AudioComponent type name

When adding an audio component to a Blueprint via reflection, the type name
is `Audio`, not `AudioComponent`. Some servers' helpers handle either; raw
reflection lookups don't. Sound asset assignment goes through the `Sound`
UPROPERTY (a `FObjectProperty`); pass the sound asset's path as the value
and the property handler resolves the load.

### 5.14 UltraDynamicSky: override booleans first

The UltraDynamicSky / UltraDynamicWeather plugin uses a "manual override"
pattern. Each weather parameter (rain, snow, wind, etc.) has a companion
`bool` flag named `<Param> - Manual Override`. **The manual override bool
must be set to `true` before setting the parameter value** — otherwise the
plugin's auto-weather logic overrides whatever you set on the next tick.

Other UltraDynamicSky notes:

- Spawn `Ultra_Dynamic_Sky` and `Ultra_Dynamic_Weather` at origin together.
- First spawn triggers 150+ shader compiles; visual output isn't reliable
  until they finish.
- Conflicts with existing DirectionalLights — remove or hide them.
- Rain/snow particles render most visibly in PIE; editor viewport often
  shows the sky but not the particle layer.

### 5.15 Sequencer: extending the playback range doesn't extend track sections

`UMovieScene::SetPlaybackRange(...)` updates the scene's logical playback
range, but per-track sections (created by `AddNewCameraCut`, `AddSection`
on a TransformTrack, FloatTrack, etc.) keep their original lengths. The
camera cut track section in particular bounds what Movie Render Queue
actually renders — **MRQ stops at the end of the active camera cut
section regardless of the playback range**. Symptom: a sequence whose
`GetPlaybackRange()` reports 12 s renders only the first 5 s; the
returned image count matches the section length, not the playback range.

After extending the playback range, iterate every track on every binding
and call `SetRange` on every section:

```cpp
const TRange<FFrameNumber> NewRange = MovieScene->GetPlaybackRange();
for (UMovieSceneTrack* Track : MovieScene->GetTracks())                       // master tracks
    for (UMovieSceneSection* Sec : Track->GetAllSections()) Sec->SetRange(NewRange);

if (UMovieSceneTrack* CutTrack = MovieScene->GetCameraCutTrack())             // camera cut
    for (UMovieSceneSection* Sec : CutTrack->GetAllSections()) Sec->SetRange(NewRange);

for (const FMovieSceneBinding& B : MovieScene->GetBindings())                 // per-binding tracks
    for (UMovieSceneTrack* T : B.GetTracks())
        for (UMovieSceneSection* Sec : T->GetAllSections()) Sec->SetRange(NewRange);
```

Symmetrically: shrinking the playback range while leaving sections long
is also a no-op for MRQ (sections still play to their end). If you want
"playback range and sections always match," apply the same loop on every
range mutation. Real-world failure mode: a sequence's playback range and
its camera cut section's range drift over a series of edits and the next
render silently uses whichever happens to be shorter.

### 5.16 Sequencer: channel keys at the same time stack instead of replacing

`FMovieSceneDoubleChannel::AddLinearKey(FrameNumber, Value)` and the
equivalent on `FMovieSceneFloatChannel` append a key to the channel's
time-sorted array even if a key already exists at `FrameNumber`. The
MovieScene tracks both keys as separate entries; on interpolation, the
first-found one can shadow the just-added one — silently producing the
wrong animated value. Re-keying the same time looks like a successful
no-op.

Detect and update in place via the channel's `TMovieSceneChannelData`
wrapper:

```cpp
TMovieSceneChannelData<FMovieSceneDoubleValue> Data = Channel->GetData();
const int32 ExistingIdx = Data.FindKey(FrameNumber);     // exact-frame match
if (ExistingIdx != INDEX_NONE)
{
    TArrayView<FMovieSceneDoubleValue> Values = Data.GetValues();
    FMovieSceneDoubleValue Updated = Values[ExistingIdx];
    Updated.Value = NewValue;                            // preserves tangent / interp
    Values[ExistingIdx] = Updated;
}
else
{
    Channel->AddLinearKey(FrameNumber, NewValue);
}
```

`FindKey` has an optional `InTolerance` parameter (`FFrameNumber(0)` by
default) for inexact matches. The same pattern applies to
`FMovieSceneFloatChannel` / `FMovieSceneFloatValue`,
`FMovieSceneIntegerChannel`, and `FMovieSceneBoolChannel` — each
`Channel->GetData()` returns the matching `TMovieSceneChannelData<T>`
wrapper.

For 3D transform sections specifically, channel-proxy index order is
`[0-2] Translation X,Y,Z`, `[3-5] Rotation X,Y,Z` (where X=Roll, Y=Pitch,
Z=Yaw), `[6-8] Scale X,Y,Z`. All nine channels need the same
set-or-replace treatment when re-keying a transform — there's no
top-level helper that does all nine at once.

### 5.17 Sequencer: save the sequence package before MRQ re-reads it

Movie Render Queue's PIE executor re-loads the level sequence package
from disk when it spawns PIE. In-memory edits to the `MovieScene`
(playback range changes, transform keys, camera bindings, sub-sequences,
etc.) that haven't been flushed to disk via `UPackage::SavePackage` are
lost — the render uses the stale on-disk version even though
`LoadObject<ULevelSequence>(SeqPath)` returns the in-memory copy. The
result is a successful-looking render that doesn't reflect the most
recent edits.

This is a sequence-asset specialisation of the general "save before
reading from disk" rule (see §2.4) — MRQ counts as a from-disk reader
because the PIE world it spawns reloads the sequence asset fresh. Save
the sequence's outermost package before kicking the render:

```cpp
UPackage* SeqPkg = Seq->GetOutermost();
if (SeqPkg && SeqPkg->IsDirty())
{
    const FString Filename = FPackageName::LongPackageNameToFilename(
        SeqPkg->GetName(), FPackageName::GetAssetPackageExtension());
    FSavePackageArgs Args;
    Args.TopLevelFlags = RF_Public | RF_Standalone;
    Args.SaveFlags = SAVE_NoError;
    UPackage::SavePackage(SeqPkg, Seq, *Filename, Args);
}
```

Same hazard applies to any authoring → MRQ chain where the on-disk state
diverges from the in-memory state — camera cuts, sub-sequence bindings,
shot tracks, etc. Saving the level alone (`FEditorFileUtils::SaveCurrentLevel`)
does not cover this; `/Game/...` sequence assets live in their own
packages.


### 5.18 Character push launches light physics props

`CharacterMovementComponent` defaults are tuned for crates: `PushForceFactor = 750000` with
`bPushForceScaledToMass = false`. A 0.1-0.4 kg prop touched by the player receives that full
force, leaves the room in one frame and can tunnel through the floor - it reads as "the toy
disappeared when I touched it". On the character class defaults (`<CDO>.CharMoveComp`, flat
properties that `set_properties` does write):

| Property | Default | Light-prop value that worked |
|---|---|---|
| `bPushForceScaledToMass` | false | true |
| `pushForceFactor` | 750000 | ~1800 |
| `initialPushForceFactor` | 500 | ~160 |
| `maxTouchForce` | 250 | ~60 |
| `repulsionForce` | 2.5 | ~0.6 |

On the prop: simple convex collision (`StaticMeshTools.generate_convex_collisions`), and in
BeginPlay `SetCollisionProfileName "PhysicsActor"`, `SetMassOverrideInKg`, some linear and angular
damping, `SetUseCCD true`, then `SetSimulatePhysics true` (nested body settings cannot be set
through MCP properties). Set `canCharacterStepUpOn = ECB_No` on the prop's mesh component,
otherwise the pawn climbs onto small props and logs
`LogCharacterMovement: ... is stuck and failed to move`.

### 5.19 Look-at interaction when several targets are in range

Per-actor "player is near, show a prompt, enable input" breaks down as soon as two interactables
overlap: prompts draw on top of each other, and because key events consume input only the actor
that enabled input last receives the key. A pattern that holds up without a central manager:

- Each interactable computes a **focus score** every tick: inside its radius, take the dot of the
  camera forward vector with the direction to the part's bounds centre
  (`GetComponentBounds`), compare against a **per-instance** threshold, and normalise
  (`(dot - threshold) / (1 - threshold)`, or -1 when it does not qualify). Thresholds that worked:
  ~0.985 for stacked drawers 20 cm apart, ~0.95 for doors, ~0.93 for tall cupboards. One fixed
  cone either catches three drawers at once or misses low furniture from standing height.
- It publishes the score through a small function and yields if any other interactable scores
  higher (`GetAllActorsOfClass`, a dozen actors is cheap). Only the winner shows its prompt and
  calls `EnableInput`; everyone else hides and calls `DisableInput`.
- Proximity-only prompts (no aiming) yield whenever any aimed interactable qualifies at all.
- Keep class references one-way (A reads B's score, B never reads A's) to avoid circular
  Blueprint dependencies; let the less specific target do the yielding.

---

## 6. MCP transport requirements

### 6.1 Accept header on Streamable HTTP

Servers implementing MCP 2025-03-26 Streamable HTTP generally require both
content types in the Accept header:

```
Accept: application/json, text/event-stream
```

Omit it and the server returns `406 Not Acceptable`. Most MCP clients
(Claude Desktop, Cursor, VS Code's MCP UI, Epic's EDA panel) set this
automatically. Raw `curl` does not — pass
`-H 'Accept: application/json, text/event-stream'` when testing manually.

### 6.2 Image content blocks

MCP supports an `image` content block alongside `text`:

```json
{
  "content": [{
    "type": "image",
    "data": "<base64-encoded PNG>",
    "mimeType": "image/png"
  }]
}
```

The decoded bytes start with `\x89PNG\r\n\x1a\n`. Most MCP clients render
images inline in the chat UI. UE5 servers commonly use this for editor
viewport / PIE / depth captures.

### 6.3 Cancellation

MCP 2025-03-26 defines `notifications/cancelled` with a `requestId`
parameter. Whether it actually aborts an in-flight tool call is
server-dependent — synchronous servers can't interrupt themselves
mid-execution. Don't depend on cancellation working unless the server
documents support.

### 6.4 Sessions

Servers that implement the `Mcp-Session-Id` header expect clients to echo
it back on subsequent requests in the same session. The server mints a
fresh ID if the request arrives without one. Sessions usually expire on
idle timeout — re-send `initialize` if the server returns "unknown
session."

---

## 7. Python ↔ MCP data channel

UE's Python interpreter is reachable from most MCP servers via a console
command (`py <code>`) or a dedicated `execute_script` tool. Python is the
right hammer for:

- Bulk asset operations where the MCP surface lacks a vectorised tool
- Niagara parameter manipulation when the dynamic-input path is broken
- Sequencer batch edits
- Anywhere the agent needs N+1 operations that depend on each other and a
  round-trip per dependency would be expensive

**Critical limitation:** Python's `print()` and stdout go to the UE log,
not back to the MCP client. The agent that ran the script can't see what
it produced.

**Workaround — Actor Tags as a data channel:**

```python
import unreal
result = "...whatever the script produced..."
note = unreal.EditorLevelLibrary.spawn_actor_from_class(
    unreal.Note, unreal.Vector(0, 0, 9999)
)
# Keep tags short — UE truncates very long tag strings on save.
note.tags = [result[:200]]
```

Read back via MCP: query the Note actor's properties and inspect `tags`.
Delete the Note actor after. Spawn a fresh actor for each result — stale
actors return stale tags.

For larger payloads, write to a known file under `Saved/Logs/` or
`Saved/AgentScratch/` and read it back via the MCP server's file-read tool
(if available).

**Server-side Python execution alternative:** some MCP servers expose
`execute_script` (or similar) that captures the return value of a `run()`
function directly into the response. If your server has this, prefer it —
the data-channel workaround becomes unnecessary.

---

## 8. Patterns for MCP server authors targeting UE5

If you're building an MCP server against the UE5 editor, the following
patterns have proven valuable in practice. None are required by the MCP
spec — they're hard-won pragmatic recommendations.

### 8.1 Schema-in-error self-correction

When a tool call fails input validation, return the tool's full input JSON
Schema inline in the error text. The LLM caller reads the schema, fixes
the argument, and retries. Saves 3–5 round-trips per error compared to a
bare "Invalid argument" message.

```json
{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Validation failed: 'body_type' must be one of [Skinny, Athletic, Heavyset]. Full schema:\n\n{...inputSchema JSON...}"
  }]
}
```

### 8.2 Output schema as authority

Ship an `outputSchema` for every introspection / read-only tool. Fields in
the schema are guaranteed to appear; additional metadata fields may also
appear but aren't promised. Clients can parse responses against the schema
instead of guessing field names.

### 8.3 Continuation tokens for large responses

UE5 asset dumps can run hundreds of KB. MCP clients vary on how they
handle large `text` content. Pattern: cap response text at N bytes (64KB
is a reasonable default), stash the remainder under an opaque token,
return token + first chunk + `_remaining_chars` so the client knows
there's more. Expose a `continue_response(token, max_bytes)` tool to fetch
the next chunk.

### 8.4 `FScopedTransaction` for mutating tools

Wrap every UPROPERTY write, asset edit, level mutation, or Blueprint graph
change in `FScopedTransaction`. Ctrl+Z in the editor then reverts the
agent's change — critical for user trust. Losing the undo path is the
fastest way to make agents feel scary to work with.

### 8.5 Lazy tool registration for large surfaces

If your server exposes 200+ tools, the default `tools/list` response can
overwhelm small-context-window clients. Pattern: split the surface into
categories, default `tools/list` to a small set of meta-tools
(`list_categories`, `describe_category`, `load_category`) plus a few
always-on essentials, and load full categories on demand. Use
`notifications/tools/list_changed` to signal subscribers when the visible
surface changes.

### 8.6 Game-thread discipline

Slate operations, viewport rendering, asset operations, and Python
execution must all run on the game thread. MCP requests typically arrive
on a worker thread; dispatch the actual work back to the game thread via
`AsyncTask(ENamedThreads::GameThread, ...)` and signal completion via a
`TPromise` or similar. `check(IsInGameThread())` defensively before any
Slate / viewport call.

### 8.7 Recursion-cap the dumpers

Asset structures can contain cycles (Blueprint references, Material
Functions, Sound Cues with self-referential branches). Always cap
recursion depth (1024 is a safe default for graph walks). Always cap
output size before returning. Always opportunistically GC any per-tool
caches.

### 8.8 `.uplugin`'s `"Optional": true` describes a build-time relationship, not a runtime one — and doesn't survive contact with a data symbol

If your MCP-server plugin wraps a big optional engine subsystem (Niagara,
GameplayAbilities, MetaHuman, Mutable/CustomizableObject, MovieRenderPipeline)
so it builds clean whether or not that subsystem is enabled, the standard
recipe is: reference it in `.uplugin` with `"Optional": true`, gate the
`Build.cs` dependency behind a plugin-presence check, and `#if`-guard the
code that uses it. That recipe closes the build-time gap. It does **not**
by itself close the runtime gap.

**The trap:** if the optional plugin *was* present when you built, your
binary now hard-links against it — `"Optional": true` only told UBT "don't
fail the build if this is absent," it did not make the resulting `.dll`'s
imports soft. Drop that binary into a project where the optional plugin is
disabled and the OS loader fails to resolve those imports at mount time
(`GetLastError=126` on Windows), with no useful diagnostic pointing at
which optional dependency is the culprit.

The standard fix is `/DELAYLOAD` (MSVC) — defer resolving the DLL's
imports until first actual use, so a build that never calls into the
optional module never needs to load it. This works cleanly for **function
calls**. It does **not** work for direct references to an **exported data
symbol** — a global `UClass*`, a `static const FName`, an `extern` in the
optional module's headers — because `/DELAYLOAD` indirects function calls
through a thunk it generates, but a data-symbol reference compiles to a
direct memory address that has to be resolved at link time; there's no
thunk mechanism for it. If your `#if`-guarded code touches one of those
instead of exclusively calling functions, the linker fails outright
(MSVC LNK1194-class error) even with delay-loading correctly configured —
and the fix isn't "configure delay-loading harder," it's "don't reference
the data symbol at all outside the guard, or wrap access to it behind a
function the optional module itself exports."

**Practical rule:** before assuming `"Optional": true` + delay-load has
made a dependency fully soft, audit every symbol your `#if`-guarded code
touches from the optional module and confirm none of them are exported
globals/statics — function-only access is the only shape `/DELAYLOAD`
actually covers. And test runtime disable, not just build success —
"builds clean without the plugin present" and "loads clean in a project
where the plugin is present-but-disabled" are two different claims, and
only the second one is what an end user actually hits.

### 8.9 macOS: a too-minimal test project can hard-crash a `LoadingPhase: Default` editor plugin on `!AreShaderTypesInitialized()`

A freshly-built editor plugin, dropped into a deliberately minimal test
project (a handful of actors, few other plugins enabled) and launched, can
crash before the UI ever appears:

```
Assertion failed: !AreShaderTypesInitialized() [File:.../RenderCore/Private/Shader.cpp]
Shader type was loaded too late, use ELoadingPhase::PostConfigInit on your
module to cause it to load earlier. This shader will not be compiled or function.
```

Stack: a shader type's static registration, triggered by `dlopen()` inside
`FModuleManager::InternalLoadLibrary` as your plugin's module loads. **The
specific shader type that faults is not stable across runs** — different
launches of the identical binary can fault on different shader classes
from different engine modules. That instability is the tell: this is a
**load-order race**, not a bad dependency in your plugin.

**The mechanism:** `AreShaderTypesInitialized()` locks at some point during
normal engine startup — any *new* shader-type static registration after
that point is fatal. Renderer/RenderCore dylibs are core engine modules
that are supposed to already be loaded by then. But macOS dylib loading is
lazy — dyld resolves and initializes a library on its first real touch,
not eagerly at process start. In a minimal project with little else
forcing those dylibs open early, a plugin module loading at `Default`
phase can be the *first* thing that ever triggers `dlopen()` on one of
them — and whichever shader-owning dylib that happens to pull in registers
its shader types right then, after the lock, and asserts. Which dylib it
is (hence which shader type faults) depends on link order and symbol
resolution timing.

**What does NOT fix it** (both testable via `.uplugin`-only edits — no
rebuild needed, `LoadingPhase` is read from the manifest at mount time):
- `LoadingPhase: "PostConfigInit"` (the phase the assert message itself
  recommends) moves the crash **earlier** instead of fixing it if your
  module's `StartupModule()` touches the UObject/package system — at
  `PostConfigInit` that system isn't up yet, and you get a *different*
  fatal error (`Object is not packaged`) instead.
- `LoadingPhase: "PreDefault"` (one phase earlier than `Default`) lands
  back in the identical shader-type race. If a safe window exists between
  "UObject system ready" and "shader types locked," it isn't reachable
  through a simple `ELoadingPhase` value.

**What did fix it:** use a normal-structured test project instead of the
leanest possible one — real content, several other plugins already
enabled. That's enough to force the Renderer/RenderCore dylibs open
through the engine's own normal startup path before your plugin's
`Default`-phase module load ever gets a turn, so the race never triggers.
Counterintuitively, the "more realistic" project is the *safer* smoke test
here, not the minimal one — don't use a deliberately empty project to
smoke-test a macOS editor plugin; the minimalism itself is what exposes
this class of crash.

**Related gotcha hit while chasing this:** a command-line `-ini:` override
targeting a `UDeveloperSettings` class with `config=EditorPerProjectUserSettings`
can be silently ignored — the editor boots fine and the override simply
doesn't apply, with no error. If a runtime setting you overrode via `-ini:`
doesn't seem to have taken effect, verify the *actual* value from a log
line or a live read-back before concluding the editor failed to start —
it may have started completely normally on the un-overridden default.

---

## 9. Patterns for MCP clients (agents)

### 9.1 Cache `tools/list` once per session

Tool surfaces are stable within a session. Cache the response on connect.
Polling mid-session wastes round-trips and can confuse cancellation logic.

### 9.2 Parse against `outputSchema` when present

If the server publishes output schemas, validate against them instead of
guessing field names. Saves debugging cycles when an agent assumes a field
exists that doesn't, or doesn't notice a new field appearing in a later
version.

### 9.3 Always verify writes

UE5 has too many silent-fail edges to trust a successful response. The
full pattern:

1. Issue the write.
2. Issue a read of the same state.
3. Compare to what you asked for.
4. If they differ, re-examine (snake_case? wrong enum form? async-deferred?).

Verify-after-mutate is the difference between an agent that works 80% of
the time and one that works 99%.

### 9.4 Treat `isError: true` as load-bearing

The MCP spec specifies tool errors return `isError: true` with the error
text in `content[0].text`. Servers may also return JSON-RPC transport-level
errors with the `error` field at the top level. Both need handling; both
contain debugging info worth reading.

### 9.5 Don't chain a read after a write without saving

If a tool dumps an asset from disk, the dump reflects the on-disk state.
If you just mutated the asset in memory and haven't saved, the dump shows
the pre-mutation state. Save explicitly between mutate and dump if you
need the current state.

---

## 10. UE 5.7 vs 5.8 — engine-level differences

These affect any agent driving UE5 across engine versions, regardless of
MCP layer.

### 10.1 MovieRenderGraph is 5.8-only

`UMovieGraphConfig`, `UMovieGraphPipeline`, and graph-based rendering
composition land in 5.8. UE 5.7 has MovieRenderQueue
(`UMoviePipelineQueueEngineSubsystem`) but no graph composition layer.

### 10.2 `FJsonObject::Values` key type change

`FJsonObject::Values` is `TMap<FString, ...>` on 5.7 and
`TMap<UE::FSharedString, ...>` on 5.8. Affects native C++ iteration;
doesn't affect Python or JSON-over-the-wire usage.

### 10.3 PathTracer setting surface

Several PathTracer settings migrated from CVar-only to UPROPERTY on
`UPostProcessVolume` in 5.8. An agent that sets them via console commands
works on both engines; one that sets them via reflection on the
post-process volume needs 5.8.

### 10.4 Epic's official `ModelContextProtocol` plugin is 5.8-only

Epic's MCP plugin ships in UE 5.8 (experimental). UE 5.7 users running an
agent against the editor need a third-party MCP server.

### 10.5 Niagara editor module split

UE 5.8 reorganised some Niagara editor APIs into a `NiagaraStackEditor`
module. Tools that introspect Niagara stack issues need to depend on the
right module on each engine version.

---

## 11. Asset structure quick reference

What gets serialized when common UE5 assets are dumped to JSON. Useful for
parsing responses regardless of which server produced them. This isn't an
exhaustive schema — see Epic's UE docs for the authoritative structure.

### Blueprint

- `UbergraphPages` — event graphs plus auto-generated wrappers
- `FunctionGraphs` — user-defined functions
- `DelegateSignatureGraphs` — dispatcher signatures
- `MacroGraphs` — user macros (if any)
- `Variables` — name, type, default value, `CategoryName`, `RepNotifyFunc`
- `Components` — SimpleConstructionScript root + AddedComponents
- `ParentClass`, implemented interfaces, compile state

### Niagara System

- `SystemSpawnScript` / `SystemUpdateScript` — system-level VM scripts
- `EmitterHandles` — per-emitter wrapper (Enabled, LocalSpace, EmitterMode)
- `UserParameters` — parameters exposed to the component for runtime tuning
- Per-emitter: `SpawnScript` / `UpdateScript` / `RenderScript` stacks,
  modules per stack, renderer settings

### Material

- `Expressions` — `UMaterialExpression*` nodes (one per node in the graph)
- Connections — input pin → output pin pairs
- `ScalarParameterValues`, `VectorParameterValues`, `TextureParameterValues`
- `ShadingModel`, `BlendMode`, `MaterialDomain`

### Level

- `Actors` — array of actor entries with name, class, transform, components
- `WorldSettings` — game mode, level scripts, navmesh settings
- `Streaming` — sublevels and their state (loaded / visible / unloaded)

### Sequencer (`ULevelSequence`)

- `MovieScene` — root scene
- Tracks — per binding: TransformTrack, FloatTrack, EventTrack, etc.
- Sections per track — start/end frame, evaluation type, easing

### Widget Blueprint

- `WidgetTree` — hierarchy of widgets (root, panels, leaf widgets)
- Per-widget: `Slot` properties (depend on parent panel type),
  variable-or-not flag, accessibility text
- `BindingClass` — MVVM viewmodel class (if any)

---

## 12. Anti-patterns

### 12.1 Don't pass actor labels as identifiers

Two actors can share a label. The label is user-editable. Use the full
path.

### 12.2 Don't poll `tools/list` mid-session

Tool surfaces are stable per session. Cache once on connect.

### 12.3 Don't assume tool surface parity across servers

Two MCP servers against UE5 will have different tool catalogues, different
parameter names for similar concepts, and different output shapes. Always
read `tools/list` to discover what's actually exposed before assuming a
tool exists.

### 12.4 Don't ignore `isError: true`

The error message is usually load-bearing. Schema-in-error servers put the
input schema right in there.

### 12.5 Don't chain reads after writes without a save (or explicit in-memory mode)

Most introspection tools serialize from disk. Mutation without save is
invisible to those tools.

### 12.6 Don't assume async operations completed

Texture compile, Niagara compile, shader compile, asset save, package
compile — all async. Poll completion or wait on the relevant delegate
before continuing.

### 12.7 Don't delete a referenced asset

Check `get_asset_references` (or equivalent) first. Deleting referenced
meshes/materials crashes the editor with `RegisteredElementType`.

### 12.8 Don't connect scalar nodes to Audio-typed pins in MetaSound

Runtime crash. Use audio buffer sources (Oscillators, Noise) into Audio
pins. Scalar math (Multiply, Add) on the audio path goes through Audio
variants of those nodes, not the float variants.

### 12.9 Don't destructively rewrite committed config to toggle sim vs device

A script that flips `.ini` settings in place to switch a UE5 visionOS/AVP project between the
Simulator and a real device makes the repo stateful — easy to cook the wrong target, dirties
tracked files, and invalidates caches for a bigger recompile than necessary. Carry the delta in
the **build command** instead: build arch (`-clientarchitecture=iossimulator` for sim, arm64 for
device), code-signing team, install method (`simctl` vs `devicectl`), and a METAL_SIM shader cook
flag (`-ini:...:bEnableSimulatorSupport=True`, sim only) as `-ini:` overrides passed to
`BuildCookRun`. The committed render config never changes. Reference implementation
(`ue-avp-build.sh sim|device`) + full rationale: AgileLens internal KB,
`intelligence/techniques/ue-visionos-sim-device-build-flow.md` (ask the user for a copy if you
don't have KB access).

---

## 13. Reading list

- [MCP specification](https://modelcontextprotocol.io) — protocol-level reference
- [Unreal Engine Python API reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/) — for `unreal.*` module surface
- [Unreal Engine 5 Editor scripting](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python) — Epic's Python guide
- [Niagara documentation](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine) — for Niagara-specific module / parameter concepts
- [MetaSound documentation](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasounds-in-unreal-engine) — for audio graph semantics

For server-specific tool catalogues, query the server with `tools/list`.

Every entry: symptom in the heading, condition that triggers it, workaround if there is one.

The current editor version you are using may be newer than the versions associated with these
symptoms. Use the tools as you would normally, and only consult this document and apply workarounds
if you see suspicious results and suspect that these gotchas may be involved.

---

## Contents

- [Arguments, names and paths](#arguments-names-and-paths)
- [EditorAppToolset](#editorapptoolset)
- [ObjectTools](#objecttools)
- [ProgrammaticToolset](#programmatictoolset)
- [SequencerTools](#sequencertools)
- [PCGToolset](#pcgtoolset)
- [MaterialTools](#materialtools)
- [Animation and meshes](#animation-and-meshes)
- [PhysicsAssetToolset](#physicsassettoolset)
- [Plugins, search and odds](#plugins-search-and-odds)
- [BlueprintTools and the graph DSL](#blueprinttools-and-the-graph-dsl)
- [StaticMeshTools, UMG, saving](#staticmeshtools-umg-saving)
- [Additional EditorAppToolset / ObjectTools / ProgrammaticToolset notes (Sept 2026 build)](#additional-editorapptoolset--objecttools--programmatictoolset-notes-sept-2026-build)

---

## Arguments, names and paths

Naming across this API is not consistent, and the inconsistencies are not documented. This
section is about the tools' own surface - argument names, return shapes, truncation - rather than
about UE's object-path conventions in general, which
[the field guide (§4)](./UE-field-guide.md) already covers well.

### Argument names diverge between toolsets, and inside one toolset

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Caught in practice, all of them by having the call fail:

- `AssetTools.delete` wants `path`. Not `asset_path`.
- `SkeletalMeshTools.set_socket_transform` wants `transform`, while `ActorTools` uses `xform`
  for the same idea.
- Inside `MaterialInstanceTools`: `list_parameters` takes `material`, and
  `get_texture_parameter` takes `instance` plus `name`. Same toolset, same kind of object, two
  different words for it.
- `AssetTools.list_folders` takes `root_path` - and its own docstring says otherwise.
- `save_assets` takes plain path strings without the `.Asset` suffix, not `{refPath}` objects,
  and there is no `assets` argument at all.

**Workaround.** Let the validation error tell you the schema - that is the intended way to
discover it. But do that outside a batch script: in a script a wrong argument name rolls back
everything the script has already done, so the cheap self-correction becomes an expensive one.

### `find_actors` truncates at 20 without saying so

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Ask broadly and you get twenty results and no indication that there were more. `find_assets`
appears to do the same on wide queries.

**Workaround.** Treat exactly twenty results the way you would treat zero: as a number that means
"ask again, differently".

### Actor tools only see loaded World Partition cells

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

Everything that enumerates actors sees the streamed-in part of the world only. On a partitioned
map this is a moving target - the same query gives different answers depending on where the
editor camera was.

**Workaround.** Load the region you intend to query first, and never conclude "the actor does not
exist" from an actor query alone.

### Verify an asset path before a script uses it

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

A wrong `refPath` is not the harmless "object not found" it looks like. It is the first step of
the chain that kills the editor - see
[the ProgrammaticToolset entry](#a-script-error-kills-the-editor-outright-when-the-edited-asset-is-open-in-its-own-window).

The log names it clearly once you know what to look for: `Failed to find object` → `is not valid
Object for property` → `Undo Execute tool script` → `appError`.

**Workaround.** `find_assets` first. Every time, including the paths you are sure about - the one
that got me was a typo in a path I had typed twenty times.

Subfolders are their own trap: plugin content does not always live where its category suggests,
and the file you want may sit one level up from the folder named after its feature.

---

## EditorAppToolset

### `CaptureViewport` with `captureTransform` requires explicit arguments

**Kind:** note · **Hit on:** 5.8.2 · **Workaround:** yes. Also see `CaptureEditorImage` for another method.

The original entry (hit on 5.8.0) said `CaptureViewport` ignored `captureTransform` entirely, but it turns out
the tool call might just need explicit arguments.

**In 5.8.2**, explicit `captureTransform`, `annotations:null`, `bShowUI:false` returns
the requested camera and a matching image. (This may also work on 5.8.0 and the agent who wrote the note for
5.8.0 might have just not realized it should have tried these explicit arguments, though this is unverified; check this
if you're on 5.8.0.)

A workaround that doesn't rely on the toolset (which works for headless setups): enable the
PixelStreaming plugin in the project, open the PixelStreaming client page in a browser
(can be a headless browser such as Playwright; the page is on port 8080 on Linux and port 80 elsewhere.)
Use scripting to send events to navigate in the viewport if needed, and take browser screenshots.

Should only ask a human for a screenshot as last resort.

### Optional arguments that are not optional

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

`CaptureViewport` marks `captureTransform` and `annotations` as `TOptional`. Omit either and
the call fails with `input param X needs a default value`. Both are mandatory in practice.

`StartPIE` is the same shape: it wants the full `options` block - `bSimulate`, `playMode`,
`warmupSeconds` - and `playMode` is required even when `bSimulate` already says what you mean.

On 5.8.2, explicit `annotations:null` successfully disables annotations. The older 5.8.0
workaround was a block of zeros plus `classFilter: {"refPath": ""}`.

**Workaround.** Treat `TOptional` in this API as documentation of intent, not of behaviour.
Pass explicit values or a tested null.

### `CaptureViewport` returns ~2.8 MB and the payload lands in a file

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

The base64 image does not come back inline - it spills into a `tool-results` file, and the
client has to go read it. Worth knowing before you plan a loop around it.

The structure is `returnValue.image.data`, not `returnValue.data`. Sibling tools differ here:
the Slate inspector's screenshot puts its payload directly at `returnValue.data`. Same idea,
different shape, no warning.

**Workaround.** Parse the file, decode `returnValue.image.data`, write a `.png`, read that.

### `GetCameraTransform` only tells the truth while the camera is locked

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

Without `set_camera_lock(true)` it reports the free viewport, not the sequence camera - and
because the viewport eases into position, two reads a second apart give different numbers.
The symptom reads as "my keys are in the wrong place", which sends you to fix the keys.

`close_sequence` and `open_sequence` both drop the lock.

**Workaround.** To verify keys by pose: lock → `set_playhead_frame` → `force_evaluate` →
`GetCameraTransform`.

### There is no console-command tool

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`EditorAppToolset` can search console variables. It cannot set one, and there is no
`ExecuteConsoleCommand` anywhere in the surface. For a system built to automate the editor,
the absence is louder than most bugs on this page.

**Workaround.** Type into the editor's status-bar command box through the Slate inspector:
`Type {ref, text, submit: true}`. Find the ref with `Observe("")` then `Snapshot` on the status
bar menu - it is the textbox next to "Cmd". It works while PIE is running, too.

Console variables set this way outside PIE persist into the next PIE session, which makes
A/B tests of renderer settings possible (`r.AntiAliasingMethod`, `r.EarlyZPass`); read the value
back with `SearchCVars` and restore it afterwards. `WorldSettings.timeDilation` cannot be
written through `set_properties`.

### Every `ProfileGPU` leaves a GPU Visualizer window open, and the next profile pays for it

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

The window is never closed. They stack up, they redraw every frame, and the editor starts
crawling - which reads as "profiling made my editor slow" rather than "I have six windows
open". Worse, an unclosed visualizer adds roughly 2000 draw calls to the frame you profile
next, so the numbers you are collecting are wrong in a way that looks plausible.

**Workaround.** Close it through the Slate inspector - `Windows {action: "close", index}` -
before every subsequent measurement.

### `stat unit` typed from the status bar does not draw over PIE

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

The command goes through, the overlay never appears, and the screenshot comes back empty.

**Workaround.** Use `ProfileGPU` instead: it writes a full pass breakdown into the Output Log,
which you can read with the log toolset and a pattern filter. Slower to read, but it is text,
and text is what an agent can actually use.

---

## ObjectTools

### A failed `set_properties` still wipes the properties it touched

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

I asked for `{skeleton, sampleData}` on a BlendSpace. `skeleton` is not editable, so the call
failed - and took `sampleData` with it. The asset came back with `skeleton: None` and
`sampleData: []`. Both fields I had asked about were now empty.

So the call is not atomic and it does not roll back. A rejected write is not a no-op; it is a
partial write you did not ask for.

**Workaround.** Probe unknown properties on a duplicate, never on the asset you care about.
If the duplicate comes back gutted, you have lost nothing.

### `set_properties` does not dirty the package - the edit is lost on the next reload

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

An `InstancedStaticMeshComponent` whose `perInstanceSMData` was rewritten through
`set_properties` read back correctly, the status bar never counted its actor as unsaved, "save
all" had nothing to save, and after an editor crash the level came back with the OLD instance
list. Actors changed through `set_actor_transform` (which goes through a transaction) and newly
spawned actors were fine. So a `set_properties`-only edit lives in memory until something else
dirties the package.

**Workaround.** After property edits on an actor or its components, write its transform back
unchanged with `ActorTools.set_actor_transform` - that marks the package dirty - then save. For
assets (materials, meshes, blueprints) `AssetTools.save_assets` saves regardless of the dirty
flag, so only level actors are affected. Verify with the status-bar counter going up before the
save and files under `Content/__ExternalActors__` getting newer after it.

### Setting `staticMesh` on a component clears its `overrideMaterials`

**Kind:** note · **Hit on:** 5.8.2 · **Workaround:** yes

Swapping the mesh of a `StaticMeshComponent` through `set_properties` resets `overrideMaterials`
to empty, so the actor shows the mesh's own slot materials (for an OBJ import that is the grey
default). Set `staticMesh` and `overrideMaterials` together, or reapply the override after the swap
- and look at it: a terrain that turns grey after a mesh reimport is this.

### On a Blueprint actor's component, only the FIRST member of a vector or rotator is written

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

`set_properties` on a component of a placed Blueprint actor with
`{"relativeScale3D": {"x": 0.9, "y": 0.9, "z": 0.9}}` reads back `(0.9, <old>, <old>)`.
`relativeLocation` keeps only `x`, `relativeRotation` keeps only `pitch`. No error, and the
returned value looks plausible unless you compare all three members. One member per call does
not help either. The visible results were uniform scales that stretched meshes along one axis,
and facing yaws that silently stayed at the class default. `StaticMeshActor` components, and
actor-level transforms, were not affected.

**Workaround.** Put the transform on the actor (`ActorTools.set_actor_transform`) whenever the
design allows. For a component offset that has to exist, use editor Python:
`comp.set_relative_location(...)`, `set_relative_rotation(...)`, `set_relative_scale3d(...)`
(see headless-autonomy.md §7b). **Read every struct back after writing it** and compare all members.

### A collision profile name does not change collision; nested `bodyInstance` fields are ignored

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

`{"bodyInstance": {"collisionProfileName": "NoCollision"}}` stores the name and nothing else:
`collisionEnabled` still reads `QueryAndPhysics`, traces still hit the mesh and pawns still
collide with it. Other nested fields (`collisionEnabled`, `bSimulatePhysics`, damping) are not
applied at all. A surface meant to be walked through stays solid, and "physics" props never move.

**Workaround.** Editor Python on the placed component:
`comp.set_collision_profile_name("NoCollision")` and
`comp.set_collision_enabled(unreal.CollisionEnabled.NO_COLLISION)`. For Blueprint classes set it
at runtime in BeginPlay (`Collision|SetActorEnableCollision`, `Collision|SetCollisionProfileName`,
`Physics|SetSimulatePhysics`). For imported meshes that must never block,
`StaticMeshTools.remove_collisions` on the asset removes the auto-generated shape. Verify with
`SceneTools.trace_world` through the object.

### `set_properties` never fires `PostEditChangeProperty`

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes (manual)

The value changes and the asset goes dirty, so every check you can make through MCP says the
edit landed. What does not happen is the notification: systems that rebuild on
`PostEditChangeProperty` - preview meshes, generated thumbnails, anything listening on a
change delegate - never hear about it and keep serving stale state.

This is the known UE rule that a direct property write must be followed by an explicit
notify. The difference here is that you cannot do the explicit part: the toolset gives you no
way to construct the event.

**Workaround.** Touch the field once in the Details panel, or trigger the owning system's
rebuild by hand. If a commandlet consumes the asset afterwards, save it to disk first - a
separate process does not see in-memory edits and does not inherit console variables.

### An empty result is indistinguishable from "wrong context"

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`[]` and `""` mean both "there is nothing here" and "the object is not loaded, or you are
asking in the wrong context". The API does not separate them, so an agent reads a clean empty
answer and concludes the collection is empty.

**Workaround.** Verify emptiness a second way before believing it. This is the single
cheapest habit on this page and the one that saves the most time.

### Delta serialization swallows a child CDO override equal to the parent value

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

Write a value onto a child Blueprint's CDO that happens to equal the parent's, and the call
reports success - but no delta is stored, because there is no difference to store. Change the
parent later, or update the plugin the parent lives in, and the child silently follows the new
parent value. The override you thought you set was never there.

The mirror image bites too: per-instance overrides on placed actors shadow CDO edits entirely.
Instances that were placed months ago keep their captured values and never see the new default.

**Workaround.** Assign the override while the parent holds a different value, and re-read after
any parent change. For stale placed actors, `reset_properties` on the single property returns
that instance to inheritance without touching the rest.

### Not every UPROPERTY is reachable through reflection

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes (manual)

`bEnableStreaming` on World Partition, for one: visible in the UI, not readable through
reflection. Absence from the reflection surface does not mean absence from the object.

**Workaround.** Change it in the editor UI and move on. Not everything is worth automating.

---

## ProgrammaticToolset

### A script error kills the editor outright when the edited asset is open in its own window

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

A script fails mid-run. The registry rolls the transaction back. The rollback tries to
rename a preview object on top of an existing one, and the editor dies:

```
Fatal error: Renaming an object (MaterialEditorOnlyData /Engine/Transient.PreviewMaterial_88:...)
on top of an existing object (...M_<YourMaterial>EditorOnlyData) is not allowed
```

No dialog, no prompt to save. Everything unsaved is gone.

What made it fire in my case was a typo in an asset path - nothing more dramatic than that.
The chain reads clearly in the log once you know it:

```
LogUObjectGlobals: Warning: Failed to find object '...'
→ is not valid Object for property
→ LogEditorTransaction: Undo Execute tool script
→ appError
```

**Workaround.** Close the asset's own editor window before running a script that mutates it.
And resolve every asset path with `find_assets` *before* the script uses it - a bad refPath
is not a harmless "object not found", it is the entrance to this crash.

**Why it matters.** The cost of a script error is not the error. It is everything the editor
was holding.

### An error inside a script rolls back every mutation the script already made

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

The script is one transaction. A call that succeeded three steps ago is undone when a later
call fails on a wrong argument name. I watched `add_socket` complete and then physically
disappear because the next call used an argument that does not exist.

**Workaround.** Validate argument names before batching. A single wrong name costs the whole
run, not just its own step - and if the asset is open in its editor, see the entry above.

### Subobject paths containing a space work in direct calls and break inside scripts

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

A component named with a space in it - `My Component` - resolves fine through a direct
`call_tool`. Put the same path inside a batch script and `get_properties` returns `None` or
throws.

**Workaround.** Handle those objects with direct calls and keep them out of batches. Or rename
the component, if it is yours.

### The dictionaries are `_StrictDict`: `.get(key, default)` raises

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Script-side dictionaries look like Python dicts until you call `.get()` with a fallback, which
raises `TypeError: does not support a default value`. The defensive pattern everyone writes by
reflex is the one that breaks - and it breaks the whole script, undoing everything before it.

**Workaround.** `if key in d: d[key]`. Never `.get`.

### `open()` inside a script is read-only, and the mode argument is mandatory

**Kind:** limitation · **Hit on:** 5.8.2 · **Workaround:** yes

`open(path)` raises `missing 1 required positional argument: 'mode'`, and `open(path, "w")`
raises `Mode 'w' is not permitted. Allowed modes: ['r', 'rb', 'rt']`. `exec` is not defined.
Reading large inputs (instance lists, placement tables) with `open(path, "r")` works and keeps
the script small.

**Workaround.** Return data in the result dict and write files from the shell that called the
tool.

### `get_properties` with a property the node's class does not have kills the entire script

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Ask for `MaterialFunction` on a node that is not a `MaterialFunctionCall` and the whole
`execute_tool_script` dies. `try/except` does not save you - the error comes out of
`execute_tool`, not out of Python.

**Workaround.** Request properties strictly by node type: `MaterialFunction` only on
`MaterialFunctionCall`, `ParameterName` only on `*Parameter` nodes, `Name` only on
`NamedRerouteDeclaration`, `R` only on `Constant`.

---

## SequencerTools

### `create_level_sequence` silently destroys an existing asset at the same path

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Point it at a package path that already holds a Level Sequence and it does not fail, warn,
or ask. It replaces. The old sequence - tracks, keys, bindings - is gone.

**Workaround.** `find_assets` on the target path before every create. Treat the call as
destructive, because it is.

### A new property-track section is created with a `0..0` range, so the keys never evaluate

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

`add_section` gives you a section whose range is zero-length. Keys written into it are accepted,
`get_keys` lists them all back, and the property holds its original value on every frame except
frame 0.

The symptom is "the animation on this property does nothing", which sends you looking at the
keys - and the keys are fine.

**Workaround.** `set_section_range(0, end)` immediately after every `add_section`. This is the
narrow, creation-time case of the wider rule that section ranges are independent of the
sequence playback range - see
[UE-field-guide.md §5.15](UE-field-guide.md) for the general version.

### Property tracks silently ignore nested struct fields

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

`set_property_name_and_path` with a path into a struct - `Filmback.SensorWidth` - creates the
track, accepts the keys, and never applies the value. No error anywhere in the chain.

Flat properties work (`CurrentFocalLength`, `bConstrainAspectRatio`), and so do paths the engine
itself registers (`FocusSettings.ManualFocusDistance`). Arbitrary struct paths do not.

**Workaround.** Set whole structs through `set_properties` on the spawnable instance instead of
animating them. If you need the struct field to change over time, find the engine-registered
path for it or animate something else.

### `create_camera` already made the property tracks, and a second one averages the values

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

`create_camera` quietly creates the standard property tracks on the child CameraComponent
binding - Current Focal Length, Manual Focus Distance, Current Aperture - with empty sections.
Add your own track for the same property and the engine blends two sources: the value you get
is the arithmetic mean of your keys and the original.

I asked for a focus distance of 131 cm and got 50065. That number makes no sense until you know
there are two tracks.

**Workaround.** `get_tracks_on_binding` plus `get_track_display_name` to find what is already
there, write into the existing track, and `remove_track` on any duplicate you created.

### Unbounded sections are normal, and asking about their range throws

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

The transform section from `create_camera` and every spawn section are created without bounds.
That is correct - you can write keys outside a range that does not exist. But
`get_section_range` and `get_section_properties` on such a section raise "Section does not have
a start frame", and inside a batch script that single raise rolls back everything the script has
done.

**Workaround.** Do not call range queries on sections you did not explicitly bound. `try` does
not help here - the error comes from the tool layer, not from your script.

### Changing display rate renumbers every existing key

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

Switch a sequence from 30 to 120 fps and frame 60 becomes frame 240. Absolute time is preserved,
which is the point - but every frame number you wrote down is now wrong, and code that reasons
about "the key at frame 60" quietly targets a quarter of the way through.

Related: the Camera Cuts section is half-open. Its end has to sit at `last_key + 1`, or the final
frame is never shown through the camera.

**Workaround.** After a rate change, stop trusting your notes: read the channel with `get_keys`,
clear it, and write again from the new numbers.

---

## PCGToolset

### ☠️ `GetNodeDataView` hangs the editor, and graph size is what decides it

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** none

The tool turns on graph-level data inspection. From then on every generation retains the data
of every node - hundreds of thousands of points across dozens of nodes, gigabytes of it - and
the editor runs out of memory. Two calls in parallel freeze it outright.

I first wrote this down as "only use it on a small test volume". That was wrong. On a graph of
about seventy nodes, a second call right after a generation froze the editor hard enough to
need a kill - **on a 40 × 40 m volume**. The volume is not what costs you. The graph is.

Inspection does not turn back off. Only a restart clears it.

**Workaround.** Do not use it on a production graph at all. Debug through the PCG log with a
pattern filter, and with your eyes.

### The toolset is not called what the catalogue says

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Its full name is `PCGToolset.PCGToolset`, and the spatial one is `PCGToolset.PCGSpatialToolset`.
Call either by the short name and you get "Toolset not found", which reads like the plugin is
missing rather than like a naming quirk.

### `ListNativeNodes` hides plugin nodes, `bCommonOnly: false` or not

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

The flag defaults to true, so the first listing is short. Setting it false makes the list longer -
and still without any node a plugin contributed. Those nodes exist, they are just not
discoverable through the tool that exists to discover nodes.

**Workaround.** Find their classes by reflection (`search_subclasses` on the PCG settings base),
and build with the plugin's own primitive subgraphs through `AddSubgraphNode` rather than with
native nodes.

### Adding a native node is `AddNode`, and all six arguments are required

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

There is no `AddNativeNode` - that name returns "Unknown tool". The real one is `AddNode`, and it
wants `graph`, `nativeNodeType`, `nodeName`, `jsonParams`, `nodeTitle`, `nodeComment`, every one
of them, every time. `nativeNodeType` is the display string from `ListNativeNodes`, spaces
included: `"Spatial Noise"`, `"Density Filter"`, `"Get Spline Data"`.

### `UpdateNode` demands `nodeTitle` even when you are only changing parameters

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Leave it out and the call fails; pass `""` and the existing title is kept. So the argument is
required in order to be ignored.

Inside a batch script this is not a small annoyance - the failure rolls back every mutation the
script has already made.

### `subGraphForNode` needs the object path with the name twice

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`/Plugin/Primitives/Filter/Filter_Foo` is what `find_assets` gives you, and
`AddSubgraphNode` rejects it: "is not a valid object path for property 'SubGraphForNode'". It
wants `/Plugin/Primitives/Filter/Filter_Foo.Filter_Foo`.

This is the standard UE object-path convention rather than a bug, but it catches everyone,
because the tool that hands you the path hands you the form the next tool refuses.

### `ConnectNodePins` silently inserts conversion nodes

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

Connect two nodes whose data types do not line up and the tool inserts converters between them -
`FilterDataByType` and friends - without telling you. Your graph now has nodes you did not add,
and there is no direct edge between the two nodes you "connected", so a later
`DisconnectNodePins` fails.

The return value is the list of inserted nodes; an empty array means nothing was inserted. That
is the only notice you get.

**Workaround.** Before rewiring anything, read the actual edges from `GetGraphStructure` instead
of assuming your own connection exists.

### `paramOverrides` only holds non-default values, and that is success, not loss

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

Set a parameter to a value equal to its default and its key disappears from `paramOverrides`.
Nothing was lost - there is simply no override to record.

The trap is on the read side: a node with `mode: Perlin2D` shows no `mode` key at all, because
Perlin2D is the default. "The parameter is not set" and "the parameter is set to its default" look
identical in a dump.

**Workaround.** Read the schema with `GetNativeNodeSchema` when you need to know what a missing
key means. And guard every lookup - the dictionaries here raise on a missing key rather than
returning a default, and inside a script that raise costs you the whole run.

### "Failed to call Execute" means busy, not broken

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

`ExecuteGraphInstance` refuses while the previous generation is still running, and the message
does not say so. Same message when the editor is still warming up after launch.

I originally wrote this down as an idle timeout in the client and concluded that generation had
to be triggered by hand. That was wrong too: twenty-five consecutive runs on a full-map graph
went through the tool without a single timeout. The condition is simply a pause of around fifty
seconds between runs. The fully autonomous loop - edit the graph, execute, look at the result -
does work.

**Workaround.** Wait and retry rather than debugging the graph.

---

## MaterialTools

### `get_expression_inputs` reports the wrong `output_name` on multi-output nodes

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

When the source node has several outputs - a break-attributes node, for instance - every
connection comes back naming the same output. In my case all of them claimed to come from
"Specular". The `input_name` side is correct; it is only the output that lies.

Which means you cannot reconstruct a graph's topology from this call alone, and if you do, the
result looks coherent and is wrong.

**Workaround.** Cross-check with the node's real output names before believing any edge that
starts at a multi-output node.

### `layout_expressions` re-lays out the entire graph, not the part you touched

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

There is no "layout selection". Call it on a graph somebody else authored and every node
moves - the grouping, the comment boxes, the deliberate spacing that made the graph readable
are all gone, and there is no undo that brings the arrangement back.

**Workaround.** Never call it on a graph you did not author. Place new nodes with explicit
`x` / `y` in `add_expression`; find the free area first by taking the maximum
`MaterialExpressionEditorY` across existing nodes.

The neighbouring `delete_unused_expressions` deserves the same caution. It removes everything
not connected to a material output - which includes the author's legacy nodes, parked
deliberately and still wanted. It reads like tidying. It is data loss.

### A named reroute cannot be traced back to its declaration

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`NamedRerouteUsage` exposes neither `Declaration` nor `DeclarationGuid` to reflection - listing
its properties gives you editor coordinates and a description, nothing else. So when you walk
somebody else's material graph and hit a named reroute, the chain simply ends there.

**Workaround.** Infer the name from context. There is no programmatic route, so plan graph
traversal knowing it has holes.

---

## Animation and meshes

### An AnimBlueprint or BlendSpace cannot be pointed at a different skeleton

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes (manual)

`BlendSpace.skeleton` is read-only to reflection. On an AnimBlueprint it is worse: asking for the
asset's properties gives you the CDO of the AnimInstance, so `TargetSkeleton` is not merely
unwritable, it is not visible. And `BlueprintTools.create` goes through the plain Blueprint
factory, which has no notion of a skeleton at all.

`AssetTools.duplicate` copies everything correctly, including skeleton and samples - but a
duplicate points at the same skeleton it came from, which is the one thing you were trying to
change.

**Workaround.** Create the asset by hand in the editor, on the right skeleton. That single act is
all that needs a human.

### What does work on those assets, once they exist

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** n/a

Worth stating, because the entry above reads more hopeless than it is:

- `set_parent` works on an AnimBlueprint. Reparenting a freshly created ABP onto a custom
  AnimInstance base went through normally - reparent, compile, verify with `get_parent`.
- `blendParameters` writes fine on a BlendSpace, including as a struct array, without losing
  `sampleData` or `skeleton`.

So the only things a human has to do are creating the asset on the right skeleton and authoring
the AnimGraph. Everything else can be driven.

### Renaming a blend space axis does not need a grid rebuild

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** n/a

As long as `min`, `max` and `gridNum` stay put, editing `blendParameters` is safe: the baked grid
samples store sample indices and weights, not positions. Renaming an axis or swapping which
animation a sample points at leaves the grid valid.

### `add_socket` creates a mesh socket, not a skeleton socket

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

The second argument of the underlying call is `bAddSocketToSkeleton`, and it is false. So the
socket exists on that one mesh, and sibling meshes sharing the skeleton never see it. Verified
the unhappy way: a socket added to one variant of a character was simply absent on the other.

This is convenient when you want a targeted change that does not touch a purchased pack - and
surprising if you expected sockets to live where the editor's own UI suggests they live.

---

## PhysicsAssetToolset

### Constraint reference frames are unreachable - for reading and for writing

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes (manual)

`PhysicsAssetToolset` exposes limits (`SetConstraintLimits`), masses, shapes and modes.
It exposes nothing about Parent or Child Rotation. Reflection is closed too:
`get_properties(PhysicsAsset, ["ConstraintSetup"])` answers "could not be read", and
`ObjectTools` has no way to walk into subobjects.

This is worse than it sounds. Porting constraint limits from a finished character to a new
one carries **how far** a joint bends, but not **which way**. On an asset with auto-generated
frames the cone is centred on the bone, so a knee with `Swing1 Limited 65` folds forward as
happily as backward. No amount of copied numbers fixes that - the numbers are not where the
problem is.

**Workaround.** Rotate the frame by hand in the Physics Asset Editor: select the constraint →
Details → Constraint Transforms → **Parent → Rotation**, third component (Z / Yaw). Leave
Child Rotation at zero, and do not touch Parent Position - that is an offset along the bone
and it is per-skeleton.

Rule of thumb that held up across two characters: **the rotation is roughly equal to the
limit itself**. With `Swing1 Limited 65`, a yaw around 60 puts the straight leg at the edge
of the bend window, and the joint folds one way only. If you have a tuned donor asset, copy
its Rotation values directly - unlike Position, they do not depend on the mesh proportions.

### Do not compare constraint motions by their first letter

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

`Locked` and `Limited` both start with `L`. Shorten them while diffing two assets and every joint
matches, including the ones that do not. I verified a port this way once and declared it clean
when it was not.

**Workaround.** Compare full strings. It is a stupid rule and it costs nothing.

---

## Plugins, search and odds

### `SetPluginEnabled` does not persist

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

It returns null, the plugin appears enabled, and after a restart it is disabled again. Nothing
was written to the `.uproject`.

**Workaround.** Edit the `.uproject` yourself and restart the editor.

### The semantic search toolset ships non-functional

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`SemanticSearchToolset` is wired to OpenAI - captions and embeddings both. With no key it answers
401, and the search index on disk is empty, so the toolset that looks like the answer to "find me
the thing" is the one tool guaranteed not to work out of the box. Making it work costs money at a
third party.

**Workaround.** `find_assets`, gameplay tags, and plain text search over the project. They are
enough more often than you would expect.

### `AssetTools.delete` returns false for just-imported assets and for folders

**Kind:** limitation · **Hit on:** 5.8.2 · **Workaround:** yes

Deleting a folder path returns `false`, and so did deleting each freshly imported (never saved)
static mesh, texture and material inside it, with no reason given. The same assets deleted fine
via editor Python: `py unreal.EditorAssetLibrary.delete_directory("/Game/<Folder>")` through the
Cmd box (`tools/ue_console.sh`). Assets that had been saved once (the terrain mesh) deleted
through the tool without trouble, so treat the tool as "works on saved assets".

### `AssetTools.get_asset_class` returns short class names

**Kind:** note · **Hit on:** 5.8.2

The return value is `Material`, `Texture2D`, `StaticMesh`, `MaterialInstanceConstant` - not a
`/Script/Engine.Material` path. A filter written as `cls.endswith(".Material")` never matches
and skips its branch without any error; here it silently skipped a two-sided pass over several
hundred imported materials. Compare `cls.split(".")[-1]` so either form works.

### `StaticMeshTools` has no `get_mesh_info`

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

The obvious call does not exist. What exists: `get_lod_count`, `get_triangle_count(mesh, lod)`,
`get_lod_thresholds`, `get_material_slots`, `get_material`, `is_nanite_enabled`,
`set_nanite_enabled`. The mesh argument is `mesh`, not `static_mesh`, and `minLOD` is not readable
through reflection at all.

Instance count on an instanced static mesh is the length of its per-instance data array - there is
no counter to ask for.

### `GetQueryDescription` reports "Empty" for editable World Conditions

**Kind:** defect · **Hit on:** 5.8.0 · **Workaround:** yes

It only describes a compiled shared definition. Point it at conditions that are still editable and
it says the query is empty - which is indistinguishable from an actually empty query.

### Client-side: agent permission classifiers block Slate clicks and PIE

**Kind:** note · **Hit on:** 5.8.0 · **Workaround:** yes

Not an engine issue - this one is on the client. Automated approval refuses Slate clicks and
`StartPIE`, so a run that should be autonomous stops. With explicit human approval both work
exactly as documented: a click on a button reports true, and simulate mode brings a PIE world up
in about seven seconds.

**Workaround.** Ask for approval up front for the interactive parts, rather than discovering the
refusal in the middle of a sequence. And note that interactive tools take over the human's editor
while they run - always worth announcing before you do it.

---

## BlueprintTools and the graph DSL

All hit on 5.8.2 while authoring three Blueprints and one Widget Blueprint entirely through
`write_graph_dsl`. The DSL is the fastest way to author logic, but it has edges.

### `write_graph_dsl` APPENDS to the graph

**Kind:** limitation · **Workaround:** yes

Writing a second time does not replace the first write: you get two BeginPlay events, two
Tick events, duplicate key bindings. `read_graph_dsl` shows the accumulation. Clear first:
`find_nodes(graph, title="")` returns every node; `delete_node` each; then write. Function
graphs are the exception - rewriting a `(fn ...)` graph replaced its body cleanly in practice.

### `(fn ...)` only works inside a function graph; `(event ...)` cannot create custom or key events

**Kind:** limitation · **Workaround:** yes

- `(fn Name ...)` in the EventGraph fails with `AddEvent|Name does not exist`. Create the graph
  first (`add_function_graph`), add params (`add_function_param`), then write `(fn Name (Params) ...)`
  into THAT graph.
- `(event Frenzy ...)` for a custom event fails the same way. There is no custom-event path in the
  DSL; use functions.
- `(event Input|KeyboardEvents|E ...)` and `(event E (Key) ...)` both fail, even though
  `read_graph_dsl` prints an existing key node as `(event E (Key))`. Create the key node with
  `create_node(graph, "Input|KeyboardEvents|E", pos)`, the call with
  `create_node(graph, "CallFunction|<YourFunction>", pos)`, read the pin ids with
  `get_node_infos`, and `connect_pins(Pressed -> execute)`. Only param-less or all-defaulted
  functions are practical targets.
- Existing engine events work with the palette path: `(event EventBeginPlay ...)`,
  `(event EventTick (DeltaSeconds) ...)`, `(event AddEvent|Collision|EventActorBeginOverlap (OtherActor) ...)`.

### New variables and functions need a `compile_blueprint` before the DSL can see them

**Kind:** limitation · **Workaround:** yes

`add_variable` then `write_graph_dsl` referencing `Variables|Default|GetFrenzy` fails with
"does not exist". Compile between adding members and writing graphs that use them.

### Removing a function that a graph still calls breaks the next write

**Kind:** limitation · **Workaround:** yes

`remove_function_graph("FeedNow")` while the EventGraph still holds a `CallFunction|FeedNow`
node makes the following `write_graph_dsl` fail with `Could not find a function named "FeedNow"`
(the write compiles) and the whole script rolls back. Clear the event graph (delete its nodes)
and compile BEFORE removing functions, then rebuild.

### Replacing the body of an existing function graph

**Kind:** note · **Hit on:** 5.8.2

Because `write_graph_dsl` appends, and a removed function cannot be re-added under the same name
while something still calls it, rewrite in place: `find_nodes(graph, "")`, `delete_node` each
(wrap in `try` - the entry node refuses or is recreated), then `write_graph_dsl` with the same
`(fn Name (Params) ...)` header and compile. Check `find_nodes(..., entry_points_only=true)`
returns one node and `read_graph_dsl` shows a single `(fn`.

### A `bind` of a pure expression is re-evaluated at every use

**Kind:** note · **Hit on:** 5.8.2 · **Workaround:** yes

`(bind n (not (Variables|Default|GetIsOpen)))` followed by `(Variables|Default|SetIsOpen n)` and
then `(select n ...)` reads the flipped value the second time: pure Blueprint nodes have no
cached output, so each consumer re-runs the expression against the variable you just changed.
The symptom was a toggle that worked while its prompt text always showed the wrong state.

**Workaround.** Branch on the variable and set literals in each branch
(`(if (GetIsOpen) (SetIsOpen false) ... (else (SetIsOpen true) ...))`), or derive later values
from the variable after it has been written.

### Reading another instance's variable: not from inside the same class

**Kind:** limitation · **Hit on:** 5.8.2 · **Workaround:** yes

From another Blueprint, `Class|BPOther|GetScore :self other` exists. Inside `BP_Other`'s own
graph the only getter is `Variables|Default|GetScore`, which has no target pin, so an instance
cannot read a sibling instance's variable through the DSL.

**Workaround.** Add a one-line function with an output parameter
(`add_function_param(..., input_param=false)`, body `(return (Variables|Default|GetScore))`).
Inside the class it is `CallFunction|ReadScore :self other :Unused false`; from other classes
`Class|BPOther|ReadScore :self other :Unused false`. Keep a dummy input parameter, as for any
function you need to call by node.

### Latent nodes inside functions are rejected; use timers by name

**Kind:** limitation · **Workaround:** yes

`Utilities|FlowControl|Delay` cannot live in a function graph. Split the "wait" into
`Utilities|Time|SetTimerbyFunctionName :Object self :FunctionName "Later" :Time 12.0` and put the
continuation in a param-less function `Later`. In the EventGraph, `Delay` works as a plain
sequential statement (no continuation block needed).

### Functions created without parameters are invisible to `find_node_types` and cannot be called from other Blueprints

**Kind:** defect · **Workaround:** yes

A function graph created by `add_function_graph` with no `add_function_param` before its first
compile never appears as `Class|<BP>|<Fn>` in another Blueprint, and `write_graph_dsl` there
fails with `Class|WBPFeedPrompt|HideMsg does not exist`. Adding a parameter afterwards does not
help, nor does `remove_function_graph` + re-adding under the same name (the new graph is then
treated as an event: `AddEvent|HideMsg does not exist`).

**Workaround.** Give every function you will call from *another* Blueprint at least one
parameter *before* its first `write_graph_dsl`/compile (a dummy `bool Unused` is fine), or create
it again under a **new name**. Alternatively avoid cross-Blueprint function calls: component and
variable accessors (`Class|BPFish|GetOrbit`, `Class|BPFish|GetBaseRate`) ARE registered, so the
caller can drive the other actor's components directly after a cast.

### Argument names are given by the error; positional args are echoed back

**Kind:** note

A wrong keyword fails fast with the full pin list: `Unknown input pin "InText" on Class|Text|SetText.
Input pins: ['Text', 'self']`. Cheap to iterate on outside a batch script. `read_graph_dsl` prints
positional forms and auto-bound names (`_returnvalue`, `_asbp_fish`) - fine for verification, not
for copy-paste back in. It also prints ambiguous class names for same-named functions
(`Class|CharacterMovementComponent|SetRotationRate` for a RotatingMovementComponent call, `Class|Character|GetMesh`
for `Class|BPFish|GetMesh`); the compiled graph was still correct.

### Text-typed Blueprint variables are set as plain strings

**Kind:** note

`set_properties(actor, {"promptHungry": "Press E"})` works for an FText variable once the
variable exists on the compiled class. "The following properties could not be set" here meant
the variable had not survived a rolled-back script, not a type problem. `list_properties` on the
instance shows `{"type":"string"}` for FText.

### Component collision shapes edited with `set_properties` are not rebuilt

**Kind:** defect · **Workaround:** yes

`boxExtent` on a BoxComponent trigger reads back changed but the physics shape keeps the old
size, and overlap events never fire (no `PostEditChangeProperty`). Either set the extent on the
Blueprint's component template *before* placing instances, or avoid collision for proximity:
a Tick-based `GetDistanceTo(GetPlayerPawn) < Radius` check worked first time and needs no
physics.

### Widget variables live under the Blueprint's own category

**Kind:** note

After `UMGToolSet.ToggleWidgetAsVariable(..., true)` the getter is
`Variables|WBP_FeedPrompt|GetPromptText`, not `Variables|Default|GetPromptText`. Discover it with
`find_node_types(graph, "PromptText")`. Setting the text is `Class|Text|SetText :self <textblock> :Text <text>`
(the TextBlock class is shown as `Text`), and widget visibility is `Widget|SetVisibility :self <widget> :InVisibility "Hidden"`.

---

## StaticMeshTools, UMG, saving

### `import_file` accepts only FBX/OBJ

**Kind:** limitation · **Hit on:** 5.8.0 · **Workaround:** yes

`FbxFactory does not support ".glb" files`. Request FBX from the asset service. Imports into the
same folder overwrite each other's `Image_0` / `Material_0`; use one folder per asset.

### Saving a World Partition level does not save its actors

**Kind:** limitation · **Workaround:** yes

`AssetTools.save_assets(["/Game/Maps/Lvl"])` reports success and `is_dirty` turns false, yet the
status bar still shows hundreds of unsaved packages: every actor of a World Partition level is
its own external package, and `find_assets("/Game/__ExternalActors__")` does not list unsaved
ones. `SceneTools.save_actor` refuses non-external actors (WorldSettings, Brush - "Save the level
instead") and fails with `Asset does not exist` for actors never saved before; each failure
aborts a batch script. Clicking the toolbar "Save Current Level" button through Slate did not
flush them either.

**Workaround.** Run the editor's Python through the status-bar console:
`py unreal.EditorLoadingAndSavingUtils.save_dirty_packages(True, True)`. This saved 283 actor
packages and the status bar read "All Saved". Use `tools/ue_console.sh` (below) - typing into
the Cmd box has quirks of its own.

### Arrays: a resize leaves the LAST element at its default, and resize+edit in one call fails

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

Two separate problems with array properties (seen on `perInstanceSMData`):

1. Writing a shorter or longer array whose surviving elements also changed fails with
   `ArrayAdd: elements changed alongside the size change; insertion points are ambiguous`.
   Set the property to `[]` first, then write.
2. Any write that changes the length comes back with the correct count but the **last element
   left at its default** (an identity transform, i.e. an instance at the actor origin). This is
   how a 1 m tree, a fence panel and a grass tuft ended up standing inside the house, once per
   instanced component. A second write of the identical, same-length array fixes every element.

**Workaround.** `set([])` -> `set(list)` -> `set(list)` again, then read back and assert no
element is still default. Same-length rewrites alone are reliable.

### Large per-instance arrays: one write can block the editor for minutes

**Kind:** note · **Hit on:** 5.8.2 · **Workaround:** yes

Writing `perInstanceSMCustomData` for a few thousand instances took several minutes per
`set_properties` call with the editor at 100% CPU and unresponsive. The HTTP client timed out
while the script kept running and completed correctly. `perInstanceSMData` of the same size
was much faster.

**Workaround.** Do not retry on the timeout. Poll a cheap read-only call until the server
answers again, then read the result back. Write each array once per component (twice only for
the resize defect above), and prefer fewer, larger components.

### The status-bar Cmd box: first character duplicated, submit lands every other time

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

`SlateInspectorToolset.Type {ref: <Cmd textbox>, text, submit: true}` is the only console route
(see "There is no console-command tool"). Observed: the first character of `text` is typed twice
(`py ...` arrives as `ppy ...`), text APPENDS to whatever is already in the box, and roughly
every second submit does nothing (an autocomplete popup - an untitled extra window in
`Windows list` - eats the Enter). `Type` without submit followed by `PressKey Enter`, and
`FillForm`, never submitted at all.

**Workaround.** Prefix the command with a space (the duplicate becomes harmless), press
`Escape` before each attempt, and retry until the log shows `Cmd: <your command>` (allow extra whitespace after `Cmd:`):
`grep -a "Cmd: " <Project>/Saved/Logs/<Project>.log | tail -1`. Packaged as
`tools/ue_console.sh '<command>' '<editor log>'`. The current helper uses unique Python
completion/error markers and stops on exceptions, avoiding replay of partial mutations. Older
versions could submit a slow script twice. Missing acknowledgements or connection loss still
require log/state inspection before retrying; use idempotent scripts where possible. Find the
textbox ref with `Snapshot("sp1")` - it is the
`textbox` next to the `"Cmd"` combobox at the bottom of the main window.

When the editor runs **without `-Unattended`** (the recommended way for interactive sessions,
see [setup.md](../setup.md#interactive-editing-and-saving)), popups are no longer suppressed: every FBX/OBJ import opens a **Message Log** window that
takes keyboard focus, the helper reports `No completion acknowledgement`, and
`CaptureEditorImage` can fail with `Failed to capture any editor windows`. List windows with
`SlateInspectorToolset.Windows {}` and close it with `Windows {"action":"close","index":N}`
after each import batch.

---

## Additional EditorAppToolset / ObjectTools / ProgrammaticToolset notes (Sept 2026 build)

### `CaptureEditorImage` is the screenshot tool that works

**Kind:** note

It returns the whole editor window as the user sees it (also headless with `-RenderOffscreen`,
also during PIE, also with floating PIE windows on top). Pair with `SetCameraTransform`.
`CaptureViewport` also worked in the 5.8.2 follow-up above. Multiple windows can cause the full
editor capture to be resized; obtain actual PIE viewport dimensions before mapping input coordinates.

### `StartPIE` spawns the pawn at `startTransform`, and `(0,0,0)` is inside your floor

**Kind:** defect · **Workaround:** yes

Passing a zero transform spawns the player at the origin - usually colliding
(`SpawnActor failed because of collision`) - and the view is black/underground. Pass the
PlayerStart location. Useful side effect: `startTransform` is how you position the player for a
screenshot. Prefer `PlayMode_InEditorFloating`: the in-viewport mode's world freezes on a
headless editor when no input arrives (see headless-autonomy.md §4).

A start point that overlaps geometry by even a few centimetres has the same outcome (a capsule
of radius ~34 and half-height ~96 clipping the edge of a raised deck was enough). It reads as
"fell through the world": the view is from the origin under the terrain, and every
proximity-based prompt shows at once because `GetPlayerPawn` is null and distances evaluate
to 0. Check the capsule against nearby tops before suspecting collision.

### The floating PIE window can shrink on every run

**Kind:** defect · **Hit on:** 5.8.2 · **Workaround:** yes

Most likely a bug with the built-in windowing system that is used with -RenderOffscreen
visible through editor captures and Pixel Streaming.

With `PlayMode_InEditorFloating`, `NewWindowHeight` drifted down a few dozen pixels per session
(378 -> 252 over a test series), which also changes the vertical field of view of every
screenshot. `unreal.LevelEditorPlaySettings` is not exposed to Python.

**Workaround.** `ConfigSettingsToolset.SetSectionProperties` with container `Editor`, category
`LevelEditor`, section `PlayIn`: `{"NewWindowWidth":1280,"NewWindowHeight":720,"CenterNewWindow":true}`.
With the window centred the size held.

### `LogsToolset.GetLogEntries` returns the OLDEST matches

**Kind:** defect · **Workaround:** yes

With `maxEntries: 10` and a pattern that matched earlier in the session you never see new lines.
`grep -a <pattern> <Project>/Saved/Logs/<Project>.log | tail` on disk is instant and correct.

### A `PostProcessVolume` written through `set_properties` can black out the scene

**Kind:** defect · **Workaround:** yes

Setting `settings.autoExposureMinBrightness/MaxBrightness` (with their `bOverride_` flags)
turned every viewport black, and clearing the override flags afterwards did not recover it
(no PostEditChange). `remove_from_scene` on the volume restored the picture; re-adding a fresh
volume with only `autoExposureBias`, bloom, vignette and `whiteTemp` overrides worked. Property
names are camelCase (`bUnbound`, `settings.bOverride_BloomIntensity`, `settings.bloomIntensity`).

### Script rollback is partial; make every script idempotent

**Kind:** defect · **Workaround:** yes

After a failing `execute_tool_script`, assets created by the script still exist (`create_material`,
`BlueprintTools.create`) while some in-memory edits are undone. The next run then dies on
`already exists`. Guard creation with `AssetTools.exists`, `list_variables`, `list_graphs`, and
split independent work into separate scripts.

### `try/except` catches argument errors, not tool assertions

**Kind:** note

`RuntimeError` from a missing/invalid argument IS catchable inside the script. Assertions raised
by `write_graph_dsl` / `create_node` ("The node could not be created") and `Parameter error: ... is
not valid Object` are not - they end the script. Probe existence with calls that return normally.

### Toolbar checkboxes in `SlateInspector` snapshots are unlabeled and mirrored

**Kind:** limitation · **Workaround:** yes

Every level-viewport pane repeats the same global toggles (snapping, realtime, ...) as anonymous
24x24 checkboxes, and refs change when the user changes the layout. Clicking by size/position
flipped the user's snapping settings. Click only a ref you have just read and confirmed by
tooltip (`Hover` then `Snapshot`), then re-snapshot to verify the effect.



---
#### Attribution:

ue58-mcp-field-notes by PavelVyny, used under CC BY 4.0.
https://github.com/PavelVyny/ue58-mcp-field-notes

Changes made:
- New entries for 5.8.2 added.

# Operations: Console Commands, Settings, Recovery

Read this when something is misbehaving with the MCP server (tools missing, port collision, stale tool registry), or when you need a non-default configuration.

## Console commands

Run these from the Unreal Editor console (`~`).

| Command                                              | Use it for                                                                                               |
|------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| `ModelContextProtocol.StartServer [port]`            | Start the MCP server. Pass a port to override the default (e.g. when 8000 is in use).                    |
| `ModelContextProtocol.StopServer`                    | Stop the server. Useful if the registry is in a bad state and you want a clean restart.                  |
| `ModelContextProtocol.RefreshTools`                  | Re-register every toolset. Run this after the user enables a new toolset plugin.                         |
| `ModelContextProtocol.GenerateClientConfig <client>` | Regenerate the per-client config file. Args: `ClaudeCode`, `Cursor`, `VSCode`, `Gemini`, `Codex`, `All`. |

## Tool-search mode

`tools/list` has two modes, controlled by the `bEnableToolSearch` UPROPERTY on `UModelContextProtocolSettings` (default `true`):

- **`True`** (default): `tools/list` returns only `list_toolsets`, `describe_toolset`, `call_tool`. Toolset tools are dispatched server-side through `call_tool` and stay out of the prompt; the catalog never changes mid-session, so the prompt cache stays warm.
- **`False`**: every toolset tool is registered as a native MCP tool at startup, schemas visible upfront. Used by the hash-mapping commandlet.

Override in the same `.ini` used for `bAutoStartServer`:

```ini
[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
bEnableToolSearch=False
```

## Proxy recovery

With the optional proxy, the client connects to `unreal-mcp-proxy` instead of directly to `unreal-mcp`. The proxy keeps that client session open while it reconnects to Unreal. Do not replace it with a second direct connection during normal recovery.

- `unreal_mcp_status` reports whether the proxy holds an initialized upstream session. It does not test current reachability.
- Visible tools can come from a stored catalog. Verify live access with a read-only Unreal tool call.
- With no stored catalog and no upstream session, the proxy exposes only `unreal_mcp_status`. After recovery, it sends `notifications/tools/list_changed`.
- Clients must fetch `tools/list` again after that notification. A client that ignores it can keep the status-only catalog, or an older cached catalog. Once Unreal is reachable, use the client's reconnect or configuration-reload action if available. Otherwise, restart the client to obtain the catalog. This is a client refresh limitation, not the normal proxy recovery workflow.
- Killing the proxy closes the client's STDIO connection. `Transport closed` then needs client reconnection; starting an unrelated proxy process cannot repair that connection. Ask before stopping active proxies.

If calls still fail, check the editor's MCP startup log, the configured endpoint, and proxy stderr. With multiple editors, identify which process owns the configured port. A running editor alone does not prove that the proxy targets its MCP server. Follow the recorded `.mcp.json` entry and the engine's `Extras/Proxy/README.md` for your build's transport limits.

## Troubleshooting matrix

| Symptom                                               | What to do                                                                                                                                                                                                                                                                                                          |
|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Unreal tools are missing, or `list_toolsets` errors | Check for both `unreal-mcp` and `unreal-mcp-proxy` in the client configuration. Check the editor's MCP startup log and configured endpoint. For a proxy connection, follow **Proxy recovery** above before concluding that the editor is stopped. |
| Editor logs "Failed to listen on port"                | Another process holds the default port. Change `ServerPortNumber` in the per-user `EditorPerProjectUserSettings.ini` (see `setup.md`), or pass `-ModelContextProtocolPort=<port>` on the next launch; restart the editor, and re-run `ModelContextProtocol.GenerateClientConfig ClaudeCode` to refresh `.mcp.json`. |
| A toolset you expect (e.g. `NiagaraTools`) is missing | Run `ModelContextProtocol.RefreshTools`. If still missing, the toolset's plugin may not be enabled in the `.uproject`. Check there.                                                                                                                                                                                 |
| Tool calls hang or return errors                      | Editor may be busy compiling, loading a level, or in PIE. Wait and retry. For long compiles, prefer `LiveCodingToolset.CompileLiveCoding`. It returns when the compile actually finishes.                                                                                                                           |
| `AIAssistantToolset.GetDockedContext` returns empty   | The Claude Code tab must be docked inside an asset editor (Blueprint, Material, etc.) to provide docked context. If undocked, that tool has nothing to report.                                                                                                                                                      |
| Save All leaves dirty assets and edits disappear on restart | Check whether the interactive editor was launched with `-Unattended`. UE 5.8.2 can silently cancel its normal checkout-and-save path under that flag. Preserve dirty map/content packages through direct editor Python before restarting without it; see the local [save recovery procedure](../setup.md#interactive-editing-and-saving). |
| Sequential tool calls collide                         | Tool calls execute on the game thread. Don't issue them in parallel, even when they look independent. Serialize.                                                                                                                                                                                                    |

# Unreal Engine Skills for Coding Agents

Control Unreal Editor directly from Claude Code or other coding agents via MCP. Hundreds of tools exposed via Unreal's ToolsetRegistry across 30+ toolsets: actors, blueprints, materials, Niagara, Control Rigs, Sequencer, State Trees, widgets, Gameplay Ability System, automation testing, and more.

## Contents

### Skills

- **`unreal-mcp`** (`skills/unreal-mcp`) - instructions and workflows for driving the Unreal Editor via MCP.
Accompanying documents for the unreal-mcp skill are `setup.md` and `operations.md`.

## Prerequisites

1. **Unreal Editor** with the **ModelContextProtocol** and **AllToolsets** plugins enabled (`AllToolsets` provides the tools; the server exposes none without it)
2. **Editor running to execute tools**, with the MCP server started. Run `ModelContextProtocol.StartServer`, or enable `bAutoStartServer` through `setup.md`. The optional proxy can keep the client connection open while the editor is stopped.

Read `setup.md` for the full setup procedure for a fresh project.

## Verification

1. Launch Unreal Editor, then run `ModelContextProtocol.StartServer` in the console to start the MCP server.
2. Check the Output Log for MCP server startup messages.
5. Try: "List all actors in the current level".

## Configuration

The default port is **8000** with URL path `/mcp`. If the port is in use, run `ModelContextProtocol.StartServer <port>` in the console with a different port number.

> **Note:** This plugin does not ship a static `.mcp.json` file. Run `ModelContextProtocol.GenerateClientConfig ClaudeCode` (or your coding agent of choice; see `setup.md`) in the editor console to generate it from the current server port and URL; re-run after changing either.

### Optional proxy for editor recovery

If your engine build includes `Engine/Plugins/Experimental/ModelContextProtocol/Extras/Proxy`, you can use its `unreal_mcp_proxy` executable.

The proxy keeps the client-facing MCP session open while Unreal is unavailable and reconnects when Unreal starts again. It stores Unreal's native tool catalog as a temporary fallback. Cached tools do not prove that live calls can succeed. Without a cache, it exposes only `unreal_mcp_status` until the client fetches the recovered catalog.

See [proxy setup](setup.md#4-optional-install-the-proxy) for platform binaries and installation commands. See [proxy recovery](operations.md#proxy-recovery) for status, cached catalogs, and connection failures.

### Tool search

**Tool Search is required.** Keep `bEnableToolSearch=True` in `[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]`.
The MCP server exposes `list_toolsets`, `describe_toolset`, and `call_tool`; clients discover a toolset, inspect its
schema, then dispatch it through `call_tool` on the same turn. The model-facing usage contract lives in
`skills/unreal-mcp/SKILL.md`.

## Security

Installing this plugin gives your coding agent broad, live access to the running Unreal Editor. Treat that access the same way you would treat running arbitrary code from an assistant, because in practice it is.

**Localhost is not a trust boundary.** The MCP server binds to `localhost:8000` with origin validation. Origin validation protects against a browser tab talking to the server, but any process running as the same user on the same machine can connect. Do not run the MCP server on shared or untrusted machines, and do not expose the port outside the loopback interface.

**`ProgrammaticToolset.execute_tool_script` executes arbitrary Python** inside the editor process. That script has full access to every toolset API, the project on disk, the asset database, and editor-privileged functions. Treat every invocation as a privileged operation that can mutate, move, or delete project content, and expect it to succeed without a second confirmation when approvals are disabled.

**Auto mode.** If the project is a large existing game and not meant to be a fully agent-made one/few-prompt project, prefer to keep (the equivalent of) Auto mode in your coding agent **off** so that each tool call requires approval, unless you'd like the agent to full-auto the project as much as possible. 

**Source-control hygiene.** MCP tools edit live `UObject` state and can mutate, move, or delete VCS-tracked assets in a single call. Save and commit (or shelve) before any long MCP-driven session so the working copy is recoverable if Claude produces an unexpected result. Review the diff before submitting.

## What's Available

The host discovers tools through Unreal MCP Tool Search. Tools cover the full editor surface across these domains:

- **Actors and Scene** - spawn, transform, inspect, and delete actors; manage components and outliner folders
- **Blueprints** - create, edit graphs, add nodes, connect pins, manage variables, compile
- **Assets and Content** - find, load, save, move, duplicate assets; edit Data Tables, Curve Tables, String Tables
- **Materials** - author material graphs, create and configure material instances
- **Meshes and Textures** - inspect/edit static and skeletal meshes, LODs, collisions, Nanite, sockets, bones
- **Animation** - build Control Rigs, inspect State Trees and Behavior Trees
- **Sequencer** - create and edit Level Sequences, keyframe animation, manage cameras, Control Rig integration, FBX import/export
- **VFX** - author Niagara systems and Dataflow graphs
- **UI** - build UMG widget blueprints, automate Slate UI interaction
- **Gameplay** - manage gameplay tags, inspect GAS state, create Game Feature Plugins, edit physics assets
- **Testing** - discover, run, and inspect C++ automation tests with detailed results
- **Editor** - screenshots, camera control, actor/asset selection, content browser, log inspection
- **Scripting** - batch multiple tool calls into a single Python script execution

# First-Time MCP Server Setup

Read this for first-time MCP configuration or optional proxy installation. Steps 1-3 configure direct HTTP access. Step 4 adds a proxy that keeps the client session open while Unreal is unavailable.

The goal is three things:
1. Enable the `ModelContextProtocol` and `AllToolsets` plugins in the project.
2. Make the editor auto-start the MCP server on launch.
3. Generate the `.mcp.json` Claude Code reads to connect.

Walk the user through them in order. Do not skip the user's `.uproject` edit silently. Confirm the file path first.

## 1. Enable the plugins in the `.uproject`

Two plugins are required. `ModelContextProtocol` is the server and transport; `AllToolsets` provides the tools. With only `ModelContextProtocol` enabled the server starts but exposes no tools.

Open the project's `.uproject` file. In the `Plugins` array, ensure both entries:

```json
{
  "Name": "ModelContextProtocol",
  "Enabled": true
},
{
  "Name": "AllToolsets",
  "Enabled": true
}
```

If the array doesn't exist, create it. If either entry exists with `"Enabled": false`, flip it to `true`.

`AllToolsets` is an editor-only aggregator with `EnabledByDefault` off, so it must be enabled explicitly. To expose only a subset of tools, enable the specific toolset plugins you want instead of `AllToolsets`.

## 2. Enable auto-start

The default is for the MCP server to stay stopped. To start it manually in a session, run `ModelContextProtocol.StartServer` from the editor console.

To start it automatically on every editor launch, add the snippet below to the per-user editor config file:

`<Project>/Saved/Config/<Platform>Editor/EditorPerProjectUserSettings.ini`

This is the file the editor writes when you toggle the setting in Editor Preferences. It is per-user and not source-controlled.

```ini
[/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]
bAutoStartServer=True
```

Optional overrides if the defaults conflict with another local service:

```ini
ServerPortNumber=8000
ServerUrlPath=/mcp
```

A command-line alternative also works: pass `-ModelContextProtocolStartServer` (and optionally `-ModelContextProtocolPort=<port>`) to the editor. Prefer the `.ini` because it's persistent.

## 3. Generate `.mcp.json`

The editor does not write `.mcp.json` on its own. Either run a console command from inside the editor, or hand-write the file.

**From a running editor (preferred):** run `ModelContextProtocol.GenerateClientConfig ClaudeCode` in the console (or `All` to write configs for every supported client: `ClaudeCode`, `Cursor`, `VSCode`, `Gemini`, `Codex`). Re-running merges into the existing JSON, so it is safe after changing the port or URL. Codex is the exception: it uses TOML and the writer refuses to overwrite an existing `.codex/config.toml`. Edit that one by hand if it already exists.

The destination depends on the build kind:

- **Source build** (your repo contains `Engine/`): the file is written to the workspace root, alongside `Engine/`. Not next to the `.uproject`.
- **Installed/launcher build**: the file is written next to the `.uproject`.

**Without launching the editor first** (for example, scripting a fresh-project bootstrap), hand-write `.mcp.json` at the location matching your build kind above:

```json
{
  "mcpServers": {
    "unreal-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

Adjust the URL if the port or path was overridden in step 2.

## 4. Optional: install the proxy

Use this option if you want the client session to survive editor shutdown and startup. The editor must still run for live tool calls.

Check whether your engine includes `Engine/Plugins/Experimental/ModelContextProtocol/Extras/Proxy`. If it is absent, keep the direct HTTP setup.

Choose the binary for the operating system where the MCP client runs:

| Platform | Binary under `Extras/Proxy` |
|---|---|
| Windows x64 | `Bin/Win64/unreal_mcp_proxy.exe` |
| macOS arm64 | `Bin/Mac/unreal_mcp_proxy` |
| Linux x64 | `Bin/Linux/unreal_mcp_proxy` |
| Linux arm64 | `Bin/LinuxArm64/unreal_mcp_proxy` |

First generate `.mcp.json` through step 3. Then run the matching command from `Extras/Proxy`, using the actual configuration path.

Windows PowerShell:

```powershell
.\Bin\Win64\unreal_mcp_proxy.exe --mcp-json "C:\path\to\.mcp.json" install
```

macOS:

```bash
./Bin/Mac/unreal_mcp_proxy --mcp-json "/path/to/.mcp.json" install
```

For Linux, use `Bin/Linux` or `Bin/LinuxArm64` instead of `Bin/Mac`.
An explicit `--mcp-json` path also supports projects outside the engine directory tree.

The installer replaces the HTTP entry with a STDIO `unreal-mcp-proxy` entry. It keeps the original entry under `_upstreamEntry`. Configure one Unreal connection, not both the proxy and a duplicate direct HTTP connection.

Restart the MCP client once after installation so it loads the changed configuration. Later editor shutdowns do not require stopping the proxy. If an editor integration automatically replaces `.mcp.json`, disable that integration's automatic client-configuration writes.

To restore the direct HTTP entry, run the same command with `uninstall` instead of `install`. Reload the client configuration afterward.

The proxy stores catalogs in the operating system's user cache directory. Scope includes configuration path, proxy path, engine build identity, and client protocol version. It does not supply a fixed Unreal tool catalog. See the engine's `Extras/Proxy/README.md` for cache behavior and transport limits in your build.

## Verifying

After the editor is running with the plugin enabled and auto-start on:

- The Output Log shows MCP server startup messages.
- `list_toolsets` (one of the three tool-search meta-tools) returns successfully.
- `/mcp` in Claude Code lists `unreal-mcp`, or `unreal-mcp-proxy` when installed, as connected.

A connected proxy or visible cached tools do not prove that Unreal is reachable. Confirm with a successful read-only Unreal tool call.

If any of these fail, see `operations.md` for recovery commands.

#!/usr/bin/env python3
"""Read binary FBX diffuse texture connections without importing geometry or Unreal."""
import argparse
import json
import re
import struct
from pathlib import Path


def normalize_name(name):
    """Match FBX/material names despite import punctuation substitutions."""
    return re.sub(r'[^\w]', '_', name)


def texture_map(path):
    data = Path(path).read_bytes()
    if not data.startswith(b'Kaydara FBX Binary  \x00\x1a\x00') or len(data) < 27:
        raise ValueError('Expected binary FBX, not ASCII FBX or a conversion-status stub')
    version = struct.unpack_from('<I', data, 23)[0]
    header_format = '<QQQB' if version >= 7500 else '<IIIB'
    header_size = struct.calcsize(header_format)

    def node(position, depth=0):
        if depth > 256:
            raise ValueError('FBX node depth exceeds parser limit')
        end, count, size, name_length = struct.unpack_from(header_format, data, position)
        if not end:
            return None, position + header_size
        if end <= position + header_size or end > len(data):
            raise ValueError('Invalid FBX node extent')
        position += header_size
        name = data[position:position + name_length].decode()
        position += name_length
        property_end = position + size
        if property_end > end:
            raise ValueError('FBX properties exceed node extent')
        properties = []
        scalar_formats = {'Y': 'h', 'C': '?', 'I': 'i', 'F': 'f', 'D': 'd', 'L': 'q'}
        for _ in range(count):
            kind = chr(data[position])
            position += 1
            if kind in scalar_formats:
                fmt = scalar_formats[kind]
                value = struct.unpack_from('<' + fmt, data, position)[0]
                position += struct.calcsize(fmt)
            elif kind in ('S', 'R'):
                length = struct.unpack_from('<I', data, position)[0]
                position += 4
                # Raw blobs (embedded textures) are irrelevant to the connection map.
                value = data[position:position + length].decode(errors='replace') if kind == 'S' else None
                position += length
            elif kind in 'fdlibc':
                _length, _encoding, compressed_bytes = struct.unpack_from('<III', data, position)
                position += 12 + compressed_bytes  # Skip geometry arrays, compressed or raw.
                value = None
            else:
                raise ValueError('Unsupported FBX property type: ' + kind)
            if position > property_end:
                raise ValueError('Invalid FBX property size')
            properties.append(value)
        if position != property_end:
            raise ValueError('FBX property count/size mismatch')
        children = []
        while position < end - header_size:
            child, position = node(position, depth + 1)
            if child:
                children.append(child)
        return (name, properties, children), end

    roots = []
    position = 27
    while position < len(data) - header_size:
        item, position = node(position)
        if not item:
            break
        roots.append(item)
    sections = {name: children for name, _, children in roots}
    if 'Objects' not in sections or 'Connections' not in sections:
        raise ValueError('FBX has no Objects/Connections sections')
    materials = {}
    textures = {}
    for name, properties, children in sections['Objects']:
        if name == 'Material':
            materials[properties[0]] = properties[1].split('\x00')[0].removeprefix('Material::')
        elif name == 'Texture':
            textures[properties[0]] = next(
                (values[0] for key, values, _ in children if key == 'RelativeFilename'), '')
    result = {}
    for _, values, _ in sections['Connections']:
        if (len(values) > 3 and values[1] in textures and values[2] in materials
                and values[3] in ('DiffuseColor', 'BaseColor')):
            material = normalize_name(materials[values[2]])
            filename = Path(textures[values[1]].replace('\\', '/')).name
            if not filename:
                raise ValueError('Diffuse texture has no relative filename: ' + material)
            if material in result and result[material] != filename:
                raise ValueError('Ambiguous diffuse texture for ' + material)
            result[material] = filename
    return result


if __name__ == '__main__':
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('fbx', type=Path)
    args = parser.parse_args()
    print(json.dumps(texture_map(args.fbx), indent=2))

# tools/

## uemcp.py

Dependency-free command-line client for Epic's Unreal MCP server (Streamable HTTP on
`http://127.0.0.1:8000/mcp` by default). Use it when the `unreal-mcp` server is not in your
agent's tool list yet (it was configured after the agent started), or whenever you want to run
many editor calls from one shell command.

```sh
python3 tools/uemcp.py toolsets                      # what is registered
python3 tools/uemcp.py sig <Toolset>                 # compact signatures: name(arg?:type) -> return + first doc line
python3 tools/uemcp.py describe <Toolset>            # full JSON schemas (long)
python3 tools/uemcp.py call <Toolset> <tool> '<json args>'
python3 tools/uemcp.py call <Toolset> <tool> @args.json
```

- Text results are pretty-printed. Any `{data, mimeType}` image inside a result (CaptureEditorImage,
  CaptureViewport, Slate Screenshot) is written to `/tmp/uemcp_<n>.png` and replaced by the path.
- Exit code 1 on `isError` so shell `&&`/`||` work.
- `UEMCP_URL`, `UEMCP_SESSION` (session-id cache file), `UEMCP_TIMEOUT` override defaults.
- Toolset names are the long form from `list_toolsets`
  (`editor_toolset.toolsets.actor.ActorTools`, `EditorToolset.EditorAppToolset`, ...).

Batching pattern used in practice: keep a `lib_ue.py` with helpers (`T`, `setp`, `getp`,
`by_label`, `spawn_asset`, `clear_graph`, `wire_key_to_function`), concatenate it with a task
script that defines `run()`, JSON-encode as `{"script": ...}` and pass it to
`ProgrammaticToolset.execute_tool_script` with `@file`. See
`community-field-notes/headless-autonomy.md` §6.

## ue_console.sh

```sh
bash tools/ue_console.sh 'py print("connected")' '/absolute/project/Saved/Logs/Project.log'
```

Types a console command into the editor's status-bar Cmd box through the Slate inspector and
uses unique completion/error markers for Python calls. Exceptions return failure without
replaying partial changes. Ordinary console commands are acknowledged by their new `Cmd:` log
line; that establishes submission, not semantic success. Missing acknowledgement, log rotation
or connection loss requires inspecting state before a manual retry. Pass the running editor's
log explicitly when multiple projects/processes exist.

This helper targets the **editor** Cmd box and presses Escape, which stops PIE. Do not use it
for in-game console commands during a play test. Prefer short file-execution calls for larger
scripts. `UEMCP_CMDBOX_REF` overrides automatic textbox discovery. The transport is provided by
`uemcp.py`; see the gotchas file for the Slate input quirks.

## Scene audits and placement comparison

`ue_scene_audit.py` runs inside editor Python, outside PIE. It audits the currently loaded world
without loading, saving or changing assets. Supply an explicit output path:

```python
import sys
sys.path.insert(0, '/absolute/path/to/tools')
from ue_scene_audit import audit
audit('/absolute/path/before.json', instance_hashes=True)
# After the intended edits and a save/reopen, write a separate after.json.
```

Outside Unreal:

```sh
python3 tools/ue_compare_audits.py before.json after.json
```

Exit 0 means existing placements, component transforms/counts and material overrides are
preserved within the comparison's scope. Additions and mesh swaps are reported separately.
Exit 1 reports preservation differences. Use `--tolerance` for absolute transform tolerance;
instance hashes remain exact. The audit is not a gameplay-state comparison, and its LOD0 mesh
triangle counts may be Nanite fallback data rather than actual rendered triangles.

## FBX texture connections and fresh-import binding

```sh
python3 tools/fbx_texture_map.py /absolute/path/model.fbx
```

Reads binary FBX Material→Texture diffuse connections without importing Unreal or requiring a
3D editor. Supports the 32-bit and 64-bit node-header formats. Rejects conversion-status stubs;
ASCII FBX is outside this helper's scope. Outputs normalized material names and image basenames.
It does not generate, decimate, edit or validate the appearance of a model.

When a fresh Unreal FBX import leaves TextureSample inputs empty, editor Python can use:

```python
from ue_bind_fbx_textures import bind
plan = bind('/absolute/path/model.fbx', '/Game/Imported/Prop')
print(plan)  # dry run: resolves all material connections and checks image files
# On the reviewed fresh-import folder only:
result = bind('/absolute/path/model.fbx', '/Game/Imported/Prop',
              apply=True, roughness=.8, nanite=True, instanced=False)
```

**Apply replaces the imported base-material graphs** with diffuse texture plus constant
roughness and saves them. It preserves two-sided settings, skips shared materials outside the
folder, and refuses material instances. Do not use it on authored graphs. Images default to
the adjacent `model.fbm/` directory; `texture_dir=` overrides that directory. Existing target
textures are reused, so use a fresh dedicated import folder or inspect/reimport stale textures
before applying a changed FBX.

The helper validates mappings before changing any graphs and rejects textures Unreal classifies
as normal maps. Some bad source exports assign normal-map images to diffuse connections;
metadata alone cannot establish correctness. Inspect the image and in-level result. Missing
files/import failures may leave new texture assets, but material mutation starts only after
all target textures pass validation.

## CSV Profiler summaries

```sh
python3 tools/ue_csv_summary.py Before.csv After.csv --start 300 --stop 1100 --output timing.json
```

Reports mean, median, nearest-rank p95, minimum and maximum for numeric frame rows, ignoring UE's
metadata footer. Defaults to `FrameTime`, `GPUTime`, `GameThreadTime`; `--columns` selects other
header names. Start is inclusive and stop exclusive. It never edits the source CSVs. A JSON
output path that matches an input capture is rejected.

Read [performance and safe iteration](../community-field-notes/performance-and-safe-iteration.md)
for controlled capture conditions, interpretation limits, quality switching, surface validation
and preserving manual level edits.

## Validation scope

Checked on UE 5.8.2 Linux: live read-only audits including instanced transforms; temporary
multipart FBX import, dry-run binding, graph application, usage-flag saving and cleanup; and
ordinary-command and Python success/error acknowledgement (an intentional failing script executed
once). The FBX
reader was also checked against real exports and synthetic 32/64-bit node-header fixtures.
Offline checks cover audit additions/removals/movement and CSV metadata-footer handling.
Other engine versions and export conventions should be verified with a small import first.

#!/usr/bin/env python3
"""Minimal command-line client for Epic's Unreal MCP server (Streamable HTTP).

Lets an agent drive the editor from a shell when the `unreal-mcp` server is not
(yet) registered in the agent harness - e.g. the editor was configured mid-session
and the harness only reads `.mcp.json` at startup. No third-party dependencies.

Usage:
  uemcp.py toolsets                         # list_toolsets
  uemcp.py describe <Toolset>               # describe_toolset (full JSON schemas)
  uemcp.py sig <Toolset>                    # one line per tool: name(arg:type, ...) + first doc line
  uemcp.py call <Toolset> <tool> '<json>'   # call_tool (arguments as a JSON object)
  uemcp.py call <Toolset> <tool> @args.json # arguments read from a file
  uemcp.py raw <method> '<json params>'     # any JSON-RPC method (tools/list ...)

Environment:
  UEMCP_URL      default http://127.0.0.1:8000/mcp
  UEMCP_SESSION  file that caches the Mcp-Session-Id (default: /tmp/uemcp.session)
  UEMCP_TIMEOUT  seconds per request (default 600; tool calls run on the game thread
                 and a PIE start or shader compile can take a while)

Output: the tool's text content is printed verbatim. If a text block is JSON it is
pretty-printed. Image blocks (and inline {data,mimeType} images inside JSON results, e.g.
CaptureViewport / CaptureEditorImage / Screenshot) are written to /tmp/uemcp_<n>.png
and the path is printed in place of the base64.
Exit code 1 on isError / JSON-RPC error, so shell pipelines can branch on it.
"""
import base64
import json
import os
import sys
import urllib.error
import urllib.request

URL = os.environ.get("UEMCP_URL", "http://127.0.0.1:8000/mcp")
SESSION_FILE = os.environ.get("UEMCP_SESSION", "/tmp/uemcp.session")
TIMEOUT = float(os.environ.get("UEMCP_TIMEOUT", "600"))
_id = [0]


def _post(payload, session=None):
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    }
    if session:
        headers["Mcp-Session-Id"] = session
    req = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    resp = urllib.request.urlopen(req, timeout=TIMEOUT)
    body = resp.read().decode("utf-8", "replace")
    sid = resp.headers.get("Mcp-Session-Id")
    ctype = resp.headers.get("Content-Type", "")
    msg = None
    if "text/event-stream" in ctype:
        # take the last JSON-RPC message with a result/error
        for line in body.splitlines():
            if line.startswith("data:"):
                try:
                    m = json.loads(line[5:].strip())
                except json.JSONDecodeError:
                    continue
                if "result" in m or "error" in m:
                    msg = m
    elif body.strip():
        msg = json.loads(body)
    return msg, sid


def _rpc(method, params=None, session=None):
    _id[0] += 1
    payload = {"jsonrpc": "2.0", "id": _id[0], "method": method}
    if params is not None:
        payload["params"] = params
    return _post(payload, session)


def _initialize():
    msg, sid = _rpc("initialize", {
        "protocolVersion": "2025-03-26",
        "capabilities": {},
        "clientInfo": {"name": "uemcp-cli", "version": "0.1"},
    })
    if msg is None or "error" in msg:
        raise SystemExit(f"initialize failed: {msg}")
    # notifications/initialized has no id
    headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
    if sid:
        headers["Mcp-Session-Id"] = sid
    req = urllib.request.Request(URL, data=json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}).encode(), headers=headers)
    try:
        urllib.request.urlopen(req, timeout=TIMEOUT).read()
    except urllib.error.HTTPError:
        pass
    if sid:
        with open(SESSION_FILE, "w") as f:
            f.write(sid)
    return sid


def _session():
    if os.path.exists(SESSION_FILE):
        return open(SESSION_FILE).read().strip() or None
    return None


def rpc(method, params=None):
    """JSON-RPC call with automatic (re)initialisation of the session."""
    sid = _session()
    if sid is None:
        sid = _initialize()
    try:
        msg, _ = _rpc(method, params, sid)
    except urllib.error.HTTPError as e:
        if e.code in (400, 404):  # unknown/expired session
            sid = _initialize()
            msg, _ = _rpc(method, params, sid)
        else:
            raise
    if msg is not None and "error" in msg and "session" in json.dumps(msg["error"]).lower():
        sid = _initialize()
        msg, _ = _rpc(method, params, sid)
    return msg


def print_result(msg):
    if msg is None:
        print("(no response)")
        return 1
    if "error" in msg:
        print("JSON-RPC error:", json.dumps(msg["error"], indent=1))
        return 1
    res = msg["result"]
    rc = 1 if res.get("isError") else 0
    content = res.get("content")
    if content is None:
        print(json.dumps(res, indent=1))
        return rc
    n = 0
    for block in content:
        t = block.get("type")
        if t == "text":
            txt = block.get("text", "")
            try:
                obj = json.loads(txt)
            except (json.JSONDecodeError, TypeError):
                print(txt)
                continue
            # Inline images: {returnValue:{data,mimeType}} or {returnValue:{image:{data,mimeType}}}
            def _extract(o):
                nonlocal n
                if isinstance(o, dict):
                    if isinstance(o.get("data"), str) and str(o.get("mimeType", "")).startswith("image/") and len(o["data"]) > 256:
                        n += 1
                        ext = "png" if "png" in o["mimeType"] else "jpg"
                        path = f"/tmp/uemcp_{n}.{ext}"
                        with open(path, "wb") as f:
                            f.write(base64.b64decode(o["data"]))
                        o["data"] = f"<{len(o['data'])} b64 chars written to {path}>"
                    for v in o.values():
                        _extract(v)
                elif isinstance(o, list):
                    for v in o:
                        _extract(v)
            _extract(obj)
            print(json.dumps(obj, indent=1))
        elif t == "image":
            n += 1
            path = f"/tmp/uemcp_{n}.png"
            with open(path, "wb") as f:
                f.write(base64.b64decode(block["data"]))
            print(f"[image written to {path}]")
        else:
            print(json.dumps(block, indent=1))
    if rc:
        print("(isError=true)")
    return rc


def _typ(p):
    t = p.get("type")
    if t == "object" and "refPath" in p.get("properties", {}):
        return "ref<" + p.get("title", "obj").split(".")[-1] + ">"
    if t == "array":
        return "[" + _typ(p.get("items", {})) + "]"
    if t == "object" and p.get("properties"):
        return "{" + ",".join(f"{k}:{_typ(v)}" for k, v in p["properties"].items()) + "}"
    if "enum" in p:
        return "|".join(map(str, p["enum"]))
    return t or p.get("title", "any")


def print_signatures(msg):
    if msg is None or "error" in msg:
        return print_result(msg)
    res = msg["result"]
    for block in res.get("content", []):
        if block.get("type") != "text":
            continue
        try:
            d = json.loads(block["text"])
        except json.JSONDecodeError:
            print(block["text"])
            continue
        print(f"# {d.get('name')}: {(d.get('description') or '').strip().splitlines()[0] if d.get('description') else ''}")
        for t in d.get("tools", []):
            schema = t.get("inputSchema", {})
            req = set(schema.get("required", []))
            args = []
            for k, v in schema.get("properties", {}).items():
                args.append(f"{k}{'' if k in req else '?'}:{_typ(v)}")
            out = t.get("outputSchema", {}).get("properties", {}).get("returnValue")
            doc = (t.get("description") or "").strip().splitlines()
            doc = doc[0] if doc else ""
            short = t["name"].split(".")[-1]
            print(f"{short}({', '.join(args)}) -> {_typ(out) if out else 'None'}\n    {doc}")
    return 0


def main(argv):
    if len(argv) < 2:
        print(__doc__)
        return 2
    cmd = argv[1]
    if cmd == "toolsets":
        msg = rpc("tools/call", {"name": "list_toolsets", "arguments": {}})
    elif cmd == "describe":
        msg = rpc("tools/call", {"name": "describe_toolset", "arguments": {"toolset_name": argv[2]}})
    elif cmd == "sig":
        msg = rpc("tools/call", {"name": "describe_toolset", "arguments": {"toolset_name": argv[2]}})
        return print_signatures(msg)
    elif cmd == "call":
        toolset, tool = argv[2], argv[3]
        raw = argv[4] if len(argv) > 4 else "{}"
        if raw.startswith("@"):
            raw = open(raw[1:]).read()
        args = json.loads(raw) if raw.strip() else {}
        msg = rpc("tools/call", {"name": "call_tool", "arguments": {"toolset_name": toolset, "tool_name": tool, "arguments": args}})
    elif cmd == "raw":
        params = json.loads(argv[3]) if len(argv) > 3 else None
        msg = rpc(argv[2], params)
    else:
        print(__doc__)
        return 2
    return print_result(msg)


if __name__ == "__main__":
    sys.exit(main(sys.argv))

"""Bind extracted FBX diffuse PNGs in a fresh UE import folder. Dry run by default.

Not a general material repair tool: apply=True replaces the selected imported
base-material graphs with BaseColor + constant roughness. Do not use on authored
materials. Inspect the source maps first; FBX can itself contain wrong bindings.
"""
from pathlib import Path
from fbx_texture_map import texture_map, normalize_name


def bind(fbx_path, asset_folder, apply=False, roughness=.8, nanite=False, instanced=False, texture_dir=None):
    import unreal as u
    if not 0 <= roughness <= 1:
        raise ValueError('Roughness must be between 0 and 1')
    folder = asset_folder.rstrip('/')
    if not folder.startswith('/Game/'):
        raise ValueError('Choose a dedicated imported-asset folder under /Game/')
    source = Path(fbx_path)
    mapping = texture_map(source)
    extracted = Path(texture_dir) if texture_dir is not None else source.with_suffix('.fbm')
    materials = {}
    for path in u.EditorAssetLibrary.list_assets(folder, recursive=False):
        asset = u.load_asset(path)
        if isinstance(asset, u.StaticMesh):
            for slot in asset.static_materials:
                mat = slot.material_interface
                if not mat or not mat.get_path_name().startswith(folder + '/'):
                    continue  # Never rewrite a shared material outside this import folder.
                if isinstance(mat, u.Material):
                    materials[mat.get_path_name()] = mat
                else:
                    raise ValueError('Material instance needs manual handling: ' + mat.get_path_name())
    if not materials:
        raise ValueError('No mesh-owned base materials found in ' + folder)
    plan = []
    for path, mat in sorted(materials.items()):
        filename = mapping.get(normalize_name(mat.get_name()))
        if not filename:
            raise ValueError('No diffuse FBX connection for ' + path)
        image_file = extracted / filename
        if not image_file.is_file():
            raise FileNotFoundError(image_file)
        plan.append({'material': path, 'source': str(image_file),
                     'texture': folder + '/T_' + normalize_name(mat.get_name())})
    if not apply:
        return {'applied': False, 'bindings': plan}
    # Validate all mappings/files before the first material mutation. Texture imports
    # are reversible; finish checking texture types before replacing any graph.
    textures = {}
    for item in plan:
        texture = u.load_asset(item['texture']) if u.EditorAssetLibrary.does_asset_exist(item['texture']) else None
        if texture is None:
            task = u.AssetImportTask()
            task.filename = item['source']
            task.destination_path = folder
            task.destination_name = item['texture'].rsplit('/', 1)[-1]
            task.automated = True
            task.save = True
            u.AssetToolsHelpers.get_asset_tools().import_asset_tasks([task])
            texture = u.load_asset(item['texture'])
        if not isinstance(texture, u.Texture2D):
            raise ValueError('Texture import failed: ' + item['source'])
        if texture.get_editor_property('compression_settings') == u.TextureCompressionSettings.TC_NORMALMAP:
            raise ValueError('Diffuse connection points to a normal map; inspect/fix source: ' + item['source'])
        textures[item['material']] = texture
    edit = u.MaterialEditingLibrary
    for item in plan:
        mat = materials[item['material']]
        edit.delete_all_material_expressions(mat)
        sample = edit.create_material_expression(mat, u.MaterialExpressionTextureSample, -300, 0)
        sample.set_editor_property('texture', textures[item['material']])
        assert edit.connect_material_property(sample, 'RGB', u.MaterialProperty.MP_BASE_COLOR)
        value = edit.create_material_expression(mat, u.MaterialExpressionConstant, -300, 140)
        value.set_editor_property('r', roughness)
        assert edit.connect_material_property(value, '', u.MaterialProperty.MP_ROUGHNESS)
        if nanite:
            edit.set_base_material_usage(mat, u.MaterialUsage.MATUSAGE_NANITE, True)
        if instanced:
            edit.set_base_material_usage(mat, u.MaterialUsage.MATUSAGE_INSTANCED_STATIC_MESHES, True)
        edit.recompile_material(mat)
        assert u.EditorAssetLibrary.save_loaded_asset(mat, only_if_is_dirty=False)
    return {'applied': True, 'bindings': plan}

#!/usr/bin/env python3
"""Compare ue_scene_audit snapshots; additions and mesh swaps are reported separately."""
import argparse
import json
import math
from pathlib import Path


def close(left, right, tolerance):
    if isinstance(left, (int, float)) and isinstance(right, (int, float)):
        return math.isclose(left, right, rel_tol=0, abs_tol=tolerance)
    if isinstance(left, list) and isinstance(right, list):
        return len(left) == len(right) and all(close(a, b, tolerance) for a, b in zip(left, right))
    if isinstance(left, dict) and isinstance(right, dict):
        return left.keys() == right.keys() and all(close(left[k], right[k], tolerance) for k in left)
    return left == right


def compare(before, after, tolerance=1e-4):
    if before.get('schema') != 1 or after.get('schema') != 1:
        raise ValueError('Expected schema 1 snapshots from ue_scene_audit.py')
    if before['world'] != after['world']:
        raise ValueError('World paths differ; do not compare unrelated levels')
    old, new = before['actors'], after['actors']
    result = {'added': sorted(new.keys() - old.keys()), 'removed': sorted(old.keys() - new.keys()),
              'placement_changes': [], 'component_changes': [], 'mesh_swaps': []}
    for key in old.keys() & new.keys():
        a, b = old[key], new[key]
        if not close(a['transform'], b['transform'], tolerance):
            result['placement_changes'].append(key)
        ac, bc = a['components'], b['components']
        if ac.keys() != bc.keys():
            result['component_changes'].append({'actor': key, 'change': 'component names'})
        for name in ac.keys() & bc.keys():
            x, y = ac[name], bc[name]
            if x['mesh'] != y['mesh']:
                result['mesh_swaps'].append({'actor': key, 'component': name, 'before': x['mesh'], 'after': y['mesh']})
            for field in ['world_transform', 'count', 'overrides', 'instance_transform_hash']:
                if not close(x.get(field), y.get(field), tolerance):
                    result['component_changes'].append({'actor': key, 'component': name, 'change': field})
    result['preserved_existing_placements'] = not any(result[k] for k in ['removed', 'placement_changes', 'component_changes'])
    return result


def main():
    p = argparse.ArgumentParser(description=__doc__)
    p.add_argument('before', type=Path)
    p.add_argument('after', type=Path)
    p.add_argument('--tolerance', type=float, default=1e-4, help='Absolute tolerance; positions are UE units')
    args = p.parse_args()
    if args.tolerance < 0:
        p.error('Tolerance must be nonnegative')
    result = compare(json.loads(args.before.read_text()), json.loads(args.after.read_text()), args.tolerance)
    print(json.dumps(result, indent=2))
    raise SystemExit(0 if result['preserved_existing_placements'] else 1)


if __name__ == '__main__':
    main()

#!/bin/bash
# Run an Unreal console command (e.g. a `py ...` line) through the editor's status-bar Cmd box,
# using SlateInspectorToolset, and retry until the editor log confirms it executed.
#
# usage: tools/ue_console.sh '<command>' [project log path]
# env:   UEMCP_CMDBOX_REF  (default tb2)  ref of the Cmd textbox from Snapshot("sp1")
#
# Quirks handled (UE 5.8.2): first typed character is duplicated (we prefix a space), submit
# only lands every other attempt (we press Escape and retry), text appends (a stray submit
# flushes leftovers). Python calls emit a unique completion/error marker. A Python
# error is never retried: earlier statements may already have changed the project.
# This targets the editor Cmd box and presses Escape. Do not use during PIE.
set -u
if [ "$#" -lt 1 ]; then echo "usage: $0 '<console command>' [project log]" >&2; exit 2; fi
CMD="$1"; LOG="${2:-}"
ORIGINAL_CMD="$CMD"
HERE="$(cd "$(dirname "$0")" && pwd)"
REF="${UEMCP_CMDBOX_REF:-}"
if [ -z "$REF" ]; then  # find the status-bar textbox (bottom of the main window, wide) from a fresh snapshot
  python3 "$HERE/uemcp.py" call SlateInspectorToolset.SlateInspectorToolset Observe '{"ref":"","maxDepth":40}' >/dev/null
  REF=$(python3 "$HERE/uemcp.py" call SlateInspectorToolset.SlateInspectorToolset Snapshot '{"ref":"","maxDepth":40}' | python3 -c '
import sys,json,re; t=json.load(sys.stdin)["returnValue"]; candidates=[]
for l in t.split("\n"):
    m=re.search(r"textbox \[pos=(\d+),(\d+) size=(\d+),\d+\] \[ref=(\w+)\]", l)
    if m and int(m.group(3))>150: candidates.append((int(m.group(2)),m.group(4)))
if candidates: print(max(candidates)[1])')
  REF="${REF:-tb2}"
fi
if [ -z "$LOG" ]; then LOG=$(ls -t "$HOME"/Unreal\ Projects/*/Saved/Logs/*.log 2>/dev/null | head -1); fi
if [ ! -r "$LOG" ]; then echo "Pass the running project's readable editor log as argument 2." >&2; exit 2; fi
BEFORE_BYTES=$(stat -c %s "$LOG")
# Slate may insert several leading spaces; Unreal preserves them after Cmd:.
# Compare complete commands after trimming only surrounding whitespace.
dispatched() {
  tail -c +$((BEFORE_BYTES + 1)) "$LOG" | python3 -c 'import sys
command=sys.argv[1].strip()
seen=any("Cmd:" in line and line.split("Cmd:",1)[1].strip()==command for line in sys.stdin)
sys.exit(0 if seen else 1)' "$CMD"
}
ACK="UE_CONSOLE_DONE_${$}_${RANDOM}"
IS_PYTHON=false
if [[ "$CMD" == "py "* ]]; then
  IS_PYTHON=true
  CMD=$(python3 -c 'import sys
source=sys.argv[1][3:]; marker=sys.argv[2]
wrapped="import traceback\ntry:\n    exec("+repr(source)+", globals())\nexcept BaseException:\n    traceback.print_exc()\n    print("+repr(marker+" ERROR")+")\nelse:\n    print("+repr(marker+" OK")+")"
print("py exec("+repr(wrapped)+")")' "$CMD" "$ACK")
fi
ARGS_FILE=$(mktemp "${TMPDIR:-/tmp}/ue-console.XXXXXX.json")
trap 'rm -f "$ARGS_FILE"' EXIT
for i in 1 2 3 4 5 6; do
  python3 "$HERE/uemcp.py" call SlateInspectorToolset.SlateInspectorToolset PressKey '{"key":"Escape"}' >/dev/null || exit 1
  python3 -c 'import json,sys; print(json.dumps({"ref":sys.argv[1],"text":" "+sys.argv[2],"submit":True}))' "$REF" "$CMD" > "$ARGS_FILE"
  if ! python3 "$HERE/uemcp.py" call SlateInspectorToolset.SlateInspectorToolset Type "@$ARGS_FILE" >/dev/null; then
    echo "Submission status uncertain; inspect the editor log before retrying." >&2; exit 1
  fi
  sleep 2
  if [ "$(stat -c %s "$LOG")" -lt "$BEFORE_BYTES" ]; then
    echo "Editor log was rotated/truncated; inspect it before retrying." >&2; exit 1
  fi
  if "$IS_PYTHON"; then
    # Match the emitted LogPython line, never the source echoed in a Cmd line.
    if tail -c +$((BEFORE_BYTES + 1)) "$LOG" | grep -a -F "LogPython: $ACK ERROR" >/dev/null; then
      echo "Python failed; partial changes may exist. See $LOG. Not retrying." >&2; exit 1
    fi
    if tail -c +$((BEFORE_BYTES + 1)) "$LOG" | grep -a -F "LogPython: $ACK OK" >/dev/null; then
      echo "completed (try $i): $ORIGINAL_CMD"; exit 0
    fi
    if dispatched || tail -c +$((BEFORE_BYTES + 1)) "$LOG" | grep -a -F 'LogPython: Error:' >/dev/null; then
      echo "Python dispatch/error seen without completion. Inspect $LOG; not retrying." >&2; exit 1
    fi
  elif dispatched; then
    echo "submitted (try $i): $ORIGINAL_CMD"; exit 0
  fi
done
echo "No completion acknowledgement. Inspect the editor log before retrying: $ORIGINAL_CMD" >&2; exit 1

#!/usr/bin/env python3
"""Summarize numeric frame rows from UE CSV Profiler captures (no dependencies)."""
import argparse
import csv
import json
import math
import statistics
from pathlib import Path


def summarize(path, columns, start=0, stop=None):
    with Path(path).open(newline='', encoding='utf-8-sig') as stream:
        reader = csv.DictReader(stream)
        missing = set(columns) - set(reader.fieldnames or [])
        if missing:
            raise ValueError(f'{path}: missing columns {sorted(missing)}')
        frames = []
        for row in reader:
            # UE appends metadata after the frame rows. Do not count it as frames.
            try:
                values = {key: float(row[key]) for key in columns}
            except (TypeError, ValueError, KeyError):
                continue
            if all(math.isfinite(value) for value in values.values()):
                frames.append(values)
    sample = frames[start:stop]
    if not sample:
        raise ValueError(f'{path}: no frames in requested slice')
    result = {'file': str(path), 'total_frames': len(frames),
              'sample_start': start, 'sample_count': len(sample), 'columns': {}}
    for key in columns:
        values = sorted(row[key] for row in sample)
        result['columns'][key] = {
            'mean': statistics.mean(values), 'median': statistics.median(values),
            'p95': values[max(0, math.ceil(len(values) * .95) - 1)],
            'min': values[0], 'max': values[-1],
        }
    return result


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('captures', nargs='+', type=Path)
    parser.add_argument('--columns', nargs='+', default=['FrameTime', 'GPUTime', 'GameThreadTime'])
    parser.add_argument('--start', type=int, default=0, help='First numeric frame index, inclusive')
    parser.add_argument('--stop', type=int, help='Last numeric frame index, exclusive')
    parser.add_argument('--output', type=Path, help='JSON destination; otherwise stdout')
    args = parser.parse_args()
    if args.start < 0 or (args.stop is not None and args.stop <= args.start):
        parser.error('Require 0 <= start < stop')
    result = [summarize(p, args.columns, args.start, args.stop) for p in args.captures]
    text = json.dumps(result, indent=2) + '\n'
    if args.output:
        if args.output.resolve() in [p.resolve() for p in args.captures]:
            parser.error('Output must not overwrite a capture')
        args.output.write_text(text)
    else:
        print(text, end='')


if __name__ == '__main__':
    main()

"""Read-only UE editor audit. Import and call audit(output_path, instance_hashes=False).

Audits the currently loaded editor world; never loads, saves, or changes a level.
Triangle counts are LOD0 render data, potentially Nanite fallback, NOT per-frame cost.
"""
import hashlib
import json
from pathlib import Path


def transform(value):
    return {
        'position': [value.translation.x, value.translation.y, value.translation.z],
        'rotation_quaternion': [value.rotation.x, value.rotation.y, value.rotation.z, value.rotation.w],
        'scale': [value.scale3d.x, value.scale3d.y, value.scale3d.z],
    }


def audit(output_path, instance_hashes=False):
    import unreal as u
    world = u.get_editor_subsystem(u.UnrealEditorSubsystem).get_editor_world()
    if not world:
        raise RuntimeError('No editor world loaded')
    if u.get_editor_subsystem(u.UnrealEditorSubsystem).get_game_world():
        raise RuntimeError('Stop PIE before auditing the authored editor world')
    result = {'schema': 1, 'world': world.get_path_name(), 'actors': {}, 'meshes': {},
              'dirty_maps': [p.get_name() for p in u.EditorLoadingAndSavingUtils.get_dirty_map_packages()],
              'dirty_content': [p.get_name() for p in u.EditorLoadingAndSavingUtils.get_dirty_content_packages()]}
    subsystem = u.get_editor_subsystem(u.EditorActorSubsystem)
    for actor in subsystem.get_all_level_actors():
        row = {'label': actor.get_actor_label(), 'class': actor.get_class().get_path_name(),
               'transform': transform(actor.get_actor_transform()), 'components': {}}
        result['actors'][actor.get_path_name()] = row
        for component in actor.get_components_by_class(u.StaticMeshComponent):
            mesh = component.static_mesh
            if not mesh:
                continue
            instanced = isinstance(component, u.InstancedStaticMeshComponent)
            count = component.get_instance_count() if instanced else 1
            item = {'mesh': mesh.get_path_name(), 'world_transform': transform(component.get_world_transform()),
                    'count': count, 'cast_shadow': component.get_editor_property('cast_shadow'),
                    'desired_max_draw_distance': component.get_editor_property('ld_max_draw_distance'),
                    'overrides': [m.get_path_name() if m else None for m in component.get_editor_property('override_materials')]}
            if instanced and instance_hashes:
                digest = hashlib.sha256()
                for index in range(count):
                    value = component.get_instance_transform(index, world_space=False)
                    digest.update(json.dumps(transform(value), sort_keys=True).encode())
                item['instance_transform_hash'] = digest.hexdigest()
            row['components'][component.get_name()] = item
            key = mesh.get_path_name()
            if key not in result['meshes']:
                bounds = mesh.get_bounds()
                result['meshes'][key] = {
                    'lod0_render_triangles': mesh.get_num_triangles(0),
                    'nanite': mesh.get_editor_property('nanite_settings').enabled,
                    'bounds_origin': [bounds.origin.x, bounds.origin.y, bounds.origin.z],
                    'bounds_extent': [bounds.box_extent.x, bounds.box_extent.y, bounds.box_extent.z],
                    'material_slots': [s.material_interface.get_path_name() if s.material_interface else None for s in mesh.static_materials],
                    'instances': 0,
                }
            result['meshes'][key]['instances'] += count
        if isinstance(actor, u.Light):
            row['light'] = {'cast_shadows': actor.light_component.cast_shadows}
    Path(output_path).write_text(json.dumps(result, indent=2, sort_keys=True) + '\n')
    u.log(f'Scene audit saved: {output_path} ({len(result["actors"])} actors)')
    return result