H-RAMWatch

!API !Java

H-RAMWatch is a lightweight but powerful server management plugin for PaperMC, specifically designed to protect server performance on resource-constrained hardware. Its core function is to act as a "smart resource limiter" that identifies and gently removes players who are both idle (AFK) and located in an area that consumes excessive server resources.

The plugin's core philosophy is to only target players who are both idle (AFK) and in a resource-intensive area. Active players will never be affected.

Features

• Smart AFK Limiter: Automatically kicks players who are AFK and are loading an excessive number of chunks or are near a high concentration of entities.
• In-Game Resource Dashboard: A public command (/hrw dashboard) that displays live performance metrics for the server, worlds, and players.
• Live Admin Controls:
  • Enable or disable the AFK kicker on-the-fly with /hrw toggle.
  • Reload the configuration file without a server restart using /hrw reload.
• Fully Configurable: Almost every aspect of the plugin can be changed in the config.yml file.
• Permission-Based: Fine-grained permissions allow you to control who can use admin commands and who should be exempt from being kicked.
• Lightweight: The plugin is designed to have a minimal performance impact, running its checks asynchronously and scheduling API calls on the main thread for safety.

How It Works: A Technical Breakdown

The plugin's logic cycle is a multi-stage process designed for safety and efficiency. This ensures that the plugin itself does not contribute to server lag.

1. Asynchronous AFK Detection: The plugin runs a low-impact, asynchronous task to monitor player activity (movement, chat, etc.). If a player's inactivity exceeds the configured time, they are flagged as AFK. This check happens off the main server thread.

2. Synchronous Resource Scan: Once a player is flagged as AFK, a new task is scheduled on the main server thread to safely query the game world. It measures two key proxies for server load:

   • Loaded Chunks: Counts the number of chunks loaded within the player's client-side view distance. This is a strong indicator of both memory (RAM) and CPU tick cost.
   • Nearby Entities: Counts the number of entities within a configured radius. This is a direct indicator of AI processing load.

3. Decision and Action: The results of the scan are compared against the configured thresholds. If a player exceeds either limit, the plugin initiates the warning or kick process as defined in the configuration. All subsequent actions, like sending messages or kicking the player, are also handled safely on the main thread.

Installation

1. Download the latest release JAR file.
2. Place the H-RAMWatch-X.X.X.jar file into your server's /plugins directory.
3. Start your server to generate the plugins/H-RAMWatch/config.yml file.
4. Stop the server, edit the config.yml to your liking, and start it again.

Commands & Permissions

Command	Permission	Default	Description
/hrw dashboard [server|worlds|players]	hramwatch.dashboard	true	Displays the resource usage dashboard.
/hrw toggle	hramwatch.toggle	op	Toggles the AFK kicker on or off live.
/hrw reload	hramwatch.reload	op	Reloads the plugin's configuration file.
(No command)	hramwatch.bypass	op	Grants immunity from being kicked by the AFK limiter.

Configuration (config.yml)

The default configuration is well-balanced, but you can customize it to fit your server.

# --- H-RAMWatch Configuration ---

# How often (in seconds) the plugin should check players for high resource usage.
check-interval-seconds: 30

afk-kick:
  # Should the AFK kicker be enabled when the server starts?
  enabled-by-default: true

  # Time in minutes a player must be inactive to be considered AFK.
  afk-time-minutes: 10

  # If an AFK player has more than this many chunks loaded in their view, they are a candidate for kicking.
  chunk-threshold: 500

  # If an AFK player has more than this many entities within the check-radius, they are a candidate for kicking.
  entity-threshold: 250

  # The radius (in blocks) around the player to check for entities.
  entity-check-radius: 64

  # Set to true to send a warning message before kicking the player.
  warning-enabled: true
  
  # Message sent to the player if they are over the limits and warning-enabled is true.
  warning-message: "&c[Warning] You are AFK in a resource-intensive area and may be kicked soon."

  # The message shown to the player when they are kicked.
  kick-message: "&cYou were kicked for being AFK in a resource-intensive area.\n&eThis is done to keep the server running smoothly for everyone!"

Building from Source

To build the plugin yourself, you'll need:

• Java 17 (or newer)
• Apache Maven

Clone the repository and run the following command from the project's root directory:

mvn clean package

The compiled JAR file will be located in the target/ directory.