Minestom features a number of interaction methods for players. Many of them are described below, however this list is not exhaustive.

Sidebars (Scoreboards)

Sidebars can be used to display up to 16 lines on a scoreboard for the player. They are created given a title as follows:

Sidebar#<init>(Component /* title */)

Sidebar titles do not support JSON chat components, however the provided component will be serialized using Adventure's legacy serializer.

Once created, a scoreboard can be added and removed from players as follows:

Sidebar#addViewer(Player);
Sidebar#removeViewer(Player);

Sidebar Line

Lines on a sidebar are made up of ScoreboardLines. They render on the scoreboard in order of their line number (score), where the vertically highest line represents the highest line number (score). If two lines have the same line number (score), they will be sorted alphabetically.

ScoreboardLines can be created using their constructor:

Sidebar.ScoreboardLine#<init>(String /* unique id*/, Component /* content */, int /* line */);

// For example
Sidebar.ScoreboardLine line = new Sidebar.ScoreboardLine(
        "some_line_0",
        Component.text("Hello, Sidebar!", NamedTextColor.RED),
        0
);

Once created, scoreboard lines may be added to Sidebars as follows:

Sidebar#createLine(Sidebar.ScoreboardLine);

Lines are indexed by their unique id, and can be modified with it:

Sidebar#getLine(String /* unique id */);
Sidebar#updateLineContent(String /* unique id */, Component /* new content */);
Sidebar#updateLineScore(String /* unique id */, Int /* new score */);

Notifications

Notifications are a system to send advancement completion toasts to a player as a form of communication.

Notification#<init>(Component /* title */, FrameType, ItemStack /* icon */);

// For example
Notification notification = new Notification(
        Component.text("Hello, Notifications!", NamedTextColor.GREEN),
        FrameType.GOAL,
        ItemStack.of(Material.GOLD_INGOT)
);

To send the notification, use one of the static methods on NotificationCenter:

NotificationCenter.send(Notification, Player);
NotificationCenter.send(Notification, Collection<Player>);

The example renders as the following:

Adding Microtus to your Java project is really simple, you only need to add a few repositories:

Repositories

Dependencies

Audiences

What is an Audience?

The following, taken from the Adventure documentation, describes the concept of an Audience:

As an API, Audience is designed to be a universal interface for any player, command sender, console, or otherwise who can receive text, titles, boss bars, and other Minecraft media. This allows extending audiences to cover more than one individual receiver - possible “audiences” could include a team, server, world, or all players that satisfy some predicate (such as having a certain permission). The universal interface also allows reducing boilerplate by gracefully degrading functionality if it is not applicable.

Put simply, every class that implements Audience, or one of the subtypes, provides access to the full Adventure API.

In Minestom, the following classes are audiences:

• CommandSender,

• Player,

• Instance,

• Scoreboard, and

• Team.

This means that if you have an instance of any one of these classes, you can use the full Adventure API to, for example, show a title to every member of the audience. This allows for more powerful and direct control over how you communicate with players.

Obtaining Audiences

As mentioned in the previous section, some Minestom classes implement Audience directly. This means that if you have a reference to, for example, an Instance, you can simply use the Adventure API on that instance. As an example, the following code would be used to send a message to all players in an instance:

Minestom also provides a way to obtain audiences through the Audiences class. The following code provides an example of how this class would be used in your project:

The Audiences class also provides a players(Predicate) function that allows you to collect an audience of players that match a specific predicate. For example, this could be used to check permissions before sending a broadcast. Additionally, if you would like access to each audience as an iterable, you can instead use the IterableAudienceProvider, an instance of which can be obtained using Audiences#iterable().

Custom audiences

The Audiences class also provides the ability to add custom audience members identified by a Key. This could be used to add an audience for file logging or a ForwardingAudience representing a custom collection of players. Audiences can be registered using the AudienceRegistry, an instance of which can be obtained using Audiences#registry(). For example, if you wanted to share a collection of staff members to send alerts to between plugins, this could be done using the following code:

You can also create your own Audience, use the Adventure method Audience.audience(Iterable) or the Minestom PacketGroupingAudience.of() method to create an audience backed on an iterable object. This means that you could register a custom audience backed by a collection that you continue to update and the changes will be reflected when anyone uses the custom methods.

The all() and of(Predicate) methods will collect every custom audience using streams, and combine this with the server audience. Such an operation is relatively costly, so should be avoided where possible.

Packet grouping

Minestom also provides a new ForwardingAudience implementation called PacketGroupingAudience. This is implemented by every audience in Minestom that has multiple players. Instead of the normal ForwardingAudience implementation that iterates through the audience members, this implementation uses PacketUtils#sendGroupedPacket(Collection, ServerPacket) to attempt to send a grouped packet to all of the players in this audience.

To create your own PacketGroupingAudience, you can use the static of(Collection) and of(Iterable) methods in the class which return an instance of PacketGroupingAudience when provided a group of players.

Viewable

In addition, the Viewable class includes two methods to obtain the viewers of the viewable object as an audience. This means that you can use the full Adventure API on the viewers of a viewable object. For example, to send a message to everyone who can view a player in the old API you would do:

With the Adventure API you can simply do:

The added benefit of using the audience provided by the Viewable Class is that it implements PacketGroupingAudience which means the outgoing packets are grouped where possible, reducing networking overhead when compared to the looping method of sending messages.

Color

Alongside the deprecation of the Minestom ChatColor class, a new color package has been created to replace all existing usage of the ChatColor class. These new classes are an accurate representation of how Minecraft stores colors for certain objects and allows for proper validation, preventing developers from applying styles to colorable objects at compile-time.

The base class is the Color class is a general purpose class for representing RGB colors, similar to java.awt.Color. As this class implements Adventure's RGBLike interface, it can be used anywhere in the Adventure API that requires coloring (e.g. component text). A new addition to this class is the mixWith method which mixes this color with a series of other RGBLike colors to create a new color using the same method that vanilla Minecraft uses to mix dyes and colors.

There is also one additional color class; DyeColor. This enum represents the different colors of the dyes within Minecraft and provides values for each of the different vanilla dye types. This class includes a method to get the RGB color of the dye and the equivalent firework color. As with the Color class, this class also implements RGBLike so it can also be used throughout the Adventure API.

Translation

The Adventure update in Minestom adds the SerializationManager class, a powerful and feature-rich way to control the flow of component translation. Adventure provides the concept of a GlobalTranslator. By supplying sources, a collection of key-value pairs, you can perform server-side translations without any additional code or complicated localization libraries.

To enable automatic component translation, you need to set the constant SerializationManager#AUTOMATIC_COMPONENT_TRANSLATION to true. With this set, any components that are being sent to players will be translated using their locale automatically.

Additionally, the SerializationManager provides access to the serializer used to convert all components to JSON strings. By default, the serializer is a Function<Component, String> that uses Adventure's GsonComponentSerializer to serialize a component into a JSON string using the GSON library. However, you can mutate this serializer or change it completely.

For example, if you wanted to replace all instances of the word "dog" with "cat" every single time a component is serialized, you could use the following code:

Migrating to Adventure

The Adventure update in Minestom replaces and deprecates a lot of old functionality existing in Minestom. This section of the wiki will explain how to migrate your code to use the new Adventure API.

Boss Bar

The net.minestom.server.bossbar package has been entirely deprecated. To create a boss bar you should instead use the static builder methods in the Adventure BossBar class. For example, with the old API you might do:

With the Adventure API you would instead do:

As before, any changes made to the boss bar will be automatically propagated to all those who have been added to a boss bar.

Books

Sound

For example, in the old API you would use the following code:

With Adventure you would use the following code:

Additionally, you can now stop specific sounds constructing a SoundStop object and passing that to a player using Player#stopSound. This StopSound object can be used to stop all sounds, usingSoundStop#all(), in addition to specific sounds, using SoundStop#named(SoundEvent) or SoundStop#named(Key), or specific sounds in specific sources, using the previous methods with an additional Sound.Source argument.

Text

The biggest difference between the old chat API and Adventure is that in Adventure, chat components are immutable. This means that any methods used on components do not change the component and instead return a new component. This is explained more on the Adventure documentation.

The net.minestom.server.chat package has been entirely deprecated. To construct message you should instead use the Component class and its builder methods as discussed in the Adventure documentation. However, JsonMessage does implement the Adventure interface ComponentLike. This means that you can use JsonMessage and all its subtypes throughout the Adventure API within Minestom. You can also use JsonMessage#fromComponent(Component) to convert an Adventure component to a JsonMessage, allowing you to use new Adventure components with the old Minestom chat API.

