Modding Documentation

Reference documentation for modding Creation — content configuration, textures, Lua scripting, and server setup.

Creation is modded through YAML configuration files and optional Lua scripts, organized per mod under instances/<instance>/mods/<YourMod>/. Start with Lua Modding Overview for the mod directory layout and the Mod Manifest reference for the root config file, then use the reference pages below for each config file your mod needs. Schema Conventions covers the vocabulary — units, colours, chance vs. weight, casing — shared across all of them.

Naming & namespacing

Every piece of content is identified by a namespaced name, ModName:name (for example Creation:iron_bar). You never write the prefix when defining an entry — the name: you give it is bare, and the engine qualifies it with your mod’s name automatically:

items:
  - name: iron_bar      # becomes YourMod:iron_bar

When you reference content — a drop’s item, a crafting ingredient or result, an ore’s biomes, a mob’s valid-spawn-blocks, a world-builder’s block, and so on — the rule is:

  • A bare name resolves to your own mod. Write iron_bar to refer to your own iron_bar.
  • Prefix with another mod’s name only for cross-mod references. Write OtherMod:iron_bar to refer to content from OtherMod.

So within a single mod you should always use bare names; a YourMod: prefix on your own content is redundant (it still resolves, but it’s noise). This one rule applies uniformly to every reference field in every config file below.

Unknown fields

A field name the engine doesn’t recognize is almost always a load-time error, and it skips the entry that declares it. This holds for the fields of an entry across every config file on this page — catalogs, world-generation files, and texture configs alike. The log names the offending key and the entry it was on:

Unknown field 'tool-break-type' in interactable 'YourMod:chest' in mod YourMod — entry skipped (check for a typo)

The point is that a typo can never quietly cost you a field. A misspelled tool-break-types would otherwise leave an object unbreakable, and a misspelled light would leave it dark, in both cases looking exactly like you’d meant it. Failing the entry outright makes the mistake obvious at startup instead of hours into play.

Two consequences worth knowing:

  • Skipping is per-entry, not per-file. One bad block doesn’t stop the rest of block-config.yaml from loading. Where a config nests (a tree and its variations, a weather and its layers), the log message says which level was skipped.
  • A skipped entry can cascade. If an item fails to load, every recipe and drop table referencing it will also fail, with its own error. Fix the first error in the log and the rest usually clear on their own.
  • Unknown keys are rejected inside nested blocks too, not just at the top level. The strict check reaches into the hand-read sub-blocks: a mob’s spawn-rules and mount, the inline itemstack form a crafting ingredient/result or a drop/loot entry’s item: can take, and the scripts hook map on every config that has one — mob, mount, interactable, block, item, weather and player, with no exceptions (see Shared Blocks → scripts for which hooks each accepts). A misspelled hook name like server-udpate fails the entry with a named error instead of being silently skipped, so a typo can’t quietly leave a hook unwired. The strict check reaches the entries inside a structure’s placement groups too (static-object-placements / entity-placements), where the legal key set depends on the entry’s static-object-type / entity-type — so default-state on a tree, or a chance copied over from a structure link, fails the entry by name rather than sitting there doing nothing. The remaining leniency is about type, not spelling: a wrong-typed optional wielded-item-data block, and a wrong-typed projectile/wielded texture block, collapse to all-defaults rather than erroring — those are the only blocks left to double-check by hand.

The same rule covers unrecognized values of a closed-set field. Most enum-style fields accept only a fixed set the engine defines, and writing something outside it fails the entry exactly as a misspelled key does: a sound’s category, a control binding’s trigger and modifiers, an item’s type, an armor piece’s armor-type, a weapon’s type, a structure’s spawn-type. Note the contrast with the schema’s open registries — tool-types / tool-break-types, a crafting station’s type, an item’s material-types, a mob’s spawn-group, an ammo ammo-type — where any string you invent is a valid new tag by design. Each field’s own page says which kind it is.

An open registry can’t reject a typo, since a typo is indistinguishable from a new tag. Where that could bite, the engine cross-checks instead: a tool-break-types value that no item declares in its tool-types is warned about at load, naming the object and the unmatched category. The failure is also the safe direction — an object requiring a category nothing has is breakable by nothing, rather than by everything.

If some content doesn’t appear in game, read the startup log before anything else.

Reference

Foundational pages that apply across every config file.

  • Mod Manifest — the root ModName.yaml: metadata, config registration, and what loads by folder convention instead.
  • Schema Conventions — casing, units, coordinates, quantities, chance vs. weight, colours, and document shape shared by all configs.
  • Shared Blocks — the nested blocks that appear identically across many configs: hitbox, light, drop-table, scripts and particles.

Content Configuration

Catalog files that define what your mod adds to the game.

Rendering

Textures and shaders for content added by your mod.

Lua Modding

Server