Editor tools, packaging, and diagnostics

0.57.0-dev · beta source documentation. Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See validation and limits.

Keep shareable runtime policy in UQuartzUIProjectSettings / DefaultGame.ini. Keep workstation Node/Vite/debug preferences in UQuartzUIEditorSettings / EditorPerProjectUserSettings. Neither a successful browser preview nor a green JavaScript suite proves a packaged client.

Build metadata

quartzui.build.manifest is JSON with a stageable suffix. The external frontend build writes it; the audit does not run Node, install packages, or rebuild your app.

For the first-UI example only, with no String Table, no supported cultures, and no generated localization files, the native localization canonical input is exactly:

{"schemaVersion":1,"stringTable":"","cultures":[],"files":[]}

Include one LF after that object when hashing its UTF-8 bytes. This Node build fragment assumes the generated contract has been compiled into the stated path and outputDirectory is your already-created app output:

import { createHash } from 'node:crypto';
import { writeFile } from 'node:fs/promises';
import { join } from 'node:path';
import { QUARTZUI_CONTRACT_HASH } from './generated/gameui.contract.js';
const canonical = JSON.stringify({ schemaVersion: 1, stringTable: '', cultures: [], files: [] }) + '\n';
const localizationFingerprint = 'sha256:' + createHash('sha256').update(canonical, 'utf8').digest('hex');
await writeFile(join(outputDirectory, 'quartzui.build.manifest'), JSON.stringify({
  schemaVersion: 1, appId: 'gameui', resourceOwner: 'project', entryPage: 'index.html',
  contractFingerprint: QUARTZUI_CONTRACT_HASH, localizationFingerprint,
}) + '\n', 'utf8');

For localized projects use the native Editor API FQuartzUIProjectAuditService::ComputeLocalizationFingerprint(Settings, ProjectDirectory, OutFingerprint, OutIssues) and BuildCanonicalAppMetadata, or mirror its exact canonicalization in your build and compare against audit output. It hashes the String Table path, sorted cultures, and generated files including project-relative paths, sizes, and SHA-256. Do not reuse the empty-localization hash after configuring localization. LocalizationStringTable and SupportedCultures require generated catalog files; this checkout does not supply a complete project localization exporter.

Audit and cook