Another difference between the old chat API and Adventure is that you cannot use colors inside a string to create messages. In the old API you could do ChatColor.RED + "some text". This is not possible with Adventure as it does not properly represent how text is stored in Minecraft. Instead, you can set the style of components using the methods found in the Component class, such as Component.text(String, TextColor), or by setting the style using the Style method.

Adventure also splits the old API's ChatColor class into classes for TextColor and TextDecoration. TextDecoration can also be negated, meaning you can remove styles from nested components whilst not impacting components that may follow this one. The old ChatColor class has been deprecated and replaced with new classes for Color and DyeColor across the Minestom codebase. Both of these implement RgbLike and can be used to color Adventure components.

Hover and click events can be added to any Component using .hoverEvent() and .clickEvent. Instead of using ChatHoverEvent.showItem(ItemStack) you can instead put an ItemStack directly into the argument of a hover event. For example, in the old chat API you would do:

However, with the Adventure API you can simply do:

Title

The methods used to send titles to players have been deprecated and replaced with Adventure methods. The multiple different messages have been replaced with the two Adventure methods #sendTitle(Title) and #showActionBar(Component).

For example, with the old API you would do:

However, with the Adventure API you would do:

Some things are needed before being able to connect to your Minestom server.

• Initialize the server

• Registering events/commands

• Start the server at the specified port and address

Here is a correct example:

However even after those steps, you will not be able to connect, what we miss here is an instance (the world)

Here is an example of a working Minestom server

Building the server JAR

Once you have created your Minestom server, you will probably want to build it and distribute it to a host or friend. To do so we will set up the Shadow plugin so that we can make a final working uber (fat) jar.

Side note: For Maven users, you will need the "Shade" plugin. If you use Maven and would like to contribute an example it would be appreciated :)

First, let's add the Shadow plugin to our project.

If the JAR is meant to be run, which it probably is, you also need to specify the class containing the main method like so,

With all of this done, all we need to do is run the shadowJar task to create a working uber (fat) jar! (The jar will be put in /build/libs/ by default)

Now, just to be sure that you understood everything, here is a complete build.gradle/build.gradle.kts file.

Overview

Event listening is a fairly hard part to keep easy while having a clear understanding of the execution flow. In Minestom, a tree is used to define inheritance for filtering and extensibility. Each node of the tree contains:

• Event class, where only subclasses are allowed to enter (Event/PlayerEvent/etc...)

• Condition for filtering

• List of listeners

• Name for identification

• Priority

The tree structure provides us many advantages:

• Context-aware listeners due to node filtering

• Clear execution order

• Ability to store the event tree as an image for documentation purpose

• Listener injection into existing nodes

API

Node

// Can listen to any Event, without any condition
EventNode<Event> node = EventNode.all("demo");
// Can only listen to entity events
EventNode<EntityEvent> entityNode = EventNode.type("entity-listener", EventFilter.ENTITY);
// Can only listen to player events
EventNode<PlayerEvent> playerNode = EventNode.type("player-listener", EventFilter.PLAYER);
// Listen to player events with the player in creative mode
EventNode<PlayerEvent> creativeNode = EventNode.value("creative-listener", EventFilter.PLAYER, Player::isCreative);

Each node needs a name to be debuggable and be retrieved later on, an EventFilter containing the event type target and a way to retrieve its actor (i.e. a Player from a PlayerEvent). All factory methods accept a predicate to provide an additional condition for filtering purposes.

Listener

EventNode<Event> node = EventNode.all("demo");
node.addListener(EntityTickEvent.class, event -> {
    // Inline listener
});
node.addListener(EventListener.builder(EntityTickEvent.class)
    .expireCount(50) // Stop after 50 executions
    .expireWhen(event -> event.getEntity().isGlowing()) // Stop once the predicate returns true
    .handler(entityTickEvent ->
        System.out.println("Entity tick!"))
    .build());

EventNode<PlayerEvent> playerNode = EventNode.type("player-listener", EventFilter.PLAYER);
// playerNode.addListener(EntityTickEvent.class, event -> {}); -> does not work as playerNode only accept player events
playerNode.addListener(PlayerTickEvent.class, event -> {});

Child

Children take the condition of their parent and are able to append to it.

EventNode<Event> node = EventNode.all("demo");
EventNode<PlayerEvent> playerNode = EventNode.type("player-listener", EventFilter.PLAYER);

node.addChild(playerNode); // Works as PlayerEvent is also an Event

// playerNode.addChild(node); -> Doesn't compile as the parent would be more restrictive than the child

Event execution

Events can be executed from anywhere, not only the root node.

EventNode<Event> node = EventNode.all("demo");
node.call(new MyEvent());

In practice

Now that you are familiar with the API, here is how you should use it inside your Minestom project.

Node to use

Server JAR

The root node of the server can be retrieved using MinecraftServer#getGlobalEventHandler(), you can safely insert new nodes.

var handler = MinecraftServer.getGlobalEventHandler();
handler.addListener(PlayerChatEvent.class,
        event -> event.getPlayer().sendMessage("You sent a message!"));
var node = EventNode.all("demo");
node.addListener(PlayerMoveEvent.class,
        event -> event.getPlayer().sendMessage("You moved!"));
handler.addChild(node);

Extensions

Extensions should use their defined node from Extension#getEventNode(), which is removed from the root node once unloaded. Listeners inserted to external nodes must be removed manually.

Structure

Having an image of your tree is highly recommended, for documentation purposes and ensuring an optimal filtering path. It is then possible to use packages for major nodes, and classes for minor filtering.

Server/
   Global.java
   Lobby/
      Rank/
         - AdminRank.java
         - VipRank.java
      - DefaultRank.java
   Game/
      Bedwars/
         Kit/
            PvpKit.java
            BuildKit.java
         Bedwars.java
      Skywars/
         Kit/
            PvpKit.java
            BuildKit.java
         Skywars.java

Custom event

Overview

Items in Minestom are immutables, meaning that an ItemStack cannot change after being built. This provides us many benefits:

• Thread safety, as you cannot change the same object from multiple threads.

• No side effects where a change to an item would modify all inventories where the same object is present.

• Reuse ItemStack in multiple places. For example, if all your players start with the same set of items, you could just store those as constants and add them to each player inventory to avoid a lot of allocation.

• Related to the second point, it allows us to internally cache items packet (eg: window packet) to keep improving performance

API

However, as items are immutable, creating complex objects require using a builder:

And some special methods have been made to modify an existing item easily:

Understanding what happens when an event is called or when a new node is added can help you to make better decisions, especially when desiring great performance.

Listener handle

A ListenerHandle represents a direct access to an event type listeners, they are stored inside the node and must be retrieved for the listeners to be executed

EventNode#call(Event) is as simple as retrieving the handle (through a map lookup) and executing ListenerHandle#call(Event). As you may have realize, you could completely avoid the map lookup by directly using the handle, hence why EventNode#getHandle(Class<Event>) exists!

Keeping the handle in a field instead of doing map lookups for every event call may also help the JIT to entirely avoid the event object allocation in case where there are no listener.

Registration

First and foremost, it is important to note that all registration (and methods touching the tree) are synchronized, it is not considered as a huge flaw since event calling is much more important. This however means that you should try to avoid temporary nodes/listeners as much as possible.

Event calling

Event calling is very simple to understand, it will first check if the listeners inside the handle are up-to-date (if not, loop through all of them to create the consumer) and run the said consumer.

It is the reason why you should avoid adding listeners other than in your server init, because it will invalidate the associated handles.

Conclusion

The event implementation has been heavily optimized for calling instead of utilities, which seems fair but must be well understood before attacking a high-performance server.

Overview

In Minestom all entities must extend Entity directly or from their subclasses. The Entity class mainly provides developers with a serverside API that doesn't have much of an effect on the client. Similarly to ItemStack there is a thing named EntityMeta that allows you to change what the client sees. This article will talk in detail about the implementations of EntityMeta.

Entity Classes

Entity creation starts with an entity class selection. Regardless of the type of entity being created, you can instantiate it as any of the following classes:

• Entity is the most barebones version of an entity. It provides you with a minimal API (and minimal overhead), including spawning packet handling, metadata support, default physics.

• LivingEntity extends Entity and also allows you to grant your entity liveliness. The type of entity doesn't matter, minestom doesn't restrict you to what Mojang intends. If you give it health, it will have health. This subclass also provides an API to modify the entity's equipment and attributes.

• EntityCreature extends LivingEntity and also provides you with the navigation and AI API.

