ChunkReceipt | Chunk Reports & Comparisons [1.18.2-26.2]

Find concentrations of entities, container blocks and hopper blocks without changing the world. Take a report before adjusting a farm, take another afterwards and compare the same coordinate sample.

Features

• Scan loaded chunks gradually with a per-tick chunk limit, soft time budget and hard scan cap.
• Rank chunks by entities, container blocks or hopper blocks.
• Export CSV rows and text reports with entity-type and block-entity-type totals.
• Keep two reports per world. Compare totals only when both scans cover the same nonempty coordinate sample.
• Skip unloaded, incomplete or entity-unloaded chunks; no chunk tickets or forced entity loading.
• Administrator-only commands and coordinates.
• No external plugin, service, telemetry or network requests.

Counts help you choose places to investigate. They do not measure tick cost or prove what causes lag. ChunkReceipt does not remove entities, edit blocks or inventories, teleport players or automatically optimize the server.

Install and try it

1. Stop the server, place ChunkReceipt-1.0.0.jar in plugins/, and start it normally.
2. As an operator, run /chunkreceipt scan. Console must specify a loaded world: chunkreceipt scan world.
3. Wait for completion and export messages, then run /chunkreceipt top hoppers.
4. Inspect the reported coordinates and make your own changes if appropriate.
5. After the cooldown, scan the same loaded area again and run /chunkreceipt compare.

If the scanned coordinate sample changed, the plugin explains why totals cannot be directly compared.

Commands and permission
chunkreceipt.admin defaults to operators. All commands and tab completion require it. Reports reveal world/chunk coordinates, so grant access only to administrators.

scan defaults to the player's current world. Console must provide a loaded world name. World names with spaces can be written directly after scan, without quotes. Only one scan runs at a time. cancel discards unfinished results and keeps the scan-start cooldown.

top and compare use the world of the most recently completed scan, regardless of your current world. status identifies that world. Two completed reports are kept per world in memory. Restarting resets in-game comparison history; finish two new scans of the same world to compare again. Disk exports remain and continue rotating.

Configuration
plugins/ChunkReceipt/config.yml

• chunks-per-tick: integer 1-100; maximum chunks read per tick.
• max-chunks: integer 1-20000; scan cap, selected in ascending x then z order. Omitted chunks are reported.
• tick-budget-ms: integer 1-25; soft deadline before starting another chunk. One busy chunk can exceed it.
• cooldown-seconds: integer 1-3600; global delay between scan starts, including cancelled scans.
• top-limit: integer 1-50; maximum displayed ranking rows.

/chunkreceipt reload validates the whole configuration. Invalid edits leave current settings active; a running scan keeps its starting settings.

The initial loaded-chunk list and coordinate selection run on the server thread. The per-tick budget covers individual chunk reads, not that initial snapshot. Start conservatively on large servers.

Exports
CSV contains one row per scanned chunk with UTC times and counts. Text reports include sample scope and type totals. Only two versions per world are retained; copy files elsewhere for longer history.

Only immutable data enters the bounded background writer. Each file is replaced atomically; all four files are not a single transaction. Match files by UTC times. Export errors are reported while the report remains available in memory. Filesystems without atomic-move support report an error instead of partially overwriting existing files. Shutdown waits up to two seconds for exports before cancelling queued work.

Counting details

• Only chunks loaded at scan start are selected. Chunks that unload, are not fully generated or have unloaded entities at read time are skipped completely. Unloading the world cancels the scan.
• Containers are blocks implementing Bukkit Container. Double-chest halves count separately. Inventory contents are not opened or inspected.
• Hopper blocks also count as containers and block entities. Hopper minecarts count only as entities.
• All entity types are counted, including anonymous PLAYER totals. Player names, player UUIDs, IP addresses, inventory contents and item metadata are not exported. An initiating administrator UUID is held transiently in memory for completion notices.
• Counts are collected across ticks; entity movement can affect even identical coordinate samples. This is not an instantaneous snapshot or performance profiler.
• Folia and proxy servers are unsupported.

Multi-version compatibility and verification
Target range: Spigot/Paper 1.18.2-26.2. Compiled against Spigot 1.18.2 with Java 17 bytecode. Use the Java version required by your server. Stable Bukkit APIs avoid the need for packet-library or NMS dependencies.

15 module tests pass, covering configuration, ranking, valid comparisons, immutable data, CSV formula safety, report rotation and unloaded chunk/entity handling. Source compilation also passes against Spigot 1.19.4, 1.20.4, 1.20.6, 1.21.11, 26.1.2 and 26.2. The release JAR passes MockBukkit loading, lifecycle, reload and permission checks in 1.18.2, 1.21.11 and 26.2 API environments. These simulated-server tests are not live Minecraft gameplay or performance tests and do not verify every intermediate build. The Tested Major MC Versions field is left empty for that reason.

Documentation, source and feedback
See the Documentation tab for the scan workflow. Open the JAR as a ZIP for English/Chinese manuals and VERIFICATION.md in META-INF/docs/. A standalone Maven project with source and tests is in META-INF/source/; build with mvn clean verify using JDK 17+.

Use Discussion for bugs, questions and useful reporting suggestions. Include the exact server/Java versions, plugin version, reproduction steps, expected/observed results and relevant errors. Remove private information. All features are available without a rating or review.

1.0.0: Initial release. Developed with AI assistance; source is included for inspection. Author: AtBar. License: MIT.