Statestream

StateStream

Radical performance optimization for Minecraft 26.1.2 — zero gameplay changes, guaranteed.

StateStream surgically targets three of the most expensive hot-paths in Minecraft's server loop and replaces them with lean, cache-friendly implementations. Every optimization is independently toggleable and self-disabling on error, so a bad config silently falls back to vanilla rather than causing bugs.

---

Summary

The Statestream mod removes a lot of unnececary cheks in the game which allows your server to run more smothly. This makes your TPS higher if it issnt at 20 (20 is max). So the mod is especially helpfull if you experience server lag. Even though you dont have less that 20 TPS (20 is max) the mod will still help because your computer has to do fewer calculation. Therefore the mod is extremely helpfull when playing singleplayer or hosting a server/world on your computer as it allows the PC to use more of the CPU to give you higher FPS.

Performance Improvements

FPS (Client Frames Per Second)

StateStream's optimizations live on the server side, but they indirectly improve client FPS in three ways:

1. Fewer server lag spikes → smoother animation interpolation
When the server misses a tick (falls below 20 TPS), the client interpolates entity and block positions incorrectly. Rubber-banding, stuttering, and "jittery" movement all trace back to server lag. StateStream keeps the server at 20 TPS more consistently, which the client experiences as a visibly smoother framerate even if your actual GPU FPS hasn't changed.

2. Singleplayer / integrated server (most important for solo players)
In singleplayer, the server and client share the same CPU. Every millisecond saved in the server tick is a millisecond returned to the render thread. In a typical survival world:

• BlockState cache eliminates redundant HashMap traversals during chunk rendering border calculations
• Reactive ticking reduces time spent in the tick thread, directly lowering frame times

Estimated singleplayer FPS improvement: +3 – 12 FPS at 60 FPS baseline; higher gains where the server is using more of the CPU, higher render distance, multiplayerworlds hosted from same PC as client.

3. Reduced garbage collection pressure
The flat long[] cache avoids thousands of boxed Boolean and Integer object allocations per tick that vanilla's generic property system produces. Fewer short-lived objects → fewer GC pauses → fewer frame drops.

**NB!
FPS improvments will only be seen when the server/world is running on the same computer as the client, for example when hosting a server for you and your friends localy on your PC or using essentials etc. When the mod is put on a server running externaly you will experience that the server is running smoother rather than your client.

---

How Each Optimization Works

JIT BlockState Inlining

Every block in Minecraft has one or more BlockStates (a grass block has snowy: true/false, a log has axis: x/y/z, etc.). Vanilla looks up properties through a generic HashMap inside StateHolder — flexible, but slow when called millions of times per tick.

StateStream pre-bakes the five most-queried properties (solid, opaque, hasCollision, isAir, lightEmission) into a flat long[] array at startup, one entry per blockstate ID. A lookup becomes a single array read instead of a map walk. The array is laid out so frequently co-accessed properties share the same CPU cache line.

Reactive Block Ticking

Vanilla samples random.nextInt(4096) per subchunk per tick. In a typical survival world, most of those 4096 positions are air or non-tickable stone. StateStream maintains a registry of only the positions that contain tickable blocks (crops, grass, kelp, ice, etc.) and skips straight to them.

Tick rates are mathematically identical to vanilla. The 1/4096 probability per block per tick is preserved exactly — we don't switch to a round-robin or deterministic schedule. Crop growth rates, ice formation, tree spread — everything is statistically the same, just smoother and using less of the CPU.

Update Culling

When a block changes, Minecraft notifies up to 6 neighboring blocks. Many of those notifications are genuinely necessary (redstone, water flow, falling sand). But some receiver blocks probably do nothing with the notification — they receive it and immediately return.

StateStream lets you register these "inert pairs" in a JSON config file. Before propagating a neighbor notification, it checks the table and skips the call if the receiver is known-inert for that source. The default config ships empty — zero suppression out of the box, maximum safety.

---

Commands

Requires operator level 2.

/statestream stats      — cache hit rate, suppressed updates, tracked tickable positions
/statestream status     — which modules are active / self-disabled
/statestream reload     — reload inert_pairs.json without restarting
/statestream benchmark  — timed performance scan (results in server log)

---

Configuration

config/statestream.toml — auto-created with safe defaults on first launch:

[general]
jit_inlining_enabled = true
update_culling_enabled = true
reactive_ticking_enabled = true
debug_logging = false

[culling]
inert_pairs_file = "config/statestream/inert_pairs.json"

All three modules are independently toggleable. Disable any module that conflicts with another mod in a single config line.

---

FAQ - just that im answering my own questions - heh :(

Will this change how my farms work?
No. Tick rates, growth probabilities, and all random-tick behaviour are mathematically identical to vanilla. The 1/4096 probability model is preserved exactly.

Will this break redstone?
Not by default. Update Culling ships with zero suppressed pairs. Redstone behavior is entirely unaffected unless you manually add inert pairs (and only after verifying them against vanilla source).

Can this corrupt my world?
No. StateStream never writes block data or modifies world state. It only changes how fast the server reads block properties, not what those properties are.

What happens if something goes wrong?
The affected module logs a warning and silently disables itself. Your world continues on vanilla behavior for the rest of that session. No crash, no data loss.