---
title: "Preset (asset type)"
description: "A preset is a captured, named configuration of a single component. Instead of typing the same fields into every component.add call, you save a preset once and load it. Presets are component-scoped:…"
section: "Types"
slug: "types-preset"
canonical: "https://origozero.ai/docs/types-preset"
updated: "2026-08-22T07:41:56.142920995+00:00"
tags: ["asset-type", "reference"]
---

# 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.**
  - `.metadata` — agent-editable tags + free-form fields. **Required.**

## How to create one

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

-- `folder` places it in a subfolder of /source instead of the root:
asset.create("preset", "<Name>", { folder = "presets" })
```

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.