Distant Decorations

Distant Decorations

Distant Decorations — это высокопроизводительный фреймворк для Fabric на Minecraft 26.2, который позволяет поддерживающим его модам сохранять и отрисовывать декоративные визуалы блоков-сущностей далеко за пределами стандартной дальности чанков. По умолчанию клиентская дальность подписки составляет 512 чанков (8 192 блока), а серверный максимум — 1 024 чанка (16 384 блока). Такие интеграции, как Fast Paintings и Camerapture, предоставляют собственные лёгкие серверные провайдеры метаданных и дальние клиентские рендереры.

Разделяя визуальное представление и тикающие блоки-сущности и используя иерархическую пространственную индексацию, отсечение по проецируемому размеру и ограниченный отбор top-K, Distant Decorations удерживает обход дальних декораций в пределах нескольких миллисекунд даже при больших синхронизированных наборах данных — без проблем сосуществуя с рендерерами дальнего ландшафта вроде Voxy.

🌟 Ключевые возможности

• Экстремальная дальность видимости: Расширяет видимость декораций до 512 чанков (8 192 блока) по умолчанию, с серверной поддержкой подписок до 1 024 чанков (16 384 блока), независимо от стандартной дальности прорисовки чанков.

• Иерархическая пространственная индексация:

  • Ячейки 4×4 чанка (64×64 блока): Расчёт агрегированного ограничивающего бокса для мгновенного грубого отсечения по пирамиде видимости.
  • Регионы 32×32 чанка (512×512 блоков): Монотонное отслеживание ревизий, сброс грязных регионов (каждые 5 с) и вытеснение простаивающих (60 с).

• Динамический уровень детализации (LOD) и масштабирование дальних визуалов:

  • Отсечение по проецируемому размеру с учётом провайдера: Позволяет рендерерам задавать собственные пороги отсечения по субпикселям через cullBelowProjectedPixelSize() (по умолчанию глобальные 0.10 px, настраивается вплоть до 0.01 px).
  • Поддержка дальнего LOD-отпечатка: Ядро выдаёт точные метрики проекции и неотсечённые данные, чтобы рендереры провайдеров могли масштабировать субпиксельные дальние квады вокруг их центра для поддержания растеризуемого визуального отпечатка ~1 px (например, с ограничением до 16x без изменения физических AABB в мире).

• Бесшовная передача без мерцания:

  • Динамический порог дальности (64 x entityDistanceScaling блоков) и 200 мс льготного периода загрузки чанков обеспечивают плавные переходы между рендерерами живых блоков-сущностей и Distant Decorations.
  • Захват изменений в реальном времени (MixinBlockEntity), отслеживающий обновления блоков-сущностей (setChanged) и удаления в активных чанках.
• Сосуществование с OBE: Разработан для чистого сосуществования с OptimisedBlockEntities (OBE), работая полностью независимо от жизненных циклов тикающих блоков-сущностей.
• Интеграция с Chunky: Безопасно перехватывает асинхронную генерацию чанков от Chunky и переносит согласование обратно в главный поток сервера для атомарной фиксации новых сгенерированных блоков-сущностей в мировой индекс.

• Ограничение нагрузки на GPU и сеть:

  • Ограничитель бюджета с приоритетом по дальности и экранному пространству (projectedPixelSize * 1000 - distance) с использованием ограниченного отбора top-K (O(N log K)).
  • Потоковая передача фрагментированных многочастных снапшот-пакетов с ограничением пропускной способности (128 КиБ/тик) (сначала ближайшие) с атомарной сборкой на стороне клиента.
  • Преддекодирование полезной нагрузки во время приёма: нулевая десериализация полезной нагрузки или выделение ByteBuf в цикле рендеринга.

🧩 Архитектура провайдеров

Distant Decorations задуман как модульный базовый фреймворк. Контентные моды регистрируют собственные лёгкие провайдеры метаданных на сервере и кастомные рендереры на клиенте:

⚙️ Конфигурация и диагностика

Distant Decorations предоставляет команды диагностики во время выполнения и настройку через системные свойства:

Команды диагностики

• Клиент:

  • /ddc stats: Показывает активную конфигурацию, синхронизированные счётчики регионов/декораций и разбивку последнего кадра (Visible/Rendered, Far-LOD Scaled, Suppressed (Live), Culled (Distance), Culled (Subpixel), Culled (Frustum) и Culled (Budget)).
  • /ddc toggle: Включает или выключает отрисовку дальних декораций во время выполнения.

