Worlds

A Basalt world is one dimension. A server loads as many as worlds.toml declares, each with its own chunks, region files and settings, and players move between them with /tp or through portals.

worlds/<name>/
  region/            r.<x>.<z>.linear
  poi/               points of interest (villager workstations, beds, portals)
  settings.toml      this world's settings, inheriting from worlds.toml
  mobs.toml          this world's mob settings, inheriting from worlds/mobs.toml

Player data is not stored here. It lives in players.db next to worlds/, so a world can be deleted, copied or reset without touching anyone's inventory.

Declaring worlds#

config/worlds.toml declares what to load. It never deletes anything:

• Add a table for a name with no directory and the world is created.
• Copy a world directory into worlds/ and add its table and the world is imported.
• Remove a table and the world stops loading. Its files stay, and putting the table back loads it as it was.
• Deleting a world means deleting worlds/<name>/ yourself.

[worlds.world]
default = true
type = "normal"
dimension = "overworld"

[worlds.world_nether]
type = "normal"
dimension = "nether"
linked_to = "world"

[worlds.world_the_end]
type = "normal"
dimension = "end"
linked_to = "world"

Several sets of dimensions#

linked_to is what lets one server run several Overworlds, each with its own Nether and End, without a plugin rewriting portal travel:

[worlds.skyblock]
type = "normal"

[worlds.skyblock_nether]
dimension = "nether"
linked_to = "skyblock"

[worlds.skyblock_the_end]
dimension = "end"
linked_to = "skyblock"

The rules are checked at startup and a violation stops the server, naming the world, rather than sending portals somewhere nobody chose: only a Nether or End can have linked_to, it must name an Overworld that the file declares, and an Overworld has at most one Nether and one End. A Nether or End with no seed of its own shares the seed of its Overworld, as a vanilla save does. Removing a dimension's table makes portals to it stop working (the log says so); its files stay.

Seeds#

Once a world exists, the seed it was generated with wins over the one in worlds.toml. A mismatch is logged and nothing is regenerated, because changing a seed does not rewrite terrain already on disk. To use a new seed, delete worlds/<name>/ and start again. When a vanilla world is imported, its own seed is kept and a differing configured one only logs a warning.

Inherited settings#

Settings follow one chain: the world's own settings.toml, then the [defaults] of worlds.toml, then vanilla's values. A world only needs to list the keys it changes. The generated settings.toml is full of commented-out lines to uncomment.

In worlds.toml the keys sit under [defaults] (and rule tables under [defaults.<table>]). In settings.toml the same keys sit at the top (and rule tables as plain [<table>]). A world's settings are read when it loads, so changing them needs a restart. A settings.toml that does not parse or holds an invalid value leaves that world on the inherited defaults and logs a warning.

Loot refill#

Not vanilla, off by default. With loot-refill = true, a loot container keeps its table after the first opening and fills again once a random time between loot-refill-min-seconds and loot-refill-max-seconds (12 hours and 48 hours by default) has passed since it was filled, for the next player who opens it. loot-max-refills is how many times a container may fill in all, the first fill included (-1 is unlimited). loot-reloot-seconds is how long a player must wait to loot a refilled container they already looted (-1 is never). The maximum is raised to the minimum if it is smaller.

Rules and game rules#

The same files carry tables that change how a world plays. Every value shipped is vanilla's, and anything different is marked NOT VANILLA in the generated comments. Rules are read when the world loads.

[gamerules]#

Initial game rules for a world that is being created, using the vanilla 26.3 names (keep_inventory, pvp, random_tick_speed, spawn_monsters, advance_time...). Values are true, false or a whole number. A world that already has level data keeps its own rules, and /gamerule still changes them afterwards.

[gamerules]
keep_inventory = true
random_tick_speed = 6

[growth]#

How often plants try to grow, as a percentage of vanilla's chance. 100 is vanilla, 0 stops the plant, 200 doubles the rate. Range 0 to 100000. Anything but 100 is NOT VANILLA.

