Preset (asset type)

When to use one

• You re-use the same component configuration in multiple places (e.g. a "fast-jump" Locomotion config, a "loud-fall" Audio config).
• You want designers to swap configurations without editing code.
• You want a stable identity (@<lib>::<presetName>) callers can reference without hardcoding values.

If you're capturing a whole entity assembly, use a .bundle. If you're factoring shared logic (not configuration), use a .module.

Where it lives

• Source: /zero/source/.../<Name>.preset/
• Identity: <Name> (the .preset suffix strips).
• Folder shape:
  • preset.yaml — names the target component + lists property values. Required.
  • README.md — instance documentation. Required.

How to create one

asset.create("preset", "<Name>")
-- Creates: /zero/source/presets/<Name>.preset/
--   preset.yaml   (component name + property scaffold)
--   README.md     (instance README template)

Then edit preset.yaml to point at the right component and fill in the values you want captured.

How it operates

1. Registration. Writing preset.yaml indexes the preset against its target component name.
2. Loading. preset.load("<name>") returns a plain Luau table of the preset's property values. Use the returned table directly in component.add, or layer overrides on top before attaching.
3. No live linkage. A preset is a snapshot, not a live binding. Editing the preset doesn't update entities that loaded it earlier — they have to re-attach to pick up the change.

Discovery

• asset.list("preset") — every registered preset.
• asset.inspect("<name>") — target component, captured property values, source, this type README.
• cat /zero/source/<Name>.preset — same summary.

Authoring conventions

• Name presets descriptively + by the configuration they capture (fast_jump, slow_camera, wet_tarmac). Avoid the component name in the preset identity — preset.yaml::component names the binding.
• One preset = one component. If you need a multi-component bundle of configurations, that's a .bundle with the components pre-attached.
• Document overrides callers commonly layer on top — those become the preset's de-facto API surface.

Common pitfalls

• Component name mismatch. If preset.yaml::component doesn't match a registered component, preset.load fails. Make sure the identity is correct.
• Stale loads. preset.load returns a snapshot. Reload after editing the preset if you want the new values, or rebuild via a fresh component.add.
• Renaming. The folder name is the identity. Update every preset.load callsite.

Related types

• .component — the type a preset configures.
• .bundle — for multi-component / multi-entity assemblies.
• .material — conceptually similar (shader + property values), but for GPU surfaces instead of components.