Skip to content

Settings UI v1 ​

Behavior and constraints ​

Root settings references a pack-relative JSON document. Omitted settings with zero options yields Empty; with options it yields AutoGenerated. A valid path yields Authored. Invalid paths/documents reject the whole candidate without fallback to AutoGenerated. UI source/canonical hash is recorded separately from manifest identity.

Root schemaVersion=1, defaultLocale and pages are required; translations defaults to an empty dictionary and hiddenOptions to an empty array. Page requires id/title/groups. Group requires id/controls and may omit title. Both default order to 0 and visibleWhen to an empty array. A nonempty page needs a group, and a group needs a control. Preserve authored array order; order ranges from −1000000 to 1000000.

Control requires id/option. widget defaults to auto and also accepts toggle/choice/slider. label/description/unit/format is presentation; advanced/developerOnly defaults false and conditions default empty. Slider step is positive and matches option type; min/max appear together and may only narrow hard bounds. Choice values is required and exactly covers allowed, with display order preserved; entries permit value/label, requiring label. Toggle binds boolean, choice string/integer and slider bounded integer/number. auto rejects widget-specific fields.

Every canonical option appears exactly once in a control or hiddenOptions. Hidden entries permit only required option/reason. Missing, duplicate or simultaneously hidden/visible options fail with P9UI201. UI cannot redefine option type/default/allowed/hard bounds/impact.

A UI condition is option plus exactly one of equals/notEquals/in. Arrays combine with AND; in is nonempty and unique, with type/range-valid values. Page/group conditions affect descendants; controls separate visibility and enablement. The controlled-option → dependency-option DAG rejects self-dependencies and cycles (P9UI203). Manifest oneOf conditions use a different contract.

translations maps locale → key:text. Locale comparison ignores case; keys are case-sensitive. Any translation table requires defaultLocale. Resolve current locale → defaultLocale → caller fallback → key. A missing individual key falls back normally.

Paths are pack-relative .json, at most 256 characters; documents at most 1 MiB. Limits: 32 pages, 64 groups/page, 512 controls/document, 256 choices/control, 16 conditions/owner, 256 condition values, 4096 conditions/document, 512 hidden options, 32 locales, 2048 translations/locale and 8192/document. Local IDs allow 64 characters, short text 256, description/translation/reason 4096 and locale IDs 1–35. Reject duplicate keys and unknown properties at every level. The following fields are an actual Loader-whitelist projection, not an upstream official UI JSON Schema.

root ​

FieldOwnership
schemaVersionReviewed Loader whitelist; behavior above
defaultLocaleReviewed Loader whitelist; behavior above
translationsReviewed Loader whitelist; behavior above
pagesReviewed Loader whitelist; behavior above
hiddenOptionsReviewed Loader whitelist; behavior above

page ​

FieldOwnership
idReviewed Loader whitelist; behavior above
titleReviewed Loader whitelist; behavior above
orderReviewed Loader whitelist; behavior above
groupsReviewed Loader whitelist; behavior above
visibleWhenReviewed Loader whitelist; behavior above

group ​

FieldOwnership
idReviewed Loader whitelist; behavior above
titleReviewed Loader whitelist; behavior above
orderReviewed Loader whitelist; behavior above
controlsReviewed Loader whitelist; behavior above
visibleWhenReviewed Loader whitelist; behavior above

control ​

FieldOwnership
idReviewed Loader whitelist; behavior above
optionReviewed Loader whitelist; behavior above
widgetReviewed Loader whitelist; behavior above
labelReviewed Loader whitelist; behavior above
descriptionReviewed Loader whitelist; behavior above
unitReviewed Loader whitelist; behavior above
formatReviewed Loader whitelist; behavior above
stepReviewed Loader whitelist; behavior above
minReviewed Loader whitelist; behavior above
maxReviewed Loader whitelist; behavior above
advancedReviewed Loader whitelist; behavior above
developerOnlyReviewed Loader whitelist; behavior above
valuesReviewed Loader whitelist; behavior above
visibleWhenReviewed Loader whitelist; behavior above
enabledWhenReviewed Loader whitelist; behavior above

choice ​

FieldOwnership
valueReviewed Loader whitelist; behavior above
labelReviewed Loader whitelist; behavior above

condition ​

FieldOwnership
optionReviewed Loader whitelist; behavior above
equalsReviewed Loader whitelist; behavior above
notEqualsReviewed Loader whitelist; behavior above
inReviewed Loader whitelist; behavior above

hiddenOption ​

FieldOwnership
optionReviewed Loader whitelist; behavior above
reasonReviewed Loader whitelist; behavior above

Complete examples ​

Sources and machine records ​

Coverage inventory · Schema v5 · Catalog v2 · Completion v2

schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·

ShaderPackSettingsUiLoader.cs

Author documentation · Manifest v5 / Scene ABI v2