|
Window Framework for UI Toolkit v2.0.x
|
Let players make the interface their own without opening Unity or changing your application code.
Player Themes provide independently editable JSON/image folders, runtime discovery and selection, and useful reports when a value or file needs attention. They build on your configured themes and supported Developer Extensions. You control the available settings, font references, application targets, and validation boundaries.
This guide covers developer setup and the player's copy/edit/select workflow. It uses the existing settings controls and the existing example.hotbar Demo extension—not another demonstration control or theme system.
The controller initializes the existing selection owner during startup after its root/configuration is available. Configured Addressables hydration can defer that initialization; see Optional: Addressables Theme Loading. Creating a settings form alone does not initialize the controller or create a player copy.
Use 11. Prepare Values When Offering Player Themes for the preparation controls and 9. Prepare the Theme for Player Use for custom settings. Do not create a second owner for the same UI just to enable this workflow.
The supplied Theme Settings form presents built-in themes and imported player themes together. Its relevant actions are:
Copy/refresh controls require enabled support and a ready runtime session. Open Theme Folder is available on the supported desktop platforms; other targets need an application-appropriate file-access workflow. No action here grants arbitrary filesystem access or creates UI content for your game.
The copy uses prepared framework values, supported extension snapshots and raster images. It validates its staged output before promoting the new folder, then refreshes the catalog and selects the copy. The source theme, source player folder and existing destinations are not overwritten.
A compatible prepared baseline is required. For a built-in source, that is the selected built-in theme. For an imported source, the configured default supplies omitted framework values; accepted player values and supported extensions are layered over it. A copy is not a duplicate of every arbitrary USS selector, layout rule or unregistered behavior.
If required preparation, fonts, scope or supported values are missing, read the report rather than creating a competing defaults file. Copying can fail before any theme files are committed. If a copy was already committed but could not be selected or saved as the active choice, its folder remains: refresh/select that copy instead of assuming it was deleted.
Cancellation applies before commit and releases the operation's pending work. It does not delete an independent folder after commit.
A copy name is one literal folder name, 1–80 characters. Internal spaces are allowed, but leading/trailing spaces, trailing dots, path separators, control characters and portable Windows-reserved names are not. Unicode names must use the supported normalized form.
Existing file/folder names are checked case-insensitively, so My Theme and my theme are not independent destinations. Choose another name when validation disables Create Copy. Suggestions are not automatic commits.
The exporter generates a new player-... ID. Keep that ID when editing the copy. It identifies the theme independently of its display name or folder position. Duplicate IDs cause all matching discovered themes to be rejected.
The configured root is:
The default local root name is WindowFrameworkThemes. This is runtime storage, not the project's Assets/Resources theme repository. Use Open Theme Folder where supported instead of guessing an absolute machine-specific path.
Each theme is an immediate child folder containing theme.json. Copies can also include:
Image numbering is an export detail; use the actual references in your copy. Unreferenced loose files do not automatically become theme settings.
Generated copies contain "nameSource": "folder", so their displayed name follows the validated folder name when loaded. The JSON name field is still required metadata; changing it alone does not rename a folder-named copy. Older manifests without nameSource use their JSON name. To rename a generated copy, use a valid folder name and refresh while preserving its ID.
Start with the copy generated by the application. Change only the values you intend to customize, save the file, and refresh. Normal JSON syntax and unique field names are required; malformed or duplicate-key input produces a report with a line/position where available.
The following compact example shows the data structure. It is documentation text, not an instruction to replace your copy's generated identity or remove its other fields:
formatVersion 1** is the portable manifest version, separate from the 2.0 theme architecture. Use the ID from your real copy, not the example ID above. A manifest is limited to 256 KiB of UTF-8 JSON.
Framework values are grouped JSON keys.window.backgroundColor means the backgroundColor field inside window; it is not a USS class or the literal root key "window.backgroundColor".
Unknown framework groups/keys are not accepted. A recognized field with an invalid supported value can be omitted with a warning and retain its configured default. Missing overrides do not erase the baseline. A valid key is still only a supported value; visible effects depend on the controls/rules that consume it.
Put the image inside that player's theme folder and change the relevant relative reference. For example, an existing copy can reference "images/custom-icon.png" after the player places that file beneath its own folder.
Use forward slashes, not backslashes. Do not use absolute paths, project asset URLs/GUIDs, web URLs, .., empty path segments, or links/reparse paths to files outside the folder. Validating the JSON path is followed by filesystem containment and image validation before loading.
The optional root preview value controls the list thumbnail, independently of window/background/icon settings. A missing preview can leave the list without that thumbnail and produce a report. Missing or corrupt supported artwork can be omitted with issues while other values remain usable; unsafe paths reject the theme.
Player inputs are raster PNG/JPG/JPEG, not SVG or native VectorImage assets. When a configured source includes supported compiled vector artwork, the asynchronous copy path rasterizes it for export. That does not enable player-supplied SVG parsing or promise lossless reproduction of every vector asset.
Keep images sensibly sized for your target's memory and display needs. The importer checks representation, headers and containment, but a safe path is not a promise of unlimited image memory or identical decoding on every platform.
text.fontId is optional metadata identifying a font already supplied by the application:
Keep an exported identifier or choose one the application actually provides. Players cannot import a new font by placing a TTF/OTF file in the folder or entering an arbitrary path. Invalid/unavailable identifiers produce recovery guidance and use the configured fallback where supported.
Fonts, glyph coverage and panel text settings remain developer configuration. See Theme Studio and Manager for authoring and preparation rather than adding another font-defaults store to a player theme.
The existing example.hotbar section supplies the Demo's appearance/geometry settings. The JSON example above changes its width and normal slot color. For the full key list, declaration files, selector scope and image mapping, follow Developer Extensions.
Players change namespace/key values, not metadata types, constraints, class names, C# types or selector structure. Missing keys use the configured prepared defaults. Invalid typed/out-of-range known values can recover with issues; unknown keys in a known generated section or unsafe image paths reject it.
Unknown unregistered extension namespaces remain opaque data, are ignored for application, and can be retained during export. They do not create or execute a new handler. The application must declare/prepare supported custom settings before those controls can participate.
After saving edits, choose Refresh Player Themes. Discovery reads immediate theme folders and validates their data/images. It is explicitly requested, not continuous file watching.
If the currently selected identity is still available, refresh can reapply that identity's new values. To switch to another theme, use its Set Active action. Creating an editable copy also performs its own refresh/selection after a successful commit.
The existing controller-owned session persists successful selection through framework storage and restores by identity at startup. An unavailable saved theme can fall back to the configured default. Invalid default/built-in identity configuration is a developer setup problem, not a request to infer defaults from whichever row appears first.
A root-level discovery failure retains the previous catalog/selection instead of replacing it with an incomplete snapshot. Individual rejected folders are reported as unavailable entries. At most 100 immediate folders are considered in a catalog discovery; the naming scan also has its own bounded repository-entry checks.
Selecting a built-in/default theme releases the player-value bindings; it does not delete editable folders. Use the existing default-selection path when resetting appearance. Deleting or renaming an active folder externally requires refreshing and may cause identity fallback. Keep a copy of your edits when reorganizing files manually.
Window-memory enablement remains the controller's developer-owned policy. Player theme selection and preference reset do not enable or disable it.
The issue card uses the existing controller-managed modal and scrolling body. It does not create a separate windowing host or new theme owner.
Common blocking causes include malformed/duplicate JSON, unsupported framework groups/keys, invalid identity, duplicate player IDs, unsafe paths or links, unavailable source configuration, and known-extension validation failures. Recoverable cases include invalid recognized field values and missing/corrupt supported images.
Correct the reported field/file, save, then refresh. A warning is not proof that every requested value was used, and a successful structural parse is not a complete visual test. See Troubleshooting for the troubleshooting guide.
The supplied ThemeSelectorFormElement already provides the copy/refresh/folder/selection workflow. Use the controller's existing runtime owner for custom integration rather than another unrelated session for the same controls.
Relevant existing APIs are:
Copy requires an attached, resolved application scope and current prepared values. With extensions, that scope must belong to the configured independent application scopes without ambiguity. Image-capable extension import/application uses the existing folder-aware resources, not unvalidated paths in a custom callback.
When you change controls while a player theme is active, retain the existing attach/detach and explicit RefreshControls integration. Bindings own their applied properties and release before imported textures/folders are disposed. Your application's subscriptions, business data and unrelated UI remain your responsibility.
Neither the exporter nor a successful copy serializes arbitrary CSS, C# behavior, new asset types, gameplay logic or every fixed inline style. The prepared framework/extension vocabulary defines what can be carried into the copy. Use Stylesheet Setup and Theme Structure and Developer Extensions to design supported application rules.
These are the 164 current catalog fields, grouped as JSON objects. Names/case are exact. Fields listed within a group belong inside that group's object; for example, backgroundColor below window means window.backgroundColor.
All numeric bounds below are inclusive. Dimensions/font sizes are pixels unless identified as motion time or opacity. This reference describes accepted data, not a guarantee that every value has an independent visible consumer in every application. text.fontId is additional prepared-font metadata described above, not one of the 164 catalog entries.
Check the existing application workflow with its intended configuration:
Continue to Developer Extensions for application-specific settings, Theme Studio and Manager for authoring/preparation, or Troubleshooting for configuration problems. Player Themes expand supported appearance customization; they do not require duplicating the application's styling system or provide unrestricted modding.