windows-development-sandbox 1.23.2 → 1.25.1

package/dist/shared/unreal/engines.d.ts

@@ -0,0 +1,161 @@
+/** Where an engine came from, which decides whether it is writable and how it is listed. */
+export type EngineOrigin = 
+/** Installed on this PC, mapped read-only under C:\PcInstalls\unreal (pcInstalls.unrealEngines). */
+'pc'
+/** A folder of this PC you registered (pcInstalls.unrealEngineFolders), mapped writable. */
+ | 'pc-folder'
+/** Installed by the Epic Games Launcher in a sandbox, in tools\unreal\engines on the data disk. */
+ | 'launcher'
+/** Another engine folder in tools\unreal\engines (a source build or a copy). */
+ | 'data'
+/** A source build found in a project root (C:\Projects\<root>\<folder>). */
+ | 'project';
+export declare const ORIGIN_LABELS: Readonly<Record<EngineOrigin, string>>;
+export interface BuildVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly changelist: number;
+    readonly branch: string;
+}
+/** One engine the sandbox knows. */
+export interface UnrealEngine {
+    /** UE_5.4 for an installed build; the source build's registered name (a GUID or a plain name). */
+    readonly id: string;
+    /** The engine's folder (holds Engine\Build\Build.version). */
+    readonly dir: string;
+    readonly version: BuildVersion;
+    /** "installed": a launcher or installed build (InstalledBuild.txt); "source": built from the engine's source. */
+    readonly build: 'installed' | 'source';
+    readonly origin: EngineOrigin;
+    readonly writable: boolean;
+}
+/** How engine files are read: bounded reads, folder lists, existence. */
+export interface EngineFs {
+    exists(file: string): boolean;
+    /** At most `max` bytes, null when it is missing, too big or not a file. */
+    read(file: string, max: number): Buffer | null;
+    /** The names in a folder ([] when it is not one). */
+    list(dir: string): string[];
+}
+/** Engine\Build\Build.version: the version of an engine folder, or null when the text is not one. */
+export declare function parseBuildVersion(text: string): BuildVersion | null;
+/** "5.4": the name the launcher and the registry give an engine version. */
+export declare const majorMinor: (v: BuildVersion) => string;
+/** "5.4.4": the full version for people. */
+export declare const versionText: (v: BuildVersion) => string;
+/** "UE_5.4": the launcher's app name (and the folder it installs into). */
+export declare const launcherAppName: (v: BuildVersion) => string;
+export declare function compareVersions(a: BuildVersion, b: BuildVersion): number;
+/** Engine\Build\Build.version of a folder, or null when it is not an engine. */
+export declare function readEngineVersion(dir: string, fs: EngineFs): BuildVersion | null;
+/** Whether an engine folder is an installed build (what the launcher installs): Engine\Build\InstalledBuild.txt. */
+export declare function isInstalledBuild(dir: string, fs: EngineFs): boolean;
+/** Whether a name can be a source build's registered name (UnrealVersionSelector writes a {GUID}). */
+export declare const isBuildId: (id: string) => boolean;
+/**
+ * A source build's registered name when it has none of its own: a GUID made from its folder, so it is the same every
+ * boot and a project that was switched to it keeps finding it.
+ */
+export declare function stableBuildId(dir: string): string;
+/** The engine in a folder, or null when it is not one. `id`: a source build's registered name (else one is made). */
+export declare function engineAt(dir: string, origin: EngineOrigin, writable: boolean, fs: EngineFs, id?: string): UnrealEngine | null;
+/** What the guest knows of this PC's engines (session.json's pcInstalls items of kind "unreal"). */
+export interface MappedEngine {
+    readonly guest: string;
+    readonly id: string;
+    /** A registered folder of this PC: mapped writable. */
+    readonly writable?: boolean;
+    /** A source build's registered name on this PC (HKCU ... Builds), kept so the project's association still matches. */
+    readonly buildId?: string;
+}
+export interface EngineSources {
+    /** Engines of this PC mapped into the sandbox. */
+    readonly mapped: readonly MappedEngine[];
+    /** tools\unreal\engines on the data disk. */
+    readonly enginesRoot: string;
+    /** The folders of the engines the launcher installed there (from its saved manifests). */
+    readonly launcherDirs: readonly string[];
+    /** Project roots in the sandbox (C:\Projects\<root>): their folders are looked at for source builds. */
+    readonly projectRoots: readonly string[];
+}
+/** At most this many engines are used. */
+export declare const MAX_ENGINES = 16;
+/** Every engine the sandbox can use, in a fixed order (this PC's, the data disk's, the project roots'), once each. */
+export declare function findEngines(s: EngineSources, fs: EngineFs): UnrealEngine[];
+export type EngineAssociation = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'version';
+    readonly version: string;
+} | {
+    readonly kind: 'build';
+    readonly id: string;
+};
+/** What a .uproject's EngineAssociation names: "5.4" (an installed build), "{GUID}" or a name (a source build). */
+export declare function parseEngineAssociation(value: unknown): EngineAssociation;
+/** The EngineAssociation of a .uproject's text (null when it is not JSON). */
+export declare function uprojectAssociation(text: string): EngineAssociation | null;
+/** A project's .uproject: in its folder, else one folder down (the first by name), or null. */
+export declare function findUproject(workspace: string, fs: EngineFs): string | null;
+export interface EngineChoice {
+    readonly engine: UnrealEngine | null;
+    /** Why this one, in plain words (or why none). */
+    readonly reason: string;
+    /** The name the project gave a source build that is not registered here by that name: register it for this engine. */
+    readonly alias?: string;
+}
+/**
+ * The engine a project builds with: the one its EngineAssociation names (a version: a writable one before this PC's
+ * read-only one; a build: that registered build), else the newest. Null when the project names one that is not here.
+ */
+export declare function chooseEngine(engines: readonly UnrealEngine[], association: EngineAssociation): EngineChoice;
+/** One registry value the sandbox writes (string values only). */
+export interface RegistryValue {
+    readonly hive: 'HKLM' | 'HKCU';
+    readonly key: string;
+    /** '' is the default value. */
+    readonly name: string;
+    readonly value: string;
+}
+/** Installed builds: where an installer records them (UnrealVersionSelector and the editor read it). */
+export declare const INSTALLED_KEY = "SOFTWARE\\EpicGames\\Unreal Engine";
+/** Source builds: UnrealVersionSelector's list (name = the build's id, value = its folder). */
+export declare const BUILDS_KEY = "Software\\Epic Games\\Unreal Engine\\Builds";
+/**
+ * The installed build of each version that the editor and UnrealVersionSelector use: one per major.minor, chosen the
+ * way chooseEngine chooses (writable before read-only, then the newest).
+ */
+export declare function preferredInstalled(engines: readonly UnrealEngine[]): UnrealEngine[];
+/**
+ * The registry values that make Unreal find the engines: an installed build as HKLM\SOFTWARE\EpicGames\Unreal
+ * Engine\<5.4> InstalledDirectory (one per version: the one a project would pick), a source build as a value under
+ * HKCU\Software\Epic Games\Unreal Engine\Builds. `aliases`: names a project uses for a source build here (its GUID on
+ * this PC), registered for the folder they stand for, so the .uproject works unchanged.
+ */
+export declare function registryPlan(engines: readonly UnrealEngine[], aliases?: readonly {
+    readonly id: string;
+    readonly dir: string;
+}[]): RegistryValue[];
+/** UnrealVersionSelector inside an engine (it opens, switches and generates project files for .uproject files). */
+export declare function versionSelectorIn(dir: string): string;
+/**
+ * The .uproject file association UnrealVersionSelector /fileassociations writes (per user): open in the editor, launch
+ * the game, generate Visual Studio project files, switch the engine version.
+ */
+export declare function fileAssociationPlan(selector: string): RegistryValue[];
+/** The folders of an engine an agent runs its tools from (those that exist), in PATH order. */
+export declare function engineToolDirs(dir: string, fs: Pick<EngineFs, 'exists'>): string[];
+/** The engine folders put at the END of PATH: they hold many DLLs, which every program started from PATH would load. */
+export declare function engineExtraDirs(dir: string, fs: Pick<EngineFs, 'exists'>): string[];
+/** Variables for the project's engine: UE_ROOT (the engine folder) and UE_ENGINE_DIR (its Engine folder). */
+export declare function engineVars(engine: UnrealEngine): Record<string, string>;
+/**
+ * The derived data cache: UE-LocalDataCachePath moves the local cache (and from 5.4 the Zen store, in its Zen
+ * subfolder) out of the engine and off the sandbox's disk. "local" leaves Unreal's own place (the sandbox's disk).
+ */
+export declare function ddcVars(mode: 'persisted' | 'local', ddcDir: string): Record<string, string>;
+/** The editor's MCP server (Unreal 5.8's ModelContextProtocol plugin): its default address. */
+export declare const UNREAL_MCP_URL = "http://127.0.0.1:8000/mcp";
+/** Whether an engine ships the ModelContextProtocol plugin (5.8 and later). */
+export declare function hasMcpPlugin(engine: UnrealEngine, fs: Pick<EngineFs, 'exists'>): boolean;

