mod.yaml reference

Current schema version: carbon.mods/v1.

Top-level fields

Field	Required	Description
`apiVersion`	yes	Must be `carbon.mods/v1`.
`id`	yes	Stable slug (`classic-oof`). Used in app storage and updates.
`name`	yes	Display name in the Carbon UI.
`author`	yes	Author or team name.
`version`	yes	Semver string shown in the UI.
`description`	yes	Short summary for the mod list.
`tags`	no	String labels for filtering (`ui`, `sounds`, `skybox`, …).
`priority`	no	Integer; higher runs later when multiple mods touch the same path.
`settings`	no	User-configurable options (see below).
`operations`	yes	List of patch steps applied at launch.

Settings

Each entry in settings defines one control in the mod settings panel.

Common keys

Key	Description
`key`	Identifier stored in `config.json` and used in `{placeholders}`.
`type`	`toggle`, `dropdown`, or `file`.
`label`	Short UI title.
`description`	Help text under the control.
`default`	Initial value when no `config.json` exists.

`dropdown`

- key: theme
  type: dropdown
  label: Menu theme
  default: dark
  options:
    - dark
    - light
    - midnight

`toggle`

- key: useCustom
  type: toggle
  label: Use custom cursor
  default: false

`file`

- key: customCursor
  type: file
  label: Custom cursor PNG
  accept: image/png
  assetCategory: cursor

assetCategory helps the app suggest valid pickers and validate dimensions (see built-in Cursor Swapper).

Operations

`replace-file`

Field	Description
`type`	`replace-file`
`target`	Roblox-relative file path to overwrite.
`source`	Path under the mod folder; may include `{settingKey}` placeholders.

Preset operations

Instead of type: replace-file, set preset on the operation object (you do not set type for preset rows). Carbon expands presets in ModPresetRegistry before apply.

Field	Description
`preset`	See table below.
`source`	Required. File or folder under the mod; may use `{placeholders}`.
`mode`	For directory presets: `merge` (default) or `replace-tree`.
`target`	Optional override for `textures` and `ui-textures` only.
`when`	Run only when the boolean setting key is true.
`unless`	Skip when the boolean setting key is true.

`preset` value	Expansion summary
`cursor`	Four `replace-file` ops; same `source` PNG → all arrow cursor paths.
`menu-icons`	Merge `source` → `content/textures/MenuBar`.
`sounds`	Merge `source` → `content/sounds`.
`skybox`	Merge `source/cubemap` → `PlatformContent/pc/textures/sky`; merge `source/dynamic` → `content/sky`.
`dynamic-sky`	Merge `source` → `content/sky`.
`textures`	Merge `source` → `target` or `content/textures`.
`fonts`	Merge `source` → `content/fonts` and `PlatformContent/pc/fonts`.
`ui-textures`	Merge `source` → `target` or `ExtraContent/textures/ui`.
`translations`	`replace-file` → `ExtraContent/translations/CoreScriptLocalization.csv`.

See Preset operations for asset folder layouts and desktop-app workflow.

Placeholders

Strings in source (and some preset paths) can reference setting keys: assets/themes/{theme}/logo.png.

Example manifests

No settings: Classic Oof uses a single replace-file.
Dropdown + themed assets: In-Game Menu Pack.
Toggle + file picker + preset: Cursor Swapper: walkthrough in Preset operations.
Preset merge: Menu Bar Pack, Skybox Pack, Movement Sounds.

Versioning

Bump version when you change assets or operations. Carbon uses id + version to show updates; breaking path changes should be called out in your release notes.