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.1 (Targeted)
Fabric Loader: 0.16.9 or newer
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.x → Fabric API for 1.21.x
• 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/maykeshs-secure-server.json)

The configuration file is automatically created on first run at:

config/maykeshs-secure-server.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).
• gracePeriodMs (long, default: 5000)
  • Time in milliseconds after joining where a player is immune to checks.
  • Useful for preventing false positives (like falling/phasing) during world loading.
• waitForAuth (boolean, default: true)
  • If true, grace period is extended indefinitely until the player runs /login or /register.
  • Once authenticated, the normal gracePeriodMs countdown begins.
• authTimeoutMs (long, default: 60000)
  • The maximum time (in milliseconds) a player has to authenticate after joining.
  • If waitForAuth is enabled and the player doesn't authenticate within this time, they will be kicked.
• allowOpBypass (boolean, default: true)
  • If true, players with Operator (OP) permissions (level 2+) or specific bypass permissions are ignored by security checks.
  • See PERMISSIONS.md for a full list of bypass permissions.

2.2 Chat & Command Checks (chat)

• enabled (boolean, default: true)
  • Master switch for chat and command rate limiting.
• maxMessagesPerSecond (int, default: 5)
  • Maximum number of chat messages allowed per second before being flagged as spam.
• maxCommandsPerSecond (int, default: 4)
  • Maximum number of commands allowed per second.
• kickOnViolation (boolean, default: true)
  • If true, players exceeding the rate limit are kicked (unless useCooldown is enabled).
• useCooldown (boolean, default: true)
  • If true, instead of kicking, the player is temporarily muted when exceeding the rate limit.
• cooldownSeconds (int, default: 10)
  • The duration (in seconds) the player is muted if useCooldown is enabled.

2.3 Packet Limits (packetLimit)

• maxPacketsPerSecond (int, default: 100)
  • The strict limit on incoming packets per second.
• kickOnViolation (boolean, default: true)
  • Whether to kick the player immediately upon exceeding the limit.

2.4 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.5 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.
• maxCps (int, default: 15)
  • Maximum clicks per second allowed (attacking/interacting) before flagging.

2.6 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.
• fastBreakLimit (int, default: 5)
  • Maximum number of blocks allowed to be broken in a short burst (defined by fastBreakIntervalMs).
  • Helps prevent Nuker hacks while allowing for efficiency tools.
• fastBreakIntervalMs (int, default: 50)
  • The time window in milliseconds for the fastBreakLimit.
• fastPlaceDelayMs (int, default: 50)
  • Minimum delay in milliseconds allowed between block placements.
  • Helps prevent FastPlace hacks.

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. Developer Features

3.1 Automatic Changelog Generation

When building the mod using ./gradlew build, a changelog.txt file is automatically generated in the build output directory (e.g., build/libs/1.0.x/changelog.txt).

• This file contains the last 20 git commits.
• Useful for tracking changes between versions.
• Requires the project to be a Git repository (which is automatically handled).

---

4. 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.

---

5. 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/maykeshs-secure-server.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.