package/dist/shared/unreal/engines.js

@@ -0,0 +1,308 @@
+// Unreal engines, pure: what an engine folder is (Engine\Build\Build.version; Engine\Build\InstalledBuild.txt makes it
+// an installed build), where the sandbox finds them (this PC read-only, the Epic Games Launcher's folder on the data
+// disk, source builds in a project root or registered by you), which one a project builds with (its .uproject's
+// EngineAssociation, then a writable engine over a read-only one, then the newest), and what the sandbox writes so
+// UnrealBuildTool, UnrealVersionSelector and the editor find them (registry plan) and an agent can run them (PATH,
+// variables, the derived data cache). Every file is read through the EngineFs it is given (bounded): the guest passes
+// the real disk, the self-test its fixtures.
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+const win = path.win32;
+export const ORIGIN_LABELS = {
+    pc: 'this PC, read-only',
+    'pc-folder': 'your folder on this PC',
+    launcher: 'Epic Games Launcher, data disk',
+    data: 'data disk',
+    project: 'in a project folder',
+};
+const BuildVersionSchema = z.object({
+    MajorVersion: z.number().int().min(4).max(99),
+    MinorVersion: z.number().int().min(0).max(99),
+    PatchVersion: z.number().int().min(0).max(999),
+    Changelist: z.number().int().optional(),
+    BranchName: z.string().optional(),
+});
+const stripBom = (text) => text.replace(/^\uFEFF/, '');
+/** Engine\Build\Build.version: the version of an engine folder, or null when the text is not one. */
+export function parseBuildVersion(text) {
+    try {
+        const v = BuildVersionSchema.parse(JSON.parse(stripBom(text)));
+        return {
+            major: v.MajorVersion,
+            minor: v.MinorVersion,
+            patch: v.PatchVersion,
+            changelist: v.Changelist ?? 0,
+            branch: (v.BranchName ?? '').replace(/[^\x20-\x7e]/g, '').slice(0, 100),
+        };
+    }
+    catch {
+        return null; // Not JSON, or not a Build.version.
+    }
+}
+/** "5.4": the name the launcher and the registry give an engine version. */
+export const majorMinor = (v) => v.major + '.' + v.minor;
+/** "5.4.4": the full version for people. */
+export const versionText = (v) => v.major + '.' + v.minor + '.' + v.patch;
+/** "UE_5.4": the launcher's app name (and the folder it installs into). */
+export const launcherAppName = (v) => 'UE_' + majorMinor(v);
+export function compareVersions(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch || a.changelist - b.changelist;
+}
+/** Engine\Build\Build.version of a folder, or null when it is not an engine. */
+export function readEngineVersion(dir, fs) {
+    const bytes = fs.read(win.join(dir, 'Engine', 'Build', 'Build.version'), 64 * 1024);
+    return bytes ? parseBuildVersion(bytes.toString('utf8')) : null;
+}
+/** Whether an engine folder is an installed build (what the launcher installs): Engine\Build\InstalledBuild.txt. */
+export function isInstalledBuild(dir, fs) {
+    return fs.exists(win.join(dir, 'Engine', 'Build', 'InstalledBuild.txt'));
+}
+const BUILD_ID = /^[^\x00-\x1f"\\/]{1,64}$/;
+/** Whether a name can be a source build's registered name (UnrealVersionSelector writes a {GUID}). */
+export const isBuildId = (id) => id === id.trim() && BUILD_ID.test(id);
+/**
+ * A source build's registered name when it has none of its own: a GUID made from its folder, so it is the same every
+ * boot and a project that was switched to it keeps finding it.
+ */
+export function stableBuildId(dir) {
+    const h = crypto.createHash('sha1').update(win.normalize(dir).toLowerCase()).digest('hex').toUpperCase();
+    return ('{' +
+        h.slice(0, 8) +
+        '-' +
+        h.slice(8, 12) +
+        '-' +
+        h.slice(12, 16) +
+        '-' +
+        h.slice(16, 20) +
+        '-' +
+        h.slice(20, 32) +
+        '}');
+}
+/** The engine in a folder, or null when it is not one. `id`: a source build's registered name (else one is made). */
+export function engineAt(dir, origin, writable, fs, id) {
+    if (!win.isAbsolute(dir) || /["\r\n]/.test(dir))
+        return null;
+    const version = readEngineVersion(dir, fs);
+    if (!version)
+        return null;
+    const build = isInstalledBuild(dir, fs) ? 'installed' : 'source';
+    const name = build === 'installed' ? launcherAppName(version) : id && isBuildId(id) ? id : stableBuildId(dir);
+    return { id: name, dir: win.normalize(dir), version, build, origin, writable };
+}
+/** At most this many folders are looked at in one place (a project root may hold many projects). */
+const MAX_LOOK = 200;
+/** At most this many engines are used. */
+export const MAX_ENGINES = 16;
+/** Every engine the sandbox can use, in a fixed order (this PC's, the data disk's, the project roots'), once each. */
+export function findEngines(s, fs) {
+    const found = [];
+    const add = (e) => {
+        if (!e || found.length >= MAX_ENGINES)
+            return;
+        if (found.some((f) => f.dir.toLowerCase() === e.dir.toLowerCase()))
+            return;
+        found.push(e);
+    };
+    for (const m of s.mapped)
+        add(engineAt(m.guest, m.writable ? 'pc-folder' : 'pc', m.writable === true, fs, m.buildId));
+    const launched = new Set(s.launcherDirs.map((d) => win.normalize(d).toLowerCase()));
+    for (const name of fs.list(s.enginesRoot).slice(0, MAX_LOOK)) {
+        if (name.startsWith('.'))
+            continue;
+        const dir = win.join(s.enginesRoot, name);
+        add(engineAt(dir, launched.has(dir.toLowerCase()) ? 'launcher' : 'data', true, fs));
+    }
+    for (const root of s.projectRoots)
+        for (const name of fs.list(root).slice(0, MAX_LOOK)) {
+            const dir = win.join(root, name);
+            if (fs.exists(win.join(dir, 'Engine', 'Build', 'Build.version')))
+                add(engineAt(dir, 'project', true, fs));
+        }
+    return found;
+}
+/** What a .uproject's EngineAssociation names: "5.4" (an installed build), "{GUID}" or a name (a source build). */
+export function parseEngineAssociation(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return { kind: 'none' };
+    const text = value.trim();
+    const version = /^(\d{1,2}\.\d{1,2})(?:\.\d{1,3})?$/.exec(text);
+    if (version)
+        return { kind: 'version', version: version[1] };
+    return isBuildId(text) ? { kind: 'build', id: text } : { kind: 'none' };
+}
+/** The EngineAssociation of a .uproject's text (null when it is not JSON). */
+export function uprojectAssociation(text) {
+    try {
+        const json = JSON.parse(stripBom(text));
+        if (!json || typeof json !== 'object' || Array.isArray(json))
+            return null;
+        return parseEngineAssociation(json.EngineAssociation);
+    }
+    catch {
+        return null;
+    }
+}
+/** A project's .uproject: in its folder, else one folder down (the first by name), or null. */
+export function findUproject(workspace, fs) {
+    const own = (dir) => {
+        const hit = fs
+            .list(dir)
+            .filter((n) => /\.uproject$/i.test(n))
+            .sort()[0];
+        return hit ? win.join(dir, hit) : null;
+    };
+    const here = own(workspace);
+    if (here)
+        return here;
+    for (const name of fs.list(workspace).slice(0, MAX_LOOK).sort()) {
+        if (name.startsWith('.') || /^(node_modules|Engine|Binaries|Intermediate|Saved|DerivedDataCache)$/i.test(name))
+            continue;
+        const hit = own(win.join(workspace, name));
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Writable before read-only (the editor writes into a project's engine plugins), installed before source. */
+const preference = (e) => (e.writable ? 0 : 2) + (e.build === 'installed' ? 0 : 1);
+/**
+ * The engine a project builds with: the one its EngineAssociation names (a version: a writable one before this PC's
+ * read-only one; a build: that registered build), else the newest. Null when the project names one that is not here.
+ */
+export function chooseEngine(engines, association) {
+    const best = (list) => [...list].sort((a, b) => preference(a) - preference(b) || compareVersions(b.version, a.version))[0] ?? null;
+    if (association.kind === 'version') {
+        const engine = best(engines.filter((e) => majorMinor(e.version) === association.version));
+        return engine
+            ? { engine, reason: 'the project asks for ' + association.version }
+            : { engine: null, reason: 'the project asks for Unreal Engine ' + association.version + ', which is not here' };
+    }
+    if (association.kind === 'build') {
+        const exact = engines.find((e) => e.id.toLowerCase() === association.id.toLowerCase());
+        if (exact)
+            return { engine: exact, reason: 'the project asks for the source build ' + association.id };
+        // The project names a source build of this PC's registry; here the source sits in a project root or on the data
+        // disk under another name: use the newest of those and register the project's name for it.
+        const source = [...engines]
+            .filter((e) => e.build === 'source' && e.writable)
+            .sort((a, b) => compareVersions(b.version, a.version))[0];
+        return source
+            ? {
+                engine: source,
+                alias: association.id,
+                reason: 'the project names the source build ' +
+                    association.id +
+                    ' (registered on your PC); using the source build at ' +
+                    source.dir,
+            }
+            : { engine: null, reason: 'the project asks for the source build ' + association.id + ', which is not here' };
+    }
+    const newest = [...engines].sort((a, b) => compareVersions(b.version, a.version) || preference(a) - preference(b))[0];
+    return newest
+        ? { engine: newest, reason: 'the newest engine here' }
+        : { engine: null, reason: 'no engine is installed yet' };
+}
+/** Installed builds: where an installer records them (UnrealVersionSelector and the editor read it). */
+export const INSTALLED_KEY = 'SOFTWARE\\EpicGames\\Unreal Engine';
+/** Source builds: UnrealVersionSelector's list (name = the build's id, value = its folder). */
+export const BUILDS_KEY = 'Software\\Epic Games\\Unreal Engine\\Builds';
+/**
+ * The installed build of each version that the editor and UnrealVersionSelector use: one per major.minor, chosen the
+ * way chooseEngine chooses (writable before read-only, then the newest).
+ */
+export function preferredInstalled(engines) {
+    const sorted = engines
+        .filter((e) => e.build === 'installed')
+        .sort((a, b) => preference(a) - preference(b) || compareVersions(b.version, a.version));
+    const seen = new Set();
+    return sorted.filter((e) => {
+        const v = majorMinor(e.version);
+        if (seen.has(v))
+            return false;
+        seen.add(v);
+        return true;
+    });
+}
+/**
+ * The registry values that make Unreal find the engines: an installed build as HKLM\SOFTWARE\EpicGames\Unreal
+ * Engine\<5.4> InstalledDirectory (one per version: the one a project would pick), a source build as a value under
+ * HKCU\Software\Epic Games\Unreal Engine\Builds. `aliases`: names a project uses for a source build here (its GUID on
+ * this PC), registered for the folder they stand for, so the .uproject works unchanged.
+ */
+export function registryPlan(engines, aliases = []) {
+    const values = engines
+        .filter((e) => e.build === 'source')
+        .map((e) => ({ hive: 'HKCU', key: BUILDS_KEY, name: e.id, value: e.dir }));
+    for (const a of aliases)
+        values.push({ hive: 'HKCU', key: BUILDS_KEY, name: a.id, value: a.dir });
+    for (const e of preferredInstalled(engines))
+        values.push({
+            hive: 'HKLM',
+            key: INSTALLED_KEY + '\\' + majorMinor(e.version),
+            name: 'InstalledDirectory',
+            value: e.dir,
+        });
+    return values;
+}
+/** UnrealVersionSelector inside an engine (it opens, switches and generates project files for .uproject files). */
+export function versionSelectorIn(dir) {
+    return win.join(dir, 'Engine', 'Binaries', 'Win64', 'UnrealVersionSelector.exe');
+}
+/**
+ * The .uproject file association UnrealVersionSelector /fileassociations writes (per user): open in the editor, launch
+ * the game, generate Visual Studio project files, switch the engine version.
+ */
+export function fileAssociationPlan(selector) {
+    if (!win.isAbsolute(selector) || /["\r\n]/.test(selector))
+        throw new Error('not a program path: ' + selector);
+    const exe = '"' + selector + '"';
+    const classes = 'Software\\Classes';
+    const type = classes + '\\Unreal.ProjectFile';
+    const v = (key, value, name = '') => ({ hive: 'HKCU', key, name, value });
+    const verb = (id, label, args) => [
+        v(type + '\\shell\\' + id, label),
+        v(type + '\\shell\\' + id + '\\command', exe + ' ' + args + ' "%1"'),
+    ];
+    return [
+        v(classes + '\\.uproject', 'Unreal.ProjectFile'),
+        v(type, 'Unreal Engine Project File'),
+        v(type + '\\DefaultIcon', exe),
+        ...verb('open', 'Open', '/editor'),
+        ...verb('run', 'Launch game', '/game'),
+        ...verb('rungenproj', 'Generate Visual Studio project files', '/projectfiles'),
+        ...verb('switchversion', 'Switch Unreal Engine version...', '/switchversion'),
+    ];
+}
+// ---- Environment, PATH, derived data cache ---------------------------------------------------------------------
+/** The folders of an engine an agent runs its tools from (those that exist), in PATH order. */
+export function engineToolDirs(dir, fs) {
+    return [win.join(dir, 'Engine', 'Build', 'BatchFiles')].filter((d) => fs.exists(d));
+}
+/** The engine folders put at the END of PATH: they hold many DLLs, which every program started from PATH would load. */
+export function engineExtraDirs(dir, fs) {
+    return [
+        win.join(dir, 'Engine', 'Binaries', 'Win64'),
+        win.join(dir, 'Engine', 'Binaries', 'DotNET', 'UnrealBuildTool'),
+    ].filter((d) => fs.exists(d));
+}
+/** Variables for the project's engine: UE_ROOT (the engine folder) and UE_ENGINE_DIR (its Engine folder). */
+export function engineVars(engine) {
+    return { UE_ROOT: engine.dir, UE_ENGINE_DIR: win.join(engine.dir, 'Engine') };
+}
+/**
+ * The derived data cache: UE-LocalDataCachePath moves the local cache (and from 5.4 the Zen store, in its Zen
+ * subfolder) out of the engine and off the sandbox's disk. "local" leaves Unreal's own place (the sandbox's disk).
+ */
+export function ddcVars(mode, ddcDir) {
+    return mode === 'persisted' ? { 'UE-LocalDataCachePath': ddcDir } : {};
+}
+/** The editor's MCP server (Unreal 5.8's ModelContextProtocol plugin): its default address. */
+export const UNREAL_MCP_URL = 'http://127.0.0.1:8000/mcp';
+const MCP_PLUGIN = ['Experimental', 'ModelContextProtocol', 'ModelContextProtocol.uplugin'];
+/** Whether an engine ships the ModelContextProtocol plugin (5.8 and later). */
+export function hasMcpPlugin(engine, fs) {
+    if (engine.version.major < 5 || (engine.version.major === 5 && engine.version.minor < 8))
+        return false;
+    return fs.exists(win.join(engine.dir, 'Engine', 'Plugins', ...MCP_PLUGIN));
+}

package/dist/shared/unreal/guide.d.ts

@@ -0,0 +1,19 @@
+import type { UnrealStatus } from './status.js';
+export interface UnrealGuideProject {
+    /** The project's folder in the sandbox. */
+    readonly workspace: string;
+    /** Its .uproject, when it has one. */
+    readonly uproject: string | null;
+}
+/** Optional extra guide sections. */
+export interface UnrealGuideExtras {
+    /** The Mixamo lines (where downloads land, the import script when one ships). */
+    readonly mixamo?: {
+        readonly downloads: string;
+        readonly script: string | null;
+    };
+}
+/** The guide's Unreal lines for these projects (none when Unreal is not set up). */
+export declare function unrealGuideLines(status: UnrealStatus, projects: readonly UnrealGuideProject[], extras?: UnrealGuideExtras): string[];
+/** The short tool-summary line of a project's engine. */
+export declare function unrealSummaryLine(status: UnrealStatus, workspace: string): string;

package/dist/shared/unreal/guide.js

@@ -0,0 +1,105 @@
+// The Unreal lines of the sandbox guide (the managed CLAUDE.md and AGENTS.md): which engine each project builds with
+// and the plain commands an agent builds, tests, cooks, packages and debugs with. Pure, from the status the sandbox
+// wrote (status.ts).
+import path from 'node:path';
+import { ORIGIN_LABELS } from './engines.js';
+import { mixamoGuideLines } from './mixamo.js';
+const win = path.win32;
+/** UE4 engines name their programs UE4Editor.exe; UE5 engines UnrealEditor.exe. */
+function editorName(engine) {
+    return engine && Number.parseInt(engine.version, 10) < 5 ? 'UE4Editor' : 'UnrealEditor';
+}
+/** The guide's Unreal lines for these projects (none when Unreal is not set up). */
+export function unrealGuideLines(status, projects, extras = {}) {
+    const lines = [];
+    const several = projects.length > 1;
+    for (const p of projects) {
+        const choice = status.projects.find((s) => s.workspace.toLowerCase() === p.workspace.toLowerCase());
+        const engine = choice?.engine
+            ? status.engines.find((e) => e.dir.toLowerCase() === choice.engine.toLowerCase())
+            : undefined;
+        const name = several ? ' (' + win.basename(p.workspace) + ')' : '';
+        if (engine)
+            lines.push('- Unreal' +
+                name +
+                ': engine ' +
+                engine.id +
+                ' ' +
+                engine.version +
+                ' at `' +
+                engine.dir +
+                '` (' +
+                ORIGIN_LABELS[engine.origin] +
+                '; ' +
+                (choice?.reason ?? '') +
+                '). `UE_ROOT` is set; Build.bat, RunUAT.bat, ' +
+                editorName(engine) +
+                '.exe and ' +
+                editorName(engine) +
+                '-Cmd.exe are on PATH.' +
+                (engine.writable
+                    ? ''
+                    : " Read-only: never install plugins into it; put them in the project's Plugins folder."));
+        else if (choice)
+            lines.push('- Unreal' + name + ': no engine for this project (' + choice.reason + ').');
+    }
+    if (!status.engines.length)
+        lines.push('- Unreal: no engine yet. Ask the user to install one with the Epic Games Launcher on their PC (the next sandbox maps it read-only), or to open the launcher here and sign in once: it installs into `' +
+            (status.launcher.installLocation ?? 'the data disk') +
+            '`, kept between sandboxes.');
+    else if (status.engines.length > 1)
+        lines.push('- Unreal engines here: ' +
+            status.engines.map((e) => e.id + ' ' + e.version + (e.writable ? '' : ' (read-only)')).join(', ') +
+            ". A project uses the one its .uproject's EngineAssociation names (a writable copy before this PC's read-only one), else the newest.");
+    if (status.vaults.length)
+        lines.push("- Unreal assets from the user's PC (Fab / Marketplace downloads, read-only, new ones appear at once): `" +
+            status.vaults.join('`, `') +
+            '`, one folder per pack: `<Pack>\\data\\Content\\...` (use it: `robocopy "<vault>\\<Pack>\\data\\Content" "<Project>\\Content" /E`) or a code plugin `<Pack>\\data\\<Name>.uplugin` (copy `<Pack>\\data` to `<Project>\\Plugins\\<Name>`). Never write into it. Projects under the mapped project root are the PC\'s own folders: assets the user adds there show up at once.');
+    if (!status.engines.length)
+        return lines;
+    const uproject = projects.find((p) => p.uproject)?.uproject ?? '<Project>.uproject';
+    const project = win.basename(uproject, '.uproject');
+    const q = '"' + uproject + '"';
+    const forProject = projects.find((p) => p.uproject)?.workspace ?? projects[0]?.workspace ?? '';
+    const chosen = status.projects.find((s) => s.workspace.toLowerCase() === forProject.toLowerCase())?.engine;
+    const editor = editorName(status.engines.find((e) => chosen !== undefined && chosen !== null && e.dir.toLowerCase() === chosen.toLowerCase()) ?? status.engines[0]);
+    lines.push('- Unreal commands: build `Build.bat ' +
+        project +
+        'Editor Win64 Development -Project=' +
+        q +
+        ' -WaitMutex -NoHotReload` (the game: `' +
+        project +
+        ' Win64 Development`); project files `Build.bat -projectfiles -project=' +
+        q +
+        ' -game -progress`; tests `' +
+        editor +
+        '-Cmd.exe ' +
+        q +
+        ' -ExecCmds="Automation RunTests <filter>;Quit" -TestExit="Automation Test Queue Empty" -unattended -nullrhi -nosplash -nop4 -log`; package `RunUAT.bat BuildCookRun -project=' +
+        q +
+        ' -platform=Win64 -clientconfig=Development -build -cook -stage -pak -archive -archivedirectory=<folder> -nop4 -unattended -utf8output`.', '- Unreal logs: `<Project>\\Saved\\Logs`, the build tool `%LOCALAPPDATA%\\UnrealBuildTool\\Log.txt`, crashes `<Project>\\Saved\\Crashes\\*\\UEMinidump.dmp`' +
+        (status.debugger
+            ? '; debug a crash with `cdb -z "<UEMinidump.dmp>" -c "!analyze -v;q"` (attach: `cdb -p <pid>`; windbg is on PATH too)'
+            : '') +
+        '. The editor needs a GPU (vGPU); builds, -nullrhi tests and cooking do not.' +
+        (status.ddc.dir ? ' Derived data cache: `' + status.ddc.dir + '` (kept).' : ''));
+    if (extras.mixamo)
+        lines.push(...mixamoGuideLines(extras.mixamo));
+    if (status.mcpUrl)
+        lines.push('- Unreal editor MCP: `sbx-unreal-editor` (' +
+            status.mcpUrl +
+            ') answers while the editor runs with the ModelContextProtocol and AllToolsets plugins on in the .uproject and `ModelContextProtocol.StartServer` run (or bAutoStartServer=True in Saved\\Config\\WindowsEditor\\EditorPerProjectUserSettings.ini, [/Script/ModelContextProtocolEngine.ModelContextProtocolSettings]).');
+    return lines;
+}
+/** The short tool-summary line of a project's engine. */
+export function unrealSummaryLine(status, workspace) {
+    const choice = status.projects.find((s) => s.workspace.toLowerCase() === workspace.toLowerCase());
+    const engine = choice?.engine
+        ? status.engines.find((e) => e.dir.toLowerCase() === choice.engine.toLowerCase())
+        : undefined;
+    if (engine)
+        return 'unreal: ' + engine.id + ' ' + engine.version + ' (' + ORIGIN_LABELS[engine.origin] + ')';
+    return status.engines.length
+        ? 'unreal: no engine for this project (' + (choice?.reason ?? 'none matches') + ')'
+        : 'unreal: no engine yet (sign in to the Epic Games Launcher once, or install one on your PC)';
+}

package/dist/shared/unreal/index.d.ts

@@ -0,0 +1,7 @@
+export * from './engines.js';
+export * from './launcher-files.js';
+export * from './status.js';
+export * from './guide.js';
+export * from './vs-check.js';
+export * from './room.js';
+export * from './vault.js';

package/dist/shared/unreal/index.js

@@ -0,0 +1,8 @@
+// Unreal engines, the Epic Games Launcher's files and the Unreal status, shared by the sandbox and this PC (pure).
+export * from './engines.js';
+export * from './launcher-files.js';
+export * from './status.js';
+export * from './guide.js';
+export * from './vs-check.js';
+export * from './room.js';
+export * from './vault.js';