windows-development-sandbox 1.25.0 → 1.25.1

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;
+}

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

@@ -5,7 +5,8 @@ import { SYSTEM } from '../../../shared/system.js';
 import { dryRun } from '../../runtime/paths.js';
 import { execAsync, scriptOutput } from '../../runtime/process.js';
 import { exists } from '../../runtime/fs.js';
-import { log } from '../../runtime/log.js';
+import { log, warn } from '../../runtime/log.js';
+import { errMsg } from '../../../core/util/errors.js';
 import { arch, tool } from '../tool-env.js';
 import { installFromGithub } from '../install.js';
 /**
@@ -33,6 +34,8 @@ export async function setupMesa(env, config) {
         await setupLavapipe(env, dir);
 }
 const VULKAN_RUNTIME = 'https://sdk.lunarg.com/sdk/download/latest/windows/vulkan-runtime-components.zip';
+/** Used when "latest" is not published yet (LunarG announces a version before its runtime zip is up: a 404). */
+const VULKAN_RUNTIME_PINNED = 'https://sdk.lunarg.com/sdk/download/1.4.350.0/windows/vulkan-runtime-components.zip';
 /**
  * Software Vulkan: Mesa's lavapipe plus the Khronos loader (vulkan-1.dll, from LunarG's runtime components; Windows
  * Sandbox has no Vulkan loader). The loader ignores VK_DRIVER_FILES in elevated processes, and everything in the
@@ -43,15 +46,19 @@ const setupLavapipe = async (env, mesaDir) => {
     if (!exists(icd))
         throw new Error('this Mesa build has no lavapipe (' + path.basename(icd) + ')');
     const dir = tool('vulkan');
-    if (!exists(path.join(dir, 'vulkan-1.dll'))) {
-        log('Downloading the Vulkan loader (~10 MB once) ...');
+    // vulkaninfo.exe too: a copy kept from an older runtime zip may lack it.
+    if (!exists(path.join(dir, 'vulkan-1.dll')) || !exists(path.join(dir, 'vulkaninfo.exe'))) {
+        log('Downloading the Vulkan loader (~20 MB once) ...');
         // LunarG publishes no checksum for this zip; it comes over HTTPS from LunarG, the Khronos SDK's maintainer.
         // The zip has x86 and x64 folders: only the 64-bit loader (and vulkaninfo) is extracted.
-        await downloader.archive(VULKAN_RUNTIME, dir, {
-            locate: 'vulkan-1.dll',
-            fileName: 'vulkan-runtime.zip',
-            members: ['*/x64/*'],
-        });
+        const fetchRuntime = (url) => downloader.archive(url, dir, { locate: 'vulkan-1.dll', fileName: 'vulkan-runtime.zip', members: ['*/x64/*'] });
+        try {
+            await fetchRuntime(VULKAN_RUNTIME);
+        }
+        catch (e) {
+            warn('The latest Vulkan runtime could not be downloaded (' + errMsg(e) + '); using version 1.4.350.0.');
+            await fetchRuntime(VULKAN_RUNTIME_PINNED);
+        }
     }
     const register = (file) => execAsync(SYSTEM.reg(), ['add', 'HKLM\\SOFTWARE\\Khronos\\Vulkan\\Drivers', '/v', file, '/t', 'REG_DWORD', '/d', '0', '/f'], { stdio: 'ignore' });
     await register(icd);

package/dist/guest/toolchains/native/rust-extras.d.ts

@@ -14,6 +14,13 @@ export declare function cargoShim(env: ToolEnv, rust: Toolchains['rust']): void;
  * run at once in the whole sandbox and, with linker "lld", has MinGW's gcc use Rust's own lld instead of GNU ld.
  */
 export declare function linkGate(env: ToolEnv, rust: Toolchains['rust'], host: string): void;