If none of the above fits your requirements, you are free to use any of these classes as an ancestor for your own entity class implementation. It could be viable in cases when you need to handle physics or overwrite already presented methods. There are several examples in Minestom repository itself: Player that extends LivingEntity and handles equipment and a bunch of other things; EntityProjectile that extends Entity and has its own physics and collision code.

Examples

Barebones horse creation and spawn:

Creating a boat with liveness and the possibility to manipulate the AI and navigation. For example, we can add some goals to it to make it aggressive and attacking players.

Entity Meta

Once you have selected a class for an entity and instantiated it, you can retrieve it's metadata using Entity#getEntityMeta(). Casting this to the proper type, depending on the entity type you specified on instantiation, allows you to change the way your entity will be displayed on clients.

Examples

Setting color to a horse from the first example:

Making a boat look menacing:

Useful methods

Entity presence

Immediately after instantiation, an entity is not counted as active and is therefore not present in any of your instances. To actually spawn it you must call Entity#setInstance(Instance, Position).

There's also a handy Entity#setAutoViewable(boolean) that will automatically track whether this entity is in the viewable range of the players of the instance it's in and send spawn/destruction packets to them. All entities are auto-viewable by default.

To remove the entity simply call Entity#remove().

Switching entity type

There's a possibility for you as a developer to switch the entity type of an already existing entity. Such an action can be performed using Entity#switchEntityType(EntityType) and will nullify all the metadata the entity previously had.

If you're wondering how it works internally, a destruction packet is being sent to all the viewers of that entity, then a new spawn packet takes its place. If you're changing the entity type of a player, all viewers except for himself will receive those packets, so it's impossible to render the player on his own client with a different entity type.

Efficiently performing batch-update on metadata

There could be situations when you need to modify multiple attributes of EntityMeta at once. There is an issue here because every time you modify the meta, a packet is being sent to all its viewers. To reduce network bandwidth and send all updates at once there is a EntityMeta#setNotifyAboutChanges(boolean) method. Call it with false before your first metadata update and then with true right after the last one: all performed changes will be sent at once. If you need more on this subject, look into the associated method documentation: it's rich.

For example, we can take the code that updates boat metadata: if we execute it after a boat has been spawned, it will result in 3 metadata packets being sent to each of the boat's viewers. To avoid this, all we need is to add two simple lines:

-> Microtus is a framework or literally a "construction kit", without any vanilla logic!

Why Microtus ?

Microtus has the ability to accommodate hundreds or thousands of players with little memory. It is also possible to achieve the result faster without a lot of cancellation logic. Everything that is known as NMS under Paper/Spigot is supplied as an interface with Microtus. Microtus is changing core elements to absorb unexpected behaviour in a more effective way to improve the developer experience and framework usability.

Minestom decided some time ago to add functions such as

• Terminal

• Extensions

• (TinyLog)

to be removed for various reasons

Microtus and the team behind it believe that a terminal and extensions is a very good combination for a plugin-in hybrid system to speed up update cycles or development cycles.

In addition, we believe that it is a lesser evil to leak a partial component on the internet than a large jar file containing all dependencies or internal libs.

TL;DR

We have reinstalled the above features and give full flexibility to the developers and re-document code from upstream or improve it.

Our goals

Our aim is to bring Microtus closer to the concept of stability, maintainability, and modularity. Since many people see such terms as being empty words, I have described it as a concept.

Minestom provides the ability to customise responses to five different server list ping types all in one place. Put simply, to listen to every type of server list ping event you just need to listen to the ServerListPingEvent and modify the ResponseData in the event. Regardless of the source of the ping, the response data will be formatted in the correct way for the corrosponding source.

Ping types

The different types of pings can be found in the ServerListPingType enum. The type can be obtained from the ServerListPingEvent using the getPingType() method. This allows you to change your responses based on the incoming ping, allowing you to only fill in the information that is needed or customise the response based on the type of ping.

The different types of pings that are responded to with the ServerListPingEvent can be broken down into three different categories.

Modern

Covered by the MODERN_FULL_RGB and MODERN_NAMED_COLORS constants, this category represents the most common type of response and is used on Minecraft versions 1.7 and higher. This includes the name, protocol, version, description, favicon, number of players online, max number of players online and a sample of the online players.

The description supports color and styles in addition to some more complex component types. Minecraft versions on 1.16 or higher can utilise full RGB color codes. For older versions, the colors are downsampled into named colors automatically.

The player sample is represented as a list of UUID to name mappings and do not have to be players that are on the server. The NamedAndIdentified interface is used to hold this mapping and allow both players and custom mappings to be used interchangeably in the ResponseData class. For an example on how to use this interface, see the code block below.

The methods that do not take a UUID will use a random UUID, allowing you to create any number of players without the risk of a conflicting UUID being used. Additionally, each entry can use components or strings. Using components allows you to use colour and styling for each entry. The player list displayed in the vanilla Minecraft client supports the legacy section sign color coding and the names of each entry are automatically converted to this format.

In the modern category, the player sample, along with the online and maximum players, may be hidden completely as well:

In the Vanilla client, the online / maximum player count will be replaced with ???

Legacy

Covered by the LEGACY_VERSIONED and LEGACY_UNVERSIONED constants, this category represents server list pings that are sent by clients on version 1.6 or lower. These ping types only support the description and the current/max number of players. The LEGACY_VERSIONED type additionally supports the version of the server.

The description is formatted using legacy section sign color coding and is automatically converted to this format.

Open to LAN

Covered by the OPEN_TO_LAN constant, this category represents server list pings that are sent from the server when it is mimicking being a single player world that is opened to LAN. This type only supports the description. As with the legacy type, the description is formatted using legacy section sign color coding and is automatically converted to this format.

Ping

After receiving the server list ping response, modern clients send an additional packet intended to calculate latency. Minestom provides the ClientPingServerEvent for this.

The event may be cancelled, in which case a response packet will not be sent. However, various delay methods can affect the apparant latency:

Finally, just as the ServerListPingEvent, the underlying PlayerConnection is accessible.

Overview

Entity AI is done by giving an entity an ordered list of goals to do if a condition is validated. Once an action is found, the entity will be affected by it until asked to stop.

For example, a very simple aggressive creature could have:

1. Attack target

2. Walk randomly around

3. Do nothing

Every tick, the entity will find the goal to follow based on its priority. If the entity has a target the first goal will be used, and the rest be ignored.

Groups

You might find yourself wanting to have multiple goals being executed at the same time. For example, having an entity attacking its target while swimming to avoid dying. This is done by adding multiple EntityAIGroup to the entity, each group contains a list of goals to be executed independently.

Example

In this example, instances of ZombieCreature will attack nearby players or walk around based on if a player is nearby.

As UUID implies, it has to be a unique identifier. By default, this identifier is generated randomly at the connection so unique but not persistent.

What you normally want is a unique identifier that will stay the same even after a disconnection or a server shutdown, which could be obtained by getting the Mojang UUID of the player using their API, or having your custom UUID linked to the registration system on your website, we do not implement that by default so you are free to choose what you prefer.

Here how to register your own UUID provider:

connectionManager.setUuidProvider((playerConnection, username) -> {
   // This method will be called at players connection to set their UUID
   return UUID.randomUUID(); /* Set here your custom UUID registration system */
});

A Scheduler is an object able to schedule tasks based on a condition (time, tick rate, future, etc...) with a precision linked to its ticking rate. It is therefore important to remember that Minestom scheduling API does not aim to replace JDK's executor services which should still be used if you do not need our scheduling guarantee (execution in the caller thread, execution based on tick, less overhead).

Those tasks scheduling can be configured using a TaskSchedule object, defining when the task is supposed to execute.

Scheduler scheduler = MinecraftServer.getSchedulerManager();
scheduler.scheduleNextTick(() -> System.out.println("Hey!"));
scheduler.submitTask(() -> {
    System.out.println("Running directly and then every second!");
    return TaskSchedule.seconds(1);
});

Tasks are by default executed synchronously (in the object ticking thread). Async execution is possible, but you may consider using a third party solution.

Scheduling will give you a Task object, giving you an overview of the task state, and allow some modification such as cancelling.

Scheduler scheduler = player.scheduler();
Task task = scheduler.scheduleNextTick(() -> System.out.println("Hey!"));
task.cancel();

Overview

A Tag represents a key, and a way to read/write a specific type of data. Generally exposed as a constant, you can use it to apply or read data from any TagReadable (e.g. Entity, ItemStack, and soon Block). They are implemented using NBT, meaning that applying a tag to an ItemStack will modify its NBT, same for Block, and can therefore be sent to the client.

Tag<String> myTag = Tag.String("key");
Entity entity = ...;
String data = entity.getTag(myTag);

Tags benefit are:

