MinerTrack Anti-Xray Configuration

2025-06-22

This document provides a detailed description of the configuration files (config.yml and language.yml) for the MinerTrack Anti-Xray plugin. These files define global settings, detection parameters, language options, and integration with external systems like Discord WebHooks.

Table of Contents

  1. Configuration File Overview
  2. Global Settings
  3. Discord WebHook Integration
  4. X-Ray Detection Settings
  5. Language Configuration
  6. Configuration Item Parse

Configuration File Overview

The MinerTrack Anti-Xray plugin uses two primary configuration files:

  • config.yml: Contains global settings, detection parameters, and advanced configurations.

    config.yml 
    #### MinerTrack Anti-Xray Configuration - config.yml ##############################
#
#   Welcome to MinerTrack anti-xray configuration file.
#   This file defines global settings specifically optimized for anti-xray detection.
#
#  Useful Links:
#  Get Update: https://modrinth.com/plugin/minertrack
#  View Source: https://github.com/At87668/MinerTrack
#  Report Issue: https://github.com/At87668/MinerTrack/issues
#  Pull Requset: https://github.com/At87668/MinerTrack/pulls
#  Visit Wiki: https://minertrack.pages.dev/wiki/
#  Join Discord: https://discord.gg/MzTea2W9cb
#
##################################################################################

# Check for updates on startup (recommended for latest optimizations).
check_update: true

# Visual effect when a player is kicked using /minertrack kick (default: true)
kick_strike_lightning: true

# Log Violations (default: true)
# Logs all detections in /plugins/MinerTrack/logs for easier monitoring.
log_file: true

# Auto-delete outdated logs after specified days (-1 to disable auto-deletion)
delete_time: 30

# Deny Bypass Permission - force checks on all players, including Operators.
disable_bypass_permission: false

# Discord WebHook
DiscordWebHook:
  enable: false
  WebHookURL: ''
  vl-required: 4 # If a player's violation level is greater than this value, an alert is sent.
  vl-add-message:
    color: 0xFF5733
    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%'
      - ''
      - 'Pos: %pos_x% %pos_y% %pos_z%'
  # If the custom Json format below is enabled, this Json body format will be used to send to the WebHookURL configured above
  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": {
            "x": %pos_x%,
            "y": %pos_y%,
            "z": %pos_z%
          },
          "timestamp": "%timestamp%"
        }
      }

#############################################################################################################################
##        ##   This plugin in order to capture XRayer quickly, might generate false positives for players who are lucky!   ##
##  Warn  ##   Be careful not to set the VL threshold too low!                                                             ##
##        ##   Don't detect for common ores either, you should only detect for rare ores!                                  ##
#############################################################################################################################

xray:
  enable: true  # Enable X-ray detection

  # At what height should I start detecting X-Ray?
  # Worlds that are not listed do not have XRay detection.
  worlds:
    world:
      enable: true
      max-height: 32
    world_nether:
      enable: true
      max-height: 128
    world_the_end:
      enable: false
    all_unnamed_world:
      enable: false

  # The type of ore a player has to mine before being able to be checked
  # List of allowed materials: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
  rare-ores:
    - ANCIENT_DEBRIS
    - EMERALD_ORE
    - DEEPSLATE_EMERALD_ORE
    - DIAMOND_ORE
    - DEEPSLATE_DIAMOND_ORE

  # Mined length record limit (Unit: block)
  max_path_length: 500

  # Explosion Detection (alpha)
  explosion:
    explosion_retention_time: 600  # Information is removed after {n} seconds after the mineral is exposed to the explosion
    entity-explode-check: false    # Whether or not the mining of minerals caused by explosions counts towards player mining?
    base_vl_rate: 2.0              # VL multiplier when the player's blast hit rate is suspicious
    suspicious_hit_rate: 0.1       # Suspicious when the player hits what the percentage is? (0.1 = 10%)

  # Path record is reset after the player VL is 0 {n} minutes.
  trace_remove: 15

  max_vein_distance: 5  # When two veins are close together, VL is not increased.

  # VL is increased as the player digs the number of veins
  veinCountThreshold: 3

  path-detection:
    turn-count-threshold: 10           # Maximum number of turns threshold
    branch-count-threshold: 6          # Maximum number of branches
    y-change-threshold: 4              # Maximum Y-axis change threshold
    y-change-threshold-add-required: 3 # If y pos transformation exceeds this value, the threshold is increased

  # Natural Detection
  natural-detection:
    enable: true

    # Satisfying the conditions will think they are in a natural.
    cave:
      air-threshold: 14        # When the number of air blocks reaches several, the player is considered to be in a cave?
      CaveAirMultiplier: 5     # If cave air is found, regarded as how many ordinary air?
      detection-range: 3       # 3 = 7x7x7, 2 = 5x5x5
      check_skip_vl: true      # VL add of whether or not to skip natural behavior
    sea:
      check-running-water: false  # Should we check running water?
      water-threshold: 14
      detection-range: 3
      check_skip_vl: true
    lava-sea:
      lava-threshold: 14
      detection-range: 3
      check_skip_vl: true

  # Violation level decay settings (Unit: minute)
  decay:
    interval: 3         # The interval between decay tasks (in minutes)
    amount: 1           # The value of each linear falloff
    use_factor: false   # Whether to enable nonlinear attenuation
    factor: 0.9         # Nonlinear decay scale (only works when use_factor=true)

  # Commands executed at specified violation thresholds
  commands:
    2: 'minertrack notify &f%player% &7triggered &fX-Ray &7detection [&cVL: 2&7]'
    4: 'minertrack notify &f%player% &7triggered &fX-Ray &7detection [&cVL: 4&7]'
    5: 'minertrack kick %player% X-Ray'

  • language.yml: Defines display messages, notifications, and language options.

    language.yml 
    #### MinerTrack Config - language.yml ##################################################