Keys, all default 100: crops (wheat, carrots, potatoes, beetroots, torchflower, pitcher plant), stems (pumpkin and melon), saplings, cactus, sugar-cane, bamboo, vines, kelp, cave-vines, twisting-vines, weeping-vines, nether-wart, sweet-berries, cocoa, mushrooms, chorus-flower.

[hopper]#

Anything but the defaults is NOT VANILLA.

[environment]#

[border]#

The world border a world starts with. A world that already has a saved border keeps it, and /worldborder changes it afterwards.

[anti-xray]#

Not vanilla, off by default. Hides ores from clients that cheat by reading chunk data. Blocks that touch nothing see-through are replaced in the chunk packets, and whoever mines next to them is sent the real blocks. Bedrock players are not covered.

Tuning tables#

Gameplay rules#

[gameplay.blocks], [gameplay.mechanics], [gameplay.player] and [gameplay.items] hold over a hundred finer rules. In worlds.toml they are [defaults.gameplay.<group>], in a world's settings.toml [gameplay.<group>]. Restart to apply. They are only listed in the generated file, where each key carries a comment stating its vanilla value:

Every key defaults to vanilla's value, and any other value is marked NOT VANILLA next to the key.

Mob settings#

Mob caps, spawning, despawning, dropped-item lifetimes and per-type tweaks live in config/worlds/mobs.toml, and a world overrides any key in worlds/<name>/mobs.toml. Every value shipped is vanilla's, and a change applies when the world loads. Both files are generated with a comment on every key.

The Linear format#

Worlds are stored as Linear (.linear) region files, not Anvil (.mca). The format is invisible to players, so it is not a parity difference, and it is better in every way an operator notices:

• About half the disk space for the Overworld and Nether, and far less for the End.
• One compressed stream per region (zstd) instead of one per chunk, so a region is one read or write.
• No per-chunk padding to 4096 bytes and no separate files for very large chunks.

Files are worlds/<name>/region/r.<x>.<z>.linear.

Importing a world#

Moving an existing world to Basalt is "copy the folder and start", not "run a converter first".

1. Copy the world into worlds/<name>/. For a vanilla, Paper or Spigot world, copy its region/, entities/, poi/ and level.dat.
2. Declare it in worlds.toml with the matching dimension.
3. Start the server.

When a region has only an Anvil file (region/r.<x>.<z>.mca), Basalt reads it and the entities that vanilla keeps in entities/, and writes it back as Linear. When the world has a vanilla level.dat, its seed, spawn point, time and difficulty are imported once and kept in the world.

A vanilla save holds three dimensions in one folder, while Basalt has one dimension per world. Import each as its own world: the Overworld's region/ is the root region/, the Nether's is DIM-1/region/ and the End's is DIM1/region/. Declare the second and third with dimension = "nether" and "end" and linked_to pointing at the Overworld, as in Declaring worlds.

A region that cannot be read is logged and left alone: it is never overwritten.

Metamorph#

Metamorph is the command line tool behind this conversion. It never modifies its input: the result goes to <world>.converted unless -o says otherwise, and an output folder that already holds files is refused.

metamorph convert <world> --to linear [-o <out>]
metamorph convert <world> --to anvil [-o <out>]
metamorph upgrade <world> [-o <out>]

<world> is a folder with region files anywhere under it; dimension folders, entities/ and poi/ are found automatically. A chunk that cannot be read is reported and the command exits with an error.

Backups#

Basalt does not run backups; use your own tooling. What matters is what to copy and when:

• Copy the whole server directory, or at least worlds/, config/, plugins/ and players.db. Player data is in players.db, not in the worlds.
• Region files are rewritten whole, so copy them while the server is quiet. /save-off stops writing, /save-all flushes, then copy, then /save-on. Stopping the server first is always safe.
• A world with its table removed from worlds.toml is simply not loaded; archiving it is a plain directory copy.