• Control writability and readability independently with TagReadable/TagWritable, ideal for immutable classes.

• Hidden conversion complexity, your code should not have to worry about how a List<ItemStack> is serialized.

• Automatic serialization support (as backed by NBT), easing data persistence and debuggability.

API

First of all, it is recommenced to expose Tags as contant and reused. All Tag methods should be pure, and allow to specify additional information to handle the data.

All tags are available as static factory methods inside the Tag class.

Map

Tag mapping allows you to transform the retrieved value.

Tag<String> stringTag = Tag.String("my-string");
// You should also ensure that the string is a valid uuid!
Tag<UUID> mappedTag = stringTag.map(UUID::fromString, UUID::toString);
UUID uuid = instance.getTag(mappedTag);

Default value

Tag<String> stringTag = Tag.String("my-string");
instance.getTag(stringTag.defaultValue("default"))

TagSerializer

TagSerializer is similar to the #map method, except that you can interact with multiple tags.

Structure

A structure tag is a wrapper around an nbt compound (map) independent from all the other tags.

View

A view can access every tag and is therefore mostly unsafe, should only be used at last resort.

There are three ways of defining a player skin:

• Changing it in the PlayerSkinInitEvent event

• Using the method Player#setSkin(PlayerSkin)

How to retrieve skin data from Mojang

Using PlayerSkin methods

PlayerSkin offers some utils methods to retrieve a skin using simple information such as a Mojang UUID or a Minecraft username

PlayerSkin skinFromUUID = PlayerSkin.fromUuid(MOJANG_UUID_AS_STRING);

PlayerSkin skinFromUsername = PlayerSkin.fromUsername("Notch");

Retrieve texture value & signature manually

You firstly need to get your Mojang UUID, which can be done by a request based on your username:

 GET https://api.mojang.com/users/profiles/minecraft/<username>

Then, after getting your UUID:

 GET https://sessionserver.mojang.com/session/minecraft/profile/<uuid>?unsigned=false

You'll get here both the texture value and the signature. Those values are used to create a PlayerSkin.

PlayerSkinInitEvent

The event is called at the player connection and is used to define the skin to send to the player the first time. It is as simple as

GlobalEventHandler globalEventHandler = MinecraftServer.getGlobalEventHandler();
globalEventHandler.addListener(PlayerSkinInitEvent.class, event -> {
   PlayerSkin skin = new PlayerSkin(textureValue, signature);
   event.setSkin(skin);
});

Player#setSkin

PlayerSkin skin = new PlayerSkin(textureValue, signature);
player.setSkin(skin);

Permissions are the feature allowing you to determine if a player is able to perform an action or not.

A permission contains 2 things, a unique name (same as with Bukkit if you are familiar with it), and an optional NBTCompound which can be used to add additional data to the permission (no more "my.permission.X" where X represents a number).

Handling permission access

In order to add a permission to a PermissionHandler you should use PermissionHandler#addPermission(Permission).

To remove a permission, PermissionHandler#removePermission(Permission) and PermissionHandler#removePermission(String) are available.

Checking permissions

To verify if a PermissionHandler has a permission, you have the choice between simply checking if the handler has a permission with the same name, or verifying that the handler has both the permission name and the right data associated with it.

To check if the handler has a permission with a specific name, PermissionHandler#hasPermission(String) should be used. If you want to verify that the handler has the right NBT data PermissionHandler#hasPermission(String, PermissionVerifier) is the right choice.

Alternatively, PermissionHandler#hasPermission(Permission) can be used. It does require both the permission name and the data to be equal.

Adding permissions to players and checking them

In order to add a permission to a player, you will have to call the Player#addPermission(Permission) function, an example of proper usage would be

player.addPermission(new Permission("operator"));

If you want to check, if a player has a permission, you can use the Player#hasPermission(Permission) function, here is an example of checking for a permission inside of a command:

public class StopCommand extends Command {
    public StopCommand() {
        super("stop");
        setCondition((sender, commandString) -> sender.hasPermission(new Permission("operator"));
        setDefaultExecutor((sender, context) -> MinecraftServer.stopCleanly());
    }
}

Permission wildcard matching

Minestom supports wildcard matching for permissions. This means that if a player has a permission like admin.*, this will satisfy any checks for permissions that have the same format, with differing contents for the wildcard. e.g. admin.tp will return true.

Example:

player.addPermission(new Permission("command.*")); // Gives the player every permission with the 'command.' prefix

player.hasPermission(new Permission("command.gamemode")); // This returns true

// Same thing goes for
player.addPermission(new Permission("*")); // Gives the player every permission

player.hasPermission(new Permission("user.chat")); // returns true
player.hasPermission(new Permission("3i359cvjm.sdfk239c")); // returns true

Permission serialisation

Nothing is automatically saved persistently in Minestom, permissions are not an exception.

Permissions must be serialized and deserialized back manually if you want such a feature. You are lucky since the Permission class can easily be interpreted as 2 strings, one being the permission name, and the second representing the optional data using NBTCompound#toSNBT() (and deserialized with SNBTParser#parse()).

Commands are the main communication between the server and the players. In contrary to current alternatives, Minestom takes full advantage of auto-completion/suggestion and has therefore a fairly strict API.

Overview

All auto-completable commands should extend Command, each command is composed of zero or multiple syntaxes, and each syntax is composed of one or more arguments.

If you find it confusing, here are a few examples:

/health // This is a command
/health set 50; // This is a command and its syntax
set // This is a literal argument
~ ~ ~ // This is a position argument  

Create your first command

First of all, create your command class!

package demo.commands;

import net.minestom.server.command.builder.Command;

public class TestCommand extends Command {

    public TestCommand() {
        super("my-command", "hey");
        // "my-command" is the main name of the command
        // "hey" is an alias, you can have an unlimited number of those
    }
}

After this is done, you need to register the command.

MinecraftServer.getCommandManager().register(new TestCommand());

Nothing crazy so far, let's create a callback once the command is run without any argument and another for our custom syntax.

package demo.commands;

import net.minestom.server.command.builder.Command;
import net.minestom.server.command.builder.arguments.ArgumentType;

public class TestCommand extends Command {

    public TestCommand() {
        super("command", "alias");

        // Executed if no other executor can be used
        setDefaultExecutor((sender, context) -> {
            sender.sendMessage("You executed the command");
        });

        // All default arguments are available in the ArgumentType class
        // Each argument has an identifier which should be unique. It is used internally to create the nodes
        var numberArgument = ArgumentType.Integer("my-number");

        // Finally, create the syntax with the callback, and an infinite number of arguments
        addSyntax((sender, context) -> {
            final int number = context.get(numberArgument);
            sender.sendMessage("You typed the number " + number);
        }, numberArgument);

    }
}

Argument callback

Let's say you have the command "/set <number>" and the player types "/set text", you would probably like to warn the player that the argument requires a number and not text. This is where argument callbacks come in!

When the command parser detects a wrongly typed argument, it will first check if the given argument has an error callback to execute, if not, the default executor is used.

Here an example checking the correctness of an integer argument:

package demo.commands;

import net.minestom.server.command.builder.Command;
import net.minestom.server.command.builder.arguments.ArgumentType;

public class TestCommand extends Command {

