Instances

Overview

Instances are what Minecraft calls “worlds”. Each instance contains entities, chunks, and has its own properties like dimension type, time, and weather.

InstanceManager

The InstanceManager handles the registration and lifecycle of all instances in the server.

Creating Instances

createInstanceContainer()

InstanceContainer

Creates and registers a new InstanceContainer with default settings (Overworld dimension).Returns: The created and registered InstanceContainer

InstanceManager manager = MinecraftServer.getInstanceManager();
InstanceContainer world = manager.createInstanceContainer();

createInstanceContainer(RegistryKey<DimensionType>)

InstanceContainer

Creates an instance with a specific dimension type.Parameters:

dimensionType - The dimension type (e.g., DimensionType.OVERWORLD, DimensionType.NETHER)

Returns: The created InstanceContainer

InstanceContainer nether = manager.createInstanceContainer(DimensionType.NETHER);

createInstanceContainer(RegistryKey<DimensionType>, ChunkLoader)

InstanceContainer

Creates an instance with a dimension type and chunk loader for persistence.Parameters:

dimensionType - The dimension type
loader - ChunkLoader for loading/saving chunks (null for no persistence)

Returns: The created InstanceContainer

AnvilLoader loader = new AnvilLoader("worlds/world");
InstanceContainer world = manager.createInstanceContainer(DimensionType.OVERWORLD, loader);

Shared Instances

createSharedInstance(InstanceContainer)

SharedInstance

Creates a shared instance that shares chunks with a parent InstanceContainer.Parameters:

instanceContainer - The parent instance container

Returns: The created SharedInstanceThrows: IllegalStateException if the container is not registered

SharedInstance lobby = manager.createSharedInstance(world);
// lobby shares chunks with world but can have different time/weather

Managing Instances

registerInstance(Instance)

void

Manually registers an instance. Required if you instantiate an instance directly.Parameters:

instance - The instance to register

Not necessary if using createInstanceContainer() or createSharedInstance()

unregisterInstance(Instance)

void

Unregisters an instance and unloads all its chunks.Parameters:

instance - The instance to unregister

Throws: IllegalStateException if the instance has online players

manager.unregisterInstance(world);

getInstances()

Set<Instance>

Gets all registered instances.Returns: Unmodifiable set of all instances

for (Instance instance : manager.getInstances()) {
    System.out.println("Instance: " + instance.getUuid());
}

getInstance(UUID)

Instance

Gets an instance by its UUID.Parameters:

uuid - The instance UUID

Returns: The instance, or null if not found

Instance

The Instance class represents a world with chunks, entities, time, and weather.

Block Operations

setBlock(int, int, int, Block)

void

Sets a block at the specified coordinates.Parameters:

x - Block X coordinate
y - Block Y coordinate
z - Block Z coordinate
block - The block to place

instance.setBlock(0, 64, 0, Block.STONE);

setBlock(Point, Block)

void

Sets a block at the specified position.Parameters:

blockPosition - The block position
block - The block to place

instance.setBlock(new Vec(0, 64, 0), Block.DIAMOND_BLOCK);

setBlock(int, int, int, Block, boolean)

void

Sets a block with control over block updates.Parameters:

x, y, z - Block coordinates
block - The block to place
doBlockUpdates - Whether to trigger block updates

instance.setBlock(0, 64, 0, Block.WATER, false); // No physics updates

getBlock(int, int, int)

Block

Gets the block at specified coordinates.Parameters:

x, y, z - Block coordinates

Returns: The block at the position

Block block = instance.getBlock(0, 64, 0);
if (block.compare(Block.STONE)) {
    // Block is stone
}

getBlock(Point)

Block

Gets the block at the specified point.Parameters:

point - The position

Returns: The block at the position

Chunk Management

loadChunk(int, int)

CompletableFuture<Chunk>

Forces loading of a chunk, generating it if needed.Parameters:

chunkX - Chunk X coordinate
chunkZ - Chunk Z coordinate

Returns: Future completed when chunk is loaded

instance.loadChunk(0, 0).thenAccept(chunk -> {
    System.out.println("Chunk loaded!");
});

loadChunk(Point)

CompletableFuture<Chunk>

Loads the chunk at the given point.Parameters:

point - Position in the chunk

Returns: Future completed when chunk is loaded

loadOptionalChunk(int, int)

CompletableFuture<Chunk>

Loads a chunk only if auto chunk loading is enabled or chunk is already loaded.Parameters:

chunkX, chunkZ - Chunk coordinates

Returns: Future with chunk (can be null if not loaded)

unloadChunk(Chunk)

void

