API

Javadocs for the API can be found here.

Getting Started

Use WorldsAccess as the entry point for the Worlds API:

WorldsAccess access = WorldsAccess.access();

The access object exposes the current world, level, dimension, clone, backup, and registry operations.

Common access methods:

• getWorldRegistry() - returns the WorldRegistry
• customDimensions() - returns all registered custom dimensions
• getDimension(World) - resolves a world's Dimension
• listLevels() - lists all known level directories
• load(Key) - loads a world by key
• create(Level) - creates a world
• unload(World, boolean) - unloads a world
• save(World, boolean) - saves a world, optionally flushing
• clone(World, boolean) - clones a world
• clone(World, Consumer<Level.Builder>, boolean) - clones and customizes the target level
• delete(World) - deletes a world
• regenerate(World) - regenerates a world

Creating a World

Worlds are identified by Keys. Create a Level with Level.builder(Key) and call create():

import net.kyori.adventure.key.Key;
import net.thenextlvl.worlds.Level;
import net.thenextlvl.worlds.WorldsAccess;
import net.thenextlvl.worlds.generator.GeneratorType;

var access = WorldsAccess.access();

var level = Level.builder(Key.key("example", "survival"))
        .generatorType(GeneratorType.NORMAL)
        .seed(12345L)
        .structures(true)
        .build();

level.create();

You can also pass the level to the access entry point:

WorldsAccess.access().create(level);

To change the target key while configuring a level, use Level.Builder#key(Key).

Configured Generator Types

Flat worlds use a preset:

import net.kyori.adventure.key.Key;
import net.thenextlvl.worlds.Level;
import net.thenextlvl.worlds.generator.GeneratorType;
import net.thenextlvl.worlds.preset.Preset;

Level.builder(Key.key("example", "void"))
        .generatorType(GeneratorType.FLAT.with(Preset.THE_VOID))
        .build()
        .create();

Single-biome worlds use a biome key:

import net.kyori.adventure.key.Key;
import net.thenextlvl.worlds.Level;
import net.thenextlvl.worlds.generator.GeneratorType;

Level.builder(Key.key("example", "plains"))
        .generatorType(GeneratorType.SINGLE_BIOME.with(Key.key("minecraft", "plains")))
        .build()
        .create();

Cloning a World

Use WorldsAccess.access().clone(...) to clone loaded worlds. Set full to true to include region data and other world contents, or false to clone only the level metadata.

import net.kyori.adventure.key.Key;
import net.thenextlvl.worlds.WorldsAccess;

boolean full = true;

WorldsAccess.access().clone(world, full);

Customize the cloned level with a builder consumer:

import net.kyori.adventure.key.Key;
import net.thenextlvl.worlds.WorldsAccess;

boolean full = true;

WorldsAccess.access().clone(world, builder -> {
    builder.key(Key.key("example", "survival_copy"));
}, full);

Backups

Backups are handled through the current backup API. Use the backup provider to create, restore, delete, and list world backups.

The backup API covers:

• creating backups for one world or all loaded worlds
• creating named backups
• listing backups globally or for a specific world
• restoring a specific backup or the latest backup
• deleting a backup