+/**
+ * MSVC host: link.exe writes an executable into a mapped folder (the workspace, C:\AgentData) as all zeros, so a
+ * fresh build script or test program fails with "The file or directory is corrupted and unreadable" (os error 1392).
+ * Rust's own lld (a copy of rust-lld.exe named lld-link.exe, which is how lld picks its mode) writes them whole.
+ * `rust.linker` "gnu" keeps link.exe; a linker the user set for the target wins.
+ */
+export declare function lldLink(env: ToolEnv, rust: Toolchains['rust'], host: string): void;
 /**
  * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
  * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made

package/dist/guest/toolchains/native/rust-extras.js

@@ -7,7 +7,7 @@ import { execOutput } from '../../runtime/process.js';
 import { ensureCompiled } from '../../runtime/csc.js';
 import { arch, tool } from '../tool-env.js';
 import { wanted } from '../detect.js';
-import { cargoJobs, chooseTargetDir } from '../../../shared/memory/index.js';
+import { cargoJobs, cargoLinkerVar, chooseTargetDir } from '../../../shared/memory/index.js';
 import { linkerSlots } from '../../governor/decide.js';
 import { warn } from '../../runtime/log.js';
 import { freeBytes } from '../persisted.js';
@@ -81,6 +81,28 @@ export function linkGate(env, rust, host) {
         env.vars.AGENT_LINK_SLOTS +
         ' at once');
 }
+/**
+ * MSVC host: link.exe writes an executable into a mapped folder (the workspace, C:\AgentData) as all zeros, so a
+ * fresh build script or test program fails with "The file or directory is corrupted and unreadable" (os error 1392).
+ * Rust's own lld (a copy of rust-lld.exe named lld-link.exe, which is how lld picks its mode) writes them whole.
+ * `rust.linker` "gnu" keeps link.exe; a linker the user set for the target wins.
+ */
+export function lldLink(env, rust, host) {
+    if (!host.endsWith('-pc-windows-msvc') || rust.linker !== 'lld')
+        return;
+    const variable = cargoLinkerVar(host);
+    if (process.env[variable])
+        return;
+    const rustEnv = { ...process.env, RUSTUP_HOME: tool('rust', 'rustup'), CARGO_HOME: tool('rust', 'cargo') };
+    const sysroot = execOutput(tool('rust', 'cargo', 'bin', 'rustc.exe'), ['--print', 'sysroot'], { env: rustEnv });
+    const lld = sysroot ? path.join(sysroot, 'lib', 'rustlib', host, 'bin', 'rust-lld.exe') : '';
+    if (!lld || !exists(lld))
+        return;
+    const shim = path.join(mkdirp(tool('shims')), 'lld-link.exe');
+    fs.copyFileSync(lld, shim);
+    env.vars[variable] = shim;
+    env.summary.push('rust linking: lld (link.exe writes empty files into mapped folders)');
+}
 /**
  * Cargo defaults that fit Windows, written only when there is no $CARGO_HOME\config.toml yet: fewer parallel jobs
  * (parallel rustc ran out of paging file) and, for the GNU host, only line tables as debug info (full debug info made

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

@@ -2,6 +2,6 @@ import type { Toolchains } from '../../../core/types.js';
 import type { ToolCtx } from '../step.js';
 import { type ToolEnv } from '../tool-env.js';
 export { UNREAL_COMPONENTS } from './vs-request.js';
-/** Downloads the DirectX redistributable ahead of the install (only once the licence is accepted). */
+/** Downloads the DirectX redistributable and the launcher ahead of the install (only once the licence is accepted). */
 export declare function fetchDirectX(config: Toolchains['unreal']): Promise<void>;
-export declare function setupUnreal(env: ToolEnv, config: Toolchains['unreal'], ctx: ToolCtx): Promise<void>;
+export declare function setupUnreal(env: ToolEnv, config: Toolchains['unreal'], _ctx: ToolCtx): Promise<void>;

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

@@ -1,18 +1,25 @@
-// Unreal Engine development (toolchains.unreal): the DirectX End-User Runtime the engine lists (a real installer: it
-// runs every boot), then the engines (engines/unreal-engines.ts: the launcher's install folder on the data disk, PC
-// engines from pcInstalls, the derived data cache). Visual Studio (Community with the C++ game workload, or the Build
-// Tools) is its own step (visual-studio.ts), which the plan runs first. The engine itself comes from the Epic Games
-// Launcher or its source.
+// Unreal Engine development, machine-wide (toolchains.unreal, once per boot): the DirectX End-User Runtime the engine
+// lists and the Epic Games Launcher (real installers: they run every boot), the launcher pointed at the data disk for
+// engines and given back the engines it installed there, the Windows SDK debuggers for crash dumps, and a check that
+// UnrealBuildTool finds Visual Studio the way it looks (the Setup Configuration API). Visual Studio itself is its own
+// step (visual-studio.ts), which the plan runs first; each project's engine is set up by engines/unreal-engines.ts.
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { runInstaller } from '../../runtime/pools.js';
+import { errMsg } from '../../../core/util/errors.js';
+import { readValid } from '../../../shared/io/json.js';
 import { safeRemove } from '../../../shared/io/safe-remove.js';
