OritechDefender

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

1. Stop the server.
2. Back up the world, mods, and config directories.
3. Place the OritechDefender JAR in the server’s mods directory.
4. Make sure the supported Oritech 1.2.8 JAR is installed as oritech-neoforge-1.21.1-1.2.8.jar.
5. Start the server.
6. Run /oritechdefender status.
7. Confirm that Oritech is reported as SUPPORTED, then keep OBSERVE enabled through a representative peak-load period.
8. 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.