ChunkScanner 🔍

A fast and efficient Rust-based tool for Minecraft server administrators to detect potential duplication stashes and monitor valuable item distribution across worlds and player inventories.

Overview

ChunkScanner recursively scans Minecraft region files (.mca) and player data files (.dat) to identify locations and players that exceed configured thresholds for specific items. This helps server administrators quickly locate suspicious concentrations of valuable items that may indicate duplication exploits or require investigation.

Features ✨

• 🌍 World Scanning: Analyzes all containers in region files (chests, shulker boxes, hoppers, etc.)
• 👤 Player Scanning: Examines player inventories and ender chests
• 🔄 Recursive Container Analysis: Automatically scans nested containers (shulker boxes within shulker boxes)
• ⚙️ Configurable Thresholds: Customize which items to flag and at what quantities
• 🎯 Regex Support: Use pattern matching for flexible item detection (e.g., all smithing templates)
• 🚀 Multi-threaded Processing: Parallel scanning for maximum performance
• 📁 Glob Pattern Support: Flexible file path specifications with wildcards
• 📊 Detailed Reporting: Clear output showing exact locations and quantities
• 💾 Flexible Output: Log to files or stdout

Installation

Prerequisites

• Rust 1.70+ (Install Rust)

Build from Source

git clone https://github.com/yourusername/chunkscanner.git
cd chunkscanner
cargo build --release

The binary will be available at target/release/chunkscanner.

Quick Start

1. Create Configuration File

./chunkscanner create-config

This creates a chunkscanner.toml file with default settings.

2. Configure Scan Targets

Edit chunkscanner.toml to customize what items to scan for:

check_player_data = true
check_worlds = true
player_data_files = ["./world/playerdata/"]
region_files = [
    "./world/region/*",
    "./world_nether/DIM-1/region/",
    "./world_the_end/DIM1/region/",
]
log_file = "stdout"

[[items]]
pattern = "minecraft:netherite_ingot"
min_count = 10
is_regex = false

[[items]]
pattern = "(.*)_smithing_template"
min_count = 5
is_regex = true

3. Run Automatic Scan

./chunkscanner scan

Usage

Commands

Command	Description
scan	Automatic scan using config file
create-config [file]	Create default configuration
scan_world <paths...>	Manual world file scanning
scan_players <paths...>	Manual player data scanning
help	Show help information

Configuration Options

Setting	Type	Description
check_player_data	boolean	Enable/disable player inventory scanning
check_worlds	boolean	Enable/disable world region scanning
player_data_files	array	Paths to player data files/directories
region_files	array	Paths to region files/directories
log_file	string	Output destination ("stdout" or filename)
items	array	List of items to scan for

Item Configuration

Each item in the [[items]] array supports:

• pattern: Item ID or regex pattern
• min_count: Minimum quantity to trigger a flag
• is_regex: Whether to treat pattern as regex

Examples

Basic World Scan

# Scan specific region files
./chunkscanner scan_world ./world/region/r.0.0.mca ./world/region/r.1.0.mca

# Scan entire region directory
./chunkscanner scan_world ./world/region/

Player Data Scan

# Scan playerdata directory
./chunkscanner scan_players ./world/playerdata/

# Scan specific player files
./chunkscanner scan_players player1.dat player2.dat

Using Custom Config

# Create named config
./chunkscanner create-config production.toml

# Use specific config file
./chunkscanner scan --config production.toml

Sample Output

🔍 Scan configuration:
  • Check player data: true
  • Check worlds: true
  • Player files found: 15
  • Region files found: 64

👤 Scanning player files...
  Processed: player1.dat (1/15) - No items found
  Processed: player2.dat (2/15)

🌍 Scanning world files...
  Processed: r.0.0.mca (1/64)
  Processed: r.1.0.mca (2/64) - No items found

SCAN RESULTS:
Player SuspiciousPlayer contains minecraft:netherite_ingot -> 127x
---- End of player info for SuspiciousPlayer ----

=== r.0.0.mca ===
Chunk at block coordinates (256, 512) contains minecraft:bundle -> 15x
Chunk at block coordinates (272, 512) contains pattern (.*)_smithing_template -> 23x total
---- End of chunk info for (1, 2) ----
---- End of file info for r.0.0.mca ====

✅ Automatic scan complete!
   📊 Files scanned: 79
   🎯 Files with items: 2

Default Scan Targets

The default configuration scans for these potentially suspicious items:

Item	Threshold	Notes
Bundles	1+	Rare item that may indicate duping
Smithing Templates	5+	Valuable and limited items
Enchanted Golden Apples	5+	Extremely rare in survival
Netherite Blocks	1+	Requires significant resources
Netherite Ingots	10+	High-value items
Shulker Shells	10+	Limited mob drops

Advanced Configuration

Regex Patterns

Use regex patterns to match multiple items:

# Match all smithing templates
[[items]]
pattern = "(.*)_smithing_template"
min_count = 3
is_regex = true

# Match all music discs
[[items]]
pattern = "minecraft:music_disc_(.*)"
min_count = 5
is_regex = true

Multiple World Support

region_files = [
    "./world/region/*",
    "./world_nether/DIM-1/region/*",
    "./world_the_end/DIM1/region/*",
    "./creative_world/region/*",
]

Output to File

log_file = "scan_results.txt"

Performance

ChunkScanner is designed for efficiency:

• Multi-threaded: Utilizes all CPU cores for parallel processing
• Memory efficient: Processes files individually to minimize RAM usage
• Fast parsing: Uses optimized NBT parsing libraries
• Selective scanning: Only processes relevant container data

Performance depends on server size and item distribution as well as CPU and disk speed. Typical performance metrics:

• ~100-600 region files per minute
• ~100-2000 player files per minute (These are rough estimates based on manual testing with over 18,000 region files, not formal benchmarks)

Contributing

We welcome contributions! Please feel free to:

1. Report bugs or suggest features via GitHub issues
2. Submit pull requests with improvements
3. Add support for additional item types or detection methods

TODO

• Advanced item NBT data analysis (enchantments, custom names, etc.)
• Web-based dashboard for results visualization
• Integration with server plugins for real-time monitoring
• Statistical analysis and anomaly detection
• Support for modded items and custom NBT structures
• Database storage for historical tracking

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is designed to help server administrators maintain fair gameplay. Always investigate flagged locations manually before taking action, as legitimate players may accumulate items through normal gameplay or trading.