windows-development-sandbox 1.25.0 → 1.27.0

package/dist/guest/toolchains/engines/unity-status.js

@@ -0,0 +1,39 @@
+// tools\unity\status.json: what the sandbox found for Unity, for the guide and the Unity page on the PC. The boot's
+// project step writes its editor choice, the licence step the licence, the daemon the editors; every write keeps what
+// the other parts wrote.
+import path from 'node:path';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
+import { UNITY_STATUS_FILE, UnityStatusSchema } from '../../../shared/unity/index.js';
+import { mkdirp } from '../../runtime/fs.js';
+import { tool } from '../tool-env.js';
+export const UNITY_DIR = tool('unity');
+/** The Unity CLI, one folder per version (unity.exe). */
+export const CLI_DIR = path.join(UNITY_DIR, 'cli');
+/** The editors on the data disk: one folder per version (Editor\Unity.exe). */
+export const EDITORS_DIR = path.join(UNITY_DIR, 'editors');
+/** Asset Store downloads made in the sandbox (assetCache "persisted"). */
+export const ASSET_DIR = path.join(UNITY_DIR, 'asset-store');
+const FILE = path.join(UNITY_DIR, UNITY_STATUS_FILE);
+const EMPTY = {
+    updatedAt: '',
+    cli: null,
+    editors: [],
+    projects: [],
+    licence: { state: 'unknown', kind: '', detail: 'not checked', user: null },
+    assetCache: { mode: 'local', dir: null },
+    pcAssets: [],
+    hub: { installed: false, path: null },
+    mcp: null,
+    skills: false,
+    problem: null,
+};
+export function readUnityStatus() {
+    return readValid(UnityStatusSchema, FILE) ?? EMPTY;
+}
+/** Changes the status with `change` and writes it (whole, atomically). */
+export function updateUnityStatus(change) {
+    const next = { ...change(readUnityStatus()), updatedAt: new Date().toISOString() };
+    mkdirp(UNITY_DIR);
+    writeJsonAtomic(FILE, next);
+    return next;
+}

package/dist/guest/toolchains/engines/unity.d.ts

@@ -1,4 +1,23 @@
+import { type UnityEditor, type WantedEditor } from '../../../shared/unity/index.js';
 import type { Toolchains } from '../../../core/types.js';
 import type { ToolCtx } from '../step.js';
 import type { ToolEnv } from '../tool-env.js';
-export declare function setupUnity(env: ToolEnv, _config: Toolchains['unity'], _ctx: ToolCtx): Promise<void>;
+import { type UnityCli } from './unity-cli.js';
+/** Every editor this sandbox has. */
+export declare function sandboxEditors(ctx: Pick<ToolCtx, 'pcInstalls'>): UnityEditor[];
+/**
+ * The editor a project asks for: its ProjectVersion.txt (read bounded) always wins, since opening a project in another
+ * version upgrades its files; the version the setting names is only for folders without one.
+ */
+export declare function wantedEditor(config: Pick<Toolchains['unity'], 'version'>, workspace: string): WantedEditor | null;
+/** Whether the project's editor is already here (a first install goes to the background). */
+export declare function unityEditorSaved(config: Toolchains['unity'], ctx: Pick<ToolCtx, 'pcInstalls'>): boolean;
+/**
+ * Installs one editor version on the data disk with the CLI (into a staging folder with TEMP inside it) and returns its
+ * folder. One heavy slot while the CLI runs.
+ */
+export declare function ensureUnityEditor(cli: UnityCli, version: string, changeset: string | null, modules: readonly string[], keepVersions: number): Promise<string>;
+/** While the sandbox runs: lists the editors again (the user may have installed one with Hub) for the status. */
+export declare function captureUnityEditors(): Promise<void>;
+/** The editors, the project's choice, the CLI, the licence, the asset cache: set up and written to the status. */
+export declare function setupUnity(env: ToolEnv, config: Toolchains['unity'], ctx: ToolCtx): Promise<void>;

package/dist/guest/toolchains/engines/unity.js

