Configuration Guide

Complete reference for MinerTrack's three-layer configuration system.

📁 Configuration Structure

/plugins/MinerTrack/
├── config.yml                 # Global settings (all worlds)
├── language.yml               # Messages, formatting, prefixes
└── Configuration/             # World-specific detection profiles
    ├── overworld.yml          # minecraft:overworld
    ├── nether.yml             # minecraft:the_nether
    ├── end.yml                # minecraft:the_end
    └── <custom>.yml           # Custom dimensions (namespace_dimension.yml)

Key Concept: World configs use Minecraft namespace IDs (minecraft:overworld), not folder names. This works regardless of your world folder naming (world, survival, world_nether, etc.).

⚙️ config.yml — Global Settings

Core Settings

# Config version — DO NOT EDIT MANUALLY
_config-version: 3

# Check for updates on startup
check_update: true
# Channel: stable / beta / alpha
check_update_channel: "stable"

# Visual effect on /mtrack kick
kick_strike_lightning: true

# Log all detections to files in /plugins/MinerTrack/logs/
log_file: true

# Auto-delete logs older than N days (-1 = never)
delete_time: 30

# Force detection on ALL players (including ops, bypass permission)
disable_bypass_permission: false

Discord Webhook Configuration

DiscordWebHook:
  enable: false
  WebHookURL: ""
  # Minimum VL to trigger webhook
  vl-required: 4

  # Embed message format (used when custom-json: false)
  vl-add-message:
    color: 0xFF5733  # Decimal or hex (0xRRGGBB)
    title: "X-Ray Alert"
    text:
      - 'Player Name: %player%'
      - 'Player UUID: %player_uuid%'
      - 'Player Violation Level: %player_vl%'
      - ''
      - 'Mining Ore: %ore_type%x%ore_count%'
      - 'Mined Veins: %mined_veins%'
      - ''
      - 'World: %world%'
      - 'Pos: %pos_x% %pos_y% %pos_z%'
      - ''
      - '%timestamp%'

  # Custom JSON payload (advanced)
  custom-json:
    enable: false
    format: |
      {
        "title": "X-Ray Alert",
        "data": {
          "player": {
            "name": "%player%",
            "uuid": "%player_uuid%",
            "violation_level": %player_vl%
          },
          "mining": {
            "ore_type": "%ore_type%",
            "ore_count": %ore_count%,
            "mined_veins": %mined_veins%
          },
          "location": {
            "world": "%world%",
            "x": %pos_x%,
            "y": %pos_y%,
            "z": %pos_z%
          },
          "timestamp": "%timestamp%"
        }
      }

Webhook Placeholders