• Сервер:

  • /dd stats: Показывает проиндексированные счётчики декораций, загруженные измерения, активные клиентские подписки и отслеживание изменённых регионов.
  • /dd toggle: Главный серверный переключатель синхронизации декораций.

Свойства конфигурации

🛠️ API для разработчиков

Distant Decorations предоставляет чистый расширяемый API, позволяющий сторонним модам регистрировать собственные типы декораций, серверные провайдеры и клиентские рендереры.

1. Определите тип декорации и провайдер (на стороне сервера)

public record MyCustomData(Identifier texture, Direction facing, int width, int height, int packedLight) {}

public class MyCustomProvider implements DecorationProvider<MyCustomData> {
    public static final DecorationType<MyCustomData> TYPE = new DecorationType<>(
        Identifier.fromNamespaceAndPath("mymod", "custom_deco"),
        (data, buf) -> {
            buf.writeIdentifier(data.texture());
            buf.writeByte(data.facing().get2DDataValue());
            buf.writeVarInt(data.width());
            buf.writeVarInt(data.height());
            buf.writeInt(data.packedLight());
        },
        buf -> new MyCustomData(
            buf.readIdentifier(),
            Direction.from2DDataValue(buf.readByte()),
            buf.readVarInt(),
            buf.readVarInt(),
            buf.readInt()
        )
    );

    @Override
    public DecorationType<MyCustomData> type() { return TYPE; }

    @Override
    public boolean matches(BlockEntity be) { return be instanceof MyCustomBlockEntity; }

    @Override
    public MyCustomData capture(ServerLevel level, BlockPos pos, BlockEntity be) {
        MyCustomBlockEntity custom = (MyCustomBlockEntity) be;
        return new MyCustomData(custom.getTexture(), custom.getFacing(), custom.getWidth(), custom.getHeight(), getPackedLight(level, pos));
    }

    @Override
    public AABB calculateBounds(ServerLevel level, BlockPos pos, MyCustomData data) {
        return new AABB(pos);
    }
}

2. Реализуйте клиентский рендерер (на стороне клиента)

public class MyCustomRenderer implements DecorationClientRenderer<MyCustomData> {
    @Override
    public DecorationType<MyCustomData> type() { return MyCustomProvider.TYPE; }

    @Override
    public double cullBelowProjectedPixelSize() {
        // Opt into custom subpixel threshold for far-LOD scaling
        return 0.01;
    }

    @Override
    public void render(
        DecorationRecord record,
        MyCustomData data,
        Camera camera,
        PoseStack poseStack,
        SubmitNodeCollector submitNodeCollector,
        ProjectionMetrics metrics,
        double projectedPixelSize
    ) {
        BlockPos anchor = record.pos();
        Vec3 camPos = camera.position();

        poseStack.pushPose();
        poseStack.translate(anchor.getX() - camPos.x, anchor.getY() - camPos.y, anchor.getZ() - camPos.z);
        poseStack.translate(0.5, 0.5, 0.5);

        // Optional Far-LOD visual scaling for subpixel quads
        double targetMinPixelSize = 1.0;
        if (projectedPixelSize > 0 && projectedPixelSize < targetMinPixelSize) {
            double visualScale = Math.min(16.0, targetMinPixelSize / projectedPixelSize);
            poseStack.scale((float) visualScale, (float) visualScale, 1.0F);
            TelemetryMetrics.clientFarLodScaledRenders++;
        }

        RenderType renderType = RenderTypes.entityCutout(data.texture());
        submitNodeCollector.submitCustomGeometry(poseStack, renderType, (pose, buffer) -> {
            // Submit vertex geometry
        });

        poseStack.popPose();
    }
}

3. Регистрация

// Common / Server Mod Initializer
DecorationRegistry.registerProvider(new MyCustomProvider());

// Client Mod Initializer
ClientDecorationRegistry.registerRenderer(new MyCustomRenderer());

📦 Сборка и тестирование из исходников

git clone https://github.com/justbecauseph/distant-decorations.git
cd distant-decorations
./gradlew build

Чтобы запустить полноценное клиентское тестовое окружение с предзагруженными Voxy, Sodium и Spark:

./gradlew runIntegrationClient

Скомпилированный JAR мода будет лежать в build/libs/.

📄 Лицензия

Distant Decorations распространяется под лицензией Mozilla Public License 2.0 (MPL-2.0).