    public TestCommand() {
        super("command");

        setDefaultExecutor((sender, context) -> {
            sender.sendMessage("Usage: /command <number>");
        });

        var numberArgument = ArgumentType.Integer("my-number");

        // Callback executed if the argument has been wrongly used
        numberArgument.setCallback((sender, exception) -> {
            final String input = exception.getInput();
            sender.sendMessage("The number " + input + " is invalid!");
        });

        addSyntax((sender, context) -> {
            final int number = context.get(numberArgument);
            sender.sendMessage("You typed the number " + number);
        }, numberArgument);

    }
}

Command data

One of the very important features of the command API is the fact that every syntax can return optional data. This data is presented in a structure similar to a Map (in fact, it is only a small wrapper around it).

addSyntax((sender, context) -> {
    final int number = context.get("number");
    sender.sendMessage("You typed the number " + number);

    // Put the argument data into the returned command data
    context.setReturnData(new CommandData().set("value", number));
}, Integer("number"));

The data will be created and returned every time the syntax is called. It can then be retrieved from the CommandResult. CommandManager#executeServerCommand(String) allows you to execute a command as a ServerSender (which has the benefit of not printing anything on CommandSender#sendMessage(String), and permit to differentiate this sender from a player or the console).

CommandResult result = MinecraftServer.getCommandManager().executeServerCommand("command 5");
if (result.getType() == CommandResult.Type.SUCCESS) {
    final CommandData data = result.getCommandData();
    if (data != null && data.has("value")) {
        System.out.println("The command gave us the value " + data.get("value"));
    } else {
        System.out.println("The command didn't give us any value!");
    }
} else {
    System.out.println("The command didn't work out!");
}

This tool opens a lot of possibilities, including powerful scripts, remote calls, and an overall easy-to-use interface for all your APIs.

Inventories take a large place in Minecraft, they are used both for items storage and client<->server communication.

In order to create one, you can simply call its constructor by specifying an InventoryType and its name

// Create the inventory
Inventory inventory = new Inventory(InventoryType.CHEST_1_ROW, "The inventory name");

// Open the inventory for the player 
// (Opening the same inventory for multiple players would result in a shared interface)
player.openInventory(inventory);

// Close the current player inventory
player.closeInventory();

Sometimes you will want to add callbacks to your inventory actions (clicks). There are currently 3 ways of interacting with them.

Adding an inventory condition

Inventory conditions are specific to only one inventory. You are able to cancel the interaction by using InventoryConditionResult#setCancel

inventory.addInventoryCondition((player, slot, clickType, inventoryConditionResult) -> {
   player.sendMessage("click type inventory: " + clickType);
   System.out.println("slot inv: " + slot);
   inventoryConditionResult.setCancel(false);
});

Really similar to inventory conditions except that it listens to every inventory (you can obviously add checks when needed, but its goal is to be more "general")

This event only listens to successful actions (not canceled) and is fired after setting the items in the inventory.

The inside

I will begin by saying that you do not need to know anything written here to utilize the acquirable API. It can however teach you about our code structure and how it achieves thread-safety. Be sure to read all the previous pages in order to properly understand everything said here.

Tick architecture

Ticks are separated in multiple batches. After those are created, every batch gets assigned to a thread from the ThreadDispatcher thread pool.

Threads are assigned depending on the ThreadProvider, a single thread is used by default.

After all this, threads start and the UpdateManager will wait until all of them are done. The cycle continues until the server stops.

Object acquisition

After a batch gets assigned to a thread, the same happens to every element added to it. Meaning that each entity knows in which thread it will be ticked before it even happens!

What advantage does it have? It allows us to know if the object in question can be safely accessed! When you execute Acquirable#acquire, it will first check if the current thread is the same as the one where the object to acquire will be ticked, meaning no synchronization required, the overhead in this case is a simple Thread#currentThread call.

This is obviously the best scenario but it does not always happen, how does the system react if the two threads are different? Well firstly it will signal to the object's thread that an acquisition needs to happen and then block the current thread, and secondly, it will wait for the signaled thread to handle the acquisition. Acquisition signals are checked at the start of every entity tick, and at the end of the thread tick execution.

During acquisition handling, the thread is blocked until all of them are processed and can then continue its execution safely.

Conclusion

Nothing is magical, and this API is not an exception. It has the potential to make your application faster when acquisitions are controlled (to limit synchronization) and with a ThreadProvider specific to your need. If you want to have one world per player, then using one batch per Instance is probably the best solution. If you have a very precise pattern where every 3 chunks are completely independent of each other, manage your batches in this direction!

Overview

Setup

To start the query system, simply run one of the start methods in the Query class. If the query port isn't already open, it will start listening for queries on the specified port.

To stop the query system, you can call the stop method.

Modifying responses

By default, this system will act as close to Vanilla and other server implementation's responses as possible. This includes filling in the plugin system with information about the currently installed extensions.

If you wish to customise the responses, you can listen to the two query events that are called when each response is being created. Both of these events allow you to access the SocketAddress of the sender in addition to the session ID that they initiated the request with. This information can be used to identify who is sending a request. Additionally, each event is cancellable, meaning that if you don't want to send a response you can simply cancel the event. This is a powerful system that enables you to keep a query system open for obtaining arbitrary information from your server without letting everybody access the query system.

Basic queries

The BasicQueryEvent is called when the requester is asking for basic information about the server. This event uses the BasicQueryResponse class to write a fixed set of data, each of which needs to be filled in so that responses can be parsed correctly.

Full queries

The FullQueryEvent is called when the requester is asking for full information about the server. This event uses the FullQueryResponse class to write an arbitrary set of data in a key-value format in addition to a list of online players. There are some keys that should be filled in as standard. These are set by default and can be edited using the put method that accepts a QueryKey, this being an enum containing the default key-value mappings. Other arbitrary mappings can be inserted using the other put method.

By sending a series of packets to a multicast address, Minestom provides the ability to mimic being a single player world that is opened to LAN. This will make it show up in the server list of all open Minecraft instances running in your local network below the "Scanning for games on your local network" section.

This does not actually open the server to anywhere other than your local network and it not a replacement for port forwarding or a proper network setup. It is mainly designed as a fun feature that can be useful during testing if you're spinning up a dynamic amount of servers and don't want to manually connect to each one of them.

Setup

To start sending the required packets, you can simply run OpenToLAN.open() anywhere. This will send the ping every 1.5 seconds and call the ServerListPingEvent with the OPEN_TO_LAN ping type for each outgoing ping.

To modify how often the event is called and the pings are sent, pass in a OpenToLANConfig in the open method. This is a simple builder-style class which lets you configure various elements of the system.

Modifying the description

Introduction

Minecraft maps usually hold a 128x128 image representing an aerial view of an area. This is done by saving a 128x128 image inside the map data and rendering it.

The thing is... the server decides the contents, and there is no requirement to show an aerial view. This means that maps can serve as arbitrary 128x128 textures which can then be used for custom blocks, graphics and more.

Writing map data - Low level API

Minestom does not save map data for you, but it will send it for you. At the most basic level, map framebuffers (the 128x128 pixel area the server draws on) hold the 1-byte indices of colors in a pre-determined color palette, but not RGB.

• mapId is an int to be able to reference which map to change.

• data is a byte[] array which holds the indices inside the color palette. Its size should be at least rows*columns.

• x is an unsigned byte (stored inside a short) which represents the X coordinate of the left-most pixel to write. Ranges from 0 to 127 (inclusive).

• y is an unsigned byte (stored inside a short) which represents the Y coordinate of the top-most pixel to write. Ranges from 0 to 127 (inclusive).

• rows is an unsigned byte (stored inside a short) which represents the number of rows to update.

• columns is an unsigned byte (stored inside a short) which represents the number of columns to update.

Pixels are stored in a row-major configuration (ie index is defined by x+width*y). Attempting to write pixels outside of the 128x128 area WILL crash and/or disconnect the client, so be careful. Minestom does not check which area you are writing to.

You can then send the packet to players through PlayerConnection#sendPacket(ServerPacket)

Framebuffers - High level API

While directly writing to the pixel buffer is fast and easy for simple graphics, it is rapidly cumbersome to write each pixel individually. For this reason, Minestom provides framebuffers: a high-level API for rendering onto maps.

Framebuffers are split into 2 categories: Framebuffer and LargeFramebuffer. The difference is that Framebuffer is meant to render to a single map (so resolution limited to 128x128), while LargeFramebuffer can render to any framebuffer size, by rendering over multiple maps. Large framebuffers offer a method to create Framebuffer views to help with rendering onto a map.

Once you have finished rendering on your framebuffer, you can ask it to prepare the MapDataPacket for you.

Framebuffers have 3 default flavors provided by Minestom: Direct, Graphics2D and GLFW-Capable.

DirectFramebuffer / LargeDirectFramebuffer

Direct framebuffers are very close to writing directly the pixel buffer inside MapDataPacket. They hold an internal byte[] representing the colors on the map, which can be accessed and modified through get and set respectively. The entire internal buffer is also exposed via getColors() (you can modify it from the returned value).

Example use:

Graphics2DFramebuffer / LargeGraphics2DFramebuffer

These framebuffers require a conversion from RGB to MapColors. This is done automatically by Minestom but can seriously impact rendering performance when the resolution increases.

As the name suggests, these framebuffers allow usage of the Graphics2D API from the AWT library included in the Java standard library. Access the Graphics2D object through getRenderer() and render your content on it.

Example use:

Graphics2D framebuffers also support getting/setting pixels individually if necessary.

GLFW-Capable buffers

First of all, this page's goal is to only be an overview of how to achieve thread-safety. The reader will be provided with keywords for further documentation, but the document here should be enough to understand everything that follows.

As for its usage in Minestom, you do not have to remember everything you will read here. But it will teach you good practice and allow you to understand the internals to make better decisions.

What is thread-safety?

A code is called "thread-safe" if and only if this code can be called from multiple threads without unexpected behavior. Therefore the term does not say anything about performance or design, it is simply a way to denote how the code can be accessed.

What does it cost?

Transforming a single-threaded code to a multi-threaded one is not as easy as creating multiple threads. The main issue you will encounter is about memory visibility, you can imagine that 2 threads cannot access the same variable in memory at the exact same time without any drawback. Synchronization requires having the thread check if it has the right to access the X method and has therefore a cost, mostly in the order of nano or microseconds, but could lead to an unusable program if too repetitive. Common issues in multithreaded applications are:

1. Race-condition: when the same method is called by two threads at the same time, which generally lead to undebuggable issues

2. Deadlock: when two locks are waiting for each other, meaning that those will never be freed

What to use?

A lot of tools/features exist to make developing thread-safe and efficient code easier.

Fields

Fields need to have some sort of synchronization mechanism. The JVM comes with the volatile access flag which forces the field to be always on the main memory instead of in the cache (with some other details that I will not describe) so every thread reads the value from the exact same place. Depending on your application, a ThreadLocal<T> object could be enough, you could think of it as a Map<Thread, T> where Thread is always the current thread. The easiest way to make a field thread-safe is to make it immutable with the final keyword, if you cannot change a field, you do not risk multiple threads to change it at the same time.

Methods

Additionally to the fields, you need to way to manage your flow control so two methods are not called at the exact time which is likely to break every non-thread-safe program (race-condition). Thread synchronization happens thanks to the help of locks, those are mechanisms that will make the current thread waits until someone tells him that he can now open the door and close behind him.

GLFW capable framebuffers require access to an API supported by GLFW: OpenGL, OpenGL ES, Vulkan, or EGL. Software-based drivers should work out-of-box but no guarantee.

These framebuffers can require conversion from RGB to MapColors, but options are provided to accelerate the process, see the end of the article (Color Mapping).

GLFW (and its LWJGL bindings) provide access to a window onto which a program can render. By making the window invisible, it is possible to render to an offscreen buffer, grab its contents and send it as a map.

Setup

Start by creating a GLFWFramebuffer or a LargeGLFWFramebuffer.

You must be aware that this creates a new GLFW context and a new window. It is possible to change the used API via an overloaded constructor in both GLFWFramebuffer and LargeGLFWFramebuffer. It defaults to OpenGL, and creation via native API (OSMesa is an option via LWJGL).

Instantaneous rendering

This type of rendering should be done if you plan on rarely updating the map.

Start by calling GLFWCapableBuffer#changeRenderingThreadToCurrent() to bind the rendering context to the current thread. Then call GLFWCapableBuffer#render(Runnable) to render your content. This will call the Runnable argument, swap the invisible window buffer, extract the framebuffer pixels and convert to map colors. The map colors are available via Framebuffer#toMapColors() if you do not use Framebuffer#preparePacket. Using render is highly recommended to ensure Minestom grab the contents of the framebuffer and converts the pixels to map colors.

Continuous rendering

In the case that you want to render continuously, it is advised to use setupRenderLoop(long period, TimeUnit unit, Runnable renderCode).

• period is a long, representing the period between two render calls. Expressed in unit units.

• unit unit in which the period is expressed

• renderCode your render code.

This sets up a repeating task through the SchedulerManager to automatically render contents every period. It also binds to the correct thread before rendering for the first time.

Color mapping

Maps do not use RGB, but an index into a color palette. By default, Minestom will convert the RGB pixels from the framebuffer on the CPU after each rendering. While this works and gives appreciable results, this conversion is not done in parallel, and the higher the resolution, the longer it takes.

Although Graphics2D framebuffers are not able to accelerate this process, GLFW capable buffers provide a way to quickly convert. There are two ways of doing this conversion.

Manual conversion

Calling GLFWCapableBuffer#useMapColors() will tell the framebuffer that you are not rendering with RGB directly, but with map colors. The map color is in this case encoded in the RED channel of the framebuffer. When grabbing the pixels from the framebuffer for processing, Minestom will only query the red channel and interpret the red intensity as the index inside the color palette. If you want to use this mode manually, you can always convert a color index to a color intensity by simply dividing the index by 255f.

Automatic/Post-processing conversion

Requires to use OpenGL or OpenGL-ES that understand OpenGL calls

You probably need modern OpenGL code for this to work, but you should be using modern OpenGL code in $currentYear anyway.

Adapting existing code, or thinking in map colors is not particularly convenient for complex/big/massive projects. For this reason, Minestom provides a post-processing shader that automatically converts from RGB to map colors for you. Enter MapColorRenderer.

Example code to set it up:

As you can see, this requires only one more line to initialize the map color auto-conversion and modifying one line to use it.

Required files for this to work (all inside classpath, src/something/resources during dev). All already inside Minestom LWJGL code:

• /shaders/mapcolorconvert.vertex.glsl a simple vertex shader to render a full-screen quad

• /shaders/mapcolorconvert.fragment.glsl fragment shader responsible for converting RGB to map colors

• /textures/palette.png the color palette used by maps. Can be autogenerated via net.minestom.server.map.PaletteGenerator, outputs to src/lwjgl/resources/textures/palette.png.

This renderer works by rendering your content inside an OpenGL framebuffer for more control over the framebuffer format. By default, RGBA color texture, Depth 24 bits, and Stencil 8 bits render buffer), and then rendering a full-screen quad (with texture unit 0 containing your color result and texture unit 1 containing the palette) with the mapcolorconvert shader.