#
#     Hi, welcome to use MinerTrack anti-xray, this is language.yml, which is used
#  to define the display language of anti-xray. Here you can define what message
#  the anti-xray displays.
#
#  Useful Links:
#  Get Update: https://modrinth.com/plugin/minertrack
#  View Source: https://github.com/At87668/MinerTrack
#  Report Issue: https://github.com/At87668/MinerTrack/issues
#  Pull Requset: https://github.com/At87668/MinerTrack/pulls
#  Visit Wiki: https://minertrack.pages.dev/wiki/
#  Join Discord: https://discord.gg/MzTea2W9cb
#
#  Anyway, thanks for using MinerTrack anti-xray! ❤
#
#####################################################################################

# You can define the message prefix here
prefix: '&8[&9&lMiner&c&lTrack&8]&r '

# Define the announcement message after the player is kicked out by anti-xraying
kick-format: '&b%player% &7kicked out of the server for allegedly using X-Ray! &8(%reason%)'

# Define the verbose message format
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%'

# Define the log format
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%'

# Should MinerTrack broadcast a message when a player is kicked?
kick-broadcast: true

help:
  - "&8----[&9&lMiner&c&lTrack &6Help&8]-----------"
  - ""
  - "&f/mtrack notify <message> &7- Send alerts to staff"
  - "&f/mtrack verbose &7- Turn on Detailed Mode, and send a notification to the staff who have Detailed Mode enabled whenever the player's VL increases"
  - "&f/mtrack check <player> &7- Check player's history of violations"
  - "&f/mtrack reset <player> &7- Reset player's violation record"
  - "&f/mtrack help &7- Get plugin's help"
  - "&f/mtrack update &7- Check update"
  - "&f/mtrack kick <player> <reason> &7- Kick the player with a specified reason"

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>"

reset-success: "&aSuccessfully reset {player}'s violation record."

violation-level: "&e{player}'s violation level is {level}."

player-not-found: "&cPlayer {player} not found."

config-reloaded: "&aConfiguration and Language reloaded successfully."

unknown-command: "&cUnknown subcommand. Use /mtrack help for a list of commands."

verbose-enable: '&7Verbose Mode &aEnabled&7!'
verbose-disable: '&7Verbose Mode &cDisabled&7!'

update:
  alpha-available: '&cNew alpha version %latest_version% now available!'
  beta-available: '&eNew beta version %latest_version% now available!'
  stable-available: '&aNew stable version %latest_version% now available!'
  using-latest: '&2You are using the latest version.'
  check-failed: '&cFailed to check for updates.'

Global Settings

config.yml

