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.

The registry also drives the create-new-world menu: an entry that sets menu-visible: true (see Fields) is offered to players as a world they can start a new save in. The menu is built from this data across the instance’s enabled mods — there is no hardcoded list — so adding a startable world type is a registry entry, not an engine change.

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.

Two fields are 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 registers the home world, Genesis — the only world offered in the create-new-world menu — and the four corrupted worlds it opens onto, each a travel-only destination that grants its arrival milestone:

worlds:
  Genesis:
    world-type: Genesis
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: genesis
    preset-type: Default
    menu-visible: true      # offered in the create-new-world menu
  The Ashenhollow:
    world-type: Ashenhollow
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: ashenhollow
    preset-type: Default     # no menu-visible flag → reachable by name, but not shown to players
    arrival-milestone: reached_ashenhollow   # granted on first arrival; must be a metric: event milestone
  The Necracombs:
    world-type: Necracombs
    world-type-mod: Creation
    preset-mod: Creation
    preset-name: necracombs
    preset-type: Cave
    arrival-milestone: reached_necracombs

Read as: Genesis is a startable world built with the Default builder; The Ashenhollow, when something sends a player to it — a portal, /world The Ashenhollow, a Lua transfer_to_world — builds with the Default builder using Creation’s world-builders/default/ashenhollow.yaml preset and never appears in the new-world menu; The Necracombs builds with the Cave builder from world-builders/cave/necracombs.yaml.

Two things the shipped file shows that are easy to miss:

• The key is the name the player reads, spaces and article included. It appears in the travel overlay, the Almanac’s discovered worlds, and (when menu-visible) the create-save menu, so it must match the world’s milestone name: in almanac-milestones-config.yaml. The world-type and preset-name values are file names and are not player-facing — which is why they drop the article.
• Whatever sends a player by name uses the key verbatim. A portal’s destination-world (interactable-config.md), the operator /world command (which joins its arguments, so /world The Ashenhollow works; an optional trailing x y pair is the arrival position) and player:transfer_to_world("The Ashenhollow") all name the key.

Registering several worlds is just more keys under worlds:, and a world may reuse another’s world type and preset — this is how a second copy of a terrain recipe becomes a separate dimension:

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

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 Sep 29, 2026