Tessellate

Tessellate

Tessellate is a performance mod for Minecraft 1.21.1 on NeoForge and Fabric. It splits distant loaded areas into separate regions, then runs those regions on different CPU cores.

That matters when players are spread across the world. A busy base in one region can no longer hold up every other region, and if one area becomes too expensive, Tessellate can slow that area down while the rest of the server stays responsive.

Situation	What happens
Several distant bases are busy	Their regions run at the same time
One region exceeds the server's budget	Only that region's simulation rate is reduced
Two regions move close enough to interact	They merge before ticking
A worker touches unsafe shared state	Tessellate switches to serial ticking for the session

Tessellate works best on servers where players or force-loaded areas are spread out. One dense base, mob farm, or machine cluster still belongs to one region, so that work cannot be divided across multiple cores. Tessellate also does not replace single-thread optimizers such as Lithium; the two solve different problems.

Requirements and installation

• Minecraft 1.21.1
• NeoForge 21.1.x
• Java 21
• No required optimization-mod dependencies

Put the JAR in the server's mods folder. Installing it on clients is optional. Players with the mod get the GPU-rendered region map and boundary overlay; everyone else can use the particle fallback.

Performance

We benchmarked four force-loaded regions placed 2,048 blocks apart, with 1,200 persistent zombies in each region. Parallel ticking reduced 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, and Java 21 with the same nine mods installed.

This test deliberately favors a workload with several separate regions. It does not predict the improvement on every server. Hardware, region layout, entity count, and installed mods all affect the result.

How it works

Tessellate divides the loaded world into 4×4-chunk sections. Nearby entity-ticking sections are joined into a region so anything close enough to interact stays on the same worker. Regions that are far enough apart can run in parallel.

Not everything leaves the main thread. Packets, lifecycle callbacks, saves, and other shared work still run there. The region map is also temporary: regions form, merge, split, and disappear as chunks load and unload.

Regional TPS: slicing instead of skipping

Tessellate measures the cost of every region on each tick. When the server is about to miss its tick-time target, the most expensive region receives a tick divisor. A divisor of 4 means that region runs at an effective 5 TPS while unaffected regions can remain at 20 TPS.

The simple way to do that would be to run the entire region once every fourth tick. The average rate would be correct, but players would feel a large hitch every time the region ran. Tessellate spreads the work across all four ticks instead.

	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

Slicing trades a slightly higher average MSPT for much smaller spikes, which is usually the difference players notice.

The trade-off

Throttling slows everything inside the affected region. Mobs move more slowly, farms produce less, and hoppers transfer fewer items. This can contain a lag machine, but Tessellate cannot tell a lag machine from a legitimately busy base.

If you would rather let the whole server fall below 20 TPS, turn adaptive throttling off:

[regions]
adaptiveThrottling = false

Region tracking, parallel ticking, and diagnostics will continue to work.

Configuration

Settings are stored in config/tessellate-common.toml.

Option	Default	What it controls
regions.enabled	true	Region tracking; disabling it makes Tessellate inert
regions.adaptiveThrottling	true	Regional TPS control
regions.budgetMillis	25.0	Minimum time reserved for region work
regions.targetTickMillis	45.0	Target tick time; raise it to intervene later
regions.maxTickDivisor	16	Lowest allowed region rate: 1.25 TPS
regions.minThrottleMillis	2.0	Regions cheaper than this are never slowed
regions.sectionShift	2	Region grid size: 4×4 chunks
regions.parallelTicking	true	Runs independent regions on worker threads
regions.directWorkerChunkReads	true	Resolves loaded chunk reads directly on workers
regions.parallelNaturalSpawning	true	Runs owner-region spawn searches concurrently
regions.shardEntityStorage	true	Enables the storage isolation needed for parallel ticking
regions.asyncRegionLoops	true	Lets regions run without a global join on every tick
regions.scopedScheduledTicks	true	Uses region-owned block and fluid tick schedulers
regions.scopedBlockEvents	true	Uses region-owned block-event queues
compatibility.rulesEndpoint	Public rules service	Downloads reviewed compatibility rules; leave blank to disable
compatibility.rulesApiKey	Public key	Read-only key used to download rules
compatibility.reportEndpoint	Blank	Optional reporting service; leave blank to disable uploads
compatibility.reportApiKey	Blank	Public key used only when reporting is enabled

To temporarily use serial regional ticking while diagnosing a problem:

[regions]
parallelTicking = false
asyncRegionLoops = false

Commands

• /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 lists thread-ownership violations. This should stay empty.
• /tessellate visualize toggles the region map and boundary display.

Compatibility

Independent region loops have been tested 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 special handling, so Tessellate replaces two of its level-wide caches with worker-safe versions. C2ME is optional; Tessellate has no hard dependency on it.

Compatibility reports and automatic fixes

Some mods assume every entity and block entity runs on the main server thread. Parallel ticking can expose that assumption. If Tessellate detects one of these failures, it switches to a safer execution mode and writes the details to the normal server log.

Server owners may also send a small compatibility report. These reports help identify repeatable conflicts without requiring a full log or hours of trial-and-error configuration changes.

A report may contain:

• Minecraft, Tessellate, and mod-loader versions
• Installed mod IDs and versions
• The Tessellate component that encountered the problem
• The failure class
• The suspected mod and one relevant code location
• The entity or block-entity type, when known

Reports do not contain raw server logs, server addresses, world names, player names, chat, coordinates, or player data. The service does not store the sender's IP address with a report; it derives a one-way value used only for rate limiting.

A report is evidence, not a rule. It cannot block a mod or change a server by itself. The maintainer reviews grouped reports before fixing the issue in Tessellate, reporting it upstream, or publishing a version-specific compatibility rule. If a problem exists in version 1.1 of a mod but is fixed in 1.2, for example, the rule can apply only to 1.1.

Compatibility rules can:

• Move one entity or block-entity type to the main thread
• Prevent entity tick bodies from overlapping
• Disable parallel natural spawning for one mod
• Use serial region ticking when the problem cannot be isolated

Remote rules can only reduce concurrency. They cannot enable features, modify worlds, run commands, or upload data.

Opting out

Compatibility reporting is off by default. With a blank reportEndpoint, failures stay in the local server log and nothing is uploaded.

To explicitly disable reporting:

[compatibility]
reportEndpoint = ""
reportApiKey = ""

Remote rules are separate from reporting. By default, Tessellate checks a public, read-only rules list during startup so it can work around known problems.

To disable that check:

[compatibility]
rulesEndpoint = ""
rulesApiKey = ""

Neither service is required for startup. If the rules service is unavailable or a report upload fails, the server continues normally with its local configuration.

What we tested

Check	Result
JVM regression suite	106 tests passed
Tessellate-only NeoForge GameTests	All 7 required tests passed
Scheduled ticks	30 minutes, 422 rebuild cycles, no failures 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	All 1,200 entities survived a 49-chunk unload and reload
Main-thread boundaries	8,519 deferred operations balanced with no pending work

Current limitations

• Tessellate protects the shared state it knows about, but another mod can still introduce a race through its own global state. A detected ownership violation causes Tessellate to fall back to serial ticking.
• C2ME 0.4.0-alpha.0.120 passes live benchmarks, save/unload, restart, and shutdown tests, 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.
• Benchmarks are specific to their workload and hardware.

Known incompatibility

Bukkit hybrids for NeoForge or Fabric, such as Arclight, may load but are not fully supported. Bukkit's threading model is not compatible with Tessellate's parallel region ticking.