Threadcore API

Threadcore API

This is the developer-facing half of Threadcore, a mod that replaces Minecraft's single-threaded server tick with a regionized parallel one.

If you just want the mod, install Threadcore it requires this and lists it as a dependency. Read on only if you are writing a mod and want it to cooperate with Threadcore rather than merely survive it.

Why you would use it

When Threadcore is installed, parts of the server tick run on region worker threads instead of the main thread. Most mods are unaffected: Threadcore guards the dangerous paths and defers anything cross-region back to main. But if your mod does heavy per-tick work of its own, you can do better than being guarded you can opt in:

• RegionScheduler run a task on the thread that owns a given block, chunk or region, so your work happens in parallel with the rest of the world instead of queueing behind it.
• MutationGate change a block, or run an arbitrary mutation, from a region thread safely. It is deferred and replayed on the main thread in order, so you get correctness without writing your own queue.
• SnapshotService read block state off-thread from a per-tick frozen view, instead of racing the world.
• ThreadGuard / ThreadContext / ThreadDomain ask what kind of thread you are on, and assert that you are where you think you are. In strict mode a violation is loud, rather than a corrupted world three hours later.
• @RegionSafe / @AsyncReadOnly / @RequiresMainEquivalent declare your own threading contract and have ContractValidator check it.

Safe to depend on when Threadcore is absent

Every accessor returns null until Threadcore installs its implementations, and isAvailable() tells you whether it has. So you can soft-depend: take the fast path when Threadcore is present, fall back to ordinary main-thread behaviour when it is not, and ship one jar either way.

Version independence

The API carries no Minecraft classes at all. The same source has been built clean against every Minecraft version Threadcore targets, from 1.8.9 to 1.21.11, and the published jar is a single artifact for all of them there is no per-version copy to manage. It is also versioned separately from Threadcore, so its public surface can be tracked on its own.

Using it

repositories {
    maven { url = 'https://maven.pkg.github.com/mrimmortal1749/shadowmark-threadcore' }
}
dependencies {
    modImplementation 'net.threadcore:threadcore-api:0.2.0'
}

if (ThreadcoreAPI.isAvailable()) {
    ThreadcoreAPI.getScheduler().scheduleAt(worldKey, pos, () -> { /* on the owning region */ });
} else {
    runOnMainThreadAsUsual();
}

Declare it as a dependency in your own fabric.mod.json:

"depends":   { "threadcore-api": ">=0.2.0" }

or, if your mod should work with or without it:

"suggests":  { "threadcore-api": ">=0.2.0" }

Licence

Apache-2.0. Use it, modify it, ship it inside a closed-source mod that is what it is for. Note that the Apache grant covers this API module only; the Threadcore implementation is All Rights Reserved and is published as a separate project. The licence also does not grant rights to the Threadcore name or logo.

Status

Alpha. The surface is deliberately small everything in it is behaviour Threadcore already implements, rather than a speculative design.