FinderTools - High-Performance Async World Scanning Tool

FinderTools is a high-performance asynchronous world scanning plugin designed specifically for Minecraft 1.20.1 Paper servers, supporting precise block and entity detection.

Note: This plugin is developed with AI assistance

Features

🔍 Async Multi-threaded Scanning - Efficient block and entity scanning without server performance impact
🌍 Flexible Scan Range - Support for entire world, specific region files, loaded/unloaded chunks
📊 Smart Memory Management - Automatic memory monitoring, garbage collection and optimization
📈 Real-time Progress Monitoring - Progress output every 10%, supports console and player messages
📄 Detailed Report Generation - Automatic YAML format scan reports with complete statistics
⚙️ Highly Configurable - Configurable thread count, scan intervals, memory thresholds and more
🔒 Permission Management - Complete permission node control for secure usage
⏯️ Task Control - Support for stopping, pausing, and resuming scan tasks with flexible process management

Requirements

Minecraft 1.20.1
Paper Server
Java 8 or higher

Installation

Download the FinderTools-1.0-SNAPSHOT.jar file
Place the file in your server's plugins folder
Restart the server or use the /reload command
The plugin will automatically create configuration files and report directories

Commands

Basic Command Format

/findertools find <block|entity> <id> <world> [options]

Command Examples

Block Scanning

# Scan for diamond ore in the entire world
/findertools find block diamond_ore world

# Scan for stone in loaded chunks only
/findertools find block stone world{type='enabled'}

# Scan for gold ore in a specific region
/findertools find block gold_ore world{region='0,0'}

Entity Scanning

# Scan for villagers in the entire world
/findertools find entity villager world

# Scan for zombies in loaded chunks
/findertools find entity zombie world{type='enabled'}

# Scan for cows in a specific region
/findertools find entity cow world{region='-1,2'}

Task Control Commands

# Stop current scan task
/findertools stop

# Pause current scan task
/findertools pause

# Resume paused scan task
/findertools start
/findertools resume

# Check current scan status
/findertools status

Other Commands

# Reload configuration file
/findertools reload

# Show help information
/findertools help

Permissions

Permission Node	Description	Default
`findertools.command`	Basic command usage permission	op
`findertools.command.find`	Find command usage permission	op
`findertools.command.reload`	Configuration reload permission	op
`findertools.command.state`	Scan task control permission	op

Configuration

Configuration file location: plugins/FinderTools/config.yml

Scan Configuration

scan:
  chunk-interval: 1        # Chunk scanning interval (ticks)
  write-interval: 10       # Chunk count interval for report writing
  debug: false            # Enable debug output

Thread Configuration

threading:
  max-threads: 4          # Maximum thread count
  max-thread-usage: 0.8   # Maximum usage per thread
  check-interval: 100     # Thread check interval (milliseconds)

Memory Management

memory:
  max-memory-mb: 512      # Memory usage threshold (MB)
  gc-threshold: 0.9       # Forced garbage collection threshold

Report Configuration

report:
  output-directory: "plugins/FinderTools/reports"  # Report save directory
  format: "yml"           # Report file format
  detailed: true          # Include detailed information

Progress Output

progress:
  output-interval: 10     # Progress output interval (percentage)
  console-output: true    # Output progress to console
  player-output: true     # Send progress messages to executor

Report Format

After scanning completion, the plugin generates report files in the format report_YYYYMMDD_8-digit-random-ID.yml.

Report Example

report:
  info:
    generated_at: "2024-01-01 12:00:00"
    plugin_version: "1.0-SNAPSHOT"
    request_id: "12345678-1234-1234-1234-123456789abc"

  parameters:
    scan_type: "block"
    target_id: "diamond_ore"
    world: "world"
    loaded_only: false

  statistics:
    total_results: 156
    total_chunks_processed: 1000
    chunks_with_results: 45
    scan_duration_ms: 30000
    scan_duration_readable: "30 seconds"
    completed_at: "2024-01-01 12:00:30"

  results:
    - world: "world"
      location: "123,45,678"
      chunk: "7,42"
      type: "block"
      target: "diamond_ore"

Performance Optimization

Memory Optimization

Automatic memory monitoring and garbage collection
Periodic report writing to release memory
Smart adjustment of write intervals

Thread Optimization

Configurable thread pool size
Thread usage monitoring
Priority adjustment to avoid server performance impact

Scan Optimization

Asynchronous chunk loading and unloading
Smart chunk state detection
Configurable scan intervals

Troubleshooting

Common Issues

Q: Scanning is very slow? A: Increase the threading.max-threads value, increase the scan.task-pool-size value, or decrease the scan.chunk-interval value.

Q: Server experiencing lag? A: Reduce thread count, reduce task pool size, increase scan intervals, or lower the threading.max-thread-usage value.

Q: High memory usage? A: Decrease the scan.write-interval value to make the plugin write reports more frequently and release memory.

Q: Cannot find report files? A: Check the report.output-directory configuration and ensure the directory exists with write permissions.

Development Information

Author: NSrank & Augment
License: MIT
Source Code: Please contact the author for source code

Support

If you encounter issues or have feature suggestions during usage, please contact the plugin author.

License

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

FinderTools - Making world scanning simple and efficient!