& '<UE_ROOT>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe' `
  '<HOST_PROJECT>.uproject' -run=QuartzUIValidate -Mode=Shipping `
  '-Manifest=<PROJECT>/Saved/QuartzUI/manifest.json' `
  '-Report=<PROJECT>/Saved/QuartzUI/audit.json' -unattended -nop4

The two evidence files above are separate from the app's quartzui.build.manifest. Audit checks settings, registered app identities, compiled files, current contract/localization fingerprints, and staging policy. Inspect each FQuartzUIValidationIssue code, app, field, value, policy, and correction. FQuartzUIProjectAuditResult lists accepted apps/files and deterministic identity; do not ship stale evidence as if it validated a new bundle.

Registered app assets discover their contract/provider closure for cooking. Their cook hook sends only audited hash-verified files through UFS. No project DirectoriesToAlwaysStageAsUFS rule is required; do not add a loose NonUFS fallback. Use the host's signed/encrypted Pak/IoStore policy as appropriate. Ship static output and required licenses, not Node, development source maps, credentials, or a runtime CDN dependency.

Runtime resources use exact https://<app-id>.quartzui.test/ origins without DNS/network access. Roots/entries are immutable registered mappings; production allows at most 63 project IDs alongside the built-in fixture. Resource policy rejects traversal/reparse escapes, denies unwanted navigation/popups, sets MIME/CSP/no-store headers, and bounds full bodies to 64 MiB. A tested range-policy seam does not imply browser Range support: Epic's public adapter lacks request headers. Seekable media needs separately validated adapter work.

DevTools and Vite

Start PIE, then Tools > Quartz UI > Open DevTools. Select the correct page when several are present. The startup log's debugging-port message proves configuration, not a live inspector. Preferences default to loopback port 9222; changes need restart, and simultaneous editors need distinct ports. Project development policy can disable the capability. Packaged Shipping behavior must not depend on editor debugging.

Under Development Server, configure a project-owned frontend root, Node executable, app ID, and fixed port before Start Vite Dev Server. The checked-in default root is a legacy relative path and may not match your project. Install locked frontend dependencies separately. Stop Vite Dev Server ends only the Editor-owned process tree; new views then use packaged resources. Development registry, launch policies, and DevTools target records are advanced editor implementation seams, not gameplay endpoints.

Contract and migration tools

QuartzUIContract -App=<id> -Output=<file> generates one configured app's identity and declarations. -Check verifies freshness without accepting a mismatch. Omitting App or selecting core generates the immutable middleware catalog. The menu chooses the configured default app. QuartzUI.ExportContract <app-id> <filename.ts> writes under the host's QuartzUI/Generated root; it does not recook changed assets.

For legacy fixture migration, use Advanced > Migrate Reference App to Project or QuartzUIMigrate -LegacyFixture -AppId=reference -Entry=index.html -Asset=/Game/QuartzUIConfig/DA_QuartzUIReference. Use -Source=<prebuilt-directory> for project-owned prebuilt source and -DryRun first. Destinations must be unoccupied. The tool records changes under Saved/QuartzUI/Migrations. -Rollback restores recorded Default App selection while retaining created assets/files for recovery; it is not deletion.

For the former PrismUI/WebUIUnreal identity, update includes/module names, configuration, browser origins, generated contracts, and frontend together. Config/DefaultQuartzUI.ini contains serialized asset redirects. Resave assets through Unreal; never edit .uasset bytes. Host-specific AngelScript bindings, migration scripts, or Lyra probes cited in historical docs are not shipped here.

Diagnostics and validation

Use UQuartzUIDiagnosticsLibrary::GetRuntimeStats, DumpRuntimeStats, EstimateSurfaceBytes, and EvaluateRuntimeBudget. FQuartzUIRuntimeBudget contains caller-selected limits; negative limits disable their gate. Compare baseline/current stats and inspect violation IDs. The surface estimate is four bytes per BGRA pixel, not complete CEF/GPU memory. QuartzUI.DumpStats and stat QuartzUI expose the same bounded operational picture; Insights and Chromium profiling are needed for full timing.

Repository-only commands:

powershell -NoProfile -ExecutionPolicy Bypass -File Scripts/ValidateRepository.ps1
Get-ChildItem Resources/Client/*.test.mjs | ForEach-Object { node $_.FullName }
python -m unittest discover -s Scripts -p 'test_*.py'

Check each command's exit status. Direct test-file execution avoids child-process isolation restrictions; node --test <explicit files> is the normal alternative. Do not pass an unexpanded wildcard to older Windows Node versions.

Build a host Editor target before native tests, then run the relevant QuartzUI.* automation groups. Host/RHI runs must separately cover readiness/recovery, exact-player split-screen isolation, Back ordering, input/IME, travel, textures, scene backdrop, direct surfaces, and packaged UFS reads. The module inventory does not provide a standalone Editor target.

Shared authoring skills and fixtures

Skills/game-ui-design and Skills/quartz-ui-implementation are authoring instructions, not runtime modules. Scripts/link_agent_skills.py --project <host> --check checks links; omit --check for deliberate installation. It refuses conflicting destinations and Windows needs symlink capability. The host owns agent routing and its frontend components. Resources/Web and the effects/visual-suite docs are compatibility/test fixtures, not a reusable production component library. See the inventory for every shipped tool and boundary.

Audit implementation (source: Source/QuartzUIEditor/Private/QuartzUIProjectAudit.cpp), editor guide (source: Documentation/EditorTools.md), development guide (source: Documentation/Development.md). Command templates require host substitutions and were not executed against Unreal during this scan.