What is an instance

Instances are what replace "worlds" from Minecraft vanilla, those are lightweight and should offer similar properties. There are multiple instances implementation, currently InstanceContainer and SharedInstance (both are explained below)

All instances can be accessed by using the InstanceManager or by getting an entity instance

Internally, the default Instance class have its own sets to store the entities in it, but all chunk based methods are abstract and meant to be implemented by a sub-class

InstanceContainer

"Container" here means that this is an instance that can store chunks. And as every instance, have its own sets of entities

You can create an InstanceContainer by calling:

SharedInstance

A SharedInstance needs to have an InstanceContainer linked to it. The "Shared" means that this is an instance that takes all of its chunks from its parent instance container

What does it mean? That if you break or place a block to the instance container, the shared instance will also reflect the change (same if you place a block using the shared instance methods, changes will be reflected in the instance container and all of its shared instances)

You can create a SharedInstance using:

Create your own Instance type

You are able to create your own class extending Instance and add entities to it.

In this case, the only thing you need to be aware of is that all instances need to be registered manually in the instance manager.

This method is ONLY required if you instantiate your instance object manually, InstanceManager#createInstanceContainer and InstanceManager#createSharedInstance already register the instance internally.

Presentation

Acquirable<T> represents an object of type T that you can retrieve but where its thread-safe access is not certain.

To give an example, imagine two entities very far from each other and therefore ticked in different threads. Let's imagine that entity A wants to trade items with entity B, it is something that would require synchronization to ensure that the trade happens successfully. From entity A's thread, you can retrieve a Acquirable<Entity> containing entity B, and from there acquire it to have safe access to the entity in a different thread.

The API provides multiple benefits:

• Thread-safety with synchronous code

• Same code whether you use one thread per chunk or a single for the whole server

• Better control over your data to identify bottlenecks

Here how the acquirable API looks in practice:

Acquirable#acquire will block the current thread until acquirableEntity becomes accessible, and execute the consumer in the same thread once it is the case.

It is important to understand that the consumer is called in the same thread, it is the whole magic of the Acquirable API, your code stays the exact same.

The entity object from the consumer should however only be used inside of the consumer. Meaning that if you need to save the entity somewhere for further processing, you shall use the acquirable object instead of the acquired one.

Now, if you do not need the acquisition to happen synchronously you have the choice to create the request and handle it later on (at the end of the tick), for this you simply need to "schedule" the acquisition.

Will print you:

And a few other options:

Acquirable Collections

Let's say you have a AcquirableCollection<Player> and you want to access safely all of the players it contains. You have multiple solutions, each having pros & cons.

Naive loop

The one that you probably have in mind is:

It does work, but not efficient at all since you have to acquire each element one by one.

AcquirableCollection#forEachSync

It is the most efficient way to loop through a collection, the callback is executed for each individual element and stops only once all elements have been acquired.

It is the most used one, simply because it doesn't create as much overhead as the previous ones. The element in the consumer is released directly without having to wait for the others.

Access the acquirable object without acquiring it

I can understand that having callbacks everywhere even if you know what you are doing is not ideal. You also have the choice to directly unwrap the acquirable object to retrieve the value inside.

A similar method exists for collections.

I would personally recommend commenting everywhere you use those unsafe methods to indicate why this operation does not compromise the application's safety. If you cannot find any reason, you likely shouldn't.