General Settings

  • check_update:

    • Description: Determines whether the plugin checks for updates on startup.
    • Default: true (recommended for latest optimizations).

  • kick_strike_lightning:

    • Description: Enables or disables a visual lightning effect when a player is kicked using /minertrack kick.
    • Default: true.

  • log_file:

    • Description: Controls whether violations are logged in the /plugins/MinerTrack/logs directory for monitoring purposes.
    • Default: true.

  • delete_time:

    • Description: Specifies the number of days after which outdated logs are automatically deleted. Set to -1 to disable auto-deletion.
    • Default: 30.

  • disable_bypass_permission:

    • Description: Forces checks on all players, including operators, by disabling bypass permissions.
    • Default: false.

Discord WebHook Integration

DiscordWebHook

  • enable:

    • Description: Enables or disables Discord WebHook notifications.
    • Default: false.

  • WebHookURL:

    • Description: The URL for the Discord WebHook. Must be provided if enable is set to true.

  • vl-required:

    • Description: The violation level (VL) threshold at which notifications are sent to Discord.
    • Default: 4.

  • vl-add-message:

    • Description: Customizes the notification message format, including color, title, and text placeholders for player details, violation levels, and mined ores.

X-Ray Detection Settings

xray

  • enable:

    • Description: Enables or disables X-ray detection globally.
    • Default: true.

  • worlds:

    • Description: Configures world-specific settings, such as enabling detection and setting the maximum height for detection.
    • Example: 
      worlds:
  world:
    enable: true
    max-height: 32
  world_nether:
    enable: true
    max-height: 128

  • rare-ores:

    • Description: Defines the list of rare ores that trigger detection.
    • Example: 
      rare-ores:
  - ANCIENT_DEBRIS
  - EMERALD_ORE
  - DEEPSLATE_EMERALD_ORE

  • max_path_length:

    • Description: Sets the maximum recorded mining path length (in blocks).
    • Default: 500.

  • explosion:

    • Description: Configures explosion-related detection, including retention time, entity explode checks, and suspicious hit rate thresholds.

  • path-detection:

    • Description: Fine-tunes path-based detection parameters, such as turn count, branch count, and Y-axis change thresholds.

  • natural-detection:

    • Description: Configures natural environment detection to reduce false positives in caves, seas, and lava seas.

  • decay:

    • Description: Defines violation level decay settings, including interval, amount, and nonlinear attenuation.

  • commands:

    • Description: Specifies commands executed at specific violation thresholds.
    • Example: 
      commands:
  2: 'minertrack notify &f%player% &7triggered &fX-Ray &7detection [ &cVL: 2 &7]'
  4: 'minertrack notify &f%player% &7triggered &fX-Ray &7detection [ &cVL: 4 &7]'
  5: 'minertrack kick %player% X-Ray'

Language Configuration

language.yml

General Messages

  • prefix:

    • Description: Defines the prefix for all plugin messages.
    • Example: '&8[ &9 &lMiner &c &lTrack &8] &r'.

  • kick-format:

    • Description: Customizes the announcement message when a player is kicked for alleged X-ray usage.
    • Example: '&b%player% &7kicked out of the server for allegedly using X-Ray!'.

  • verbose-format:

    • Description: Defines the format for detailed mode notifications when a player's violation level increases.
    • Example: '&7%player% failed &fX-Ray &7check &7VL:%vl% &b(+%add_vl%) &7Block: &6%block_type% &ex%count%'.

  • log-format:

    • Description: Specifies the log format for recording violations.
    • Example: '%year%-%month%-%day% %hour%:%minute%:%second% | %player% failed X-Ray check VL:%vl%(+%add_vl%) Block:%block_type%x%count%'.

Command Usage Messages

  • usage-notify, usage-check, usage-reset, usage-kick:
    • Description: Provides usage instructions for various commands.
    • Example: '&cUsage: /mtrack notify <message>'.

Success and Error Messages

  • reset-success:

    • Description: Confirms successful reset of a player's violation record.
    • Example: '&aSuccessfully reset {player}'s violation record.'.

  • player-not-found:

    • Description: Indicates that a specified player was not found.
    • Example: '&cPlayer {player} not found.'.

Verbose Mode Messages

  • verbose-enable, verbose-disable:
    • Description: Notifies staff when verbose mode is enabled or disabled.
    • Example: '&7Verbose Mode &aEnabled &7!'.

Update Notifications

  • update.alpha-available, update.beta-available, update.stable-available:
    • Description: Announces the availability of new plugin versions.
    • Example: '&aNew stable version %latest_version% now available!'.