MekDefender

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.