---
title: "Editor tools, packaging, and diagnostics"
description: "Quartz UI 0.57.0-dev: Editor tools, packaging, and diagnostics. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# 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](https://betterbuilt.games/docs/quartz-ui/evidence).

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:

```text
{"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:

```js
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

```powershell
& '<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
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](https://betterbuilt.games/docs/quartz-ui/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.

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/tools-shipping