Skip to main content
This guide will walk you through creating a minimal but functional Minestom server. We’ll set up the server, create a world instance, and handle player connections.

​
Prerequisites

  • Java 21 or higher installed
  • A project with Minestom dependency configured (see Installation)
  • Basic understanding of Java programming

​
Creating Your First Server

Let’s build a simple server that creates a flat world and spawns players in creative mode.
1

Create the Main Class

Create a new Java class with a main method. This will be the entry point for your server.
Main.java
package com.example.myserver;

import net.minestom.server.MinecraftServer;
import net.minestom.server.Auth;

public class Main {
    public static void main(String[] args) {
        // Initialize the Minestom server
        MinecraftServer minecraftServer = MinecraftServer.init(new Auth.Offline());
        
        // Start the server on port 25565
        minecraftServer.start("0.0.0.0", 25565);
        
        System.out.println("Server started successfully!");
    }
}
Auth.Offline() disables online mode authentication. For production servers, consider using Auth.Online() or integrating with a proxy like Velocity.
2

Create a World Instance

Minestom uses “instances” instead of traditional worlds. Instances are lightweight containers for blocks and entities that can be easily created, copied, and managed.Add the following code before starting the server:
Main.java
import net.minestom.server.instance.InstanceContainer;
import net.minestom.server.instance.InstanceManager;
import net.minestom.server.instance.block.Block;
import net.minestom.server.instance.LightingChunk;

public class Main {
    public static void main(String[] args) {
        MinecraftServer minecraftServer = MinecraftServer.init(new Auth.Offline());
        
        // Get the instance manager
        InstanceManager instanceManager = MinecraftServer.getInstanceManager();
        
        // Create a new instance
        InstanceContainer instanceContainer = instanceManager.createInstanceContainer();
        
        // Set up a simple flat world generator
        instanceContainer.setGenerator(unit -> {
            unit.modifier().fillHeight(0, 40, Block.STONE);
            
            // Add a torch at y=40 for each chunk
            if (unit.absoluteStart().blockY() < 40 && unit.absoluteEnd().blockY() > 40) {
                unit.modifier().setBlock(
                    unit.absoluteStart().blockX(), 40, unit.absoluteStart().blockZ(),
                    Block.TORCH
                );
            }
        });
        
        // Enable lighting (optional but recommended)
        instanceContainer.setChunkSupplier(LightingChunk::new);
        
        // Set time to day and stop time progression
        instanceContainer.setTimeRate(0);
        instanceContainer.setTime(12000);
        
        minecraftServer.start("0.0.0.0", 25565);
    }
}
The generator function is called for each chunk section. Use unit.modifier() to place blocks efficiently in bulk.
3

Handle Player Connections

Now we need to handle player login and spawning. We’ll use Minestom’s event system to listen for player configuration and spawn events.
Main.java
import net.minestom.server.coordinate.Pos;
import net.minestom.server.entity.GameMode;
import net.minestom.server.entity.Player;
import net.minestom.server.event.GlobalEventHandler;
import net.minestom.server.event.player.AsyncPlayerConfigurationEvent;
import net.minestom.server.event.player.PlayerSpawnEvent;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public class Main {
    public static void main(String[] args) {
        MinecraftServer minecraftServer = MinecraftServer.init(new Auth.Offline());
        
        InstanceManager instanceManager = MinecraftServer.getInstanceManager();
        InstanceContainer instanceContainer = instanceManager.createInstanceContainer();
        
        instanceContainer.setGenerator(unit -> {
            unit.modifier().fillHeight(0, 40, Block.STONE);
            if (unit.absoluteStart().blockY() < 40 && unit.absoluteEnd().blockY() > 40) {
                unit.modifier().setBlock(
                    unit.absoluteStart().blockX(), 40, unit.absoluteStart().blockZ(),
                    Block.TORCH
                );
            }
        });
        instanceContainer.setChunkSupplier(LightingChunk::new);
        instanceContainer.setTimeRate(0);
        instanceContainer.setTime(12000);
        
        // Get the global event handler
        GlobalEventHandler eventHandler = MinecraftServer.getGlobalEventHandler();
        
        // Set the spawning instance for new players
        eventHandler.addListener(AsyncPlayerConfigurationEvent.class, event -> {
            final Player player = event.getPlayer();
            event.setSpawningInstance(instanceContainer);
            player.setRespawnPoint(new Pos(0, 42, 0));
        });
        
        // Configure player on spawn
        eventHandler.addListener(PlayerSpawnEvent.class, event -> {
            final Player player = event.getPlayer();
            player.setGameMode(GameMode.CREATIVE);
            
            // Send welcome message
            player.sendMessage(
                Component.text("Welcome to my Minestom server!", NamedTextColor.GOLD)
            );
        });
        
        minecraftServer.start("0.0.0.0", 25565);
        System.out.println("Server started on port 25565");
    }
}
4

