MapEngine - библиотека карт для Paper серверов

MapEngine - это плагин для Paper серверов Minecraft, который превращает обычные карты в настоящие дисплеи. Он заточен под разработчиков: даёт API для создания карт с кастомным контентом - от простых картинок до полноценного стриминга через RTMP.

Зачем это нужно?

Обычные карты в Minecraft ограничены: можно передать только статичное изображение, и то с костылями. А если хочешь сделать на сервере экраны, кинотеатр или мониторы - нужна библиотека вроде MapEngine. Она берёт на себя всю техническую часть: рендеринг, пакеты, сглаживание.

Что умеет MapEngine?

• Пайплайн-API - можно строить цепочки обработки изображений, настраивать конвертацию
• Асинхронный рендеринг - не нагружает основной поток сервера
• Работа на пакетах - полностью пакетная архитектура, без лишних чанков
• Dithering (Floyd-Steinberg) - опциональное сглаживание, чтобы карты выглядели чётче
• Z-слои для групп - экономия трафика через интерпретацию групп как слоёв
• Побуферинг - на каждого игрока отправляются только изменённые пиксели
• Упаковка пакетов - предотвращает разрывы изображения
• Рисование примитивов - текст, линии, треугольники, прямоугольники, круги, эллипсы, полигоны

Продвинутые фишки

Вот что особенно круто: RTMP-стриминг прямо на картах. Можно транслировать видео с OBS на массив из карт, например 7x4. Разрешение источника хоть 1920x1080@20 - для карт это более чем достаточно.

Или Floyd-Steinberg dithering - когда изображение сжимается под палитру карт, этот алгоритм распределяет ошибку пикселизации, и картинка получается намного приятнее глазу, чем тупое ресемплинг.

Поддержка версий

Плагин работает практически на всех актуальных Paper:

• Paper 1.21.x (все версии от 1.21.1 до 1.21.11)
• Paper 1.20.x
• Paper 1.19.3, 1.19.4

Старые версии вроде 1.18 или 1.17 - не поддерживаются, так что если у вас сервер на них, увы. Но для 1.19+ это прям must-have.

Как подключить к проекту?

Плагин должен быть прописан в plugin.yml как зависимость. Дальше - просто добавить репозиторий и зависимость в сборщик.

Maven

<repositories>
    <repository>
        <id>minceraft</id>
        <url>https://repo.minceraft.dev/releases/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>de.pianoman911</groupId>
        <artifactId>mapengine-api</artifactId>
        <version>1.8.11</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Groovy)

repositories {
    maven {
        url = 'https://repo.minceraft.dev/releases/'
        name = 'minceraft'
    }
}

dependencies {
    compileOnly 'de.pianoman911:mapengine-api:1.8.11'
}

Gradle (Kotlin DSL)

repositories {
    maven("https://repo.minceraft.dev/releases/") {
        name = "minceraft"
    }
}

dependencies {
    compileOnly("de.pianoman911:mapengine-api:1.8.11")
}

Пример кода

Вот как это выглядит в деле:

public class Bar {

    // получаем инстанс API
    private static final MapEngineApi MAP_ENGINE = Bukkit.getServicesManager().load(MapEngineApi.class);

    public void foo(BufferedImage image, BlockVector cornerA, BlockVector cornerB, BlockFace facing, Player viewer) {
        // создаём дисплей
        IMapDisplay display = MAP_ENGINE.displayProvider().createBasic(cornerA, cornerB, facing);
        display.spawn(viewer);

        // создаём элемент пайплайна для рисования
        IDrawingSpace input = MAP_ENGINE.pipeline().createDrawingSpace(display);

        // рисуем картинку
        input.image(image,0,0);

        // треугольник прямо поверх
        input.triangle(0, 0, 10, 10, 20, 0, 0xff0000ff);

        // добавляем игрока в контекст
        input.ctx().receivers().add(viewer);

        // включаем дизеринг и буферинг
        input.ctx().converter(Converter.FLOYD_STEINBERG);
        input.ctx().buffering(true);

        // сбрасываем пайплайн - изображение отправится игроку
        input.flush();
    }
}

Более детальные примеры лежат в репозитории MinceraftMC/MapEngineExamples.

Если хочешь собрать сам

git clone https://github.com/MinceraftMC/MapEngine.git
cd MapEngine
./gradlew build  # на Linux/MacOS, на Windows просто gradlew build

Плагин соберётся в директории build/libs.

Вердикт

MapEngine - вещь специфическая, но если ты разрабатываешь сервер с картами-экранами, кинотеатрами или визуальными эффектами - это база. Лёгкий, асинхронный, с хорошим API. Единственный минус - порог входа: надо уметь программировать на Java. Но если умеешь - считай, получил мощный инструмент для визуального контента прямо на картах Minecraft.