Worlds

Basalt keeps worlds in the vanilla Bedrock format, so worlds move freely between Basalt, the game and BDS. Each world is a folder inside worlds/:

worlds/
  world/
    level.dat
    levelname.txt
    config.json
    db/

The world setting in basalt.toml names the folder to play. Basalt runs one world at a time.

Use an existing world

1. Stop Basalt.

2. Copy the world folder into worlds/, for example worlds/skyblock/.

3. Set the name in basalt.toml:

   world = "skyblock"

4. Start Basalt.

Caution

Work on a copy. Basalt writes to the world’s database as it runs.

Terrain, biomes, block entities (chests, signs and so on) and block changes all load and save. Blocks saved by an older game version are upgraded to the current format as their chunks load, so a world from an older BDS keeps blocks, such as stairs, whose format has changed since.

Create a new world

Set world to a name that has no folder yet, or whose folder has no level.dat, and start Basalt. It creates the world with vanilla-style terrain, a random seed and the default game rules. Run /seed to see the seed.

world = "survival"

Caution

New terrain comes from a partial port of the vanilla generator. It makes the overworld’s landscape but can be missing structures, and there is no Nether or End yet. The same generator fills in any chunks an imported vanilla world never saved. See Vanilla parity.

World settings: config.json

Each world folder has a config.json with the world’s game mode, difficulty, game rules and experiments in a form that is easy to edit:

{
  "game_mode": "survival",
  "difficulty": "normal",
  "game_rules": {
    "dodaylightcycle": true,
    "keepinventory": false,
    "playerssleepingpercentage": 100,
    "randomtickspeed": 1
  },
  "experiments": []
}

• game_mode is survival, creative, adventure or spectator.
• difficulty is peaceful, easy, normal or hard.
• game_rules holds every game rule by its lowercase name, as true/false or a whole number.
• experiments lists the experiments the world has turned on, by the names level.dat uses, such as "y_2026_drop_4". They are saved in level.dat and sent to players as they join. An empty list turns them all off.

Edit the file while Basalt is stopped. When Basalt starts, config.json wins over what level.dat says, and both files are written again at startup and shutdown so they agree. Anything you leave out keeps its current value. A rule name Basalt does not know is skipped with a warning, and a file with a syntax error is reported instead of being overwritten, so your edit is not lost.

While Basalt is running, change the same settings with /gamerule and /difficulty; they are saved to the world’s files. See Commands.

Note

The game mode a player gets when they join is set by gamemode and force_gamemode in basalt.toml. See Configuration.

Saving

• Players and the world are saved every autosave_ticks ticks (6000 by default, five minutes).
• A player is saved when they leave.
• Everything is saved when Basalt stops.
• Chunks nobody is near are saved and unloaded after chunk_unload_delay seconds (300 by default).

Structure files

Basalt reads .mcstructure files from the structures/ folder beside basalt.toml. Plugins can place them through world.structureManager.

File	Structure id
structures/vault/door.mcstructure	vault:door
structures/hut.mcstructure	mystructure:hut

A file inside a subfolder takes the folder as its namespace. A file at the top of structures/ gets the mystructure namespace, as vanilla names structures saved without one.