+import { VsSetupReportSchema, vsVerdict } from '../../../shared/unreal/index.js';
+import { runInstaller } from '../../runtime/pools.js';
 import { dryRun } from '../../runtime/paths.js';
 import { exists, mkdirp } from '../../runtime/fs.js';
-import { log } from '../../runtime/log.js';
-import { setupUnrealEngines } from '../engines/unreal-engines.js';
+import { log, warn } from '../../runtime/log.js';
+import { runScriptAsync } from '../../runtime/process.js';
+import { ensureLauncher, fetchLauncher, placeEngines, restoreLauncherItems } from '../engines/epic-launcher.js';
+import { resetUnrealStatus, updateUnrealStatus } from '../engines/unreal-status.js';
 import { SIGNERS, signedInstaller } from '../installers.js';
 import { tool } from '../tool-env.js';
+import { ensureDebuggers } from './debuggers.js';
 import { installedVs } from './visual-studio.js';
 export { UNREAL_COMPONENTS } from './vs-request.js';
 const DIRECTX_URL = 'https://download.microsoft.com/download/8/4/A/84A35BF1-DAFE-4AE8-82AF-AD2AE20B6B14/directx_Jun2010_redist.exe';
@@ -23,10 +30,13 @@ const directXInstalled = () => {
 };
 /** The redistributable (downloaded once, signature checked). */
 const directXRedist = () => signedInstaller(DIRECTX_URL, path.join(tool('visualstudio'), 'directx_Jun2010_redist.exe'), 'the DirectX End-User Runtime (~95 MB once)', SIGNERS.microsoft);
