New Chunk Alerts

A Paper server plugin that notifies players when they are generating brand-new chunks! Let players on your server know when they are exploring uncharted and unlooted territory. A lightweight, non-intrusive plugin, New Chunk Alerts takes advantage of the Paper API's PlayerChunkLoadEvent in tandem with Bukkit's ChunkLoadEvent to detect and notify players of newly generated chunks with great performance.

The plugin was written for the purpose of exploration, but it could also be introduced as an interesting way to find players on PvP-enabled servers! If a player isn't generating any chunks far from spawn, it's evident someone's been there and they could follow a sort of "chunk trail" by watching the New Chunk Alerts to find enemies.

In a new world's first few minutes, everyone will get lots of New Chunk Alerts! As players establish their bases and explore, New Chunk Alerts become less frequent and will only alert you to brand-new terrain! If early-game alerts get annoying, players can turn them off for themselves with /nca.

Requirements

This plugin uses a class exclusive to Paper's API, so the server software used must be Paper or a fork of Paper. New Chunk Alerts currently officially supports stable builds of Paper built for versions 1.21.11 through 26.2 of Minecraft.

Features

• After a chunk is generated, only the first eligible player whose client loads it can be alerted. Once an alert is sent for that chunk, it is removed from the notification map, preventing later false alerts for the same newly generated chunk.
• Won't significantly impact performance, especially on small to medium servers, due to careful solution laid out in the paragraphs below.
• Event-driven: if there are a ton of stationary or AFK players, or players within pre-generated chunks on your server, New Chunk Alerts simply ignores them!
• Each player can toggle chunk alerts simply by running /nca or /newchunkalerts.

Cracking this problem without commandeering the main server thread was more involved than initially thought, because ChunkLoadEvent's getPlayersViewingChunk() method will always return an empty list at generation time, and Paper's PlayerChunkLoadEvent doesn't offer any information on the recency of the chunk's generation.

To keep track of the chunks generated, in order, and to also achieve O(1) lookup and insertion times, chunks are kept track of in a Deque backed by a HashMap between generation and player loading time. A ChunkLoadEvent listener adds every brand-new chunk to both the Deque and the HashMap, and a PlayerChunkLoadEvent listener performs a lookup on the map if the player has alerts enabled and the cooldown has passed, and removes it if present. The same chunk will also be removed from the queue on the next cleanup.

This allows the plugin to hold onto chunks for notification until they are sent to the player's client, without having to perform an O(n) operation on every PlayerChunkLoadEvent. Even cleanup, which runs every 15s by default, is a summation of O(1) operations, meaning the total operation's timing is bound by the number of expired chunks.

Incompatibilities

• Pre-generated worlds (using plugins like Chunky, etc.): players are only alerted to chunks for which the ChunkLoadEvent's isNewChunk() method returns true, so this plugin will not notify players of chunks that have not yet been visited but have already been generated by another plugin.

Configuration

A default configuration file (plugins/NewChunkAlerts/config.yml) is generated upon running the plugin with your server for the first time. This is where the list of players who've disabled alerts is stored, but it also contains a few other important variables by default that server owners can tweak. The default values of these variables should work for the majority of servers, but feel free to tweak them as you see fit.

chunk-queue-cleanup-cooldown-ms (default equivalent to 15s): The number of milliseconds the plugin waits before repeating cleanup of the chunk queue. Decreasing this will simply make the plugin check for expired chunks more often.

chunk-queue-entry-expiration-time-ms (default equivalent to 3m): The number of milliseconds to retain a chunk in the queue after it is generated. Making this number too small will cause the plugin to "forget" new chunks before the player has time to trigger a PlayerChunkLoadEvent and be alerted. The default for this configuration option should be just fine for most servers. However, if the plugin doesn't seem to be working and players move very slowly on the server or have very low render distances, increasing this number and restarting the server may fix it.

max-queued-chunks (default = 100,000): The maximum number of chunks to allow in the queue. Once the queue exceeds this size, the oldest chunks in the queue are removed until the size of the queue is once again under this value. Try increasing this number if your server is extremely large and players are not correctly receiving alerts.

notification-cooldown-ms (default equivalent to 1m): The minimum number of milliseconds the plugin must wait before sending another notification to the same player.

Other Projects

Check out my other projects on either Modrinth or CurseForge:

modrinth.com/user/timnorthrop

curseforge.com/members/timnorthrop/projects

None of the code in this plugin is AI-generated. The same holds true for all of my plugins. If I needed generative AI to write simple Minecraft plugins, I would probably need to start looking for a new day job.