Access all the entities in the current thread

What type to request and return in methods

You have obviously the right to do what you prefer. But as a general rule, you should return Acquirable<T> objects and request for T.

The reason behind this choice is that you are sure (unless unsafe methods are used) that you will have safe access to the given parameter, but that you do not know what the user will want to do with it once you return.

Loading a world using AnvilLoader

In order to load a world into an instance, use the InstanceContainer#setChunkLoader(IChunkLoader) function.

An example of using this method to load a world is:

This will load the world inside of the worlds/world directory into the InstanceContainer, allowing you to use the instance as before but having the world loaded inside.

In order to load a world, the world folder will only need the /region folder, as it contains the block data.

Saving a world

In order to save a world, you will have to use the InstanceContainer#saveChunksToStorage() function, this will only work if you have previously loaded a world into the instance using AnvilLoader.

Load/Save Steps

When trying to load a chunk, the instance container does multiple checks in this order:

1. Verify if the chunk is already loaded (stop here if yes)

3. Create a new chunk and execute the instance ChunkGenerator (if any) to it to generate all of the chunk's blocks.

Default behavior

AnvilLoader is the default chunk loader used by all InstanceContainer

Create your own chunk type

Making your own chunk implementation allows you to customize how you want blocks to be stored, how you want chunks tick to happen, etc...

How to make my instance use my implementation

It will be called when a chunk object needs to be provided.

The advancement API is based around AdvancementTabs which represent a tree of Advancements for one or more players. Each player viewing a single AdvancementTab will see the same progress as all of the others. If per player Advancements are needed, individual AdvancementTabs will need to be created.

Advancements represent a completable advancement in an AdvancementTab.

AdvancementTab

AdvancementTabs can be created and retrieved from the AdvancementManager.

Namespaced IDs follow the format of namespace:id, and may not have any upper case letters.

An AdvancementRoot is the origin Advancement for a tab, and has the same creation method as a regular Advancement (see below) with the exception of the background. A background is a reference to a texture file on the client, for example minecraft:textures/block/stone.png for stone block.

Once created, an AdvancementTab may be added and removed from players as follows:

Advancement

Advancements can be created with their constructor and added to an AdvancementTab with an associated parent.

The parent of an Advancement may not be null, and it must have been added to the tab already. The AdvancementRoot is a valid parent.

Once an Advancement is registered, it can be completed.

To make an advancement show a toast, use Advancement#showToast(Boolean) before setting it to achieved.

Overview

A Block is an immutable object containing:

• Namespace & protocol id

• Map<String, String> containing properties (e.g. waterlogged)

• State id which is the numerical id defining the block visual used in chunk packets and a few others

• Optional nbt

• A BlockHandler

The immutability allows block references to be cached and reused.

Usage

Registry

Each block has unique data which can be retrieved with Block#registry().

Tags

Tags data can be serialized and will be saved on disk automatically.

Handlers

The BlockHandler interface allows blocks to have behavior by listening to some events like placement or interaction. And can be serialized to disk thanks to their namespace.

You can then decide to use one handler per block, or share it with several.

When manipulating a lot of blocks, it is wiser to make use of a Batch to update all of the chunks at once. There are 3 types of batches: ChunkBatch, AbsoluteBlockBatch, RelativeBlockBatch.

All batches have a similar set of methods to set blocks, however the coordinate systems are not all the same. See the individual batch for specifics.

Batch#setBlockStateId(int /* x */, int /* y */, int /* z */, short /* block id */, Data);
Batch#setCustomBlock(int /* x */, int /* y */, int /* z */, short /* custom block id */, Data);
Batch#setSeparateBlocks(int /* x */, int /* y */, int /* z */, short /* block id */, short /* custom block id */, Data);

Applying a batch can be always done with Batch#apply(Instance, Callback). This will apply the batch in the "default" position (dependent on the batch). See the individual apply variants on each batch for alternative application options.

BatchOption provides some configuration related to how the batch will behave. The options are:

• Full Chunk: If set, every chunk modified by this batch will assume that the batch is responsible

  for the entire chunk, so any existing blocks will be removed.

• Calculate Inverse: If set, the apply methods will return an inverse of the batch. See Inverses below.

• Unsafe Apply: If set, the batch will not wait for itself to be ready when applying. See Inverses below.

Each batch fits a different use case, however it is wise to use the most specific batch possible for the use case. For example, setting a set of blocks all inside one chunk can be done with all 3 batches. It should, however, be done with a ChunkBatch because it is the most efficient of the 3.

ChunkBatch

Contains changes completely contained within 1 chunk, the changes can be applied to any chunk.

Coordinates are given in relative chunk coordinates (ie 0-15), not world coordinates.

The default apply location is chunk (0, 0), however it may be applied to any chunk.

ChunkBatch#apply(Instance, int /* chunkX */, int /* chunkZ */, ChunkCallback);
ChunkBatch#apply(Instance, Chunk, ChunkCallback);

// For example
// Will apply at chunk 1, 2 (ie block 16, 32)
chunkBatch.apply(instance, 1, 2, null);

AbsoluteBlockBatch

Represents a set of block changes relative to the origin (0, 0, 0). All changes will be made to the coordinates given to Batch#set*, thus coordinates are given in world coordinates.

AbsoluteBlockBatch does not have any batch-specific apply options.

RelativeBlockBatch

Represents a set of block changes with no specified position. Coordinates are given in world coordinates, however they will be translated to any position given to apply.

The default apply location is the instance origin (0, 0, 0), however it may be applied to any position

RelativeBlockBatch#apply(Instance, BlockPosition, Runnable);
RelativeBlockBatch#apply(Instance, int /* x */, int /* y */, int /* z */, Runnable);

RelativeBlockbatch has a significant performance difference from the other two options, and they should be used over RelativeBlockBatch if possible. It is possible to convert a relative batch to an AbsoluteBlockBatch using the following methods. This should be used (and cached) if the batch will be applied several times to the same location.

RelativeBlockBatch#toAbsoluteBatch();
RelativeBlockBatch#toAbsoluteBatch(int /* x */, int /* y */, int /* z */);

Inverses

Inverses exist to undo a batch operation after applying it. If Calculate Inverse is set in the BatchOptions, apply will return a new back containing the opposite of every action performed during application.

When an inverse is returned from apply, it will not necessarily be ready for application. If the Unsafe Apply option is set, no checks will be made. Otherwise, apply on the inverse will block the current thread until it is ready.

It is possible to check if a batch is ready and wait for it to be ready regardless of the Unsafe Apply option.

// Returns true if ready
Batch#isReady()

// Block until ready
Batch#awaitReady()

An inverse will always be ready to apply in the apply callback.

Summary:

Writing your own extension for Microtus

To test in a dev environment, see last section.

Start by creating a new extension class:

package testextension;

import net.minestom.server.extensions.Extension;

public class TestExtension extends Extension {
    @Override
    public void initialize() {
        System.out.println("Hello from extension!");
    }

    @Override
    public void terminate() {

    }
}

Then, create a extension.json at the root of the resources folder (src/main/resources for instance) and fill it up: This part is autogenerated

{
  "entrypoint": "testextension.TestExtension",
  "name": "TestExtension",
  "version": "1.0.0",
  "dependencies": [
    "DependentExtension",
    "Extension2"
  ],
  "externalDependencies": {
    "repositories": [
      {"name": "Central", "url": "https://repo1.maven.org/maven2/"}
    ],
    "artifacts": [
      "com.squareup:javapoet:1.13.0"
    ]
  }
}

• entrypoint: Fully qualified name of your extension class

• name: Name to use to represent the extension to users. Must match regex [A-Za-z][_A-Za-z0-9]+

• version: Version of your extension

• dependencies (optional): List of extension names required for this extension to work.

• externalDependencies (optional): List of external libraries used for this extension (see Dependencies)

How extensions are loaded

This section is purely informational and not required to work on extensions, but it is a good thing to know how extensions are loaded inside Minestom.

1. Discovery

At launch, Minestom inspects the extensions folder (resolved from the current working folder) for jar files. For each file found, it then checks if there is an extension.json file and attempts to parse it. If the file exists, and parsing succeeds, the extension is considered discovered.

Discovery can also be forced when using ExtensionManager#loadDynamicExtension(File) but works the same.

2. Load order generation / Dependency solving

Then, Minestom ensures all required dependencies for the extension are found. For external dependencies, it will download them if necessary. For extension dependencies, it simply checks if they are already loaded, or about to be loaded (because discovered in the current load-cycle).

4. Instanciation and callbacks

Dependencies

Minestom extensions can have two types of dependencies:

