Skip to content
CarbonDocscarbonlabs.dev

Mods overview

Mods are folders with a mod.yaml manifest and an assets/ tree. When you enable a mod in the Carbon desktop app and launch a session, the launcher runs the mod’s operations against the selected Roblox version directory. That can mean replacing one file or merging a whole preset (cursors, skyboxes, menu icons, sounds).

In the Carbon app

Section titled “In the Carbon app”
Step Where What happens
Install Mods → Install Folder / Install Zip Community packs land in <Carbon root>/mods/<id>/ (Skeleton.Mods).
Enable Mod card toggle Built-in state (enable + config.json) is stored under bin/configs/mods/<id>/.
Settings Expanded mod card or Mods → Cursor Dropdowns/toggles/file pickers write keys into config.json.
Patch Launch flow ModManager.ApplyEnabledMods expands presets, resolves {placeholders}, applies when / unless, then patches the client.

Built-in mod assets ship inside the app; only config and enable flags are writable on disk. Community mods are fully editable in your mods/ folder.

Lifecycle

Section titled “Lifecycle”
  1. Discover: Carbon loads bundled mods from the install and scans mods/ for community packages (ModManager.LoadAllPackages).
  2. Configure: Optional settings in mod.yaml render in the UI. Values persist in config.json (see table above).
  3. Apply: On launch, operations run after preset expansion. Higher priority wins when two enabled mods target the same path.
  4. Play: Roblox reads the patched files from disk for that session.

Two operation styles

Section titled “Two operation styles”

replace-file

Section titled “replace-file”

Map one Roblox-relative path to one file in your mod:

operations:
  - type: replace-file
    target: content/sounds/oof.ogg
    source: assets/oof.ogg

source paths are relative to the mod folder. target paths follow Roblox’s layout (content/, ExtraContent/, PlatformContent/, and so on).

Presets (preset + mode)

Section titled “Presets (preset + mode)”

For bundles of related files, use a preset instead of listing every path:

Preset Typical use
cursor Arrow cursor PNGs across DPI variants
menu-icons Top menu bar icons under content/textures/MenuBar
skybox Cubemap + dynamic sky layers
sounds Merge .ogg / .mp3 into content/sounds

Presets often use mode: merge to overlay files from source onto the client.

For a full catalog (including fonts, ui-textures, and translations), folder layouts, and step-by-step Menu Bar Pack / Cursor Swapper walkthroughs tied to the app UI, see Preset operations.

Settings

Section titled “Settings”

Mods can expose toggles, dropdowns, and file pickers. Setting keys can appear in source paths as {key} placeholders, and operations can be gated with when / unless:

settings:
  - key: theme
    type: dropdown
    label: Menu theme
    default: dark
    options: [dark, light, midnight]


operations:
  - type: replace-file
    target: ExtraContent/textures/ui/InGameMenu/roblox_logo.png
    source: assets/themes/{theme}/roblox_logo.png

See Authoring and the reference for every field.

Next steps

Section titled “Next steps”