Threadcore API

0.0.2 — first public release

Fabric · client and server · Java 16 · Minecraft 1.17 and newer

What it is

The developer-facing half of Threadcore. If you only want the mod, install Threadcore — it requires this and will tell you so. This is for writing a mod that cooperates with Threadcore rather than merely surviving it:

• RegionScheduler — run a task on the thread that owns a given block, chunk or region.
• 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.
• SnapshotService — read block state off-thread from a per-tick frozen view.
• ThreadGuard / ThreadContext / ThreadDomain — ask what thread you are on and assert it.
• @RegionSafe / @AsyncReadOnly / @RequiresMainEquivalent — declare your own threading contract, checked by ContractValidator.

Safe to depend on when Threadcore is absent

Every accessor returns null until Threadcore installs its implementations, and isAvailable() tells you whether it has. Soft-depend, take the fast path when it is there, fall back when it is not, ship one jar either way.

Version range — it is about Java, not Minecraft

This jar contains no Minecraft code and declares no Minecraft dependency, so Minecraft does not constrain it. It needs Java 16 or newer:

• 1.17 and newer: supported, with no upper bound. Every release from 1.17 on ships Java 16, 17, 21 or 25, so it will keep working on versions that do not exist yet.
• 1.16.5 and below: only if the server runs Java 16+. Those versions ship Java 8 by default. On a server running a newer JVM it loads normally, but that is the operator's choice, not a promise.

Java 16 is the floor because BlockVec, ChunkVec, RegionKey and TickStats are records. Targeting Java 11 or 8 produces 62 "records are not supported" errors — it would mean gutting the public API to reach servers that could simply run a newer JVM.

Using it

dependencies {
    modImplementation 'net.threadcore:threadcore-api:0.0.2'
}

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

Versioning

Versioned separately from Threadcore, and raised on every change to the public surface. That is not cosmetic: Fabric keeps the highest version of a shared library and breaks ties arbitrarily, and an older copy winning that tie once caused a NoSuchMethodError at boot. Its own version is the guard against that.

Licence

Apache-2.0 — use it, modify it, ship it inside a closed-source mod. The grant covers this API only; the Threadcore implementation is All Rights Reserved and is a separate project. It 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.