1. Extension dependencies

2. External dependencies

Extension dependencies

Extensions can require other extensions to be present at runtime in order to be loaded. This is done via the dependencies array inside extension.json.

Extensions and their dependencies will be loaded in parent-first order: the root extensions of the dependency graph will always be loaded first, then extensions with one dependency, then extensions with two, and so on. If an extension is a dependency of at least two other, it is guaranteed that it will be loaded only once.

External dependencies

Your extension is free to depend on external libraries. For the moment, only maven-accessible libraries are supported.

To declare external dependencies, use the externalDependencies object inside extension.json:

"externalDependencies": {
    "repositories": [
      {"name": "Central", "url": "https://repo1.maven.org/maven2/"}
    ],
    "artifacts": [
      "com.squareup:javapoet:1.13.0"
    ]
  }

• repositories is the list of repositories to contact to get the artifacts

  • name: Name of the repository, used to recognize the repository inside logs

  • url: URL of the repository to contact

• artifacts is the list of Maven coordinates from the dependencies you want to use

Minestom will download and cache the libraries inside extensions/.libs/, so that it does not require to redownload them at each launch.

Callback order

During MinecraftServer#start, Minestom calls preInitialize on all extensions, then initialize on all extensions, and finally postInitialize on all extensions. Minestom does NOT guarantee the loading order of extensions, but it should be deterministic.

Extension Isolation

All extensions are completely isolated from each other by default, this means that you may not load a class from another dependency (without shading it, which has other concerns). If your extension depends on another, it must be specified in the extension.json, and then it will have access to the relevant classes.

Currently, if two extensions depend on the same library they will not share the same instance.

Testing in a dev environment

You may set the following vm arguments to load an extension from the classes and resources on disk (eg in your build directory), as opposed to a packaged jar file.

• -Dminestom.extension.indevfolder.classes=<folder to compiled classes of your extension> Specifies the folder in which compiled classes of your extension are. With a default Gradle setup, build/classes/java/main/ should work.

• -Dminestom.extension.indevfolder.resources=<folder to resources of your extension> Specifies the folder in which resources of your extension are. With a default Gradle setup, build/resources/main/ should work.

Overview

All coordinates classes in Minestom are immutables (like a lot of others), Point being the common interface, and the implementations Pos and Vec.

Vec is a containing for the x, y & z coordinates, adding a few vector methods. Pos contains the 3 coordinates + yaw/pitch for the view. Point should be used when the type does not matter.

Immutability performance

Some may express concern about the performance penalty of using immutable classes for math. Here is our reasoning:

• Immutability give us the guarantee that coordinate objects can be reused, reducing allocation

API

Initialization

All coordinates can be created using their respective constructors

Vec vec1 = new Vec(3, 0, 1); // [3;0;1] -> x;y;z
Vec vec2 = new Vec(1, 1); // [1;0;1]
Vec vec3 = new Vec(5); // [5;5;5]

Pos pos1 = new Pos(1,2,3,4,5); // [1;2;3;4;5] -> x;y;z;yaw;pitch
Pos pos2 = new Pos(1,2,3); // [1;2;3;0;0]
Pos pos3 = new Pos(new Vec(1)); // [1;1;1;0;0]
Pos pos4 = new Pos(new Vec(1),2,3); // [1;1;1;2;3]

Vec

Vec vec = new Vec(1, 2, 1);
vec = vec.add(0, 5, 0) // add 5 y
   .apply(Vec.Operator.FLOOR) // floor all coordinates
   .neg() // -x -y -z
   .withX(x -> x * 2); // double x

Pos

Very similar to Vec.

Pos pos = new Pos(0, 0, 0);
pos = pos.withView(50, 90)
        .add(0, 5, 0)
        .mul(5);

Block coordinates

Point point = new Vec(1);
final int blockX = point.blockX();
final int blockY = point.blockY();
final int blockZ = point.blockZ();

Basics

Each Instance has an optional Generator that is responsible for generating areas of various sizes.

The area size is abstracted as a GenerationUnit representing an aggregate of sections, the generator then has the ability to place blocks (and biomes) using relative and absolute coordinates. The dynamically sized area allows the API to be more flexible, and allows the instance to choose whether to generate full chunks at once or section by section without changing the generator.

Generation tasks are currently forwarded to the common JDK pool. Virtual threads will be used once Project Loom is integrated into the mainline.

Your first flat world

Here is the naive way of generating a flat world from y=0 to y=40

Instance instance = ...;
instance.setGenerator(unit -> {
    final Point start = unit.absoluteStart();
    final Point size = unit.size();
    for (int x = 0; x < size.blockX(); x++) {
        for (int z = 0; z < size.blockZ(); z++) {
            for (int y = 0; y < Math.min(40 - start.blockY(), size.blockY()); y++) {
                unit.modifier().setBlock(start.add(x, y, z), Block.STONE);
            }
        }
    }
});

GenerationUnit#absoluteStart returns the lowest coordinate of the unit which is useful for absolute placements. Now, we can heavily simplify the code by using one of our hand-optimized methods:

Instance instance = ...;
instance.setGenerator(unit -> 
    unit.modifier().fillHeight(0, 40, Block.STONE));

Modifying over unit borders

Modification over the border of a GenerationUnit cannot be done without extra steps. GenerationUnits cannot be resized during generation, instead we need to create a new GenerationUnit that encloses the area around our target blocks. We can do this through the GenerationUnit#fork methods.

Forked units are designed to be placed into the instance whenever it is possible to do so. This eliminates any section bordering issues that may arise.

There are two fork methods, both useful in their own ways. Here is a simple example of adding a structure (snowman):\

Instance instance = ...;
instance.setGenerator(unit -> {
    Random random = ...;
    Point start = unit.absoluteStart();

    // Create a snow carpet for the snowmen
    unit.modifier().fillHeight(-64, -60, Block.SNOW);

    // Exit out if unit is not the bottom unit, and exit 5 in 6 times otherwise
    if (start.y() > -64 || random.nextInt(6) != 0) {
        return;
    }

    // Lets fork this section to add our tall snowman.
    // We add two extra sections worth of space to this fork to fit the snowman.
    GenerationUnit fork = unit.fork(start, start.add(16, 32, 16));

    // Now we add the snowman to the fork
    fork.modifier().fill(start, start.add(3, 19, 3), Block.POWDER_SNOW);
    fork.modifier().setBlock(start.add(1, 19, 1), Block.JACK_O_LANTERN);
});

Adding structures using forks is trivial. However, for this GenerationUnit#fork method, you must know how large these structures are beforehand. To alleviate this condition, there is an alternative GenerationUnit#fork method that gives access to a direct Block.Setter. This Block.Setter automatically adjusts the fork's size depending on the blocks you set using it. Here is the same example written with the Block.Setter utility:

Instance instance = ...;
instance.setGenerator(unit -> {
    Random random = ...;
    Point start = unit.absoluteStart();

    // Create a snow carpet for the snowmen
    unit.modifier().fillHeight(-64, -60, Block.SNOW);

    // Exit out if unit is not the bottom unit or 5 in 6 times
    if (start.y() > -64 || random.nextInt(6) != 0) {
        return;
    }

    // Add the snowman
    unit.fork(setter -> {
        for (int x = 0; x < 3; x++) {
            for (int y = 0; y < 19; y++) {
                for (int z = 0; z < 3; z++) {
                    setter.setBlock(start.add(x, y, z), Block.POWDER_SNOW);
                }
            }
        }
        setter.setBlock(start.add(1, 19, 1), Block.JACK_O_LANTERN);
    });
});

These examples will generate a flat snow world with chunky snowmen scattered throughout, cleanly applying the snowmen whenever it is possible to do so.

Example with missing terrain for clarity:

Heightmaps with JNoise

This example shows a simply approach to building heightmaps using JNoise, this can be expanded to other noise implementations as well.

// Noise used for the height
JNoise noise = JNoise.newBuilder()
        .fastSimplex()
        .setFrequency(0.005) // Low frequency for smooth terrain
        .build();

// Set the Generator
instance.setGenerator(unit -> {
    Point start = unit.absoluteStart();
    for (int x = 0; x < unit.size().x(); x++) {
        for (int z = 0; z < unit.size().z(); z++) {
            Point bottom = start.add(x, 0, z);

            synchronized (noise) { // Synchronization is necessary for JNoise
                double height = noise.getNoise(bottom.x(), bottom.z()) * 16;
                // * 16 means the height will be between -16 and +16
                unit.modifier().fill(bottom, bottom.add(1, 0, 1).withY(height), Block.STONE);
            }
        }
    }
});

Here's and example of what that looks like: