kuohsuanlo/chunkguardagent

ChunkGuardAgent is a small Java agent that attaches to a Minecraft server, specifically Paper or Folia servers, to stop a specific kind of world data corruption. In Minecraft, a world is split into pieces called chunks, and when a server runs critically low on memory while loading one, that load can fail, and the game quietly substitutes a blank placeholder for it. The real danger comes later: if the server then saves that blank placeholder to disk before it fully recovers, it can overwrite the actual, good chunk data already saved, permanently destroying a piece of a player's world. The author noticed that if a server happens to crash before that bad save reaches disk, the original good data survives on its own. This tool turns that lucky accident into something guaranteed: it refuses to let a failed blank chunk get written over good existing data. To decide when to block a save, it does not look at file size, since a chunk a player intentionally cleared out can also be small. Instead it checks the chunk's internal status field, which in Minecraft only ever moves forward through a fixed set of stages and never backward. A failed, blank chunk is always stuck in an early stage, while even a chunk a player emptied out by hand still reaches the final stage. So the rule is simple: only skip a save when new data is unfinished but the version already on disk is finished, since that can only mean corruption. On a real production server with many plugins, the author reports it inspected over ten thousand real save events with zero incorrect blocks. It is designed to use very little memory at the exact moments when the server is already short on memory, falling back to reading only a small piece of file header information when memory is critically low. Later versions added two more protections: one that checks how long a chunk has actually been inhabited by players, to avoid a freshly regenerated but empty looking area overwriting an old, long lived chunk, and one that repairs chunk data on read if mislabeled but still intact, so the game does not regenerate over it and wipe out what remains. Installation is done by adding a Java agent flag when starting the server, and it includes a safe trial mode that only logs what it would have blocked.