TickWeave

TickWeave

TickWeave 0.3.0-beta provides targeted, configurable optimizations for
Minecraft Java 26.3 and Java 25. Separate builds support Forge 66.0.9,
Fabric Loader 0.19.5 and NeoForge 26.3.0.76. Use the build matching your
loader. Other loader versions and Quilt are not validated by this release.

TickWeave works on dedicated servers, integrated single-player servers, LAN hosts
and multiplayer clients. Each installation optimizes its own process; the other
side does not need TickWeave. Installing it only on a multiplayer client does not
optimize the remote server’s hoppers or change network latency.

What changes

• Small eligible entity-section queries use bounded direct lookups, retaining
  vanilla ordering, visibility checks and early termination. Large or unsuitable
  queries use the original path.
• Vanilla block hoppers reuse one immutable suction bounding box while its source
  geometry and position remain identical. This does not cache entities, inventories
  or query results. Unsupported shapes and hopper implementations fall back.
• The Forge build avoids allocating the iterator for the supported empty multipart
  entity collection. Nonempty or unfamiliar collections keep the original path.

No blocks, items or network protocol are added. Tick frequency, hopper cooldowns,
redstone, AI, farm rules and world formats are preserved. Removing the mod does not
remove world content. The mod does not load client classes on a dedicated server.

Install and configure

1. Use Minecraft 26.3, Java 25 and one of the exact tested loaders above.
2. Stop the game or server and back up the world before changing its mod setup.
3. Put exactly one matching TickWeave JAR in that instance’s mods directory.
4. Start the instance. Settings are created in config/tickweave.properties.

directSectionLookup=true
maxDirectSections=64
cacheHopperSuctionShape=true
emptyMultipartIterator=true

emptyMultipartIterator affects Forge only. maxDirectSections accepts 1–64 and
limits optimization eligibility, not query results. Restart after changing a
setting. Disabled optimizations are skipped before their Mixins are applied.
Unreadable or malformed configuration disables all TickWeave optimization Mixins.
An existing 0.2 TOML configuration supplies the old section-query settings when
no properties file exists; the old file is retained.

Lithium, Canary or Radium detected at startup disable TickWeave’s optimizations to
avoid overlapping transformations. Real Lithium 0.26.2 coexistence was checked
on Fabric and NeoForge. This does not establish compatibility with every modpack.
Sodium, ModernFix, FerriteCore and other combinations not listed in the test report
remain untested. Fabric API is not required.

Measurements and limits

The controlled dedicated-server comparison used 0.2.0-beta versus 0.3.0-beta,
18 completed runs, three repetitions per variant and workload in A–B–B–A–A–B
order. Each fresh process used the same world, 60 seconds of warm-up and 60 seconds
of measurement at the normal 20 TPS target. Hardware: i7-11800H, 16 GB RAM,
Windows 11, Java 25.0.4.1+1, Forge 66.0.9, 2–4 GiB G1 heap.

The following numbers are medians of the respective per-run metrics, not pooled
samples. Markers populate the section index; they do not simulate active mobs.

In these hopper workloads allocation on the server thread fell by 20.90% and
18.22%. Mean active tick time fell by 0.16% and 5.37%. Both versions
already maintained approximately 20 TPS. Idle allocation increased slightly.
Allocation includes work between ticks on that thread; it is not whole-process
allocation or resident memory.

There was no general GC or memory improvement: median GC pause sums increased
from 18.833 to 26.257 ms for hoppers and from 20.074 to 47.984 ms with markers.
Sampled heap results were mixed. Three short repetitions on one machine are
limited descriptive evidence, not a promise for other worlds or hardware.

See BENCHMARK-DE.md and the accompanying raw evidence for all measurements,
including the excluded client benchmark attempts and their recorded failure reasons.
The client performance comparison is unavailable: three attempts were excluded after a control-path mismatch or a minimized-window rendering-surface failure, including a failure with the unchanged 0.2 baseline. Completed functional client tests remain valid. No partial client series is used as performance evidence.
No general FPS gain, shorter physical input latency or reduced network ping is
promised. Client wall-time instrumentation does not measure displayed frames or
input-to-photon latency. Dedicated results cannot be extrapolated to other loaders.

Validation

All three builds underwent actual integrated-client and dedicated-server startup,
hopper/redstone/entity checks, saving and reloading. Forge also passed multipart
entity checks and real loopback interoperability in both directions: a vanilla
client joining the TickWeave LAN host and a TickWeave client joining a vanilla
server. The dedicated Forge test included a vanilla client, dimension teleports
and distant chunk exploration. Fabric and NeoForge have their own functional
checks and real Lithium coexistence runs.

Automated suites passed 23 tests on Forge and 18 each on Fabric and NeoForge,
including 20,083 section-query differential cases with 40,209 assertions and 10,000
random geometry cases. Fabric’s complete suite was run through a standalone JUnit
launcher against the release artifact and verified runtime classpath; it is not
represented as a successful full Gradle test run.

Windows and the recorded loader/Java combinations are tested. Authenticated
Internet play, a second physical LAN machine, every launcher, other operating
systems, prolonged farms and arbitrary modpacks remain untested. Local network
tests used isolated loopback-only offline identities; this is a test setup, not a
requirement for normal installation. See TESTS-DE.md for exact scope and excluded
failed or interrupted test-fixture runs.

Source and license

TickWeave code is MIT licensed. The source archive contains all three loader
projects, the Gradle wrapper, tests and measurement-tool sources. Game binaries,
Java, worlds and account data are not distributed. Test agents are not runtime
dependencies and must not be placed in mods.

The source and test-data archives referenced above are prepared in the author’s local release package. They are not included in the installable CurseForge JAR downloads; no public archive link is provided here yet.