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

1. Download the FinderTools-1.0-SNAPSHOT.jar file
2. Place the file in your server's plugins folder
3. Restart the server or use the /reload command
4. 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 or decrease the scan.chunk-interval value.

Q: Server experiencing lag? A: Reduce thread count, 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
• Version: 1.1-SNAPSHOT
• 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!