Run Your Server

Compile and run your application. You should see output indicating the server has started:
Terminal
./gradlew run
Connect to your server using the Minecraft client at localhost:25565.
Make sure you’re using a Minecraft client version that matches your Minestom version (1.21.x based on the data version 1.21.11-rv2).

​
Complete Example

Here’s the complete working example based on the Minestom demo:
Main.java
package com.example.myserver;

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import net.minestom.server.Auth;
import net.minestom.server.MinecraftServer;
import net.minestom.server.coordinate.Pos;
import net.minestom.server.entity.GameMode;
import net.minestom.server.entity.Player;
import net.minestom.server.event.GlobalEventHandler;
import net.minestom.server.event.player.AsyncPlayerConfigurationEvent;
import net.minestom.server.event.player.PlayerSpawnEvent;
import net.minestom.server.instance.InstanceContainer;
import net.minestom.server.instance.InstanceManager;
import net.minestom.server.instance.LightingChunk;
import net.minestom.server.instance.block.Block;

public class Main {

    public static void main(String[] args) {
        // Initialize the server with offline mode
        MinecraftServer minecraftServer = MinecraftServer.init(new Auth.Offline());
        
        // Create an instance (world)
        InstanceManager instanceManager = MinecraftServer.getInstanceManager();
        InstanceContainer instanceContainer = instanceManager.createInstanceContainer();
        
        // Set up world generator - creates a flat stone world
        instanceContainer.setGenerator(unit -> {
            unit.modifier().fillHeight(0, 40, Block.STONE);
            
            // Place a torch on top of each chunk
            if (unit.absoluteStart().blockY() < 40 && unit.absoluteEnd().blockY() > 40) {
                unit.modifier().setBlock(
                    unit.absoluteStart().blockX(), 40, unit.absoluteStart().blockZ(),
                    Block.TORCH
                );
            }
        });
        
        // Enable lighting support
        instanceContainer.setChunkSupplier(LightingChunk::new);
        
        // Set to daytime and stop time progression
        instanceContainer.setTimeRate(0);
        instanceContainer.setTime(12000);
        
        // Register event listeners
        GlobalEventHandler eventHandler = MinecraftServer.getGlobalEventHandler();
        
        // Handle player configuration (pre-spawn)
        eventHandler.addListener(AsyncPlayerConfigurationEvent.class, event -> {
            final Player player = event.getPlayer();
            event.setSpawningInstance(instanceContainer);
            player.setRespawnPoint(new Pos(0, 42, 0));
        });
        
        // Handle player spawn
        eventHandler.addListener(PlayerSpawnEvent.class, event -> {
            final Player player = event.getPlayer();
            
            // Set game mode to creative
            player.setGameMode(GameMode.CREATIVE);
            
            // Send welcome message on first spawn
            if (event.isFirstSpawn()) {
                player.sendMessage(
                    Component.text("Welcome to my Minestom server!", NamedTextColor.GOLD)
                );
            }
        });
        
        // Start the server on default port
        minecraftServer.start("0.0.0.0", 25565);
        System.out.println("Server started successfully on port 25565!");
    }
}

​
What’s Next?

Congratulations! You’ve created your first Minestom server. Here are some next steps:

Core Concepts

Understand instances, blocks, entities, and the event system

Commands

Add custom commands using Brigadier

Block Handlers

Implement custom block interactions like chests and doors

Event System

Learn how to listen and respond to server events

​
Additional Configuration

​
Enable Compression

Reduce bandwidth usage by enabling packet compression: 
MinecraftServer.setCompressionThreshold(256);

​
Register Commands

Add custom commands to your server: 
import net.minestom.server.command.CommandManager;
import net.minestom.server.command.builder.Command;

CommandManager commandManager = MinecraftServer.getCommandManager();
commandManager.register(new MyCustomCommand());

​
Enable Benchmarking

Monitor server performance: 
import net.minestom.server.utils.time.TimeUnit;
import java.time.Duration;

MinecraftServer.getBenchmarkManager().enable(Duration.of(10, TimeUnit.SECOND));
Check out the demo directory in the Minestom repository for more advanced examples including block handlers, custom entities, inventories, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us