🌍 World Configuration (Configuration/*.yml)

Each world profile controls detection behavior for that dimension.

Overworld Example (overworld.yml)

_config-version: 3

xray:
  enable: true                    # Enable detection in this world

  # Only scan below this Y level (surface noise reduction)
  max-height: 32

  # Ores that trigger detection (namespace format)
  rare-ores:
    - minecraft:emerald_ore
    - minecraft:deepslate_emerald_ore
    - minecraft:diamond_ore
    - minecraft:deepslate_diamond_ore

  # Maximum path history length (blocks)
  max_path_length: 500

  # Minutes after VL=0 to clear path history
  trace_remove: 15

  # Distance between veins to count as separate (blocks)
  max_vein_distance: 5

  # Veins mined before VL increases
  veinCountThreshold: 2

  # Small vein detection sensitivity (blocks ≤ this use cluster analysis)
  small_vein_detection_size: 4

  # Path analysis thresholds
  path-detection:
    turn-count-threshold: 10        # Max direction changes
    branch-count-threshold: 6       # Max branch paths
    y-change-threshold: 4           # Max Y-level changes
    y-change-threshold-add-required: 3  # Extra threshold if Y change exceeded

  # Natural environment detection (reduces false positives in caves)
  natural-detection:
    enable: true

    # Cave detection
    cave:
      air-threshold: 14              # Air blocks in radius to consider "cave"
      CaveAirMultiplier: 5           # Cave air counts as N normal air
      detection-range: 3             # 3 = 7×7×7, 2 = 5×5×5
      check_skip_vl: true            # Skip VL increase if in cave
      ignore-artificial-air: true    # Ignore player-placed/broken air
      artificial-air-remove-time: 20 # Minutes before broken blocks count as natural

    # Water detection (ocean/lake mining)
    sea:
      check-running-water: false     # Check flowing water
      water-threshold: 14
      detection-range: 3
      check_skip_vl: true

    # Lava detection (lava lakes)
    lava-sea:
      lava-threshold: 14
      detection-range: 3
      check_skip_vl: true

Nether Example (nether.yml)

_config-version: 3

xray:
  enable: true
  max-height: 128                   # Nether roof is ~127
  rare-ores:
    - minecraft:ancient_debris
  max_path_length: 500
  trace_remove: 15
  max_vein_distance: 3
  veinCountThreshold: 3
  small_vein_detection_size: 4
  path-detection:
    turn-count-threshold: 10
    branch-count-threshold: 6
    y-change-threshold: 4
    y-change-threshold-add-required: 3
  natural-detection:
    enable: true
    cave:
      air-threshold: 14
      CaveAirMultiplier: 5
      detection-range: 3
      check_skip_vl: true
      ignore-artificial-air: true
      artificial-air-remove-time: 20

End Example (end.yml)

_config-version: 3

xray:
  enable: false                     # End rarely needs X-ray detection
  # ... (same structure, disabled by default)

Custom Dimensions

For modded/custom dimensions (e.g., minecraft:the_nether → mymod:my_dimension):

1. Create Configuration/mymod_my_dimension.yml
2. Copy structure from overworld.yml
3. Adjust rare-ores for dimension-specific ores
4. Reload with /mtrack reload

📝 language.yml — Messages & Formatting

# Chat prefix for all MinerTrack messages
prefix: '&8[&9&lMiner&c&lTrack&8]&r '

# Broadcast when player kicked by anti-xray
# Placeholders: %player% %reason%
kick-format: '&b%player% &7kicked out of the server for allegedly using X-Ray! &8(%reason%)'

# Verbose mode notification (staff with minertrack.verbose)
# Placeholders: %player% %vl% %add_vl% %block_type% %count% %vein_count% %world% %pos_x% %pos_y% %pos_z%
verbose-format: '&7%player% failed &fX-Ray &7check &7VL:%vl%&b(+%add_vl%) &7Block:&6%block_type%&ex%count%&7(Vein&ax%vein_count%&7) &7World: %world% Pos: X%pos_x% Y%pos_y% Z%pos_z%'

# Log file format
# Placeholders: %year% %month% %day% %hour% %minute% %second% %player% %vl% %add_vl% %block_type% %count% %vein_count% %world% %pos_x% %pos_y% %pos_z%
log-format: '%year%-%month%-%day% %hour%:%minute%:%second% | %player% failed X-Ray check VL:%vl%(+%add_vl%) Block:%block_type%x%count%(Veinx%vein_count%) World: %world% Pos: X%pos_x% Y%pos_y% Z%pos_z%'

# Broadcast kick messages to all players
kick-broadcast: true

# Help text (/mtrack help)
help:
  - "&8----[&9&lMiner&c&lTrack &6Help&8]-----------"
  - ""
  - "&f/mtrack reload &7- Reload plugin's configuration file"
  - "&f/mtrack notify <message> &7- Send alerts to staff"
  - "&f/mtrack verbose &7- Toggle Detailed Mode (notifies staff on VL changes)"
  - "&f/mtrack check <player> &7- Check player's violation history"
  - "&f/mtrack reset <player> &7- Reset player's violation record"
  - "&f/mtrack help &7- Get plugin's help"
  - "&f/mtrack update &7- Check for plugin updates"
  - "&f/mtrack kick <player> <reason> &7- Kick player with reason"
  - "&f/mtrack logs <log name.log> &7- View a MinerTrack log file"

# Error messages
no-permission: "&cYou do not have permission to use this command."
usage-notify: "&cUsage: /mtrack notify <message>"
usage-check: "&cUsage: /mtrack check <player>"
usage-reset: "&cUsage: /mtrack reset <player>"
usage-kick: "&cUsage: /mtrack kick <player> <reason>"
usage-logs: "&cUsage: /mtrack logs <log name.log>"

# Success messages
# Placeholder: {player}
reset-success: "&aSuccessfully reset {player}'s violation record."
# Placeholders: {player} {level}
violation-level: "&e{player}'s violation level is {level}."

Color Codes

⚙️ Configuration Parameter Reference

Global (config.yml)

World (Configuration/*.yml)

🎯 Tuning Guide

For Fewer False Positives (Conservative)

# config.yml
disable_bypass_permission: false  # Let trusted staff bypass

# World config
xray:
  veinCountThreshold: 3           # Require more veins before VL++
  max_vein_distance: 3            # Closer veins = same vein
  natural-detection:
    enable: true
    cave:
      check_skip_vl: true         # Don't flag cave mining
      air-threshold: 10           # More lenient cave detection

For Aggressive Detection (Strict)

# config.yml
disable_bypass_permission: true   # Monitor everyone including ops

# World config
xray:
  veinCountThreshold: 1           # Flag on first rare vein
  max_vein_distance: 8            # Wider separation = separate veins
  max-height: 64                  # Scan higher (catch branch mining)
  natural-detection:
    enable: false                 # Disable cave forgiveness

For Specific Ore Types

# Only detect ancient debris in Nether
rare-ores:
  - minecraft:ancient_debris

# Add modded ores (namespace format)
rare-ores:
  - minecraft:diamond_ore
  - minecraft:deepslate_diamond_ore
  - mymod:rare_ore
  - anothermod:special_gem

🔄 Configuration Reloading

# In-game (requires minertrack.reload)
/mtrack reload

# Console
mtrack reload

What reloads:

• ✅ config.yml (global settings, webhook)
• ✅ language.yml (messages)
• ✅ Configuration/*.yml (world profiles)

What requires restart:

• ❌ Java version changes
• ❌ Plugin JAR updates
• ❌ New world dimensions (config files auto-created on dimension load)

📋 Configuration Best Practices

1. Backup before changes — Copy /plugins/MinerTrack/ before editing
2. Change one thing at a time — Test each adjustment for 24–48 hours
3. Keep logging enabled — log_file: true during tuning
4. Monitor console — Watch for [MinerTrack] [Verbose] messages
5. Use verbose mode — /mtrack verbose to see real-time detections
6. Don't set VL threshold too low — Default vl-required: 4 for webhooks is conservative
7. Test on test server first — Replicate your world config if possible

🔗 Related Pages

• Installation — First-time setup
• Commands — Staff commands & permissions
• Troubleshooting — Config-related issues
• FAQ — Common configuration questions