preset

Preset namespace — apply named tuning bundles to components. Auto-injected by the prelude from @builtin::modules.preset.

preset: any

The preset namespace: 11 functions.

globals/preset/addDefault

preset.addDefault(source: AssetRef<preset>, opts: { filter: string?, at: number? }?) -> number

Add one Preset Manager row for source, governing the declarer the preset targets. opts.filter limits it to new things whose path matches; opts.at places it (1 = first); it goes last otherwise.

Parameters

• source AssetRef<preset> — The preset.
• opts { filter: string?, at: number? } (optional) — { filter?, at? }.

Returns number — The new row's index.

preset.addDefault("pixel_art")

globals/preset/apply

preset.apply(source: AssetRef<preset>, into: AssetRef | ComponentTarget) -> ApplyResult

Write a preset's values into something its target governs: an asset whose settings the target declares, or a component on an entity, named { entity = <id>, component = <name> }, whose component the target is. Struct groups merge field by field. Only valid fields are written; the rest are returned in rejected.

Parameters

• source AssetRef<preset> — The preset.
• into AssetRef | ComponentTarget — The asset, or the component on an entity, to write into.

Returns ApplyResult — { applied, rejected, targetChanged }.

preset.apply("pixel_art", "hero_sprite")
preset.apply("red_tint", { entity = id, component = "Model" })

globals/preset/capture

preset.capture(from: AssetRef | ComponentTarget, name: string, opts: CaptureOpts?) -> AssetRef<preset>

Save the settings something has now as a new preset targeting the declarer that governs them: an asset's settings, or the live values of a component on an entity, named { entity = <id>, component = <name> }.

Parameters

• from AssetRef | ComponentTarget — The asset, or the component on an entity, whose values are captured.
• name string — A bare name (lands in /source/presets/) or an absolute .preset path.
• opts CaptureOpts (optional) — { overwrite = true } re-authors an existing preset of that name, keeping its guid.

Returns AssetRef<preset> — The new preset.

local p = preset.capture("hero_sprite", "pixel_art")
local tint = preset.capture({ entity = id, component = "Model" }, "red_tint")

globals/preset/create

preset.create(name: string, entityId: string, componentType: string, opts: PresetCreateOpts?) -> PresetCreateResult

Capture a component's live values on an entity as a preset targeting that component; forwards to preset.capture, overwriting a preset of the same name.

Parameters

• name string — Either a bare preset name (lands under /source/presets/) or an absolute path to a .preset asset or its /preset.yaml.
• entityId string — Source entity id.
• componentType string — Component to capture (e.g. "CharacterController").
• opts PresetCreateOpts (optional) — { name = <display name> } sets the preset's .metadata title.

Returns PresetCreateResult — { path, entityId, component, properties }: the written preset.yaml, and the values it holds.

globals/preset/defaultFor

preset.defaultFor(declarer: AssetRef | string, path: string) -> ({ [string]: any }?, any?)

The values a new thing declarer governs would take from the Preset Manager at path, and the row that gives them — the layer itself, before the creating importer's and the caller's settings. A path is a /source/... path for an asset or an import, and an entity's hierarchy path for a component.

Parameters

• declarer AssetRef | string — The declarer: an assetType, an importer or a component.
• path string — The new thing's path.

Returns ({ [string]: any }?, any?) — (values, match), or nil when no row matches.

local values, match = preset.defaultFor("@builtin::importers.texture", "/source/sprites/hero.png")

globals/preset/defaults

preset.defaults() -> { any }

The world's Preset Manager rows, in order. Each row names the declarer it governs (target), the preset a new thing takes (preset) and a glob over the new thing's path (filter), resolved, with every problem that keeps it from applying.

Returns { any } — { { index, target, preset, filter, targetGuid, presetGuid, targetName, presetName, problems } }.

for _, row in ipairs(preset.defaults()) do print(row.index, row.targetName, row.presetName, row.filter) end

globals/preset/load

preset.load(source: AssetRef<preset>, overrides: table?) -> { [string]: any }

Read a preset as a plain table: a typed preset's valid values, or a component-only preset's properties as authored, with overrides laid over the top. Forwards to preset.values.

Parameters

• source AssetRef<preset> — The preset.
• overrides table (optional) — Optional table merged onto the values.

Returns { [string]: any } — Plain table.

globals/preset/removeDefault

preset.removeDefault(index: number)

Remove the Preset Manager row at index. The other rows are kept exactly as written, so removing succeeds while another row is broken.

Parameters

• index number — The row's index, as preset.defaults() reports it.

preset.removeDefault(1)

globals/preset/setDefaults

preset.setDefaults(rows: { DefaultRowInput })

Replace the world's Preset Manager rows. Each row names a preset, optionally its declarer (the preset's own target when omitted) and a filter (empty matches everything). Every row is checked first; any problem refuses the whole write, naming every one. Rows change only what is created afterwards.

Parameters

• rows { DefaultRowInput } — The complete ordered rows.

preset.setDefaults({ { preset = "pixel_art", filter = "sprites/**" } })

globals/preset/setValues

preset.setValues(source: AssetRef<preset>, values: { [string]: any })

Replace a preset's values. The whole table is checked against the target's schema first; any violation refuses the write, naming every one. A preset in the component-only form is written in the typed form, its target the component it names and its legacy name moved to the .metadata title, as a heal moves it.

Parameters

• source AssetRef<preset> — The preset.
• values { [string]: any } — The complete values table the preset holds from now on.

preset.setValues("pixel_art", { filter = "nearest", generateMipmaps = false })

globals/preset/values

preset.values(source: AssetRef<preset>) -> ({ [string]: any }, Report)

A preset's values and a report on them. Every value is checked against the target declarer's current schema: the fields that pass are returned, every field that fails is listed by path in report.rejected, report.pinned says the preset's .refs pins the target by guid, and report.targetChanged says the target differs from the version pinned. A preset still in the component-only form reads as authored, and report.rejected lists what its component's schema would refuse.

Parameters

• source AssetRef<preset> — The preset.

Returns ({ [string]: any }, Report) — (values, report), where report is { format, target, targetGuid, pinned, targetChanged, rejected }.

local values, report = preset.values("pixel_art")