Thread Weave
If you have ever built a complex reactor, a swarm of AI entities, or a sprawling factory system in Minecraft, you know the pain of server tick lag. Every calculation your machine performs competes for time on the game's single main thread. The result is often a world that stutters, freezes, or slows to a crawl. Thread Weave offers a clever solution: a lightweight simulation framework that moves expensive logic off the Minecraft thread entirely, while keeping every world modification thread-safe.
This isn't a mod that changes how you play. Instead, it is a library for other mods. It allows developers to take the heavy math, the AI pathfinding, the physics engine calculations, and run them in the background. The best part? It does not modify Minecraft or patch vanilla code. It works alongside the game, creating a safe bridge between background threads and the main server thread.
Why Your Mods Need Thread Weave for Minecraft
Minecraft mods often suffer from a few common performance bottlenecks. The main culprits are usually heavy tick logic on the main thread, expensive calculations inside BlockEntities, and complex systems like reactors or factories that need constant updates. When all of this runs on a single core, the game's performance budget is quickly exhausted.
Thread Weave for Minecraft changes this dynamic. It allows you to move only the computation part into asynchronous execution. The framework handles the heavy lifting of extracting data, running simulations on multiple threads, and then applying the results back safely. This means you can build bigger, more complex machines without grinding the server to a halt.
The Core Principle: Pure Data, Safe Execution
The magic of Thread Weave lies in its strict rules. Simulation methods must be pure. This means they take an input DTO (Data Transfer Object) and return an output DTO. There are no side effects allowed inside the async execution. This restriction is what prevents race conditions and keeps the Minecraft world safe. The framework ensures that the world is never accessed from background threads. Only simple data is used during calculations, and all world changes happen safely on the main thread.
How Thread Weave Works
Thread Weave separates what your mod does into two distinct parts: data processing and world changes. Normally, Minecraft runs everything on a single thread. Thread Weave changes this by safely moving the heavy calculations to background threads. The process is straightforward: the tick extracts data from a BlockEntity, runs the simulation in background threads, gets the updated values, and then applies those changes back to the world.
The modder only needs to define three things: what data is used, what calculation should happen, and how the results are applied. Everything else is automated. The framework manages tick timing, prevents unsafe access to the game world, and applies results back safely. It even supports two tick modes: WORLD_SYNCED for normal game logic that runs at 20 ticks per second, and ISOLATED for simulations that need to run faster or slower than the game itself.
Setting Up Your Development Environment
Getting started with the framework is simple. To download Thread Weave, you add the Modrinth Maven repository to your build script and declare the dependency. After that, you must define the dependency in your mods.toml file to ensure your mod loads after Thread Weave. This is crucial for avoiding crashes. The framework is currently available for a range of Minecraft versions, with support for the 1.7.10 through 26.x range, and it primarily targets the Forge loader, though a Fabric port is planned.
A Practical Example: The Reactor BlockEntity
Imagine you have a ReactorBlockBE that extends BlockEntity. In its tick method, you are currently adding heat and consuming fuel. With Thread Weave, you first define a record for the data you need, like ReactorData(int heat, int fuel). Next, you create a simulation method annotated with @SimulatedThread. This method contains the pure calculation logic. Finally, in your tick method, you submit the data to the framework using Simulations.submit(this). The framework takes care of the rest.
For more advanced control, you can use the @SimulatedInterpreter and @SimulatedExtractor annotations. This is particularly useful for tasks like merging results from region-based processing, such as generating a baked navmesh for AI pathfinding. You can also manually control the interpreter to handle complex result merging.
Installation Guide and Getting Started
If you are a mod developer looking to optimize your creations, the installation process is straightforward. You need to add the Maven repository to your project, declare the dependency, and then ensure your mod is set to load after Thread Weave. For players who want to experience the benefits of optimized mods, you will typically find that mods using Thread Weave include it as a required dependency automatically. When you download Thread Weave, you are getting a library that will be used by other mods to enhance their performance.
When you are ready to test your creations, managing multiple mod versions and dependencies can be a hassle. Using a launcher that simplifies this process can save you a lot of time. The foxygame.net launcher offers a one-click install feature that handles version compatibility automatically, so you can get your Thread Weave setup running without manually juggling files. Its integrated add-on catalog makes it easy to find and install the latest mods that rely on the framework.
Is Thread Weave the Ultimate Optimization?
The developer is clear that this is not the peak of optimization. There is still work to be done. For example, most TickingBlockEntities are not yet fully compatible due to their need for a Level reference. However, the framework is a significant step forward. It allows modders to create more ambitious systems without sacrificing server performance. By moving the expensive math to background threads, Thread Weave gives your machines, AI, and reactors the breathing room they need to run at full speed. It is a powerful tool for any modder looking to push the boundaries of what is possible in Minecraft.