OritechDefender

OritechDefender is a server-side NeoForge performance mod that reduces redundant encoding and delivery generated by Oritech machine synchronization.

When the same Oritech block entity produces multiple absolute-state updates in a short period, OritechDefender keeps the latest state and delivers it safely according to real chunk tracking, connection writability, and bounded send budgets.

The default mode is OBSERVE. It records real statistics without changing packet delivery. Administrators can review the results before switching to ENFORCE.

Features

Coalesces Oritech TICK and SPARSE_TICK absolute-state updates;
Keeps only the latest pending state for each block entity;
Sends updates only to players who are actually tracking the relevant chunk;
Uses an independent queue for every player, so a slow connection cannot block healthy players;
Applies payload-count budgets, estimated-byte budgets, and Netty backpressure;
Revalidates the dimension, chunk, block entity identity, and player tracking state immediately before sending;
Reports real request, encoding, coalescing, delivery, deferral, and backlog statistics;
Can switch to OFF at any time to restore Oritech's original delivery path.

Real-World Results

The following cumulative statistics were recorded during a long-running session on a real server:

Type	requested	encoded	Encoding reduction
TICK	4,768,552	1,076,220	About 77.43%
SPARSE_TICK	123,237	120,114	About 2.53%
Total	4,891,789	1,196,334	About 75.54%

Encoding reduction is calculated as 1 - encoded / requested. Results depend on machine count, player count, chunk tracking, and configuration. Encoding reduction is not the same as network-interface traffic reduction.

Safety Boundaries

OritechDefender manages only Oritech TICK and SPARSE_TICK broadcasts:

INITIAL, GUI_OPEN, GUI_TICK, and CUSTOM always pass through;
Targeted sendUpdate(type, player) synchronization always passes through;
Machine ticking, energy, items, fluids, recipes, NBT, and world data are not modified;
It does not force chunks to load;
It does not write world SavedData;
Optimization remains disabled when the version or exact injection points do not match;
A full queue, failed thread or entity validation, or an encoding exception preserves the original delivery path.

OritechDefender does not require a world-data migration. Stop the server and remove its JAR to return to an uninstalled state.

Requirements

Minecraft: 1.21.1
Mod loader: NeoForge 21.1.240 or newer within the 21.1.x line
Oritech: 1.2.8
Installation side: Server only
Java: 21

OritechDefender verifies the full Oritech 1.2.8 JAR fingerprint and the required Mixin injection points. A different, modified, or unsupported Oritech build is reported as PASS_THROUGH; optimization is not forced.

Installation

Stop the server.
Back up the world, mods, and config directories.
Place the OritechDefender JAR in the server's mods directory.
Make sure the supported Oritech 1.2.8 JAR is installed as oritech-neoforge-1.21.1-1.2.8.jar.
Start the server.
Run /oritechdefender status.
Confirm that Oritech is reported as SUPPORTED, then keep OBSERVE enabled through a representative peak-load period.
After confirming that the statistics and server state are healthy, run /oritechdefender mode enforce.

Clients do not need to install OritechDefender.

Commands

`/oritechdefender status`

Displays the current mode, compatibility gate, hook activity, request/encoding/ coalescing/delivery counters, scheduler timing, backlog, backpressure, invalidation, and fail-open statistics.

`/oritechdefender top [1..60]`

Displays the busiest dimensions, chunks, and Oritech synchronization types in the selected time window.

`/oritechdefender player <name>`

Displays the selected player's pending count, oldest-entry age, previous-tick delivery volume, connection writability, and pressure state.

`/oritechdefender mode <off|observe|enforce>`

OFF: Uses Oritech's original delivery behavior.
OBSERVE: Records statistics without changing delivery.
ENFORCE: Enables safe coalescing, independent queues, and backpressure.

This command requires permission level 2. The selected mode is persisted in the configuration file.

`/oritechdefender reload`

Reloads the configuration. Requires permission level 2.

`/oritechdefender resetstats`

Clears accumulated statistics. Requires permission level 2.

Reading the Statistics

requested: Synchronization requests initiated by Oritech;
encoded: Oritech payloads that were actually encoded;
coalesced: Requests replaced by a newer state and therefore not sent separately;
sent: Recipient-payloads actually delivered to players;
deferred: Scheduling attempts postponed by a budget or backpressure;
pending: States currently waiting in a player queue;
oldest: Age of the oldest pending entry;
failOpen: Times a failed safety check preserved the original path;
queueFull: Times a bounded queue reached its configured limit.

sent may be higher than encoded because one encoded payload can be delivered to multiple players who are tracking the same chunk.

Recommended Rollout

OBSERVE → ENFORCE → OFF if needed

Keep OBSERVE enabled during a representative peak-load period and save the output of status and top 60 before enabling ENFORCE. If a problem appears, immediately run:

/oritechdefender mode off

Configuration

The first server start creates:

config/oritechdefender-server.toml

Default minimum synchronization intervals:

TICK: 10 ticks
SPARSE_TICK: 100 ticks

The defaults prioritize state freshness and safe rollback. Increasing these intervals may reduce more encoding, but it also increases visible client-side state latency. Aggressive changes are not recommended without controlled comparison testing.

Reporting Issues

When reporting a problem, include:

Minecraft, NeoForge, OritechDefender, and Oritech versions;
Redacted output from /oritechdefender status;
The current configuration file;
Minimal reproduction steps;
Relevant logs and exception stack traces;
Whether switching to OFF stops the problem.

Remove server addresses, player information, authentication tokens, RCON passwords, and other sensitive data before posting.