Mod Manifest

The mod manifest (ModName.yaml) — its metadata fields, the config files it registers, and which content the engine loads by folder convention instead.

Every mod has exactly one manifest: a YAML file at the root of the mod folder. It carries the mod’s identity (mod-info) and a list of which config files to load. This page is the authoritative reference for that file. For the surrounding directory layout and Lua wiring, see the Lua Modding Overview.

File Location & Name

instances/<instance>/mods/<ModName>/<ModName>.yaml

The manifest’s filename must match its mod folder name exactly — the engine looks for <ModName>/<ModName>.yaml, using the folder name for both halves. A folder named MyMod is loaded from MyMod/MyMod.yaml; a mismatch (MyMod/mymod.yaml) will fail to load the mod on case-sensitive filesystems (Linux servers), even though it may appear to work on a case-insensitive one (macOS/Windows). Match the case.

`mod-info`

The one required block. It identifies the mod and drives dependency resolution and client/server compatibility checks.

mod-info:
  name: MyMod
  version: 1.2.0
  description: Adds glorbos and their habitat.
  authors:
    - Your Name
  dependencies:
    - name: Creation
      version: 1.0.0
  required: true
  min-client-version: 1.2.0
  side: both

Field	Required	Default	Description
`name`	No	folder name	Display name of the mod. Defaults to the folder name if omitted.
`version`	No	`0.0.0`	The mod’s own version. Semver (`MAJOR.MINOR.PATCH`).
`description`	No	empty	One-line description.
`authors`	No	empty list	List of author names (strings).
`dependencies`	No	none	Other mods this one requires, each `{name, version}`. `version` is the minimum acceptable. Used for load-order and to fail fast when a dependency is missing.
`required`	No	`true`	Whether a client connecting to a server running this mod must also have it. `true` = clients missing it (or too old, see `min-client-version`) are rejected at login. Set `false` for purely cosmetic/optional mods a client can safely lack.
`min-client-version`	No	none	Minimum version a connecting client’s copy of this mod must satisfy. Only enforced when `required` is `true`. Semver.
`side`	No	`both`	Which side loads this mod’s content: `client`, `server`, or `both`. Any other value (or omitting it) means `both`. The mod is still registered on both sides for dependency resolution — `side` only gates whether content registration runs.

required defaults to true. An unmarked mod is assumed to matter to gameplay, so clients missing it are turned away. If your mod is safe to be absent client-side (a server-only tweak, an optional resource pack), you must set required: false explicitly.

Registering config files

Below mod-info, add one line per config category your mod uses. The key alone is enough — the file defaults to <key>.yaml in your mod folder:

block-config:
item-config:
mob-config:
commands-config:

Give the key a value only if you want a different filename:

item-config: catalog/my-items.yaml

Only include the categories you actually use — every key is optional, and leaving a key out is how you opt out of that config. That is the distinction the loader cares about: a key with no value still loads (from the default filename), while an absent key loads nothing. A misspelled registration key (mob-confg:) fails the manifest at load with a named error, rather than silently dropping that whole config, so a typo can’t quietly cost you an entire file.

The complete set of registerable keys:

control-config, block-config, ore-config, structure-config, crafting-config, item-config, particle-config, interactable-config, loot-table-config, mob-config, aoe-zone-config, mount-config, sound-config, player-config, projectile-config, weather-config, tree-config, commands-config, shader-config.

health-config and oxygen-config are not manifest keys — health and oxygen are declared as nested health: / oxygen: blocks inside mob and player configs, not as standalone files. See Health Configuration and Oxygen Configuration.

Registered vs. auto-discovered content

This is the single most confusing thing about the loader for newcomers: not all content is registered in the manifest. Some categories are loaded by listing them in the manifest (above); others are loaded by scanning a conventional folder, and never appear in the manifest at all. Reading Creation.yaml and assuming it lists everything will mislead you.

Content	How it loads	Location
Items, blocks, mobs, mounts, trees, ores, crafting, loot tables, projectiles, AoE zones, particles, sounds, interactables, weather, control bindings, chat commands, shaders, player	Registered — a `*-config:` key in the manifest	path you give the key
Textures (blocks, items, mobs, UI, icons, …)	Auto-discovered — the engine scans the asset folders	`assets/textures/<category>/*.yaml`
Biomes	Auto-discovered — folder scan	`biomes/surface/`, `biomes/cave/`, `biomes/sky-island/`
World types	Auto-discovered — loaded by name	`world-types/<Name>.yaml`
World builders (generation presets)	Auto-discovered — loaded by name	`world-builders/<category>/<preset>.yaml`
Underground features	Auto-discovered — folder scan	`underground-features/*.yaml`
Sky-island features	Auto-discovered — folder scan	`sky-island-features/*.yaml`
Structure block layouts	Auto-discovered — binary files	`structures/<name>/.structure` (the structure definition* is registered via `structure-config`; its actual block layout is a folder file)
Lua scripts	Referenced by path from a config’s `scripts:` block	anywhere in the mod, conventionally `scripts/` / `lib/`

Rule of thumb: catalog content (things you add to the game) is registered in the manifest; world-generation content and textures are discovered by living in the right folder with the right name. When a folder-discovered file doesn’t show up, check its name and location before anything else — there’s no manifest line to fix.

Complete example

mod-info:
  name: MyMod
  version: 1.0.0
  description: A small example mod.
  authors:
    - Your Name
  dependencies:
    - name: Creation
      version: 1.0.0

block-config: block-config.yaml
item-config: item-config.yaml
mob-config: mob-config.yaml
crafting-config: crafting-config.yaml

With this manifest, MyMod loads its four listed configs, requires Creation 1.0.0 or newer, and — because required/side are omitted — is treated as required on both sides. Its textures under assets/textures/, and any biomes/ or world-types/ it ships, load automatically without further manifest entries.