H-RAMWatch

H-RAMWatch

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 resource-intensive area and in a resource-intensive area. Active players will never be affected.

Features

- Lightweight: Automatically kicks players who are AFK and are loading an excessive number of chunks or are near a high concentration of entities. - Lightweight: A public command (`/hrw dashboard`) that displays live performance metrics for the server, worlds, and players. - Lightweight: - Enable or disable the AFK kicker on-the-fly with `/hrw toggle`. - Reload the configuration file without a server restart using `/hrw reload`. - Lightweight: Almost every aspect of the plugin can be changed in the `config.yml` file. - Lightweight: 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. Nearby Entities: 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: * Nearby Entities: 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.

```yml

--- 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: ```bash mvn clean package ``` The compiled JAR file will be located in the `target/` directory.