-/** Downloads the DirectX redistributable ahead of the install (only once the licence is accepted). */
+/** Downloads the DirectX redistributable and the launcher ahead of the install (only once the licence is accepted). */
 export async function fetchDirectX(config) {
-    if (config.acceptLicense && !directXInstalled())
+    if (!config.acceptLicense)
+        return;
+    if (!directXInstalled())
         await directXRedist();
+    await fetchLauncher();
 }
 async function installDirectX() {
     if (directXInstalled())
@@ -42,17 +52,85 @@ async function installDirectX() {
     if (code !== 0)
         throw new Error('the DirectX End-User Runtime installer failed (exit ' + code + ')');
 }
-export async function setupUnreal(env, config, ctx) {
+/** What UnrealBuildTool's way of finding Visual Studio finds (scripts\get-vs-setup.ps1 calls the Setup API). */
+async function checkVisualStudio() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sbx-vs-check-'));
+    const file = path.join(dir, 'result.json');
+    try {
+        await runScriptAsync('get-vs-setup.ps1', ['-ResultFile', file]);
+        const report = readValid(VsSetupReportSchema, file);
+        return report ? vsVerdict(report) : { ok: false, text: 'the check left no result' };
+    }
+    catch (e) {
+        return { ok: false, text: 'the check failed: ' + errMsg(e) };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Runs one part, warning (not failing the step) when it does not work. */
+async function part(what, work, fallback) {
+    try {
+        return await work();
+    }
+    catch (e) {
+        warn('Unreal: ' + what + ' failed (' + errMsg(e) + ')');
+        return fallback;
+    }
+}
+export async function setupUnreal(env, config, _ctx) {
     if (!config.acceptLicense)
-        throw new Error('Unreal tools are installed only with toolchains.unreal.acceptLicense = true: Visual Studio Community and the DirectX End-User Runtime come under Microsoft licence terms (https://visualstudio.microsoft.com/license-terms/)');
+        throw new Error("Unreal tools are installed only with toolchains.unreal.acceptLicense = true: Visual Studio Community and the DirectX End-User Runtime come under Microsoft licence terms (https://visualstudio.microsoft.com/license-terms/), the Epic Games Launcher under Epic's (https://www.epicgames.com/site/eula)");
     if (dryRun) {
-        log('(dry run) would install the DirectX End-User Runtime and set up the Unreal engines');
+        log('(dry run) would install the DirectX End-User Runtime and the Epic Games Launcher');
         return;
     }
-    await installDirectX();
-    await setupUnrealEngines(env, config, ctx);
+    resetUnrealStatus();
+    await part('the DirectX End-User Runtime', installDirectX, undefined);
+    const launcher = await part('the Epic Games Launcher', ensureLauncher, null);
+    // Before anyone opens the launcher: engines go to the data disk, and it knows the ones it installed there before.
+    const place = placeEngines(config.persistEngines);
+    if (config.persistEngines)
+        await part("restoring the launcher's engines", async () => restoreLauncherItems(), []);
+    if (place.problem) {
+        warn('Unreal: ' + place.problem);
+        env.summary.push('UNREAL: ' + place.problem);
+    }
+    const debuggers = await part('the Windows SDK debuggers', ensureDebuggers, null);
+    if (debuggers)
+        env.append.push(debuggers);
     const vs = installedVs();
-    env.summary.push('unreal: ' +
-        (vs ? 'Visual Studio ' + vs.version + ' at ' + vs.path + '; ' : '') +
-        'DirectX End-User Runtime; get the engine from the Epic Games Launcher (Start menu)');
+    const check = vs ? await checkVisualStudio() : { ok: false, text: 'no Visual Studio with the C++ tools' };
+    if (!check.ok)
+        warn('Unreal: UnrealBuildTool would not find a compiler: ' + check.text);
+    else
+        log('Unreal: UnrealBuildTool finds ' + check.text);
+    const kept = Boolean(vs && /\\visualstudio\\persist\\/i.test(vs.path + '\\'));
+    updateUnrealStatus((s) => ({
+        ...s,
+        launcher: {
+            installed: launcher !== null,
+            installLocation: place.installLocation,
+            problem: place.problem,
+            freeBytes: place.freeBytes,
+            needBytes: place.needBytes,
+        },
+        visualStudio: {
+            version: vs?.version ?? '',
+            path: vs?.path ?? '',
+            how: vs ? (kept ? 'kept on the data disk' : 'installed in this sandbox') : '',
+            check: check.text,
+            ok: check.ok,
+        },
+        debugger: debuggers ? path.join(debuggers, 'cdb.exe') : null,
+    }));
+    env.summary.push('unreal tools: ' +
+        (vs
+            ? 'Visual Studio ' +
+                vs.version +
+                (check.ok ? ' (UnrealBuildTool finds it)' : ' (UnrealBuildTool would NOT find it)')
+            : 'no Visual Studio') +
+        ', DirectX End-User Runtime' +
+        (launcher ? ', Epic Games Launcher' : '') +
+        (debuggers ? ', cdb/windbg' : ''));
 }

package/dist/guest/toolchains/plan.js

@@ -12,6 +12,7 @@ import { setupDotnet } from './native/dotnet.js';
 import { setupMesa } from './native/mesa.js';
 import { setupMsvc } from './native/msvc/index.js';
 import { fetchDirectX, setupUnreal } from './native/unreal.js';
+import { setupUnrealEngines } from './engines/unreal-engines.js';
 import { fetchRustupInit, setupRust } from './native/rust.js';
 import { setupNode } from './languages/node.js';
 import { setupPwsh } from './tools/pwsh.js';
@@ -32,7 +33,7 @@ import { setupFlutter } from './mobile/flutter.js';
 import { setupDart } from './mobile/dart.js';
 import { setupReactNative } from './mobile/react-native.js';
 import { setupKotlin } from './languages/kotlin.js';
-import { rustHost, rustCaches, cargoDefaults, cargoShim, linkGate, resolveTargetDir, targetSummary, } from './native/rust-extras.js';
+import { rustHost, rustCaches, cargoDefaults, cargoShim, linkGate, lldLink, resolveTargetDir, targetSummary, } from './native/rust-extras.js';
 import { setupPythonTools } from './languages/python-tools.js';
 export function plan(config, versions, o) {
     const apps = Boolean(o.apps && (o.apps.install.length || Object.keys(o.apps.custom).length));
@@ -87,6 +88,14 @@ export function plan(config, versions, o) {
             ...ahead(() => fetchDirectX(config.unreal)),
             install: (env) => setupUnreal(env, config.unreal, ctx),
         },
+        // Each project's engine (its .uproject's EngineAssociation) on its PATH: not shared, a project that joins later
+        // gets its own. It registers every engine too, so this PC's engines work without the licence step above.
+        {
+            name: 'Unreal engines',
+            enabled: unreal,
+            after: ['Unreal'],
+            install: (env) => setupUnrealEngines(env, config.unreal, ctx),
+        },
         {
             name: 'MSVC',
             enabled: wanted(config.msvc.enabled, 'msvc') && vs === null,
@@ -108,6 +117,8 @@ export function plan(config, versions, o) {
                     cargoDefaults(rustHost(config));
                     cargoShim(env, rust);
                     linkGate(env, rust, rustHost(config));
+                    lldLink(env, rust, rustHost(config));
+                    lldLink(env, rust, rustHost(config));
                 }
             },
         },

package/dist/guest/toolchains/tools/vscode-profile.js

@@ -54,6 +54,8 @@ const BY_TOOLCHAIN = {
     rust: ['rust-lang.rust-analyzer', 'vadimcn.vscode-lldb'],
     cpp: ['ms-vscode.cpptools', 'ms-vscode.cmake-tools'],
     msvc: ['ms-vscode.cpptools', 'ms-vscode.cmake-tools'],
+    // Unreal C++ (IntelliSense from the generated .code-workspace) and the C# of the *.Build.cs / *.Target.cs rules.
+    unreal: ['ms-vscode.cpptools', 'ms-dotnettools.csharp'],
     dotnet: ['ms-dotnettools.csharp'],
     ruby: ['shopify.ruby-lsp'],
     php: ['bmewburn.vscode-intelephense-client', 'xdebug.php-debug'],

package/dist/host/accounts/kinds/epic.js

@@ -1,15 +1,21 @@
-// Epic Games: this PC's launcher sign-in ("Remember me" in its GameUserSettings.ini, often UTF-16). Taking it signs
-// the launcher on this PC out the first time a sandbox uses it (a sign-in works in one place at a time).
+// Epic Games: this PC's launcher sign-in ("Remember me" in its GameUserSettings.ini, often UTF-16; launcher 17+ keeps
+// it in Config\WindowsEditor, older ones in Config\Windows). Taking it signs the launcher on this PC out the first time
+// a sandbox uses it (a sign-in works in one place at a time).
 import path from 'node:path';
-import { epicSettingsFile, MAX_EPIC_INI_BYTES, readEpicLogin, } from '../../../shared/accounts/index.js';
+import { epicSettingsFiles, MAX_EPIC_INI_BYTES, readEpicLogin, } from '../../../shared/accounts/index.js';
 import { decodeText, readBoundedFile } from '../../../shared/io/index.js';
 export const epicSource = {
     fromPc(pc, from) {
         const localAppData = from ? path.resolve(from) : pc.localAppData;
         if (!localAppData)
             return null;
-        const bytes = readBoundedFile(epicSettingsFile(localAppData), MAX_EPIC_INI_BYTES);
-        return bytes ? readEpicLogin(decodeText(bytes).text) : null;
+        for (const file of epicSettingsFiles(localAppData)) {
+            const bytes = readBoundedFile(file, MAX_EPIC_INI_BYTES);
+            const login = bytes ? readEpicLogin(decodeText(bytes).text) : null;
+            if (login)
+                return login;
+        }
+        return null;
     },
     summary: () => null,
 };

package/dist/host/accounts/source.d.ts

@@ -4,6 +4,8 @@ export interface PcEnv {
     readonly localAppData: string;
     readonly appData: string;
     readonly programData: string;
+    /** C:\Program Files (where the Epic Games Launcher installs engines by default). */
+    readonly programFiles?: string;
     /** The environment the command runs with (a variable set in this terminal). */
     readonly env?: Readonly<Record<string, string | undefined>>;
     /** A variable of this Windows user's saved environment (HKCU\Environment), or null when it is not set. */

package/dist/host/accounts/source.js

@@ -32,6 +32,7 @@ export function pcEnv() {
         localAppData: env.LOCALAPPDATA ?? '',
         appData: env.APPDATA ?? '',
         programData: env.ProgramData ?? env.PROGRAMDATA ?? 'C:\\ProgramData',
+        programFiles: env.ProgramFiles ?? 'C:\\Program Files',
         env,
         userVariable: savedUserVariable,
     };

package/dist/host/pc-installs/discover.d.ts

@@ -10,6 +10,8 @@ export interface DiscoverOptions {
     readonly packageRoot: string;
     readonly storageRoot: string;
     readonly sources?: readonly PcInstallSource[];
+    /** This launch sets the sandbox up for Unreal ("auto" maps this PC's engines and vault cache then). */
+    readonly unrealOn?: boolean;
 }
 export interface DiscoveredInstalls {
     readonly mappings: ResolvedMapping[];

package/dist/host/pc-installs/discover.js

@@ -5,21 +5,29 @@ import { pcEnv } from '../accounts/index.js';
 import { epicInstalls } from './epic.js';
 import { steamInstalls } from './steam.js';
 import { unityInstalls } from './unity.js';
-import { unrealInstalls } from './unreal.js';
+import { unrealFolders, unrealInstalls } from './unreal.js';
+import { unrealVault } from './unreal-vault.js';
 /** At most this many installs are mapped (each one is a mapping in the .wsb). */
 export const MAX_PC_INSTALLS = 40;
 export const PC_INSTALL_SOURCES = [
     steamInstalls,
     epicInstalls,
+    unrealFolders,
     unrealInstalls,
+    unrealVault,
     unityInstalls,
 ];
+/** What a setting asks for: false (nothing), true (everything) or a list; "auto" follows the Unreal toolchain. */
+function wantedOf(s, setting, unrealOn) {
+    const value = s[setting];
+    return value === 'auto' ? unrealOn : value;
+}
 export function discoverPcInstalls(s, o, pc = pcEnv()) {
     const mappings = [];
     const items = [];
     const notes = [];
     for (const source of o.sources ?? PC_INSTALL_SOURCES) {
-        const wanted = s[source.setting];
+        const wanted = wantedOf(s, source.setting, o.unrealOn === true);
         if (wanted === false || (Array.isArray(wanted) && !wanted.length))
             continue;
         let found = [];
@@ -37,14 +45,22 @@ export function discoverPcInstalls(s, o, pc = pcEnv()) {
             }
             try {
                 const guest = pcInstallGuest(install.kind, install.id);
-                if (mappings.some((m) => m.guest.toLowerCase() === guest.toLowerCase()))
+                // Once each: a folder you registered (writable, listed first) is not mapped again read-only.
+                const same = (m) => m.guest.toLowerCase() === guest.toLowerCase() || m.host.toLowerCase() === install.host.toLowerCase();
+                if (mappings.some(same))
                     continue;
                 if (!dirExists(install.host)) {
                     notes.push('pcInstalls: ' + install.name + ' is not there any more (' + install.host + ').');
                     continue;
                 }
                 assertSafeMapping(install.host, o.packageRoot, o.storageRoot);
-                mappings.push({ host: install.host, guest, readOnly: true, label: 'this PC, read-only' });
+                const writable = install.writable === true;
+                mappings.push({
+                    host: install.host,
+                    guest,
+                    readOnly: !writable,
+                    label: writable ? 'this PC, writable' : 'this PC, read-only',
+                });
                 const { host: _host, ...shown } = install;
                 items.push({ ...shown, guest });
             }
@@ -53,7 +69,11 @@ export function discoverPcInstalls(s, o, pc = pcEnv()) {
             }
         }
         if (Array.isArray(wanted) && found.length < wanted.length)
-            notes.push('pcInstalls.' + source.setting + ': some of the listed ones are not installed on this PC.');
+            notes.push('pcInstalls.' +
+                source.setting +
+                (source.setting === 'unrealEngineFolders'
+                    ? ': some of the listed folders are missing or hold no engine (Engine\\Build\\Build.version).'
+                    : ': some of the listed ones are not installed on this PC.'));
     }
     return { mappings, manifest: { items }, notes };
 }

package/dist/host/pc-installs/epic.d.ts

@@ -1,2 +1,5 @@
+import type { PcInstall } from '../../shared/paths/index.js';
 import type { PcInstallSource } from './source.js';
+/** The games a LauncherInstalled.dat lists that `wanted` maps (by app name), each once. */
+export declare function findEpicGames(text: string | null, wanted: true | readonly (string | number)[]): PcInstall[];
 export declare const epicInstalls: PcInstallSource;

package/dist/host/pc-installs/epic.js

@@ -1,7 +1,38 @@
+// Epic Games Launcher games of this PC (pcInstalls.epicGames): the InstallationList of its LauncherInstalled.dat
+// (%ProgramData%\Epic\UnrealEngineLauncher), engines (UE_x.y) left to unreal.ts. C:\PcInstalls\epic\<AppName>.
+import path from 'node:path';
+import { readBoundedFile } from '../../shared/io/index.js';
+import { launcherInstallations, launcherInstalledFile, MAX_LAUNCHER_FILE_BYTES } from '../../shared/unreal/index.js';
+const APP = /^[A-Za-z0-9._-]{1,100}$/;
+/** The games a LauncherInstalled.dat lists that `wanted` maps (by app name), each once. */
+export function findEpicGames(text, wanted) {
+    const names = wanted === true ? null : new Set(wanted.map((w) => String(w).toLowerCase()));
+    const found = [];
+    for (const i of text ? launcherInstallations(text) : []) {
+        if (!APP.test(i.appName) || /^\.+$/.test(i.appName) || /^UE_\d/.test(i.appName))
+            continue;
+        if (names && !names.has(i.appName.toLowerCase()))
+            continue;
+        if (found.some((f) => f.id.toLowerCase() === i.appName.toLowerCase()))
+            continue;
+        found.push({
+            kind: 'epic-game',
+            id: i.appName,
+            name: path.win32.basename(i.installLocation).slice(0, 100) || i.appName,
+            ...(i.ids ? { version: i.ids.appVersion.slice(0, 60), launcher: i.ids } : {}),
+            host: path.win32.normalize(i.installLocation),
+            guest: '',
+        });
+    }
+    return found;
+}
 export const epicInstalls = {
     kind: 'epic-game',
     setting: 'epicGames',
-    find(_wanted, _pc) {
-        return [];
+    find(wanted, pc) {
+        const bytes = readBoundedFile(launcherInstalledFile(pc.programData), MAX_LAUNCHER_FILE_BYTES);
+        if (!bytes)
+            throw new Error('the Epic Games Launcher has no LauncherInstalled.dat here');
+        return findEpicGames(bytes.toString('utf8'), wanted);
     },
 };

package/dist/host/pc-installs/source.d.ts

@@ -3,7 +3,7 @@ import type { PcEnv } from '../accounts/index.js';
 export interface PcInstallSource {
     readonly kind: PcInstall['kind'];
     /** The settings key that turns it on (pcInstalls.<setting>). */
-    readonly setting: 'steamGames' | 'epicGames' | 'unrealEngines' | 'unityEditors';
+    readonly setting: 'steamGames' | 'epicGames' | 'unrealEngines' | 'unrealEngineFolders' | 'unrealAssets' | 'unityEditors';
     /** What is installed: everything (true) or the ones listed. Bounded reads only (registry, manifests). */
     find(wanted: true | readonly (string | number)[], pc: PcEnv): PcInstall[];
 }

package/dist/host/pc-installs/unreal-vault.d.ts

@@ -0,0 +1,11 @@
+import type { PcInstall } from '../../shared/paths/index.js';
+import { type VaultFs } from '../../shared/unreal/index.js';
+import type { PcEnv } from '../accounts/index.js';
+import type { PcInstallSource } from './source.js';
+/** The vault cache folders of this PC: the ones its launcher settings name, else the default. */
+export declare function vaultDirs(pc: Pick<PcEnv, 'localAppData' | 'programData'>, isDir: (dir: string) => boolean): string[];
+/** The vault folders as installs to map (read-only). */
+export declare function vaultInstalls(dirs: readonly string[]): PcInstall[];
+/** This PC's disk for vaultPacks (bounded lists). */
+export declare const PC_VAULT_FS: VaultFs;
+export declare const unrealVault: PcInstallSource;