Thread Weave

ThreadWeave — это лёгкий фреймворк для симуляций, который позволяет вынести тяжёлую логику из потока Minecraft в другие потоки, сохраняя потокобезопасность всех изменений мира

- Мод не изменяет Minecraft и не патчит ванильный код. Это библиотека для других модов

• Все изменения мира по-прежнему выполняются в основном потоке сервера

Изолированная симуляция не имеет доступа к изменению Live Level из-за гонок данных между потоками, поэтому она занимается только расчётами и тому подобным. Это может звучать бесполезно, пока вы не начнёте делать ИИ, реакторы, компьютеры или более сложные системы вроде физических движков.

Выполнение изменений мира, например установка блоков, всё ещё будет зависеть от потока Minecraft, чтобы не создавать гонок данных

Моды для Minecraft часто страдают от:

• Тяжёлой логики тиков в основном потоке
• Дорогих вычислений внутри BlockEntities
• Сложных систем (реакторы, ИИ, фабрики)

ThreadWeave позволяет вынести только вычислительную часть в асинхронное выполнение, сохраняя безопасность мира

Внутри методов симуляции допускаются только чистые данные

Важное ограничение

Методы симуляции должны быть чистыми методами:

• входной DTO -> выходной DTO
• Никаких побочных эффектов внутри асинхронного выполнения

Как это работает?

ThreadWeave работает, разделяя то, что делает ваш мод, на две части: обработку данных и изменения мира

Minecraft обычно выполняет всё в одном потоке. Это значит, что все вычисления, ИИ, машины и логика блоков конкурируют за один и тот же ограниченный бюджет производительности

ThreadWeave меняет это, безопасно перенося тяжёлые вычисления в фоновые потоки

1. Тик Minecraft
2. Извлечение данных из BlockEntity
3. Запуск симуляции в фоновых потоках
4. Получение результатов (обновлённых значений)
5. Применение изменений обратно в мир

Моддер определяет только:

• Какие данные используются
• Какое вычисление должно произойти
• Как применяются результаты

Что ThreadWeave делает автоматически?

• Извлекает данные из BlockEntity
• Запускает вычисления в нескольких потоках
• Предотвращает небезопасный доступ к игровому миру
• Безопасно применяет результаты обратно
• Управляет таймингом тиков (обычная или ускоренная симуляция)

Режимы тиков

WORLD_SYNCED

Работает синхронно с Minecraft (20 раз в секунду)

Используется для обычной игровой логики

ISOLATED

Работает независимо от скорости Minecraft

Используется для симуляций, которые могут работать быстрее или медленнее самой игры

Безопасность

• Мир Minecraft никогда не доступен из фоновых потоков
• Во время вычислений используются только простые данные
• Все изменения мира безопасно происходят в основном потоке

Фреймворк предотвращает небезопасный доступ к:

• Level
• Сущностям
• BlockEntities
• Внутренностям сервера

Как использовать?

Руководство по установке

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}

dependencies {
    implementation "maven.modrinth:thread-weave:{version}"
}

Не забудьте указать зависимость в mods.toml, иначе Minecraft упадёт

[[dependencies.${mod_id}]]
modId="thread_weave"
type="required"
versionRange="[{version},)"
ordering="AFTER" // ОЧЕНЬ важно, чтобы ваш мод загружался ПОСЛЕ ThreadWeave
side="BOTH"

Например, у вас есть BlockEntity (можно использовать кастомные классы. Неважно, minecraft это или нет)

public class ReactorBlockBE extends BlockEntity implements TickableBE {
    private int heat;
    private int fuel;

    public ReactorBlockBE(BlockPos pos, BlockState state) {
        super(ThreadBlockEntities.REACTOR_BE.get(), pos, state);
    }

    @Override
    public void tick() {
        if (level == null || level.isClientSide()) return;
        heat+=20;
        fuel-=1;
    }
}

I - Вам нужно задать, какие переменные будут использоваться в асинхронной обработке

public record ReactorData(int heat, int fuel) implements SimulationDelta {}

II — Затем нужно разделить обработку. Просто возьми все свои вычисления и вынеси их в отдельный метод. Здесь нужно поставить аннотацию @SimulatedThread. TickMode может быть Isolated или WorldSynced. WorldSynced будет работать на TPS Minecraft. Isolated будет работать на любой скорости тиков, которую ты задашь, без зависимости от Minecraft

    //value = MOD_ID + ":reactor"
    //value = "my_mod:reactor"
    @SimulatedThread(value = MOD_ID + ":reactor", mode = TickMode.WORLD_SYNCED)
    public ReactorData simulate(ReactorData data) {
        int heat = data.heat() + 20;
        int fuel = data.fuel() - 1;
        return new ReactorData(heat, fuel);
    }

III — Наконец, нужно отправить свои данные во фреймворк. Используй статический метод "submit"

    @Override
    public void tick() {
        if (level == null || level.isClientSide()) return;

        Simulations.submit(this);
        System.out.println("heat=" + this.getHeat() + " fuel=" + this.getFuel());
    }

IV — Также нужно указать, какие классы будут сканироваться на аннотацию @SimulatedThread

    public YourMainModClass(IEventBus modEventBus, ModContainer modContainer) {
        modEventBus.addListener(this::commonSetup);
        Simulations.submitScan(NavMeshSimulation.class);
        ...
    }

Ты также можешь вручную управлять интерпретатором и экстрактором с помощью аннотаций @SimulatedInterpreter и @SimulatedExtractor

Например: тики работы

    @SimulatedThread(value = MOD_ID + ":reactor", mode = TickMode.WORLD_SYNCED)
    public ReactorData simulate(ReactorData data) {
        int heat = data.heat() + 20;
        int fuel = data.fuel() - 1;
        return new ReactorData(heat, fuel);
    }

    @SimulatedInterpreter
    public void interpreter(NavData data) {
        this.heat = data.heat();
        this.fuel = data.fuel();
        workTicks++;
    }

Пример выше не самый лучший. Кастомный интерпретатор куда полезнее при обработке по регионам, когда нужно объединить результат (генерация Baked Navmesh)

    @SimulatedThread(value = MOD_ID + ":navgraph", mode = TickMode.WORLD_SYNCED)
    public NavData simulate(NavProcessorData data) {
        if (processor.isEmpty()) return null;
        return processor.build(navLevel);
    }

    @SimulatedInterpreter
    public void interpreter(NavData data) {
        if (data == null) return;
        for (NavNode node : data.toRemove()) {
            navLevel.nodes.remove(node.id());
        }
        navLevel.nodes.putAll(data.nodes());
        navLevel.portals.putAll(data.portals());
        navLevel.chunkIndices.putAll(data.chunkIndices());
    }

Это пик оптимизации?

Нет. Работы ещё много. За прогрессом можешь следить в моём discord-сервере

Например, большинство TickingBlockEntities не очень хорошо дружат с этой библиотекой из-за требования Level (пока что)

P.S: Позже выложу порт на fabric + другие версии [1.7.10 - 26.x]