Maykesh's Secure Server Mod Documentation

This documentation describes how to install, configure and operate Maykesh's Secure Server Mod, a military‑grade, server‑side anti‑cheat and security layer designed to protect the hub server.

---

0. Installation & Compatibility

Minecraft Version Support: 1.21.x (tested on 1.21.1 through 1.21.8)
Fabric Loader: 0.16.9 or newer (Tested on 0.16.10)
Java: 21

Important Requirements

• Install Fabric API for your exact Minecraft version:
  • Minecraft 1.21.1 → Fabric API for 1.21.1
  • Minecraft 1.21.8 → Fabric API for 1.21.8
• Place this mod on the server only. It is fully server‑side and does not require clients to install anything.
  • Singleplayer Support: You can also install this in your local mods folder to protect your Singleplayer world or LAN server.

---

1. What This Mod Does

Maykesh's Secure Server Mod hardens your hub server (or singleplayer world) against common and advanced cheats by monitoring player behavior on the server side and applying restrictions when abnormal behavior is detected.

Movement Security

• Speed / Timer: Detects players moving faster than allowed on the ground.
• Flight / Hover: Detects players staying in the air without proper support or gravity.
• Phase / NoClip: Detects players clipping through solid blocks.
• NoFall: Detects spoofed ground state to avoid fall damage.

Combat Security

• Reach Check: Validates that attack distance is within legitimate survival reach.
• Aura / Heuristic Check: Detects KillAura‑style behavior using aim angle and attack patterns.

Interaction & World Security

• FastBreak / Nuker: Detects breaking multiple blocks in unrealistically small time windows.
• FastPlace / Scaffold: Detects block placement spam significantly faster than humanly possible.

Packet & Network Security

• Packet Rate Limiter: Caps the number of packets a player can send per second to prevent spam and packet‑based exploits.
• Bad Packet Filter: Guards against malformed or dangerous packets (e.g. invalid coordinates) that can destabilize the server.

When a player violates a check too many times, the default action is to kick them from the server with a clear “Security Alert” message.

---

2. Configuration (config/security_config.json)

The configuration file is automatically created on first run at:

config/security_config.json

The file is structured into several sections that match the internal configuration classes.

2.1 General (general)

• kickEnabled (boolean)
  • If true, players who fail checks too many times are kicked.
  • If false, checks still run but only log/punish internally (no kick).

2.2 Packet Limits (packetLimit)

• maxPacketsPerSecond (integer, default: 100)
  • Maximum number of packets a player may send per second before being considered suspicious.
• kickOnViolation (boolean, default: true)
  • If true, exceeding the packet limit repeatedly will kick the player.
  • If false, packets are still monitored but the player is not automatically kicked.

2.3 Movement Checks (movement)

• enabled (boolean, default: true)
  • Master switch for all movement checks.
• maxSpeedHorizontal (double, default: 0.5)
  • Maximum allowed horizontal speed (blocks/tick) before the speed check starts flagging.
• checkFlight (boolean, default: true)
  • Enables/disables flight detection.
• checkPhase (boolean, default: true)
  • Enables/disables block‑clipping detection.
• checkNoFall (boolean, default: true)
  • Enables/disables NoFall detection.

2.4 Combat Checks (combat)

• enabled (boolean, default: true)
  • Master switch for all combat checks.
• maxReach (double, default: 3.5)
  • Maximum allowed attack reach in blocks. Anything beyond this is flagged.
• checkAura (boolean, default: true)
  • Enables/disables the KillAura heuristic analysis.

2.5 World / Interaction Checks (world)

• enabled (boolean, default: true)
  • Master switch for block interaction checks.
• checkFastBreak (boolean, default: true)
  • Enables detection of Nuker / FastBreak behavior.
• checkFastPlace (boolean, default: true)
  • Enables detection of FastPlace / Scaffold behavior.

All of these fields are mapped directly in SecurityConfig, so changes in the JSON are applied when the server starts or when the config is reloaded via a restart.

---

3. How Detection Works (High‑Level)

• Each player is assigned a UserChecks profile internally.
• For every relevant event:
  • Movement events call movement checks (speed, flight, phase, nofall).
  • Attack events call combat checks (reach, aura).
  • Block break/place events call interaction checks (fastbreak, fastplace).
  • Packet receive events feed into the packet‑rate limiter.
• Each check increments an internal violation counter when something suspicious is detected.
• Once the counter exceeds the allowed limit for that check, corrective action is taken (by default: kicked).

This architecture keeps the system modular and easier to extend with new checks later.

---

4. Installation Steps

1. Download the built JAR for Maykesh's Secure Server Mod (e.g., maykeshs-secure-server-mod-1.0.x.jar).
2. Place the JAR into your server’s mods folder.
3. Ensure dependencies are installed:
   • Fabric Loader (0.16.9 or newer)
   • Fabric API matching your Minecraft version
4. Start the server once to generate config/security_config.json.
5. Edit the config file to tune detection aggressiveness and restrictions for your network.
6. Restart the server to apply configuration changes.

Once running, the mod immediately begins protecting the server that is running your hub mod, aiming to make it effectively un‑hackable for real‑world clients while remaining fully server‑side and transparent to legitimate players.