Celeris

Celeris is a performance library for NeoForge and Fabric mods. It gives other mods fast building blocks so they can do heavy work without slowing the game down. On its own it adds nothing you can see in game: you install it because a mod you want needs it.

⚡ What it gives those mods

• 🧵 Work off the main thread. Heavy jobs run on worker threads and their results come back to the game thread through lock-free queues, without stalling a tick or a frame.
• 🧠 Less garbage-collector pressure. Large buffers live in off-heap memory, so big data does not cause GC pauses.
• 📐 Vector math. Bulk number crunching uses the CPU's SIMD units when Java allows it, and plain loops when it does not.
• 🗜️ Compression. Native zstd for mods' own data (no JVM flags needed) and deflate for network packets.
• 📦 Items in pipes. Networks that carry items from block to block, with no entity per item, that keep the items when pipes are placed, broken or saved.
• 🔌 Signal networks. Redstone-style graphs that only recompute what a change touches.
• 🏃 Batch physics. Thousands of entities and dropped items moved in one pass, following vanilla's movement rules.

🛡️ Safe everywhere

• ✅ Every fast path has a pure-Java fallback. If something can't run the fast way on your machine, Celeris uses the slower one instead of crashing.
• ✅ Optional on both sides of a connection: players without Celeris can join a server that has it, and you can join any server with it. A Fabric client can also join a NeoForge server with Celeris.
• ✅ Network payloads are size-capped and their headers are checked before anything uses them.
• ✅ The native code is checked with AddressSanitizer and UBSan in CI, and its results match the Java version bit for bit.

🏁 How fast

Each building block, measured against what a mod would otherwise use (JMH, Java 21, a 4-core machine; method and full tables in the benchmarks page):

• 🗜️ 12.8× faster compression than Java's built-in deflate (what Minecraft uses) for nearly the same size, and 3.1× faster decompression. As fast as zstd-jni in a jar a quarter of its size.
• 🏃 32,768 dropped items moved in 0.88 ms per tick on 3 threads with the native kernel, 5.3× faster than the same rules in Java on one thread and under 2 % of a tick.
• 🧲 Item piles no longer stall: finding the touching items in a pile of 16,384 takes 0.24 ms instead of up to a second.
• 🧵 4.9× faster hand-off from one worker thread to the game thread than JCTools, and still ahead with two or three workers.

📦 Requirements

• 🟩 Minecraft: 1.21 to 26.3. Download the file made for your version.
• 🔶 Loader: NeoForge or Fabric (with Fabric API), on the client and on the server.
• ☕ Java: 21 for 1.21.x, 25 for 26.x.

⚙️ Settings

• Network compression level (0 to 9, default 1): how hard Celeris compresses the packets it sends. 0 sends them uncompressed, 1 is the fastest, 9 gives the smallest packets. Only the sender's setting matters.
  • NeoForge: Mods → Celeris → Config, or compressionLevel in config/celeris-common.toml.
  • Fabric: with Mod Menu, Mods → Celeris → Config; or compressionLevel in config/celeris.properties (restart after editing it by hand).

Optional JVM flags are on the wiki.

🔧 Native code

Celeris ships two native libraries, built from public source by GitHub Actions on each platform's own runner, from the same tagged commit as every file published here:

• zstd 1.5.7 (Meta's Zstandard, BSD-3-Clause), compiled from the official release tarball and checked against its SHA-256, plus a few small functions of Celeris's own that let Java 21 call it without extra flags: native/zstd.
• The physics kernel, Celeris's own C++ code: native/.

GitHub releases also carry a Java-only file with no native code at all. See Native libraries.

📚 Learn more

The Celeris wiki has the settings, JVM flags, the guide for mod authors, performance numbers and how to build the project.

License

Source code: you may study, modify and redistribute it under the AGPL; if you run a modified version as a network service, its source must be available to that service's users.

Artwork: credit Bichal, no commercial use without permission, and share derivatives under the same license.

See LICENSE for the full summary.

Code: AGPL-3.0 · Art: CC BY-NC-SA 4.0 · Made by Bichal