Thread Weave

ThreadWeave is a lightweight simulation framework that allows you to move expensive logic from Minecraft main thread into isolated asynchronous computation while keeping all world modifications thread-safe

• Mod does not modify Minecraft or patch vanilla code
• All world changes are still executed on the main server thread

Isolated simulation does not have Live Level changing access due to race-conditions on threads so it only processes calculations and e.t.c. This may sound useless unless you start to make AI, reactors, computers or more complicated systems like physics Engines.

Execution changes to world like placing blocks will still depend on Minecraft Thread to not create race conditions

Minecraft mods often suffer from:

• Heavy tick logic on main thread
• Expensive calculations inside BlockEntities
• Complex systems (reactors, AI, factories)

ThreadWeave allows you to move only the computation part into async execution while keeping world safety intact

Only pure data is allowed inside simulation methods

Important limitation

Simulation methods must be pure methods:

• input DTO -> output DTO
• No side effects allowed inside async execution

How it works?

ThreadWeave works by separating what your mod does into two parts: data processing and world changes

Minecraft normally runs everything on a single thread. That means all calculations, AI, machines, and block logic compete for the same limited performance budget

ThreadWeave changes this by safely moving heavy calculations to background threads

1. Minecraft Tick
2. Extract data from BlockEntity
3. Run simulation in background threads
4. Get results (updated values)
5. Apply changes back to world

Modder only defines:

• What data is used
• What calculation should happen
• How results are applied

What ThreadWeave does automatically?

• Extracts data from BlockEntity
• Runs calculations on multiple threads
• Prevents unsafe access to the game world
• Applies results back safely
• Manages tick timing (normal or accelerated simulation)

Tick modes

WORLD_SYNCED

Runs in sync with Minecraft (20 times per second)

Used for normal game logic

ISOLATED

Runs independently of Minecraft speed

Used for simulations that can run faster or slower than the game itself

Safety

• Minecraft world is never accessed from background threads
• Only simple data is used during calculations
• All world changes happen safely on the main thread

Framework prevents unsafe access to:

• Level
• Entities
• BlockEntities
• Server internals

How to use?

Installation Guide

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

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

For example you have BlockEntity

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 - You need to set what variables will be used in async-processing

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

II - Then you need to split your processing. Simply take all of your calculations and move it to other method. Here you need to set @SimulatedThread annotation. TickMode can be Isolated or WorldSynced. WorldSynced will run at minecraft TPS. Isolated will run at any tick speed you set without minecraft dependency

    //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 - Last you need to setup getters and setters + submit your data to framework. Use static method "submit"

    public int getHeat() {
        return heat;
    }

    public int getFuel() {
        return fuel;
    }

    public void setHeat(int heat) {
        this.heat = heat;
    }

    public void setFuel(int fuel) {
        this.fuel = fuel;
    }
    
    @Override
    public void tick() {
        if (level == null || level.isClientSide()) return;

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

IV - Also you need to add this to your main mod class

public YourMod(IEventBus modEventBus, ModContainer modContainer) {
  modEventBus.addListener(this::commonSetup);
  Simulations.bootstrapScan(ReactorBlockBE.class);
  ...
  }

This will defines what classes needs to be multi-threaded

Is this peak optimisation?

No. There is still much work to do. You can follow progress in my discord server