MekDefender

A NeoForge server protection mod for Minecraft 1.21.1 + Mekanism. One mekdefender project and one JAR provide:

• owner-aware chunk loading for Anchor Upgrade machines and the Dimensional Stabilizer;
• bounded latest-state synchronization for four proven-safe Mekanism S2C payloads.

Chunk-loading policy

When an owner logs out, Mekanism releases their loader tickets immediately or after the configured grace period. Login recovery is throttled. An ownerless loader is disabled by default; an ownerless/offline Dimensional Stabilizer also skips its energy drain.

MekDefender does not own a ticket controller or a Mekanism save format. Ticket changes still use Mekanism's code. The only isolated saved cache is world/data/mekdefender_loaders.dat (owner to loader positions). Removing this mod removes its mixins and Mekanism resumes its normal behavior; the orphaned cache is ignored.

Mek synchronization safety boundary

Only these replaceable absolute-state channels may be coalesced:

• mekanism:update_tile
• mekanism:network_scale
• mekanism:fluid_network
• mekanism:chemical_network

QIO, transporter, GUI/container/inventory, configuration, security, equipment, player data, C2S, vanilla, unknown payloads, and mixed bundles pass through unchanged. Payload classification, Mekanism Mixin call contracts, injection points, tracking revalidation, live-object resolution and fail-open behavior are fixed safety rules, not administrator configuration.

Byte budgets learn from the actual S2C packet sizes produced by Minecraft's packet encoder before compression, framing and encryption. Each channel keeps an EWMA; initialEstimatedBytes is used only until real samples arrive. If a learned size exceeds a configured burst, budget charging is capped at that burst so the latest state cannot be deferred forever. Diagnostics retain the raw EWMA. Byte telemetry is optional and never participates in the decision to cancel an original Mekanism send.

The default sync mode is OBSERVE, which records statistics without cancelling Mekanism sends. Use /mekdefender mode enforce for an in-memory runtime override after checking compatibility and statistics. Already accepted final states drain safely when the mode or a channel is disabled.

Unified configuration

The only configuration file is generated for the game/server instance at:

config/mekdefender-server.toml

It uses schemaVersion = 2 and contains:

• chunkLoading.*: owner policy, grace period, login reload budget and debug logging;
• sync.channels.<channel>.*: independent enable, interval, deadline and byte estimate;
• sync.budget.*: per-player/global payload and estimated-byte token budgets;
• sync.scheduler.*: queue, bundle, source-work, epoch, interval and overdue limits;
• sync.pressure.*: soft/critical pressure and recovery thresholds;
• sync.circuitBreaker.*: bounded internal-failure window and safe fallback mode;
• sync.metrics.*: hotspot/timing windows, actual encoded-byte EWMA and real-client A/B defaults;
• logging.* and permissions.*: cooldown/transition logging and read/admin OP levels.

Loading and reloading are atomic. Unknown sections or keys, duplicate declarations, invalid types, out-of-range values, a wrong schema and contradictory cross-field values reject the whole reload with a line-numbered error; the previous live snapshot remains active.

Game commands

/mekdefender status [compact|verbose]
/mekdefender compatibility
/mekdefender top [seconds] [limit]
/mekdefender channel <tile|scale|fluid|chemical>
/mekdefender player <name>
/mekdefender config <show|validate>
/mekdefender ab <status|start <seconds>|cancel>
/mekdefender mode <off|observe|enforce>
/mekdefender reload
/mekdefender resetstats

Status and channel output split source requests/replacements/materialization from recipient enqueue/replacement/send units. The displayed source and recipient reduction percentages are therefore ratios of like units. configuredMode and the in-memory runtimeMode are shown separately. The read and mutation OP levels are independently configurable.

/mekdefender ab start <seconds> requires the configured number of real, non-FakePlayer clients (two by default). It warms and measures equal OBSERVE and ENFORCE windows, then restores the previous runtime mode. The report compares actual pre-compression encoded S2C bytes and packets, average/p95 MSPT, derived TPS, and average/p95 player latency. Traffic during warm-up is excluded; a client count below the configured minimum or a phase with no safe Mek traffic marks the comparison invalid.

For a 30-minute window per phase (about one hour plus warm-ups), keep both clients on the same representative route and run:

/mekdefender ab start 1800

If the configured number of internal scheduler/hook failures occurs inside the circuit-breaker window while enforcing, the optimizer switches to the configured safe mode and stops accepting new work. Already accepted final states still drain. An administrator must explicitly run a mode command to clear the breaker and re-enable enforcement.

During sustained socket pressure, fluid and chemical absolute-state updates retain priority while tile and scale updates remain bounded and latest-write-wins. They resume with their newest state after recovery; this protects the server but is not a strict real-time delivery guarantee.

Measured optimization effect

The final integration JAR was tested on Youer 1.21.1-4a57297f with NeoForge 21.1.241, Mekanism 10.7.19.85, a world containing live Mekanism buffered networks, and two fixed FakePlayer recipients:

sourceRequested=25005
sourceReplaced=24981
payloadMaterialized=24
recipientSent=48
players=24/24
schedulerP95Ms=0.1887
networkIndexRebuilds=7
networkIndexScanned=21
networkIndexHits=72
failOpen=0

This is a 99.904% source coalescing rate: 24,981 / 25,005 = 99.904%. With exactly two recipients, the same controlled workload would have produced 50,010 uncoalesced recipient sends; MekDefender sent 48, also a 99.904% reduction for that fixed test topology. The result demonstrates the optimization path under a repeat-heavy network workload; it is not a universal reduction guarantee. Real production savings depend on update repetition, configured intervals, tracking players and actual machine/network activity. Use the real-client A/B command above to measure a specific server.

Building and tests

Requires JDK 21:

./gradlew test build integrationTestJar

The release artifact is build/libs/mekdefender-1.2.0.jar. mekdefender-1.2.0-integration-test.jar is a separate disposable-world test variant and is never included in the release JAR.

The build downloads mekanism:Mekanism:1.21.1-10.7.19.85 from ModMaven as a reproducible compile/test baseline. That artifact does not restrict runtime compatibility, and Mekanism is not bundled in MekDefender. Development server runs additionally need the Mekanism build under test in run/mods/.

Property-gated test harnesses:

• -Dmekdefender.integrationTest=true: owner online/offline, energy and login recovery;
• -Dmekdefender.syncIntegrationTest=true: dual-FakePlayer Mek sync scheduler stress.

Compatibility

• Minecraft 1.21.1
• NeoForge 21.1.194 or newer in the 1.21.1 line
• A Mekanism build for Minecraft 1.21.1 that retains the required Mixin contracts
• Java 21

A shared compatibility plugin checks only the methods, fields and invocation sites transformed by the chunk-loading and synchronization Mixins. Unrelated Mekanism bytecode changes remain compatible. Compatibility is reported per feature: a missing transformation contract disables only that feature and leaves it in pass-through behavior. The reference build was tested with Mekanism 10.7.19.85 and was also smoke-tested in a pure NeoForge 21.1.241 development server, not only Youer; formal production acceptance still requires the release JAR and real clients under representative load.