Schedules a chunk for unloading. All non-player entities will be removed.Parameters:

chunk - The chunk to unload

Chunk chunk = instance.getChunk(0, 0);
instance.unloadChunk(chunk);

unloadChunk(int, int)

void

Unloads the chunk at the specified coordinates.Parameters:

chunkX, chunkZ - Chunk coordinates

getChunk(int, int)

Chunk

Gets an already loaded chunk.Parameters:

chunkX, chunkZ - Chunk coordinates

Returns: The chunk if loaded, null otherwise

Only returns already-loaded chunks. Use loadChunk() to load new chunks.

isChunkLoaded(int, int)

boolean

Checks if a chunk is loaded.Parameters:

chunkX, chunkZ - Chunk coordinates

Returns: true if the chunk is loaded

getChunks()

Collection<Chunk>

Gets all loaded chunks in this instance.Returns: Unmodifiable collection of loaded chunks

Chunk Generation

setGenerator(Generator)

void

Sets the chunk generator for this instance.Parameters:

generator - The generator (null to disable)

instance.setGenerator(unit -> {
    unit.modifier().fillHeight(0, 40, Block.STONE);
    unit.modifier().fillHeight(40, 41, Block.GRASS_BLOCK);
});

generator()

Generator

Gets the current chunk generator.Returns: The generator, or null if not set

enableAutoChunkLoad(boolean)

void

Enables or disables automatic chunk loading.Parameters:

enable - true to enable auto chunk loading

instance.enableAutoChunkLoad(true);

hasEnabledAutoChunkLoad()

boolean

Checks if auto chunk loading is enabled.Returns: true if enabled

World Properties

getDimensionType()

RegistryKey<DimensionType>

Gets the dimension type registry key.Returns: The dimension type key

getDimensionName()

String

Gets the dimension name.Returns: The dimension name as a string

getUuid()

UUID

Gets the instance UUID.Returns: The instance UUID

Time Management

getTime()

long

Gets the current time in the instance (sun/moon position).Returns: The time in ticks (0-24000)

setTime(long)

void

Sets the instance time.Parameters:

time - Time in ticks (0 = dawn, 6000 = noon, 12000 = dusk, 18000 = midnight)

instance.setTime(6000); // Set to noon

getWorldAge()

long

Gets the age of the instance in ticks.Returns: The world age

setWorldAge(long)

void

Sets the world age in ticks.Parameters:

worldAge - The new world age

setTimeRate(int)

void

Sets how fast time advances (default: 1).Parameters:

timeRate - Ticks to advance per server tick (0 to stop time)

Persistence

saveInstance()

CompletableFuture<Void>

Saves instance data (tags only, not chunks).Returns: Future completed when save finishes

instance.saveInstance().thenRun(() -> {
    System.out.println("Instance saved!");
});

saveChunkToStorage(Chunk)

CompletableFuture<Void>

Saves a specific chunk to permanent storage.Parameters:

chunk - The chunk to save

Returns: Future completed when save finishes

saveChunksToStorage()

CompletableFuture<Void>

Saves all loaded chunks to permanent storage.Returns: Future completed when all chunks are saved

Examples

public class WorldSetup {
    public static void main(String[] args) {
        MinecraftServer server = MinecraftServer.init();
        InstanceManager instanceManager = MinecraftServer.getInstanceManager();
        
        // Create instance with generator
        InstanceContainer world = instanceManager.createInstanceContainer();
        world.setGenerator(unit -> {
            unit.modifier().fillHeight(0, 40, Block.STONE);
            unit.modifier().fillHeight(40, 41, Block.GRASS_BLOCK);
        });
        
        // Enable auto chunk loading
        world.enableAutoChunkLoad(true);
        
        // Set time
        world.setTime(6000); // Noon
        
        server.start("0.0.0.0", 25565);
    }
}

Instances must be registered before players can join them. Use createInstanceContainer() which automatically registers, or manually call registerInstance().

Core

Systems

Utilities

Overview

InstanceManager

Creating Instances

Shared Instances

Managing Instances

Instance

Block Operations

Chunk Management

Chunk Generation

World Properties

Time Management

Persistence

Examples

Build docs developers (and LLMs) love

Core

Systems

Utilities

​Overview

​InstanceManager

​Creating Instances

​Shared Instances

​Managing Instances

​Instance

​Block Operations

​Chunk Management

​Chunk Generation

​World Properties

​Time Management

​Persistence

​Examples

Build docs developers (and LLMs) love

Overview

InstanceManager

Creating Instances

Shared Instances

Managing Instances

Instance

Block Operations

Chunk Management

Chunk Generation

World Properties

Time Management

Persistence

Examples