settings
Resolves four questions about an asset's typed settings, all answered from its type's `type.yaml` — nothing here is found by convention.
assetType.shared.settings
Resolves four questions about an asset's typed settings, all answered from its
type's type.yaml — nothing here is found by convention.
local Settings = require("@builtin::assetTypes.assetType.shared.settings")
-- or, from inside the assetType runtime:
local Settings = require("@builtin::assetTypes.assetType.shared").settings
Where does a type's schema live?
type.yaml names it in a settings: block:
settings:
values: "settings.yaml" # where an instance's own values live
schema: { type: "settings.luau" } # one schema for every asset of this type
or, for a type whose settings differ per instance (an importer):
settings:
values: "settings.yaml"
schema: { instance: "settings.luau" }
or, for a type whose schema is a table its instance's own source declares and
whose values live elsewhere (a component: its public fields, valued on each
entity it is on):
settings:
schema: { instance: "init.luau", export: "public" }
Whether an instance may lack its schema file is what the type's files:
block says of that file. Listed under files.optional, it may be absent, and
an instance without it declares no settings — the importer type lists it
there, since most importers take none. Listed under files.required, or not
listed at all, it must load, and an instance missing it is a broken
declaration and is logged.
schema.type is required at the folder relative to the TYPE's own
.assetType/ directory (one schema shared by every instance).
schema.instance is required relative to each INSTANCE's own folder (init
resolves the instance's own identity; anything else is a sibling module under
it). Without schema.export, the file is required as a module and its return
value IS the schema. With schema.export, the file is run in an environment
of its own and export is read from a returned table carrying it, or else
from the globals the file assigned — a component's public is such a global.
That environment reads through to _G and takes every write itself; its own
_G is itself, its declare and computed record into it, and its task
records spawned, deferred and delayed work instead of starting it. Every other
global is the real one, so a call the file makes through one runs as it does
anywhere. The schema is the declared table's Field descriptors. A schema that
resolves to nothing says why through Settings.schemaProblemOf(ref): the file
could not be read, compiled or run, or declared no such table. An instance
schema is read again when its file, its type's type.yaml, or the entry file
of any module the asset requires changes. Settings.blockFor(typeName)
returns the raw block; Settings.schemaForType(typeName) and
Settings.schemaOfInstance(ref) resolve the two schema shapes respectively;
Settings.schemaFor(ref) tries the type-level schema first, falling back to
the instance-level one. ref naming an assetType asset itself — e.g.
asset.resolve("texture", "assetType"), rather than an instance of it —
reports that type's own declared schema, the same one every instance of it
reports.
Where do an asset's values live?
settings.values names a file living beside the asset's own content —
Settings.valuesPathOf(ref) joins it onto the asset's path.
Settings.valuesOf(ref) / Settings.writeValues(ref, values) read and write
it; this module only names where it is. A type that declares its schema with
no settings.values keeps no values in the asset — a component's live on each
entity it is on — so valuesOf answers nil for it, asset.create refuses a
settings table for it, and asset.setSettings refuses a write.
Settings.recordedWrite(path, text) writes a file the way every values file
is written, and an editor uses it for any other file it writes. It writes the
whole contents, records the write into the open undo operation when one is
open (so undoing it restores what the file held), and raises when the write
does not land.
In what order are a schema's fields declared?
Every Field.* constructor stamps its descriptor with declaredOrder, one
more than the last. Luau evaluates a table constructor's entries in the order
they are written, so Settings.orderedNames(schema) lists a schema's fields —
and a struct's subfields — in the order the source writes them.
A values file, or a legacy .metadata settings block, may hold an older
spelling — a renamed field, an older enum member. Every read passes what is
stored through the type's normalizeSettings (Settings.normalizeFor), so
it answers in the fields the schema declares today, and writes nothing. The
next local edit of that asset rewrites the file in the declared spelling
(Settings.healLegacyIfNeeded).
asset.setSettings(ref, patch) writes a partial patch:
Settings.resolvePatch(ref, patch) normalises it, merges it over the current
values and applies the type's derived defaults for the fields it changed, and
Settings.writeValues(ref, values, patch) applies the corrections, checks the
schema and writes the file.
How is a new asset's settings resolved at creation?
asset.create calls Settings.resolveForCreate(typeName, name, destPath, creationOpts, callerSettings, importerSettings) before running the type's
onCreate, checks the result against the schema, writes it to the values
file, and hands onCreate a COPY of it as opts.settings (Settings. cloneValues) — never the same table the values file gets, so nothing
onCreate does to its own copy can reach what was stamped. onCreate reads
settings from opts.settings and never writes to it. asset.create also
seeds the change baseline with the stamped values
(Settings.seedChangeBaseline), so the values file's own first dispatch
reports nothing changed and the payload onCreate encoded is the only
encode a create runs.
The layers, lowest priority first, each overriding the ones before it field by field:
- The schema's own declared defaults (
Settings.defaultsOf). - The type's own
settingsDefaults(name, opts, asked)hook, when itsbehavior.luauexports one.askedholds what layers 3 to 5 name, so a default can follow a field one of them sets. - The Preset Manager's matching row (
Settings.presetLayerFor). - The creating importer's settings for this type.
- The
settingstable the caller passed toasset.create. - The type's own
settingsDerivedDefaults(values, explicit, changed)hook, when itsbehavior.luauexports one — a field whose default follows another field, set only when no layer from 2 to 5 named it. - The type's own
settingsCorrections(values, name, opts)hook, when itsbehavior.luauexports one — applied last, once every other layer has merged.
Layers 2 to 5 are each read through the type's normalizeSettings, so a
layer naming a field in an older spelling sets the field it names today.
asset.create's top-level settings alias accepts those older names too
(Settings.acceptedFieldNames).
Layer 7 is Settings.applyCorrections(typeName, values, explicit, context),
the one corrections path every settings write takes — this create chain, and
Settings.writeValues for every later write (asset.setSettings, a type's
first-encode seed, the legacy heal). explicit names the fields the writer
asked for: the caller's settings table here, the patch for
asset.setSettings. A correction lands SILENTLY on a field the writer did not
name — nobody asked for that value, so overriding it just states a fact. A
correction that contradicts a field the writer named REFUSES the write,
naming the field, the value asked for, and why it cannot hold — the same as
every other place this codebase refuses an explicit request it cannot satisfy
(a Field.checkSchema violation, a BC7 alignment error) rather than silently
rewriting it into something else. So asset.setSettings(tex, { compression = "rgba16" }) on a mipped texture stores generateMipmaps = false beside it,
while asset.setSettings(tex, { compression = "rgba16", generateMipmaps = true })
is refused.
Field.checkSchema runs once, over the result AFTER the corrections hook has
applied — a bad value nothing corrects refuses the creation.
Four hooks, four different jobs
Every hook is an optional export on a type's behavior.luau, alongside
onCreate / onChange. None is ever handed a table to mutate — each
reads what it's given and RETURNS a table of what it wants changed (or nil);
resolveForCreate, resolvePatch, applyDerivedDefaults and
applyCorrections are the only places that write to the values, by merging
what a hook returns the same way every other layer merges.
-
normalizeSettings(values) -> valuesmaps every older spelling a stored file or a write may carry to the field and member the schema declares now, returning a new table; a table naming both an older field and its replacement keeps the replacement. The companion exportnormalizedSettingNames = { ... }lists the older field names it accepts beyond the schema, so a write naming one is not refused as an undeclared field.texture.assetType's maps the fields its earlier schema stored tocolorSpace+compression, and the olderfilterkeywords tolinear/nearest. -
settingsDerivedDefaults(values, explicit, changed) -> partial?answers the values of fields whose default follows another field. At creationchangedholds every field; on a write it holds the fields the write moved. A returned field applies only whereexplicit— the fields the writer named — does not name it. -
settingsDefaults(name, opts, asked) -> partial?supplies a DEFAULT the schema itself has no syntax for — something only knowable at creation time, like a naming convention, a fact read off a payload the caller handed in, or a value that follows a field a higher layer sets (askedholds what the Preset Manager, the importer and the caller name, the higher one's value where two name a field). It runs early (layer 2 above), so any later layer — Preset Manager, importer, caller — freely overrides it.texture.assetType's returns thetextureTypethe name suggests (a_normal-suffixed name is anormalMap),compression = "uastc"andmaxDimension = 4096, withrgba8for atextureTypeofspritethat a higher layer names; for a pre-encoded ZTEX payload it returns the colour space, compression and sampler the payload's own header carries. Either way, an explicitsettings = { ... }from the caller still wins. -
settingsCorrections(values, name, opts) -> (partial?, reasons?)enforces a CROSS-FIELD CONSTRAINT the schema itself has no syntax for — a fact about one field that depends on another field's resolved value, true regardless of which layer produced that value. It runs last (layer 7 above), over the fully mergedvalues, and again on every later write of the values file. Nothing is left unmet in what gets validated and stamped — but a value the caller explicitly asked for is never silently rewritten to satisfy it;applyCorrectionsrefuses instead (see above). The optional second return,{ [field]: reason }, supplies the "why" for that refusal message; a field with no reason falls back to a generic one.texture.assetType's returns{ generateMipmaps = false, maxDimension = 8192, colorSpace = "linear" }whenever the RESOLVEDcompressionis high-precision (the encoder stores one verbatim, linear, and refuses a mip chain or a downsample for it outright), paired with a reason naming the compression, andnilotherwise.
What does a declarer declare?
Field.settingsOf(identity, mode) embeds another declarer's schema as a
struct field without restating it. The identity names one of two kinds of
declarer, and Settings.schemaOfDeclarer(identity) tells them apart by what
identity resolves to:
- An assetType (e.g.
"@builtin::assetTypes.texture") — embeds the schema every instance of that type carries, resolved viaschemaForType. This is the type-level shared schema from the section above, not a per-instance one — an assetType has no settings of its own to declare per instance. - Anything else (an importer, or any other asset that declares settings
of its own) — embeds that asset's own schema, resolved via
schemaOfInstance.
Every schema this module serves has already run its Field.settingsOf
fields through this resolution — a caller reading schema.someField.fields
never sees an unresolved declarer with no fields. Resolution descends
into an already-literal struct's fields and a list's element the same
way, so a declarer embedded several fields deep is still reached. A declarer
that embeds itself, directly or through another declarer, stops one level
short of the loop instead of recursing forever.
What are the defaults?
Settings.defaultsOf(schema) reads every field's declared default into a
plain table — a field declared without one is absent from the result rather
than holding a nil value.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2module AssetTypeSharedSettings Typed per-asset settings: which schema governs an asset, what its values are, and where both are declared. A type's `type.yaml` names its schema file and its values file; nothing here is found by convention.
blockFor(typeName: string) → any
The `settings:` block a type declares, or nil when it declares none.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name, e.g. "texture". |
examples
local block = Settings.blockFor("texture")listedOptional(typeName: string, file: string) → boolean
Whether `typeName`'s type.yaml lists `file` under `files.optional` — an instance of the type may then lack it. Read from the parse `TypeYaml.of` holds.
| arg | type | description |
|---|---|---|
| typeName | string | |
| file | string |
schema_from_module(identity: string?, path: string?, stem: string, export: string?, typeName: string, file: string) → void
Require a type's declared schema module and return the table it declares. `export` names a key inside the module's return value; without one the return value IS the schema. Resolved through `AssetRef.requireTypeModule` — the same resolution `behavior.luau` goes through, reaching a builtin, world-authored, or library-vendored type's module alike by its identity and its folder path together. `typeName` and `file` name the problem: a schema file the type.yaml declares that fails to load, or resolves to something other than a table, is reported by name — the type, the file, and why — and that report is the second return value.
| arg | type | description |
|---|---|---|
| identity | string? | |
| path | string? | |
| stem | string | |
| export | string? | |
| typeName | string | |
| file | string |
inert_computed(fn: any) → string
What `computed(fn)` hands back inside a declaration read: a placeholder string standing where the engine's registered sentinel would stand. It is no Field descriptor, so the schema leaves it out.
| arg | type | description |
|---|---|---|
| fn | any |
inert_task(held: { any }) → any
The `task` a declaration read sees: `task` itself for every read and wait, with each call that would start work — `spawn`, `defer`, `delay`, `delayRealtime`, `loop`, `spawnSystem`, `batched` — and `onError`, which installs a handler, recorded into `held` instead. A recorded call runs nothing and returns 0, the handle of no task; `cancel` and `collect` of such a handle do nothing.
| arg | type | description |
|---|---|---|
| held | { any } |
hold(name: string) → void
| arg | type | description |
|---|---|---|
| name | string |
onError(...: any) → void
| arg | type | description |
|---|---|---|
| ... | any |
cancel(_handle: any) → void
| arg | type | description |
|---|---|---|
| _handle | any |
collect(_handle: any) → void
| arg | type | description |
|---|---|---|
| _handle | any |
evaluate_declaration(filePath: string, export: string, typeName: string, file: string) → void
A schema declared by `export` is read by running the declaring file in an environment of its own and taking `export` from what it returns (when that is a table carrying it) or else from the globals the chunk assigned. A component's `public` is such a global. The environment is a table whose reads fall through to `_G` and which takes every write itself, the shape of the environment the engine gives each component instance. It holds five names of its own: * `_G` — the environment itself, so `_G.x = v` and `rawset(_G, k, v)` land in it; * `declare` — records its table into the environment (`__declared`); * `computed` — returns `inert_computed`'s placeholder; * `task` — `inert_task`, which records work instead of starting it; * `__heldTasks` — that record. Every other name is the real global. A call the chunk makes through one — a `require`, an engine API — runs as it does anywhere; a module a `require` loads runs once per VM and is shared with every other caller. The schema is the table's Field descriptors; a method, a computed placeholder or any other value beside them is not a setting.
| arg | type | description |
|---|---|---|
| filePath | string | |
| export | string | |
| typeName | string | |
| file | string |
declare(meta: any) → void
| arg | type | description |
|---|---|---|
| meta | any |
required_module_versions(ref: any) → void
The entry file of each module `ref`'s sources `require` that its reference table has bound, with each file's content version now, and whether some of the modules it requires are not yet known: the table cannot be read, or it still lists a `require` whose target it has not bound. A module asset is a folder whose entry is its `init.luau`; a module written as a single file is its own entry.
| arg | type | description |
|---|---|---|
| ref | any |
deps_unchanged(deps: { { path: string, version: number } }) → boolean
Whether every recorded module still holds the version it was read at.
| arg | type | description |
|---|---|---|
| deps | { { path: string, version: number } } |
pending_deps_bound(held: any, ref: any) → boolean
Whether an entry read while some required modules were unknown now knows a module it did not: derived again at most once per `PENDING_DEPS_RECHECK_S`, and the entry's pending flag cleared once nothing is unknown.
| arg | type | description |
|---|---|---|
| held | any | |
| ref | any |
awaiting_keys(block: any, identity: string?, folder: string?, file: string) → void
The require keys a schema module that resolved under none of them waits on: every key `requireTypeModule` tries, when the block requires the file as a module and not one of those keys is registered. A module source is registered after the write or move that lands it, so a read in between finds none. Nil when the block evaluates the file, or a key is registered.
| arg | type | description |
|---|---|---|
| block | any | |
| identity | string? | |
| folder | string? | |
| file | string |
registered_since(awaiting: { string }?) → boolean
Whether a module key an entry waited on is registered now.
| arg | type | description |
|---|---|---|
| awaiting | { string }? |
requiredModulesRecord(ref: any) →
What a read derived from `ref`'s code depends on beyond `ref`'s own files: the entry file of each module its sources `require` (as its reference table has bound them), with the content versions they have now, and whether some module it requires is not yet known. Hold it beside the value read, and ask `requiredModulesCurrent` before serving the value again.
| arg | type | description |
|---|---|---|
| ref | any | The asset. |
examples
held.modules = Settings.requiredModulesRecord(ref)
requiredModulesCurrent(record: any, ref: any) → boolean
Whether a value read alongside `record` still stands: every module it listed holds the version it was listed at, and — when some required module was not yet known — none of those has become known since. That last question is asked again at most every quarter second, so a read held while a module was unknown is not read again on every call.
| arg | type | description |
|---|---|---|
| record | any | What `requiredModulesRecord` answered. |
| ref | any | The asset the record was taken for. |
examples
if held and Settings.requiredModulesCurrent(held.modules, ref) then return held.value end
requiredModulesStamp(record: any, ref: any) → string
Text that moves when a module a record listed changes, or when a module it required before that module was known becomes known (asked at most every quarter second, as `requiredModulesCurrent` asks it): the content versions of its listed modules now, and whether the read beside it has gone stale. Fold it into a build signature to rebuild what was read from code that requires them.
| arg | type | description |
|---|---|---|
| record | any | What `requiredModulesRecord` answered. |
| ref | any | The asset the record was taken for. |
examples
parts[#parts + 1] = Settings.requiredModulesStamp(held.modules, ref)
declared_schema(block: any, identity: string?, folder: string?, file: string, typeName: string) → void
The schema a `schema:` block declares in `file` inside `folder`: evaluated when the block names an `export`, required as a module otherwise.
| arg | type | description |
|---|---|---|
| block | any | |
| identity | string? | |
| folder | string? | |
| file | string | |
| typeName | string |
resolveDesc(desc: any) → any
Fill in `fields` on an unresolved `Field.settingsOf` descriptor (`kind = "struct"`, `declarer` set, `fields` nil) by resolving its declarer's own schema, and descend into an already-literal struct's `fields` or a list's `element` to reach one nested deeper. Never mutates `desc` — a struct or list descriptor that needs its `fields`/`element` replaced is copied first, so the table a `require` cache holds is untouched.
| arg | type | description |
|---|---|---|
| desc | any |
resolveSchema(schema: any) → void
| arg | type | description |
|---|---|---|
| schema | any |
schemaForType(typeName: string) → any
The schema governing the settings of assets of `typeName`, when the type declares one at type level (`schema: { type = ... }`).
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local schema = Settings.schemaForType("texture")schemaOfInstance(ref: any) → any
The schema an individual asset declares for itself, when its type says the schema is per instance (`schema: { instance = ... }`). Whether an instance may lack the file is what the type's `files:` block says of it: a schema file listed under `files.optional` may be absent, and an instance without one declares no settings; one listed under `files.required`, or not listed at all, must load, and a missing one is the instance's declaration broken, and is logged.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
local schema = Settings.schemaOfInstance(importerRef)
schemaProblemOf(ref: any) → string
Why `ref`'s settings schema resolved to nothing: the declaring file could not be read, compiled, run, or did not declare its table; or the type refused what it declared — the sentence its `behavior.luau`'s exported `settingsSchemaProblem(schema, ref)` returned. Nil when the schema resolved or `ref`'s type declares none.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
local why = Settings.schemaProblemOf(compRef)
schemaFor(ref: any) → any
The schema governing `ref`'s own settings values — the type-level schema when its type declares one, else the schema the asset declares for itself. `ref` naming an assetType asset itself (rather than an instance of one) reports that TYPE's own declared schema — the same schema every instance of it reports.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
local schema = Settings.schemaFor(texRef)
whyNoSettings(ref: any) → string
Why `ref` carries no settings, as a sentence naming where they would be declared: the type declares no settings block; or the type declares a schema per instance and this instance ships none, naming the file it would be; or the type's declared schema did not load.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref, one for which `M.schemaFor` answered nil. |
examples
error("asset.setSettings: " .. Settings.whyNoSettings(ref))schemaOfDeclarer(identity: string) → any
The schema a declarer declares, named by its identity. This is what `Field.settingsOf(identity)` resolves to: an assetType's instance-settings schema, or an importer's / component's own declared schema.
| arg | type | description |
|---|---|---|
| identity | string | The declarer's asset identity. |
examples
local schema = Settings.schemaOfDeclarer("@builtin::assetTypes.texture")defaultsOf(schema: any) →
Every declared default of `schema`, one value per field. A field declared without a default is absent rather than nil-valued.
| arg | type | description |
|---|---|---|
| schema | any | The Field schema table. |
examples
local values = Settings.defaultsOf(schema)
assetPathOf(ref: any) → string
The folder `ref` names: its own `path`, or — for a ref that carries only its guid or identity, the `{ __ref, type, name }` envelope a saved asset field holds — the path that guid or identity resolves to. Nil when neither names an asset.
| arg | type | description |
|---|---|---|
| ref | any |
valuesPathOf(ref: any) → string
The path of `ref`'s settings values file, per its type's declared `settings.values`, or nil when its type declares no values file. A ref that carries its guid or identity without its path reaches the same file through what that name resolves to.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
local p = Settings.valuesPathOf(texRef)
type_behavior(typeName: string) → void
`typeName`'s own `behavior.luau`, if it ships one — the same registry-driven resolution `asset.create` uses to reach a type's `onCreate`.
| arg | type | description |
|---|---|---|
| typeName | string |
normalizeHookOf(typeName: string) →
`typeName`'s own normalisation hook — its `behavior.luau`'s exported `normalizeSettings(values, stored?)`, when it ships one — or nil. The hook maps every older spelling a stored file or a write may carry (a renamed field, an older enum member) to the field and member the schema declares now, and returns a new table. `stored`, when given, is the asset's current values, which an older spelling in a patch may need to keep the meaning it had against them.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local hook = Settings.normalizeHookOf("texture")normalizeFor(typeName: string?, values: { [string]: any }, stored: { [string]: any }?) →
`values` in the spelling `typeName`'s schema declares: the type's `normalizeSettings` applied, or `values` itself when it ships none. Every settings source passes through here — a values file, a legacy `.metadata` block, a create's preset / importer / caller layers, a `asset.setSettings` patch — so an older spelling reads, creates and writes as the field it names today. The hook is handed copies; neither table passed here is modified.
| arg | type | description |
|---|---|---|
| typeName | string? | The asset type's name (nil answers `values` unchanged). |
| values | { [string]: any } | A settings table in any spelling the type accepts. |
| stored | { [string]: any }? | The asset's current values, when `values` is a patch over them. |
examples
local values = Settings.normalizeFor("texture", { format = "bc7" })read_values_file_raw(path: string) → void
The values table a settings file holds, decoded exactly as stored. An asset with no values file answers nil without a read: a read of a path the library does not hold waits on a fetch for it, and every asset whose settings are all defaults (most builtin meshes and clips) has none, so a `:handle()` that asks for its settings would otherwise wait a frame for a file that is not there.
| arg | type | description |
|---|---|---|
| path | string |
read_values_file(path: string, typeName: string?) → void
The values table a settings file holds, in the spelling `typeName`'s schema declares.
| arg | type | description |
|---|---|---|
| path | string | |
| typeName | string? |
legacy_values(ref: any) → void
The legacy `.metadata` `settings` block, read in memory: what a type's `onCreate`/`onChange` hooks persist through `asset.set_field(ref, "settings", ...)` for content authored before the values file existed. `M.valuesOf` overlays it exactly as it overlays a values file.
| arg | type | description |
|---|---|---|
| ref | any |
stored_raw(ref: any) → void
The settings `ref` stores exactly as stored, before any older spelling is read as today's: its values file, or the legacy `.metadata` block for content that predates it.
| arg | type | description |
|---|---|---|
| ref | any |
settingsHealedHookOf(typeName: string) →
`typeName`'s own settings-heal hook — its `behavior.luau`'s exported `settingsHealed(values, stored)`, when it ships one — or nil. Healing moves an asset's settings out of older storage on a local edit; this hook answers the fields whose value that move changes, for content whose stored settings predate what the type's schema now decides. `values` is what a read of the stored settings reports, `stored` the settings exactly as stored (before an older spelling is read as today's). It returns the fields to change, or nil for none.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local hook = Settings.settingsHealedHookOf("texture")apply_heal(typeName: any, values: { [string]: any }, stored: { [string]: any }?, explicit: { [string]: any }?) → void
`values` with `typeName`'s heal applied for settings stored as `stored`: every field its `settingsHealed` hook changes that `explicit` does not name, so a field the writer names keeps what it names. Answers the values and whether any changed.
| arg | type | description |
|---|---|---|
| typeName | any | |
| values | { [string]: any } | |
| stored | { [string]: any }? | |
| explicit | { [string]: any }? |
overlay_stored(schema: any, stored: { [string]: any }?, sourceLabel: string?) → void
The schema's defaults overlaid with `stored` (already in the declared spelling): a field the schema does not declare is dropped, and a value that fails its own field's constraint reads as the declared default with a warning naming `sourceLabel`, the field and the violation.
| arg | type | description |
|---|---|---|
| schema | any | |
| stored | { [string]: any }? | |
| sourceLabel | string? |
stored_values_of(ref: any) → void
The settings `ref` itself records — its values file, else the legacy `.metadata` block — or nil when it records none.
| arg | type | description |
|---|---|---|
| ref | any |
valuesOf(ref: any) →
This asset's settings values: every declared default, overlaid with what its values file holds — or, for content that predates the values file, with its legacy `.metadata` settings. A field neither sets reads as its declared default, so content written before a field existed still answers for it. A stored field the schema no longer declares is filtered out, so a schema revision that drops a field leaves old content reading as clean rather than carrying a value nothing recognises. A stored value that fails its own field's constraint is dropped the same way — the field falls back to its declared default and a warning names the path, the field and the violation — so a read never answers with a value the schema (and therefore the type's own encode) refused. The values are resolved in memory from what is already on disk. An asset whose type declares no values file holds no settings values of its own — a component's live on each entity it is on — and reads as nil, while its schema still answers through `schemaFor`.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
local s = Settings.valuesOf(texRef)
isForeignOrigin(ref: any) → boolean
True when `ref`'s origin is outside this world — installed from a library, or carried by the engine's library by reference, rather than authored here or shipped with the engine. Read through the same envelope `asset.inspect` reports, `origin.kind`: `"installed"` for either, and `"authored"` for a world-authored or builtin asset. An origin `asset.inspect` cannot answer (it raises, or reports a shape these reads don't recognise) resolves foreign: what this guards is that a foreign asset's legacy settings are never dropped or rewritten, so an undetermined origin takes the side that leaves the asset's content as it is.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
examples
if not Settings.isForeignOrigin(ref) then Settings.healLegacyIfNeeded(ref, "local") end
contentsOf(path: string) → string
The whole text of `path`, or nil when no file is there.
| arg | type | description |
|---|---|---|
| path | string |
recordedWrite(path: string, text: string, record: boolean) → void
Write `text` to `path`, raising when the write does not land. When `record` is set and an undo operation is open, the write is recorded into it, so undoing the operation restores what the file held before; the prior contents are read only then.
| arg | type | description |
|---|---|---|
| path | string | |
| text | string | |
| record | boolean |
recordedWrite(path: string, text: string) → void
Write `text` to `path`, recording the write into the open undo operation when one is open so undoing it restores the file's previous contents. Raises when the write fails.
| arg | type | description |
|---|---|---|
| path | string | VFS path. |
| text | string | The whole new contents. |
examples
Settings.recordedWrite(ref.path .. "/values.yaml", Yaml.encode(doc))
writeValues(ref: any, values: { [string]: any }, explicit: { [string]: any }?) →
Write this asset's whole settings values file. The values (and `explicit`) are read through the type's `normalizeSettings` first, so an older spelling is stored as the field it names today. They then take the type's cross-field corrections (`M.applyCorrections`, with `explicit` as the fields the writer named — a correction contradicting one of them refuses the write), then are checked against the schema. Every violation is reported in one error naming the field, what it takes, and where the schema is declared. When the asset also carries legacy `.metadata` settings and its origin is authored — this world's own content, or the engine's builtin library — the legacy key is dropped as part of this same write, so the values file above is what a read prefers from here on. A library-installed asset keeps its `.metadata` settings key alongside the values file this call writes. Inside an undo operation, the write is recorded so undoing the operation restores the previous file contents; authored legacy content is first healed into its values file, so undo returns it to the healed file, which reads the same values as the legacy one. When that heal does not complete, the legacy settings stay in `.metadata` and the step records the values file alone, so undo falls back to the legacy values.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
| values | { [string]: any } | The complete values table. |
| explicit | { [string]: any }? | The fields the writer asked for by name (a patch), or nil. |
examples
Settings.writeValues(texRef, { filter = "nearest", colorSpace = "srgb" })write_values(ref: any, values: { [string]: any }, explicit: { [string]: any }?, record: boolean, level: number) → void
`M.writeValues`, recording its writes into an open undo operation only when `record` is set. `level` is the `error` level that names the public caller.
| arg | type | description |
|---|---|---|
| ref | any | |
| values | { [string]: any } | |
| explicit | { [string]: any }? | |
| record | boolean | |
| level | number |
resolvePatch(ref: any, patch: { [string]: any }) →
The complete values a partial settings patch writes — the values `asset.setSettings` hands `M.writeValues`. The patch is read through the type's `normalizeSettings` against the asset's current values, so an older field name lands as the field it names today with the meaning it had for this asset, and is merged over those values, a struct group field by field (`M.mergeValues`); the type's derived defaults (`M.applyDerivedDefaults`) then move each field that follows a field this patch changed, unless the patch names it too. `M.writeValues` applies the corrections with the normalised patch as the explicit fields.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
| patch | { [string]: any } | Any subset of the schema's fields, in the current or an older spelling. |
examples
local values, named = Settings.resolvePatch(texRef, { compression = "uastc" })presetLayerFor(typeName: string, destPath: string) →
The Preset Manager's layer for a new asset of `typeName` at `destPath`: the valid values of the world's first `[[presets]]` row naming the type's assetType whose filter matches the new asset's path (under `/source` for a durable asset, under `/runtime/assets` for a runtime one), and the match. Nil for any other destination, a type with no type-level schema, or no matching row.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type being created. |
| destPath | string | Where the new asset lands. |
examples
local layer = Settings.presetLayerFor("texture", "/zero/source/sprites/hero.texture")type_schema_problem(typeName: string, schema: any, ref: any?) → void
| arg | type | description |
|---|---|---|
| typeName | string | |
| schema | any | |
| ref | any? |
settingsDefaultsHookOf(typeName: string) →
`typeName`'s own create-time settings-defaults hook — its `behavior.luau`'s exported `settingsDefaults(name, opts, asked)`, when it ships one — or nil. A type contributes a layer here for whatever it can only compute at creation (a name-derived convention, a fact read off a pre-encoded payload the caller handed it, a default that follows a field another layer sets); `resolveForCreate` calls it once per create, above the schema's own defaults and below every other layer, with `asked` holding what the layers above it (the Preset Manager, an importer, the caller) name, field by field, the higher layer's value where two name one. The hook returns a fresh table of its own opinions; it is never handed anything to mutate, and a field it returns that a layer above it names takes that layer's value.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local hook = Settings.settingsDefaultsHookOf("texture")settingsCorrectionsHookOf(typeName: string) →
`typeName`'s own settings-corrections hook — its `behavior.luau`'s exported `settingsCorrections(values, name, opts)`, when it ships one — or nil. Where `settingsDefaults` supplies an opinion a layer below the caller can still override, this hook enforces a cross-field constraint the schema itself has no way to express (a field whose valid range depends on another field's resolved value). `M.applyCorrections` calls it on every settings write — once a create's layers have merged, and on every later write of the values file. Called with the complete values; it READS them and RETURNS a table of the corrections to apply (or nil for none), rather than mutating what it was given. A SECOND return, `{ [field]: reason }`, names why a corrected field cannot hold the value it is being corrected away from — used only when the writer named that field explicitly, to explain the refusal; omitted or missing a field falls back to a generic reason.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local hook = Settings.settingsCorrectionsHookOf("texture")explicit_leaves(schema: any, explicit: { [string]: any }) → void
Every leaf field `explicit` names, each as `{ path, keys, value }`: a struct field the schema declares (a `Field.struct` or `Field.settingsOf` group) is descended into, and anything else is a leaf, compared whole.
| arg | type | description |
|---|---|---|
| schema | any | |
| explicit | { [string]: any } |
walk(fields: any, t: { [string]: any }, keys: { string }, depth: number) → void
| arg | type | description |
|---|---|---|
| fields | any | |
| t | { [string]: any } | |
| keys | { string } | |
| depth | number |
value_at(t: any, keys: { string }) → any
The value at `keys` inside `t`, or nil where the path runs out.
| arg | type | description |
|---|---|---|
| t | any | |
| keys | { string } |
correction_reaches(corrections: any, keys: { string }) → boolean
Whether `corrections` sets the field at `keys`: it names the field itself, or replaces a group above it with something that is not a table.
| arg | type | description |
|---|---|---|
| corrections | any | |
| keys | { string } |
show_value(v: any) → string
A settings value as a reader sees it in a message: a scalar as itself, a table as `{ k = v, ... }` in key order.
| arg | type | description |
|---|---|---|
| v | any |
derivedHookOf(typeName: string) →
`typeName`'s own derived-defaults hook — its `behavior.luau`'s exported `settingsDerivedDefaults(values, explicit, changed)`, when it ships one — or nil. It answers the values of fields whose default follows another field (a texture's colour space follows its texture type), given the complete values, the fields the writer named (`explicit`) and the fields this write changed (`changed`). The framework applies a returned field only when the writer did not name it (`M.applyDerivedDefaults`).
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local hook = Settings.derivedHookOf("texture")creationInputsOf(typeName: string) →
The creation inputs `typeName` declares, and the shape each one belongs to — its `behavior.luau`'s exported `creationInputs` map, when it ships one, or an empty map. A key is a top-level `asset.create` opt the type's `onCreate` reads as what the asset is MADE FROM; its value is the name of the opt that selects the shape the input belongs to, or `true` for an input that belongs to every shape. `soundClip` declares `{ sampleRate = "pcm", channels = "pcm", ext = "bytes", writeSource = "bytes" }`: `sampleRate` and `channels` describe raw PCM as it arrives and mean something only alongside `pcm`; `ext` names the container encoded source bytes are in, and `writeSource` keeps a copy of them, and both mean something only alongside `bytes`. `asset.create` reads it before anything else touches the caller's opts. A declared input given alongside the opt that selects its shape is a creation input and reaches `onCreate` unchanged. A declared input given on any other shape has no meaning there and never reaches `onCreate`; one that names no declared setting refuses the create, naming the input and the opt it belongs with.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
Settings.creationInputsOf("soundClip").sampleRate --> "pcm"clone_value(v: any) → any
Copy a value for `cloneValues`: a table copies recursively, key by key, to whatever depth it nests; anything else (string, number, boolean, nil) is returned as-is, since a scalar has nothing for two tables to share.
| arg | type | description |
|---|---|---|
| v | any |
valuesEqual(a: any, b: any) → boolean
Structural equality for a settings value at any depth: two tables are equal when they hold the same keys and every value is itself equal (recursively), and two scalars (string, number, boolean, nil) are equal by `==`. Table VALUES in a settings table are always freshly built — `defaultsOf` clones a default, `read_values_file` decodes a fresh table from YAML — so comparing them by reference would report a table-valued field as changed on every read even when its contents are identical. The one comparison every settings-value equality check in this module shares — `diffFor`'s own diff and `resolveForCreate`'s caller-conflict check both call this rather than each carrying its own. Takes acyclic settings values — YAML-shaped data, the same invariant `clone_value` relies on — so the recursive walk always terminates.
| arg | type | description |
|---|---|---|
| a | any | A settings value (a scalar or a table, at any nesting depth). |
| b | any | A settings value to compare it against. |
examples
Settings.valuesEqual({ a = 1, b = { 2, 3 } }, { a = 1, b = { 2, 3 } }) --> truecloneValues(values: { [string]: any }) →
A deep copy of a settings values table — every table-valued field, and every table nested inside one (a `Field.settingsOf` group, a list of structs), copied at whatever depth it goes. Settings values are YAML-shaped data (tables, strings, numbers, booleans, never a cycle), so a plain recursive table copy is the whole guarantee this makes: nothing a hook or `onCreate` does to what it's handed, at ANY depth, can reach the table `asset.create` goes on to stamp into the values file.
| arg | type | description |
|---|---|---|
| values | { [string]: any } | The values table to copy. |
examples
local copy = Settings.cloneValues(resolved)
mergeValues(schema: any, base: { [string]: any }?, overlay: { [string]: any }?) →
Lay `overlay` over `base` under `schema`, the one way settings layers combine: a field `overlay` names replaces the field in `base`, except a struct field (a `Field.struct`, or a `Field.settingsOf` group) that both hold as tables, which merges field by field at whatever depth it nests — so a layer naming one field of a group leaves the group's other fields where the layers below put them. Neither input is modified; the result is a deep copy. depth), or nil to replace every named field.
| arg | type | description |
|---|---|---|
| schema | any | The Field schema the values follow (the fields of a struct at |
| base | { [string]: any }? | The values below. |
| overlay | { [string]: any }? | The values laid over them. |
examples
Settings.mergeValues(schema, { group = { a = 1, b = 2 } }, { group = { b = 3 } }) --> { group = { a = 1, b = 3 } }layer(t: { [string]: any }?) → void
| arg | type | description |
|---|---|---|
| t | { [string]: any }? |
diffFor(ref: any, writtenPath: string) →
The settings a write to `writtenPath` produced, and which fields it changed, when that path IS the asset's declared values file. A write to anything else answers `(nil, nil)`. A values file that fails its schema answers `(nil, nil)` too, after reporting the violations — the asset keeps the settings it last had rather than taking an invalid set. `changed` is computed against an in-process baseline (`last_values`, forgotten on delete via `forgetChangeBaseline`) — a fresh process, or an asset diffed for the first time this session, reports every field as `old = nil`.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
| writtenPath | string | The path that was written. |
examples
local values, changed = Settings.diffFor(ref, change.path)
forgetChangeBaseline(assetPath: string) → void
Forget the diff baseline `diffFor` holds for `assetPath` — the settings it last saw for that asset's own folder path. Called when the asset is deleted, so a later create that reuses the same path (a delete-then-recreate) diffs its first write against nothing rather than against what the deleted asset last held, and the baseline map does not grow for assets no longer alive.
| arg | type | description |
|---|---|---|
| assetPath | string | The asset's own folder path, as `diffFor` keys its baseline. |
examples
Settings.forgetChangeBaseline("/zero/source/Rock.texture")seedChangeBaseline(assetPath: string, values: { [string]: any }) → void
Record `values` as the settings `diffFor` last saw for `assetPath`, so the dispatch of a values file written with exactly these values reports nothing changed. Every writer that has ALREADY done what those values ask for calls it with what it writes: `asset.create` after stamping a new asset (its `onCreate` encoded against them), a type's first-encode seed of a hand-written container, and the legacy heal (which moves values without changing one). A later write that changes a field still diffs against these and reports that field.
| arg | type | description |
|---|---|---|
| assetPath | string | The asset's own folder path, as `diffFor` keys its baseline. |
| values | { [string]: any } | The complete values table the values file holds. |
examples
Settings.seedChangeBaseline(rawget(texRef, "path"), values)
writeActedValues(ref: any, values: { [string]: any }) → void
Write `ref`'s whole values file (`M.writeValues`) with `values`, the settings the caller has already acted on, and seed the change baseline with what was written (`M.seedChangeBaseline`) before that write's dispatch runs, so the dispatch reports nothing changed and no reaction runs a second time.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref. |
| values | { [string]: any } | The complete values table. |
examples
Settings.writeActedValues(texRef, values)
write_healed(ref: any, healed: { [string]: any }, before: { [string]: any }) → void
Write `healed` into `ref`'s values file and seed the change baseline with `before`, the values the asset was read as before the heal, so the write's own dispatch reports exactly the fields the type's heal changed (none when healing only relocates storage) and the type reacts to those alone. A heal records nothing into an undo operation that happens to be open. Answers as `pcall` does.
| arg | type | description |
|---|---|---|
| ref | any | |
| healed | { [string]: any } | |
| before | { [string]: any } |
heal_legacy(ref: any) → void
Move `ref`'s settings out of legacy storage into its values file: write the values a read reports, which drops a legacy `.metadata` key and states every field in the spelling the schema declares. A read that raises is a heal that did not complete. Answers as `pcall` does.
| arg | type | description |
|---|---|---|
| ref | any |
healLegacyIfNeeded(ref: any, origin: string?) → void
Migrate `ref`'s settings out of legacy storage, when a LOCAL edit just landed on an asset that still carries them there: settings in the legacy `.metadata` block move into its values file, and a values file holding an older spelling (one the type's `normalizeSettings` rewrites) is rewritten in the declared spelling — every existing asset self-heals this way as it is touched, rather than only on an explicit settings write. Called once per dispatched edit, generically, for every registered type (a type that declares no settings block, an asset whose values file its type ships no `normalizeSettings` for or holds only the declared spelling, or one with no values file whose `.metadata` carries no `settings` key, returns without writing — this is a no-op the overwhelming majority of the time, by construction, and convergent: a second call after healing finds the values file in the declared spelling and does nothing). Never runs for a REMOTE-origin dispatch — the peer whose own edit this was heals it there, and the migration reaches every other session as an ordinary synced write once it does. Never runs for installed / foreign-origin content (`isForeignOrigin`, the same check `M.writeValues` already applies to the `.metadata` removal) — a library's own content is not this world's to rewrite. The healed values are what `M.valuesOf` already reports for this asset — the stored settings read through the type's `normalizeSettings` (`M.normalizeFor`), filtered to declared fields, schema-checked — with the fields the type's `settingsHealed` hook changes for settings stored before its schema decided them (a texture whose settings predate `compression` heals to the compression it should have). The diff baseline is seeded with the values read before the heal, so that write's own follow-up dispatch reports only what the hook changed: nothing, when healing only relocates storage — the edit that triggered the heal already got its own reaction from the dispatch that called this — and the changed fields otherwise, which the type reacts to as to any settings change. `AssetChangeDispatch.dispatch`.
| arg | type | description |
|---|---|---|
| ref | any | The asset ref the just-applied edit landed on. |
| origin | string? | The dispatch's origin ("local"/nil, or "remote") — see |
examples
Settings.healLegacyIfNeeded(ref, change.origin)
orderedNames(schema: any) →
The field names of `schema` in the order they are declared: by each descriptor's `declaredOrder`, a name breaking a tie and a descriptor without one sorting after those that carry one.
| arg | type | description |
|---|---|---|
| schema | any | The Field schema table. |
examples
for _, name in ipairs(Settings.orderedNames(schema)) do print(name) end
rank(name: string) → number
| arg | type | description |
|---|---|---|
| name | string |
acceptedFieldNames(typeName: string) →
Every field name a write to `typeName` may carry: the fields its schema declares plus the older names its `normalizeSettings` maps (`behavior.luau`'s `normalizedSettingNames`), sorted.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local names = Settings.acceptedFieldNames("texture")fieldNames(typeName: string) →
Every field name `typeName`'s settings schema declares, sorted.
| arg | type | description |
|---|---|---|
| typeName | string | The asset type's name. |
examples
local names = Settings.fieldNames("texture")Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.