preset

A preset holds typed values for one declarer's settings schema: an assetType's, an importer's, a component's, or any asset that declares its own settings. preset.capture saves the settings something has now, preset.apply writes a preset's values into something its target governs, preset.values reads them checked against the target's current schema, and preset.setValues replaces them, checked first. Exposed as the preset global via --!global preset.

A preset's preset.yaml names its target as a guid envelope, target: { __ref: <guid>, type: <type>, name: <name> }, which the preset's .refs pins by guid with the target's checksum. A target written as an identity string is accepted on read, resolves by identity, reads as unpinned, and is rewritten as the envelope on the preset's next local edit.

Exports

• preset.values(source: AssetRef<preset>) -> ({ [string]: any }, Report) — the values that pass the target's current schema, and a report naming every one that does not.
• preset.apply(source: AssetRef<preset>, into: AssetRef | ComponentTarget) -> ApplyResult — write the valid values into an asset the target governs, or into a component on an entity whose component is the target. Struct groups merge field by field. Raises when another declarer governs into.
• preset.capture(from: AssetRef | ComponentTarget, name: string, opts?: CaptureOpts) -> AssetRef<preset> — save an asset's settings, or a component's live values on an entity, as a new preset targeting the declarer that governs them. A bare name lands in /source/presets/; an absolute .preset path lands where it says.
• preset.setValues(source: AssetRef<preset>, values: { [string]: any }) — replace the whole values table; any violation refuses the write, naming every one.
• preset.defaults() -> { DefaultRow } — the world's Preset Manager rows, in order, each resolved with its problems.
• preset.setDefaults(rows: { DefaultRowInput }) — replace every row; every row is checked first and any problem refuses the write, naming every one.
• preset.addDefault(source: AssetRef<preset>, opts?: { filter: string?, at: number? }) -> number — add a row for the declarer the preset targets; returns its index.
• preset.removeDefault(index: number) — remove one row, keeping every other row as written.
• preset.defaultFor(declarer: AssetRef | string, path: string) -> ({ [string]: any }?, Match?) — the values a new thing at path would take from the rows, and the row that gives them.

Types:

• ComponentTarget = { entity: string, component: string } — a component on an entity.
• Report = { format: string, target: string, targetGuid: string?, pinned: boolean, targetChanged: boolean, rejected: { Violation } } — target is the target's identity; pinned is true when .refs pins the target's guid; targetChanged is true while the pinned checksum differs from the target's current one.
• Violation = { path: string, message: string }
• ApplyResult = { applied: { string }, rejected: { Violation }, targetChanged: boolean }
• CaptureOpts = { overwrite: boolean? } — overwrite = true re-authors an existing preset, keeping its guid.
• DefaultRowInput = { preset: any, target: any?, filter: string? } — a preset, its declarer (the preset's own target when omitted) and a filter (empty matches everything).
• DefaultRow = { index, target, preset, filter, targetGuid, presetGuid, targetName, presetName, problems }
• Match = { index, target, preset, path, rejected, problem? } — the row a creation took and the path it read.

Usage

-- Capture a texture's settings, then apply them to another texture
local p = preset.capture("hero_sprite", "pixel_art")
preset.apply(p, "enemy_sprite")

-- Apply a component preset to a component on an entity
preset.apply("synty", { entity = id, component = "Locomotion" })

-- Capture a component's live values
local tint = preset.capture({ entity = id, component = "Model" }, "red_tint")

-- Read the values and what the target rejects
local values, report = preset.values("pixel_art")
for _, v in ipairs(report.rejected) do print(v.path, v.message) end

-- Replace the values
preset.setValues("pixel_art", { filter = "nearest", generateMipmaps = false })

Notes

• Every read re-checks the values against the target's current schema, so a value a later schema drops or retypes is reported by path rather than applied.
• asset.create("preset", name, { target = <identity or guid>, values = { ... } }) authors a preset directly, with the same checks as preset.capture.
• The Preset Manager rows are documented in preset.defaults; the filter grammar in preset.glob.
• Submodules: preset.document (the preset.yaml format), preset.target (target resolution and checking), preset.heal (rewriting an older preset document in the current form on a local edit).