World Registry Configuration

Map a world name to the world type and generation preset it should be created with, so a world reached by name generates correctly instead of falling back to the save default.

A save can hold more than one world. When something sends a player to a world by name — an inter-world travel destination, a portal, a Lua call — and that world does not exist yet, the engine has to create it, and it needs to know what kind of world it is. The world registry is where you say so.

Without a registry entry, a world reached by name is generated with the save’s default preset — so travelling to your intended cave dimension would produce another copy of the overworld. Registering the name fixes the world’s type and preset once, for every save.

You only need this file if your mod adds a world beyond the save’s default one. A mod that only adds blocks, mobs or recipes does not need it.

File Location

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

world-registry:

The key alone is enough — it defaults to world-registry.yaml in your mod folder. Give it a value only to use a different filename.

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/world-registry.yaml

Document Shape

This file is the one config that is keyed by name rather than being a list of entries with a name: field. The top-level worlds: block is a mapping from world name to that world’s definition:

worlds:
  <WorldName>:
    world-type: <name>
    world-type-mod: <ModName>
    preset-mod: <ModName>
    preset-name: <name>
    preset-type: <builder>

The key (<WorldName>) is the world’s name as travel destinations refer to it. It is not namespaced with your mod name — world names are global, so two mods registering the same name collide, and the mod loaded later wins (with its registration logged).

Why this file differs from the catalogs. Every other config wraps a plural list (items:, mobs:) whose entries carry a name: field. Here the world name is the map key instead. Keep that in mind when copying from another config — there is no name: field inside the definition.

Fields

The five generation fields are required; there are no defaults. An entry missing any of them is skipped with an error naming the world and your mod, and that world falls back to the save default.

One field is optional:

Why world-type-mod / preset-mod instead of Mod:name. Everywhere else in the schema you write a cross-mod reference as OtherMod:thing. This file predates that convention and splits the owning mod into its own key instead. Write your own mod’s name in both fields when the world type and preset are yours — unlike a bare name elsewhere, these do not default to the declaring mod.

preset-type

A closed set of four builders. The value also determines which folder preset-name is looked up in:

Matched case- and separator-insensitively, so SkyIsland, skyisland, sky-island and sky_island are the same value. An unrecognized value fails the world’s creation with an error listing the four valid ones.

Example

The shipped registry, which adds a surface-less cave world reachable by the name CaveTest:

worlds:
  CaveTest:
    world-type: Genesis
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: genesis
    preset-type: Cave

Read as: when something sends a player to a world called CaveTest, build it with Creation’s Genesis world type, generated by the Cave builder using Creation’s world-builders/cave/genesis.yaml preset.

Registering several worlds is just more keys under worlds::

worlds:
  CaveTest:
    world-type: Genesis
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: genesis
    preset-type: Cave
  SkyRealm:
    world-type: Genesis
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: genesis
    preset-type: SkyIsland

A world whose arrival is an Almanac milestone adds the optional arrival-milestone field — the player earns it the first time they reach the world:

worlds:
  Desolation:
    world-type: Desolation
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: desolation
    preset-type: Default
    arrival-milestone: reached_desolation   # granted on first arrival; must be a metric: event milestone

Troubleshooting

A world generates as a copy of the overworld. Its name isn’t registered, so it fell back to the save default. Check that the name in worlds: matches the destination name exactly — it is case-sensitive and not namespaced.

A world fails to generate at all. Check the startup log for the entry: an unknown preset-type, or a preset-name/preset-mod pointing at a preset file that doesn’t exist, both fail loudly and name the world.

An entry is silently absent. A misspelled key inside a definition (world_type for world-type) is rejected with a warning naming the entry, and that world is skipped. Read the startup log before anything else.

Last updated Aug 27, 2026