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 /statestrea