Tessellate
- By
Improves Minecraft server performance by isolating loaded regions, ticking independent areas in parallel, and throttling only the region causing lag.
Tessellate
Tessellate is a NeoForge performance mod for Minecraft 1.21.1. It groups distant loaded areas into independent regions and lets them run on different CPU cores. If one region gets too expensive, Tessellate can slow it down without dragging the rest of the server with it.
| Situation | What Tessellate does |
|---|---|
| Several distant bases are busy | Runs their regions concurrently |
| One region exceeds the server budget | Reduces only that region's simulation rate |
| Two regions become close enough to interact | Merges them before they tick |
| A worker reaches unsafe shared state | Falls back to serial ticking for the session |
This works best when players or forced-loaded areas are spread out. One dense base, mob farm, or machine cluster is still one region, so Tessellate cannot split that work across several cores. It also doesn't replace single-thread optimizers such as Lithium.
Requirements and installation
- Minecraft 1.21.1
- NeoForge 21.1.x
- Java 21
- No required optimization-mod dependencies
Drop the JAR into the server's mods folder. The client install is optional: players who have it
get the GPU-rendered region map and boundary overlay, while everyone else can still use the
particle fallback.
Performance
For a concrete comparison, we benchmarked four forced-loaded regions 2,048 blocks apart with 1,200 persistent zombies in each region. Parallel ticking cut median MSPT by 61.2% and p95 MSPT by 62.5%.
| Mode | Median MSPT | Median p95 | Regions at 20 TPS | Slowest region |
|---|---|---|---|---|
| Serial regional ticking | 40.55 ms | 50.80 ms | 0/4 and 1/4 | 10.0-10.6 TPS |
| Parallel regional ticking | 15.75 ms | 19.05 ms | 4/4 in both runs | 20.0 TPS |
Both modes ran on Minecraft 1.21.1, NeoForge 21.1.248, Java 21, and the same nine-mod setup. This test is deliberately built around several separate regions; it is not a promise of the same speedup everywhere. Hardware, region layout, entity count, and installed mods all matter.
How it works
Tessellate divides the loaded world into 4x4-chunk sections. Nearby entity-ticking sections join into a region before they run, which keeps areas that could interact on the same worker. Separate regions can run in parallel. Packets, lifecycle callbacks, saves, and other shared work still go through the main thread.
The region map changes with the world: regions form, merge, split, and disappear as chunks load and unload.
Regional TPS: slicing instead of skipping
Tessellate measures every region each tick. If the server is about to miss its tick-time target, the most expensive region gets a tick divisor. A divisor of 4 runs that region at 5 TPS while unaffected regions can stay at 20.
Running the whole region once every fourth tick would produce the right average rate, but it feels awful in play. Tessellate spreads that work across every tick instead:
| Gated every fourth tick | Sliced across every tick | |
|---|---|---|
| Bystander TPS | 19.6 | 20.0 |
| Mean MSPT | 20.5 ms | 23.7 ms |
| p95 MSPT | 210.9 ms | 32.9 ms |
The trade-off
Throttling has an intentional cost: when a region exceeds its share, everything inside it runs slower. Mobs move more slowly, farms produce less, and hoppers move fewer items. That is useful for containing a lag machine, but Tessellate cannot tell one apart from a legitimately busy base.
If you would rather let the whole server fall below 20 TPS, disable adaptive throttling:
[regions]
adaptiveThrottling = falseRegion tracking, parallel ticking, and diagnostics remain available.
Configuration
Settings are stored in config/tessellate-common.toml.
| Option | Default | Purpose |
|---|---|---|
regions.enabled |
true |
Enables region tracking; disabling it makes the mod inert |
regions.adaptiveThrottling |
true |
Enables regional TPS control |
regions.budgetMillis |
25.0 |
Minimum budget retained for region work |
regions.targetTickMillis |
45.0 |
Tick-time target; raise it to intervene later |
regions.maxTickDivisor |
16 |
Slowest allowed region rate, 1.25 TPS |
regions.minThrottleMillis |
2.0 |
Regions cheaper than this are never slowed |
regions.sectionShift |
2 |
Region grid granularity, 4x4 chunks |
regions.parallelTicking |
true |
Runs independent regions on worker threads |
regions.directWorkerChunkReads |
true |
Resolves loaded worker chunk reads directly |
regions.parallelNaturalSpawning |
true |
Runs owner-region spawn searches concurrently |
regions.shardEntityStorage |
true |
Enables storage isolation required by parallel ticking |
regions.asyncRegionLoops |
true |
Lets regions run without a per-tick global join |
regions.scopedScheduledTicks |
true |
Uses region-owned block and fluid tick schedulers |
regions.scopedBlockEvents |
true |
Uses region-owned block-event queues |
For a serial diagnostic mode:
[regions]
parallelTicking = false
asyncRegionLoops = falseCommands
/tessellate regions: shows the region map, cost, tick rate, and execution mode/tessellate phases: reports worker/main-thread boundaries, timing, failures, and queue depth/tessellate violations: reports thread-ownership violations; this should remain empty/tessellate visualize: toggles the region map and boundary visualization
Compatibility
We tested independent region loops with:
- NeoForge alone
- Lithium 0.15.4
- Mekanism and Mekanism Generators 10.7.19.85
- Naturalist 2.0.3, Citadel 2.7.1, Friends & Foes 4.0.27, Resourceful Lib 3.0.12, and ScalableLux 0.3.0-alpha.0.8
- C2ME 0.4.0-alpha.0.120 with the full mod set above
Lithium needs a little special handling, so Tessellate replaces two of its level-wide caches with worker-safe equivalents. C2ME is optional; Tessellate runs without it and has no hard dependency on it.
What we tested
| Check | Result |
|---|---|
| JVM regression suite | 81 tests passed |
| Tessellate-only NeoForge GameTests | All 5 required tests passed |
| Scheduled ticks | 30 minutes, 422 rebuild cycles, no failure or queued work left |
| Block events | 30 minutes, 1,001,984 callbacks, packets stayed on the main thread |
| Natural spawning | Parallel overlap confirmed; global and local caps held |
| Deferred writes | 6,947 level writes and 2,592 entity callbacks replayed exactly |
| Full-mod save/unload | 1,200 entities survived a 49-chunk unload/reload exactly |
| Main-thread boundaries | 8,519 deferred operations balanced with zero pending work |
What it cannot do
- Tessellate protects the shared state it knows about, but another mod can still introduce a race through its own global state. Tessellate falls back to serial ticking when it detects an ownership violation.
- C2ME 0.4.0-alpha.0.120 passes live benchmarks, save/unload, restart, and shutdown testing, but its natural-spawning GameTest fails in both serial and parallel regional modes.
- One hot connected region cannot use another core under the current ownership model.
- Benchmark results are workload- and hardware-specific.
The Tessellate Team
Owner
