Minestom wiki
Search…
Thread Architecture
Feature
Expansion
Storage
Map rendering
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.
Once you have selected a map ID to write to (see MapMeta for more information), you can write its contents via a
MapDataPacket:1
MapDataPacket mapData = new MapDataPacket();
2
mapData.mapId = YOUR_MAP_ID;
3
mapData.data = YOUR_PIXELS;
4
mapData.x = X_START;
5
mapData.z = Z_START;
6
mapData.rows = ROW_COUNT;
7
mapData.columns = COLUMN_COUNT;
Copied!
mapIdis anintto be able to reference which map to change.datais abyte[]array which holds the indices inside the color palette. Its size should be at leastrows*columns.xis an unsigned byte (stored inside ashort) which represents the X coordinate of the left-most pixel to write. Ranges from 0 to 127 (inclusive).yis an unsigned byte (stored inside ashort) which represents the Y coordinate of the top-most pixel to write. Ranges from 0 to 127 (inclusive).rowsis an unsigned byte (stored inside ashort) which represents the number of rows to update.columnsis an unsigned byte (stored inside ashort) 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.1
MapDataPacket mapData = new MapDataPacket();
2
mapData.mapId = YOUR_MAP_ID;
3
Framebuffer fb = //...
4
// some render code
5
fb.preparePacket(packet);
Copied!
Framebuffers have 3 default flavors provided by Minestom: Direct, Graphics2D and GLFW-Capable.
DirectFramebuffer / LargeDirectFramebuffer
DirectFramebuffer / LargeDirectFramebufferDirect 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:
1
DirectFramebuffer fb = new DirectFramebuffer();
2
byte[] colors = fb.getColors();
3
for (int i = 0; i < colors.length; i++) {
4
colors[i] = MapColors.COLOR_CYAN.baseColor();
5
}
6
fb.set(0,0, MapColors.DIRT.baseColor());
Copied!
Graphics2DFramebuffer / LargeGraphics2DFramebuffer
Graphics2DFramebuffer / LargeGraphics2DFramebufferThese 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:
1
Graphics2D renderer = framebuffer.getRenderer();
2
renderer.setColor(Color.BLACK);
3
renderer.clearRect(0, 0, 128, 128);
4
renderer.setColor(Color.WHITE);
5
renderer.drawString("Hello from", 0, 10);
6
renderer.drawString("Graphics2D!", 0, 20);
Copied!
Graphics2D framebuffers also support getting/setting pixels individually if necessary.
GLFW-Capable buffers
Last modified 1yr ago