@@ -1,4 +1,251 @@
-import { notAvailableYet } from '../not-yet.js';
-export async function setupUnity(env, _config, _ctx) {
-    notAvailableYet(env, 'Unity');
+// Unity (toolchains.unity), for each project: the Unity CLI on PATH (pinned, checked), every editor the sandbox has
+// (this PC's, read-only, and the data disk's) registered with it, the editor the project's ProjectVersion.txt names
+// (installed on the data disk when nothing has that exact version), UNITY_EDITOR, the Asset Store cache, the licence,
+// Unity Hub when asked and the agent's MCP server and skills. Machine-wide writes only add; a project that joins
+// later only adds its own editor choice. A project is never opened or changed here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from '../../../shared/io/bounded.js';
+import { chooseEditor, editorsAddArgs, findEditors, installArgs, installModulesArgs, installNeedBytes, installPathArgs, unitySummaryLine, wantedVersion, } from '../../../shared/unity/index.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { activateUnityLicence } from '../../accounts/kinds/unity.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { dryRun } from '../../runtime/paths.js';
+import { heavy } from '../../runtime/pools.js';
+import { runScriptWithJsonAsync } from '../../runtime/process.js';
+import { projectWorkspace } from '../../runtime/project-context.js';
+import { session } from '../../runtime/session.js';
+import { setupUnityAgentTools } from '../../setup/unity-agent.js';
+import { ensurePersisted, installRecords } from '../persisted.js';
+import { ensureUnityCli, runUnityCli, runUnityCliChecked } from './unity-cli.js';
+import { ensureUnityHub } from './unity-hub.js';
+import { findUnityRelease } from './unity-release.js';
+import { ASSET_DIR, EDITORS_DIR, readUnityStatus, updateUnityStatus } from './unity-status.js';
+const MAX_PROJECT_VERSION_BYTES = 64 * 1024;
+const MARKER = 'Editor\\Unity.exe';
+const TERMS = 'https://unity.com/legal/terms-of-service';
+const FALLBACK_NEED_BYTES = 15 * 1024 ** 3;
+/** The real disk, for the editor search. */
+const DISK = {
+    exists: (file) => exists(file),
+    list: (dir) => {
+        try {
+            return fs.readdirSync(dir).slice(0, 500);
+        }
+        catch {
+            return []; // Not a folder: nothing in it.
+        }
+    },
+};
+/** This PC's editors the host mapped (session.json's pcInstalls; the id is the version). */
+function mappedEditors(ctx) {
+    return ctx.pcInstalls.items.filter((i) => i.kind === 'unity').map((i) => ({ guest: i.guest, id: i.id }));
+}
+/** Every editor this sandbox has. */
+export function sandboxEditors(ctx) {
+    return findEditors({ mapped: mappedEditors(ctx), dataRoot: EDITORS_DIR }, DISK);
+}
+/**
+ * The editor a project asks for: its ProjectVersion.txt (read bounded) always wins, since opening a project in another
+ * version upgrades its files; the version the setting names is only for folders without one.
+ */
+export function wantedEditor(config, workspace) {
+    const file = path.join(workspace, 'ProjectSettings', 'ProjectVersion.txt');
+    const bytes = readBoundedFile(file, MAX_PROJECT_VERSION_BYTES);
+    return wantedVersion(bytes ? bytes.toString('utf8') : null, config.version);
+}
+/** Whether the project's editor is already here (a first install goes to the background). */
+export function unityEditorSaved(config, ctx) {
+    const wanted = wantedEditor(config, projectWorkspace());
+    if (!wanted)
+        return true;
+    return sandboxEditors(ctx).some((e) => e.version === wanted.version);
+}
+function sizeOf(e) {
+    if (e.origin !== 'data')
+        return null;
+    return installRecords().find((r) => r.name === 'unity/editors' && r.version === e.version)?.sizeBytes ?? null;
+}
+const statusEditor = (e) => ({
+    version: e.version,
+    root: e.root,
+    origin: e.origin,
+    writable: e.writable,
+    modules: [...e.modules],
+    sizeBytes: sizeOf(e),
+});
+/**
+ * Installs one editor version on the data disk with the CLI (into a staging folder with TEMP inside it) and returns its
+ * folder. One heavy slot while the CLI runs.
+ */
+export async function ensureUnityEditor(cli, version, changeset, modules, keepVersions) {
+    const release = await findUnityRelease(version);
+    const cs = changeset ?? release?.changeset ?? null;
+    const need = release ? installNeedBytes(release, modules) : FALLBACK_NEED_BYTES;
+    const installed = await ensurePersisted({ name: 'unity/editors', version, needBytes: need, marker: MARKER, what: 'Unity ' + version, keepVersions }, async (staging, temp) => {
+        log('Installing Unity ' + version + ' on the data disk (several GB; this takes a while) ...');
+        await heavy.run(() => runUnityCliChecked(cli.exe, installArgs(version, cs, modules, staging), { temp }));
+    });
+    return installed.dir;
+}
+/** Adds modules to an editor on the data disk. */
+async function addModules(cli, editor, modules) {
+    const temp = path.join(editor.root, '.temp');
+    mkdirp(temp);
+    try {
+        log('Adding to Unity ' + editor.version + ': ' + modules.join(', ') + ' ...');
+        const args = installModulesArgs(editor.version, modules, editor.root);
+        await heavy.run(() => runUnityCliChecked(cli.exe, args, { temp }));
+    }
+    finally {
+        fs.rmSync(temp, { recursive: true, force: true });
+    }
+}
+/** While the sandbox runs: lists the editors again (the user may have installed one with Hub) for the status. */
+export function captureUnityEditors() {
+    const unity = session.toolchains.unity;
+    if (dryRun || unity.enabled !== true || !exists(EDITORS_DIR))
+        return Promise.resolve();
+    const editors = sandboxEditors({ pcInstalls: session.pcInstalls ?? { items: [] } });
+    const describe = (list) => list.map((e) => e.root + '|' + e.modules.join(',')).join(';');
+    if (describe(editors) !== describe(readUnityStatus().editors))
+        updateUnityStatus((s) => ({ ...s, editors: editors.slice(0, 32).map(statusEditor) }));
+    return Promise.resolve();
+}
+/** The editors, the project's choice, the CLI, the licence, the asset cache: set up and written to the status. */
+export async function setupUnity(env, config, ctx) {
+    if (!config.acceptLicense)
+        throw new Error('Unity is set up only with toolchains.unity.acceptLicense = true: you accept the Unity terms of service (' +
+            TERMS +
+            ') and the editor needs a Unity licence (Personal is free).');
+    const workspace = projectWorkspace();
+    if (dryRun) {
+        log('(dry run) would set up Unity ' + config.version + ' for ' + workspace);
+        return;
+    }
+    const cli = await ensureUnityCli(config.cliVersion);
+    env.prepend.push(path.dirname(cli.exe));
+    let problem = null;
+    const quiet = (what) => (e) => warn('Unity CLI: ' + what + ' (' + errMsg(e) + ')');
+    // Settings that only keep the CLI quiet: a failure is not worth stopping for.
+    await runUnityCli(cli.exe, ['config', 'update-check', 'off'], { timeoutMs: 60_000 }).catch(quiet('update-check'));
+    await runUnityCli(cli.exe, ['analytics', 'opt-out'], { timeoutMs: 60_000 }).catch(quiet('analytics'));
+    mkdirp(EDITORS_DIR);
+    await runUnityCli(cli.exe, installPathArgs(EDITORS_DIR), { timeoutMs: 60_000 }).catch(quiet('install-path'));
+    let editors = sandboxEditors(ctx);
+    if (editors.length)
+        await runUnityCli(cli.exe, editorsAddArgs(editors.map((e) => e.root)), { timeoutMs: 120_000 }).catch(quiet('editors add'));
+    const wanted = wantedEditor(config, workspace);
+    let choice = chooseEditor(editors, wanted, config.modules, true);
+    const install = choice.install;
+    if (install) {
+        try {
+            const { version, changeset } = install;
+            await ensureUnityEditor(cli, version, changeset, config.modules, config.keepVersions);
+            editors = sandboxEditors(ctx);
+            choice = chooseEditor(editors, wanted, config.modules, true);
+        }
+        catch (e) {
+            problem = 'Unity ' + install.version + ' was not installed: ' + errMsg(e);
+            warn(problem);
+        }
+    }
+    let editor = choice.editor;
+    if (editor) {
+        const have = editor.modules;
+        const lack = config.modules.filter((m) => !have.includes(m));
+        if (lack.length && editor.writable) {
+            try {
+                await addModules(cli, editor, lack);
+                editors = sandboxEditors(ctx);
+                const root = editor.root;
+                editor = editors.find((e) => e.root === root) ?? editor;
+            }
+            catch (e) {
+                problem = 'Unity modules were not added: ' + errMsg(e);
+                warn(problem);
+            }
+        }
+        else if (lack.length) {
+            problem =
+                'Unity ' +
+                    editor.version +
+                    ' from this PC has no ' +
+                    lack[0] +
+                    " module: add it with Unity Hub on your PC, or remove that editor from This PC's editors to install one here.";
+            warn(problem);
+        }
+        env.vars.UNITY_EDITOR = editor.exe;
+    }
+    // The Asset Store cache: where downloads made here go (HKCU too, so an editor started from Explorer agrees).
+    // For "pc" the mapped Asset Store folder (guest of the unity-assets item) sits inside the cache root.
+    const pcAssets = ctx.pcInstalls.items.filter((i) => i.kind === 'unity-assets').map((i) => i.guest);
+    let cacheDir = null;
+    if (config.assetCache === 'persisted')
+        cacheDir = mkdirp(ASSET_DIR);
+    else if (config.assetCache === 'pc' && pcAssets[0])
+        cacheDir = path.win32.dirname(pcAssets[0]);
+    if (cacheDir) {
+        env.vars.ASSETSTORE_CACHE_PATH = cacheDir;
+        if (!ctx.duringSession)
+            await runScriptWithJsonAsync('set-registry-values.ps1', 'PlanFile', {
+                values: [{ hive: 'HKCU', key: 'Environment', name: 'ASSETSTORE_CACHE_PATH', value: cacheDir }],
+            }).catch((e) => warn('Unity: the Asset Store cache was not set for Explorer (' + errMsg(e) + ')'));
+    }
+    const licence = await activateUnityLicence({ editorExe: editor?.exe ?? null, unityExe: cli.exe }).catch((e) => {
+        warn('Unity licence: ' + errMsg(e));
+        return readUnityStatus().licence;
+    });
+    let hub = readUnityStatus().hub;
+    if (config.hub)
+        try {
+            hub = { installed: true, path: await ensureUnityHub() };
+        }
+        catch (e) {
+            warn('Unity Hub was not installed: ' + errMsg(e));
+        }
+    const agent = await setupUnityAgentTools({
+        unityExe: cli.exe,
+        projectPath: workspace,
+        mcp: config.mcp,
+        skills: config.agentSkills,
+    }).catch((e) => {
+        warn('Unity agent tools: ' + errMsg(e));
+        return { mcp: null, skills: false };
+    });
+    const chosen = editor;
+    const status = updateUnityStatus((s) => {
+        const mine = s.projects.find((p) => p.workspace.toLowerCase() === workspace.toLowerCase());
+        return {
+            ...s,
+            cli: { version: cli.version, path: cli.exe },
+            editors: editors.slice(0, 32).map(statusEditor),
+            projects: [
+                ...s.projects.filter((p) => p !== mine),
+                {
+                    workspace,
+                    version: wanted?.version ?? null,
+                    editor: chosen?.root ?? null,
+                    reason: choice.reason,
+                    bridge: mine?.bridge ?? null,
+                },
+            ].slice(-64),
+            licence,
+            assetCache: { mode: config.assetCache, dir: cacheDir },
+            pcAssets: pcAssets.slice(0, 4),
+            hub,
+            mcp: agent.mcp ?? (ctx.duringSession ? s.mcp : null),
+            skills: agent.skills || (ctx.duringSession && s.skills),
+            problem,
+        };
+    });
+    env.summary.push(unitySummaryLine(status, workspace));
+    log('Unity: ' +
+        editors.length +
+        ' editor(s); ' +
+        (editor ? editor.version + ' at ' + editor.root : 'none for this project') +
+        ' (' +
+        choice.reason +
+        ')');
 }

package/dist/guest/toolchains/engines/unreal-engines.d.ts

@@ -1,4 +1,24 @@
+import { type EngineFs, type LauncherEntry, type MappedEngine, type UnrealEngine } from '../../../shared/unreal/index.js';
 import type { Toolchains } from '../../../core/types.js';
 import type { ToolCtx } from '../step.js';
 import type { ToolEnv } from '../tool-env.js';
-export declare function setupUnrealEngines(env: ToolEnv, _config: Toolchains['unreal'], _ctx: ToolCtx): Promise<void>;
+/** The real disk, read bounded. */
+export declare const DISK: EngineFs;
+/** This PC's engines the host mapped (session.json's pcInstalls). */
+export declare function mappedEngines(ctx: Pick<ToolCtx, 'pcInstalls'>): MappedEngine[];
+/** Every engine this sandbox has (an install the launcher has not finished is not one yet). */
+export declare function sandboxEngines(ctx: Pick<ToolCtx, 'pcInstalls'>, disk?: EngineFs): UnrealEngine[];
+/** The LauncherInstalled.dat entries for the installed builds: the launcher's own saved ones, else made from them. */
+export declare function launcherEntries(engines: readonly UnrealEngine[], ctx: Pick<ToolCtx, 'pcInstalls'>): LauncherEntry[];
+/** Registers the engines machine-wide: the registry, LauncherInstalled.dat, the .uproject file association. */
+export declare function registerEngines(engines: readonly UnrealEngine[], selectorFrom: UnrealEngine | null, ctx: Pick<ToolCtx, 'pcInstalls'>, aliases?: readonly {
+    readonly id: string;
+    readonly dir: string;
+}[]): Promise<void>;
+/**
+ * While the sandbox runs (the daemon, every few minutes): saves what the launcher learned about engines it installed
+ * on the data disk and, when something is new, registers them and lists them for the Unreal page.
+ */
+export declare function captureLauncherEngines(): Promise<void>;
+/** The project's engine on PATH, its variables, the guide's facts; the engines registered. */
+export declare function setupUnrealEngines(env: ToolEnv, config: Toolchains['unreal'], ctx: ToolCtx): Promise<void>;

package/dist/guest/toolchains/engines/unreal-engines.js

@@ -1,4 +1,164 @@
-import { notAvailableYet } from '../not-yet.js';
-export async function setupUnrealEngines(env, _config, _ctx) {
-    notAvailableYet(env, 'Unreal engines');
+// Unreal engines, for each project: every engine the sandbox has (this PC's, mapped read-only or as folders you
+// registered; the launcher's and other folders in tools\unreal\engines; source builds in project roots) is registered
+// (the registry, the launcher's LauncherInstalled.dat, the .uproject file association), and the engine the project's
+// .uproject names (else the newest) goes on its PATH with UE_ROOT, the derived data cache on the data disk and, with
+// Unreal 5.8's MCP plugin, the editor's MCP server in Claude Code. Machine-wide writes only add; a project that joins
+// later only adds its own engine choice.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readBoundedFile } from '../../../shared/io/bounded.js';
+import { chooseEngine, ddcVars, engineExtraDirs, engineToolDirs, engineVars, fileAssociationPlan, findEngines, findUproject, hasMcpPlugin, incompleteDirs, itemSizes, launcherManifestsDir, launcherEntriesFor, registryPlan, UNREAL_MCP_URL, unrealSummaryLine, uprojectAssociation, versionSelectorIn, versionText, } from '../../../shared/unreal/index.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { exists, mkdirp } from '../../runtime/fs.js';
+import { log, warn } from '../../runtime/log.js';
+import { dryRun } from '../../runtime/paths.js';
+import { runScriptWithJsonAsync } from '../../runtime/process.js';
+import { projectWorkspace } from '../../runtime/project-context.js';
+import { session } from '../../runtime/session.js';
+import { setUnrealMcp, writeAddonMcpServers } from '../../setup/addon-mcp.js';
+import { saveLauncherState, savedEntries, writeLauncherEntries } from './epic-launcher.js';
+import { DDC_DIR, ENGINES_DIR, SAVED_DIR, updateUnrealStatus } from './unreal-status.js';
+const SAVED_MANIFESTS = path.join(SAVED_DIR, 'Manifests');
+/** The real disk, read bounded. */
+export const DISK = {
+    exists: (file) => exists(file),
+    read: (file, max) => readBoundedFile(file, max),
+    list: (dir) => {
+        try {
+            return fs.readdirSync(dir).slice(0, 500);
+        }
+        catch {
+            return []; // Not a folder: nothing in it.
+        }
+    },
+};
+/** This PC's engines the host mapped (session.json's pcInstalls). */
+export function mappedEngines(ctx) {
+    return ctx.pcInstalls.items
+        .filter((i) => i.kind === 'unreal')
+        .map((i) => ({
+        guest: i.guest,
+        id: i.id,
+        ...(i.writable ? { writable: true } : {}),
+        ...(i.buildId ? { buildId: i.buildId } : {}),
+    }));
+}
+/** The project roots of this sandbox (their folders may hold source builds). */
+function projectRoots() {
+    const roots = (session.mappedProjects ?? []).filter((m) => m.root).map((m) => m.guest);
+    return [...new Set([...roots, ...(session.roots ?? [])])].filter((r) => exists(r));
+}
+/** The engines the launcher installed in tools\unreal\engines (its saved manifests and entries name them). */
+function launcherDirs() {
+    return [...savedEntries().map((e) => e.InstallLocation), ...itemSizes(SAVED_MANIFESTS).keys()];
+}
+/** Every engine this sandbox has (an install the launcher has not finished is not one yet). */
+export function sandboxEngines(ctx, disk = DISK) {
+    const incomplete = incompleteDirs(launcherManifestsDir(process.env.ProgramData ?? 'C:\\ProgramData'), SAVED_MANIFESTS);
+    return findEngines({
+        mapped: mappedEngines(ctx),
+        enginesRoot: ENGINES_DIR,
+        launcherDirs: launcherDirs(),
+        projectRoots: projectRoots(),
+    }, disk).filter((e) => !incomplete.has(path.win32.normalize(e.dir).toLowerCase()));
+}
+/** The LauncherInstalled.dat entries for the installed builds: the launcher's own saved ones, else made from them. */
+export function launcherEntries(engines, ctx) {
+    return launcherEntriesFor(engines, savedEntries(), ctx.pcInstalls.items);
+}
+/** Registers the engines machine-wide: the registry, LauncherInstalled.dat, the .uproject file association. */
+export async function registerEngines(engines, selectorFrom, ctx, aliases = []) {
+    const selector = selectorFrom ? versionSelectorIn(selectorFrom.dir) : null;
+    const values = [
+        ...registryPlan(engines, aliases),
+        ...(selector && exists(selector) ? fileAssociationPlan(selector) : []),
+    ];
+    if (values.length)
+        await runScriptWithJsonAsync('set-registry-values.ps1', 'PlanFile', { values });
+    try {
+        writeLauncherEntries(launcherEntries(engines, ctx));
+    }
+    catch (e) {
+        warn("Unreal: the Epic Games Launcher's LauncherInstalled.dat was left as it is (" + errMsg(e) + ')');
+    }
+}
+/**
+ * While the sandbox runs (the daemon, every few minutes): saves what the launcher learned about engines it installed
+ * on the data disk and, when something is new, registers them and lists them for the Unreal page.
+ */
+export async function captureLauncherEngines() {
+    const unreal = session.toolchains.unreal;
+    if (dryRun || unreal.enabled !== true || !unreal.persistEngines || !saveLauncherState())
+        return;
+    const ctx = { pcInstalls: session.pcInstalls ?? { items: [] } };
+    const engines = sandboxEngines(ctx);
+    await registerEngines(engines, engines[0] ?? null, ctx);
+    const sizes = itemSizes(SAVED_MANIFESTS);
+    updateUnrealStatus((s) => ({ ...s, engines: engines.map((e) => statusEngine(e, sizes)) }));
+}
+const statusEngine = (e, sizes) => ({
+    id: e.id,
+    dir: e.dir,
+    version: versionText(e.version),
+    build: e.build,
+    origin: e.origin,
+    writable: e.writable,
+    sizeBytes: sizes.get(e.dir.toLowerCase()) ?? null,
+});
+/** The project's engine on PATH, its variables, the guide's facts; the engines registered. */
+export async function setupUnrealEngines(env, config, ctx) {
+    const workspace = projectWorkspace();
+    const engines = sandboxEngines(ctx);
+    const uproject = findUproject(workspace, DISK);
+    const text = uproject ? readBoundedFile(uproject, 1024 * 1024) : null;
+    const association = (text ? uprojectAssociation(text.toString('utf8')) : null) ?? { kind: 'none' };
+    const choice = chooseEngine(engines, association);
+    const engine = choice.engine;
+    if (dryRun) {
+        log('(dry run) would register ' + engines.length + ' Unreal engines and use ' + (engine?.dir ?? 'none'));
+        return;
+    }
+    try {
+        await registerEngines(engines, engine ?? engines[0] ?? null, ctx, engine && choice.alias ? [{ id: choice.alias, dir: engine.dir }] : []);
+    }
+    catch (e) {
+        warn('Unreal: registering the engines failed (' + errMsg(e) + '); Build.bat and RunUAT.bat still work from PATH');
+    }
+    const ddc = config.derivedDataCache === 'persisted' ? mkdirp(DDC_DIR) : null;
+    Object.assign(env.vars, ddcVars(config.derivedDataCache, DDC_DIR));
+    if (engine) {
+        env.prepend.push(...engineToolDirs(engine.dir, DISK));
+        env.append.push(...engineExtraDirs(engine.dir, DISK));
+        Object.assign(env.vars, engineVars(engine));
+    }
+    const mcp = engine && hasMcpPlugin(engine, DISK) ? UNREAL_MCP_URL : null;
+    if (mcp || !ctx.duringSession) {
+        setUnrealMcp(mcp);
+        try {
+            writeAddonMcpServers();
+        }
+        catch (e) {
+            warn("Unreal: the editor's MCP server was not added to Claude Code (" + errMsg(e) + ')');
+        }
+    }
+    const sizes = itemSizes(SAVED_MANIFESTS);
+    const status = updateUnrealStatus((s) => ({
+        ...s,
+        engines: engines.map((e) => statusEngine(e, sizes)),
+        projects: [
+            ...s.projects.filter((p) => p.workspace.toLowerCase() !== workspace.toLowerCase()),
+            { workspace, engine: engine?.dir ?? null, reason: choice.reason },
+        ].slice(-64),
+        ddc: { mode: config.derivedDataCache, dir: ddc },
+        vaults: ctx.pcInstalls.items.filter((i) => i.kind === 'unreal-vault').map((i) => i.guest),
+        mcpUrl: mcp ?? (ctx.duringSession ? s.mcpUrl : null),
+    }));
+    env.summary.push(unrealSummaryLine(status, workspace));
+    log('Unreal: ' +
+        engines.length +
+        ' engine(s); ' +
+        (engine ? 'this project uses ' + engine.id + ' at ' + engine.dir : 'none for this project') +
+        ' (' +
+        choice.reason +
+        ')');
 }

package/dist/guest/toolchains/engines/unreal-status.d.ts

@@ -0,0 +1,13 @@
+import { type UnrealStatus } from '../../../shared/unreal/index.js';
+export declare const UNREAL_DIR: string;
+/** Where the Epic Games Launcher installs engines (persistEngines). */
+export declare const ENGINES_DIR: string;
+/** The engines' local derived data cache (derivedDataCache "persisted"). */
+export declare const DDC_DIR: string;
+/** The launcher's manifests and entries of the engines in ENGINES_DIR, kept for later boots. */
+export declare const SAVED_DIR: string;
+export declare function readUnrealStatus(): UnrealStatus;
+/** Changes the status with `change` and writes it (whole, atomically). */
+export declare function updateUnrealStatus(change: (s: UnrealStatus) => UnrealStatus): UnrealStatus;
+/** A fresh status at boot: the machine parts start over, the engines and projects are found again. */
+export declare function resetUnrealStatus(): void;

package/dist/guest/toolchains/engines/unreal-status.js

@@ -0,0 +1,41 @@
+// tools\unreal\status.json: what the sandbox found for Unreal, for the guide and the Unreal page on the PC. The boot's
+// machine-wide step writes the launcher, Visual Studio and debugger parts, each project's step its engine; every write
+// keeps what the other parts wrote.
+import path from 'node:path';
+import { readValid, writeJsonAtomic } from '../../../shared/io/json.js';
+import { UNREAL_STATUS_FILE, UnrealStatusSchema } from '../../../shared/unreal/index.js';
+import { mkdirp } from '../../runtime/fs.js';
+import { tool } from '../tool-env.js';
+export const UNREAL_DIR = tool('unreal');
+/** Where the Epic Games Launcher installs engines (persistEngines). */
+export const ENGINES_DIR = path.join(UNREAL_DIR, 'engines');
+/** The engines' local derived data cache (derivedDataCache "persisted"). */
+export const DDC_DIR = path.join(UNREAL_DIR, 'ddc');
+/** The launcher's manifests and entries of the engines in ENGINES_DIR, kept for later boots. */
+export const SAVED_DIR = path.join(UNREAL_DIR, 'launcher');
+const FILE = path.join(UNREAL_DIR, UNREAL_STATUS_FILE);
+const EMPTY = {
+    updatedAt: '',
+    engines: [],
+    projects: [],
+    launcher: { installed: false, installLocation: null, problem: null, freeBytes: null, needBytes: 0 },
+    visualStudio: { version: '', path: '', how: '', check: '', ok: false },
+    debugger: null,
+    ddc: { mode: 'local', dir: null },
+    vaults: [],
+    mcpUrl: null,
+};
+export function readUnrealStatus() {
+    return readValid(UnrealStatusSchema, FILE) ?? EMPTY;
+}
+/** Changes the status with `change` and writes it (whole, atomically). */
+export function updateUnrealStatus(change) {
+    const next = { ...change(readUnrealStatus()), updatedAt: new Date().toISOString() };
+    mkdirp(UNREAL_DIR);
+    writeJsonAtomic(FILE, next);
+    return next;
+}
+/** A fresh status at boot: the machine parts start over, the engines and projects are found again. */
+export function resetUnrealStatus() {
+    updateUnrealStatus(() => EMPTY);
+}

package/dist/guest/toolchains/native/debuggers.d.ts

@@ -0,0 +1,6 @@
+/** KitsRoot10 from the registry (64-bit view), or null. */
+export declare function kitsRoot(): string | null;
+/** The debuggers' x64 folder when cdb.exe is in it, else null. */
+export declare function debuggersDir(root?: string | null): string | null;
+/** The debuggers' folder, installed with the SDK installer when missing; null when there is no SDK to add them to. */
+export declare function ensureDebuggers(): Promise<string | null>;

package/dist/guest/toolchains/native/debuggers.js

@@ -0,0 +1,57 @@
+// The Windows SDK's Debugging Tools (cdb, windbg, kd) for reading Unreal crash dumps: not part of the SDK Visual Studio
+// installs, so the Windows SDK installer (downloaded once into tools\visualstudio, Microsoft's signature checked) adds
+// only that feature into the SDK the registry names (KitsRoot10). Visual Studio kept on the data disk has its SDK
+// there, so the debuggers are installed once and come back with it (~45 s, 370 MB).
+import path from 'node:path';
+import { SYSTEM } from '../../../shared/system.js';
+import { runInstaller } from '../../runtime/pools.js';
+import { execOutput } from '../../runtime/process.js';
+import { exists } from '../../runtime/fs.js';
+import { log } from '../../runtime/log.js';
+import { SIGNERS, signedInstaller } from '../installers.js';
+import { tool } from '../tool-env.js';
+/** The Windows SDK 10.0.22621 installer (the SDK version Visual Studio's Unreal components install). */
+const SDK_SETUP_URL = 'https://go.microsoft.com/fwlink/?linkid=2311806';
+const SDK_SETUP = tool('visualstudio', 'winsdksetup-22621.exe');
+/** KitsRoot10 from the registry (64-bit view), or null. */
+export function kitsRoot() {
+    const out = execOutput(SYSTEM.reg(), [
+        'query',
+        'HKLM\\SOFTWARE\\Microsoft\\Windows Kits\\Installed Roots',
+        '/v',
+        'KitsRoot10',
+        '/reg:64',
+    ]);
+    const m = /KitsRoot10\s+REG_SZ\s+(.+)$/im.exec(out);
+    return m ? m[1].trim() : null;
+}
+/** The debuggers' x64 folder when cdb.exe is in it, else null. */
+export function debuggersDir(root = kitsRoot()) {
+    if (!root)
+        return null;
+    const dir = path.join(root, 'Debuggers', 'x64');
+    return exists(path.join(dir, 'cdb.exe')) ? dir : null;
+}
+/** The debuggers' folder, installed with the SDK installer when missing; null when there is no SDK to add them to. */
+export async function ensureDebuggers() {
+    const root = kitsRoot();
+    if (!root)
+        return null;
+    const have = debuggersDir(root);
+    if (have)
+        return have;
+    const setup = await signedInstaller(SDK_SETUP_URL, SDK_SETUP, 'the Windows SDK installer, for its debuggers (~1.5 MB, then ~100 MB)', SIGNERS.microsoft);
+    log('Installing the Windows SDK debuggers (cdb, windbg) into ' + root + ' ...');
+    const code = await runInstaller(setup, [
+        '/features',
+        'OptionId.WindowsDesktopDebuggers',
+        '/quiet',
+        '/norestart',
+        '/ceip',
+        'off',
+    ]);
+    const dir = debuggersDir(root);
+    if (!dir)
+        throw new Error('the Windows SDK installer did not add the debuggers (exit ' + code + ')');
+    return dir;
+}