ThreadWeave 是一个轻量级的模拟框架,允许你将昂贵的逻辑从 Minecraft 主线程移动到其他线程,同时保持所有世界修改的线程安全。
- 模组不会修改 Minecraft 或修补原版代码。这是一个供其他模组使用的库
由于线程竞争条件,隔离模拟无法直接访问动态变化的关卡数据,因此它仅处理计算等任务。这听起来可能毫无用处,除非你开始制作 AI、反应堆、计算机或更复杂的系统,如物理引擎。
对世界的执行更改(如放置方块)仍将依赖于 Minecraft 主线程,以避免产生竞争条件。
Minecraft 模组通常存在以下问题:
- 主线程上的繁重刻逻辑
- BlockEntity 内部的昂贵计算
- 复杂系统(反应堆、AI、工厂)
ThreadWeave 允许你仅将计算部分移至异步执行,同时保持世界安全性完好无损。
模拟方法中只允许使用纯数据。
重要限制
模拟方法必须是纯方法:
- 输入 DTO -> 输出 DTO
- 不允许在异步执行内部产生副作用
它是如何工作的?
ThreadWeave 通过将模组的功能分为两部分来工作:数据处理和世界更改。
Minecraft 通常在单个线程上运行所有内容。这意味着所有计算、AI、机器和方块逻辑都在争夺相同的有限性能预算。
ThreadWeave 通过安全地将繁重计算移动到后台线程来改变这一状况:
- Minecraft 刻(Tick)
- 从 BlockEntity 提取数据
- 在后台线程中运行模拟
- 获取结果(更新后的值)
- 将更改应用回世界
模组开发者只需定义:
ThreadWeave 自动完成以下操作:
- 从 BlockEntity 提取数据
- 在多个线程上运行计算
- 防止对游戏世界的非安全访问
- 安全地应用结果
- 管理刻计时(正常或加速模拟)
刻模式
WORLD_SYNCED
与 Minecraft 同步运行(每秒 20 次)
用于常规游戏逻辑
ISOLATED
独立于 Minecraft 速度运行
用于可以比游戏本身更快或更慢运行的模拟
安全性
- 后台线程永远不会访问 Minecraft 世界
- 计算期间仅使用简单数据
- 所有世界更改都在主线程上安全发生
框架防止对以下内容的非安全访问:
- Level(关卡/世界)
- Entities(实体)
- BlockEntities(方块实体)
- Server internals(服务端内部结构)
如何使用?
安装指南
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 将以 Minecraft TPS 的速度运行。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 注解手动解释器和提取器。
例如:工作刻(work ticks):
@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++;
}
上面的例子并不是最好的。自定义解释器在区域级处理中更加有用,当你需要合并结果时(例如烘焙导航网格生成)。
@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 服务器中关注进度。
例如,大多数 TickingBlockEntity( ticking block entity )目前还不太适合本库,因为还需要 Level(世界)的依赖。
注:稍后我会发布 Fabric 移植版及其他版本 [1.7.10 - 26.x]
ThreadWeave is a lightweight simulation framework that allows you to move expensive logic from Minecraft thread into other threads while keeping all world modifications thread-safe
- Mod does not modify Minecraft or patch vanilla code. This is library for other mods
- 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
- Minecraft Tick
- Extract data from BlockEntity
- Run simulation in background threads
- Get results (updated values)
- 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:{version}"
}
Do not forget to define dependency in mods.toml or you will get minecraft crashed
[[dependencies.${mod_id}]]
modId="thread_weave"
type="required"
versionRange="[{version},)"
ordering="AFTER" // VERY important to load your mod AFTER ThreadWeave
side="BOTH"
For example you have BlockEntity (you can use custom classes. No matter it's minecraft or not)
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 submit your data to framework. Use static method "submit"
@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 set what classes will be scanned for @SimulatedThread annotation
public YourMainModClass(IEventBus modEventBus, ModContainer modContainer) {
modEventBus.addListener(this::commonSetup);
Simulations.submitScan(NavMeshSimulation.class);
...
}
You can also manually control interpreter and extractor by
@SimulatedInterpreter and @SimulatedExtractor annotations
For example: work ticks
@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++;
}
Example above is not the best. Custom interpreter is much usable in per-region processing when you need to merge result (Baked Navmesh generation)
@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());
}
Is this peak optimization?
No. There is still much work to do. You can follow progress in my discord server
For example most of TickingBlockEntities is not really good with this library due to Level require (Yet)
P.S: I will post a fabric port + other versions later [1.7.10 - 26.x]
评论 0
登录后参与评分
还没有评论,来抢沙发吧