### Install the Plugin

Source: https://minertrack.pages.dev/wiki/v2/Installation

Standard procedure for installing the plugin JAR file into the server plugins directory.

```bash
# 1. Stop your server
./stop.sh  # or use your server management panel

# 2. Place the JAR in plugins folder
cp MinerTrack-<version>.jar /path/to/server/plugins/

# 3. Start the server
./start.sh
```

--------------------------------

### LuckPerms Configuration Examples

Source: https://minertrack.pages.dev/wiki/v2/Commands

Command-line examples for assigning MinerTrack permissions to groups using LuckPerms.

```bash
# Full admin access
/lp group admin permission set minertrack.* true

# Moderator: check, verbose, notify, logs
/lp group moderator permission set minertrack.use true
/lp group moderator permission set minertrack.check true
/lp group moderator permission set minertrack.verbose true
/lp group moderator permission set minertrack.notify true
/lp group moderator permission set minertrack.logs true
/lp group moderator permission set minertrack.sendnotify true

# Helper: only receive alerts
/lp group helper permission set minertrack.use true
/lp group helper permission set minertrack.notify true

# Trusted player: bypass detection (USE SPARINGLY)
/lp user TrustedPlayer permission set minertrack.bypass true
```

--------------------------------

### View Installation Folder Structure

Source: https://minertrack.pages.dev/wiki/v2/Installation

Expected file layout after placing the plugin JAR in the server plugins directory.

```text
/your-server/
├── plugins/
│   └── MinerTrack-<version>.jar
├── ...
```

--------------------------------

### PermissionEx Configuration Example

Source: https://minertrack.pages.dev/wiki/v2/Commands

YAML-based configuration for defining MinerTrack permissions within PermissionEx.

```yaml
groups:
  admin:
    permissions:
      - minertrack.*
  moderator:
    permissions:
      - minertrack.use
      - minertrack.check
      - minertrack.verbose
      - minertrack.notify
      - minertrack.logs
      - minertrack.sendnotify
  helper:
    permissions:
      - minertrack.use
      - minertrack.notify
  trusted:
    permissions:
      - minertrack.bypass
```

--------------------------------

### End Configuration Example

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Minimal configuration for the End dimension, where detection is disabled by default.

```yaml
_config-version: 3

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

--------------------------------

### Docker Container Deployment for MinerTrack

Source: https://minertrack.pages.dev/wiki/v2/Installation

Example Dockerfile and Docker Compose configuration for deploying MinerTrack with a Paper server.

```dockerfile
# Example: Paper + MinerTrack
FROM papermc/paper:1.21

# Copy plugin to plugins directory
COPY MinerTrack-*.jar /plugins/

# Config persistence (optional)
VOLUME ["/plugins/MinerTrack"]
```

```yaml
services:
  minecraft:
    image: papermc/paper:1.21
    volumes:
      - ./plugins:/plugins
      - ./world:/world
      - ./minertrack-config:/plugins/MinerTrack
    environment:
      - MEMORY=4G
    ports:
      - "25565:25565"
```

--------------------------------

### Nether Configuration Example

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Defines detection parameters for the Nether, adjusted for ancient debris and higher Y-level limits.

```yaml
_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
```

--------------------------------

### Overworld Configuration Example

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Defines detection parameters for the Overworld, including specific rare ores and natural environment detection settings.

```yaml
_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
```

--------------------------------

### Display Help Command

Source: https://minertrack.pages.dev/wiki/v2/Commands

Displays all available commands and their descriptions.

```text
Usage: /mtrack help
Permission: minertrack.help
Description: Displays all available commands with descriptions.
```

```text
----[MinerTrack Help]-----------
/mtrack reload - Reload plugin's configuration file
/mtrack notify <message> - Send alerts to staff
/mtrack verbose - Toggle Detailed Mode
/mtrack check <player> - Check player's violation history
/mtrack reset <player> - Reset player's violation record
/mtrack help - Get plugin's help
/mtrack update - Check for plugin updates
/mtrack kick <player> <reason> - Kick player with reason
/mtrack logs <log name.log> - View a MinerTrack log file
```

--------------------------------

### View Configuration Directory Structure

Source: https://minertrack.pages.dev/wiki/v2/Installation

Layout of the generated configuration files within the plugins folder after the first startup.

```text
/plugins/MinerTrack/
├── config.yml              # Global settings
├── language.yml            # Messages & formatting
└── Configuration/          # World-specific profiles
    ├── overworld.yml       # Overworld (minecraft:overworld)
    ├── nether.yml          # Nether (minecraft:the_nether)
    └── end.yml             # End (minecraft:the_end)
```

--------------------------------

### /mtrack help

Source: https://minertrack.pages.dev/wiki/v2/Commands

Displays all available commands with descriptions.

```APIDOC
## /mtrack help

### Description
Displays all available commands with descriptions.

### Permission
minertrack.help
```

--------------------------------

### Configure X-Ray testing settings

Source: https://minertrack.pages.dev/wiki/FAQ

Use these settings in your configuration to enable X-Ray testing and bypass permissions.

```yaml
disable_bypass_permission: true
xray:
  enable: true
```

--------------------------------

### Reload Configuration

Source: https://minertrack.pages.dev/wiki/v2/Installation

Commands to apply configuration changes without a full server restart.

```bash
/mtrack reload
# OR restart server for major changes
```

--------------------------------

### View Logs In-Game

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Commands to retrieve and paginate log files directly from the server console or chat.

```text
/mtrack logs 2024-01-15.log
/mtrack logs 2024-01-15.log 2  # Page 2
```

--------------------------------

### Configuration Reset Procedure

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Commands to perform a full reset of the MinerTrack configuration by backing up and deleting the existing folder.

```bash
# 1. Stop server
# 2. Backup current config
cp -r /plugins/MinerTrack /plugins/MinerTrack.backup

# 3. Delete config folder
rm -rf /plugins/MinerTrack

# 4. Start server → fresh configs generated
# 5. Re-apply your custom settings
```

--------------------------------

### Execute MinerTrack Console Commands

Source: https://minertrack.pages.dev/wiki/v2/Commands

Commands executed from the server console must be prefixed with 'mtrack'.

```text
# Console examples
mtrack help
mtrack reload
mtrack verbose
mtrack check Notch
mtrack reset Notch
mtrack kick Notch "X-Ray"
mtrack notify "Console alert: Check Notch"
mtrack update
mtrack logs 2024-01-15.log
```

--------------------------------

### Reload Configuration Command

Source: https://minertrack.pages.dev/wiki/v2/Commands

Reloads the plugin's configuration and language files without requiring a full server restart.

```text
Usage: /mtrack reload
Permission: minertrack.reload
Description: Reloads config.yml, language.yml, and all Configuration/*.yml files.
```

```text
[MinerTrack] Configuration and Language reloaded successfully.
```

--------------------------------

### Configure Discord Webhook in config.yml

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Enable Discord alerts by setting the webhook URL and violation level threshold in the configuration file.

```yaml
DiscordWebHook:
  enable: true
  WebHookURL: "https://discord.com/api/webhooks/..."
  vl-required: 4
```

--------------------------------

### Configure X-ray and Natural Detection Settings

Source: https://minertrack.pages.dev/wiki/Configuration

The {world_name}.yml file defines detection thresholds for rare ores and natural environment conditions. Adjust these values to balance detection accuracy and performance.

```yaml
#############################################################################################################################
##        ##   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!                                  ##
#############################################################################################################################

#############################################################################################################################
##        ##   Default configuration may be slow on the first check-out.                                                   ##
##  Info  ##   It will be more accurate afterwards,                                                                        ##
##        ##   Therefore, it is recommended to adjust the configuration to suit your needs.                                ##
#############################################################################################################################

xray:
  enable: true  # Enable X-ray detection

  max-height: 32  # Only detect operations below this height

  # 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:
    - EMERALD_ORE
    - DEEPSLATE_EMERALD_ORE
    - DIAMOND_ORE
    - DEEPSLATE_DIAMOND_ORE

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

  # 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: 2

  # Small vein detection size
  # If a vein contains <= this number of blocks, the plugin uses a more sensitive
  # comparison strategy (cluster overlap/min distance) to decide whether it's a new vein.
  # Default: 4
  small_vein_detection_size: 4

  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
      ignore-artificial-air: true # When true, ignore recently player-created air when checking for caves
      artificial-air-remove-time: 20 # Minutes to consider broken blocks as artificial air
    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
```

--------------------------------

### MinerTrack Anti-Xray Configuration File

Source: https://minertrack.pages.dev/wiki/Configuration

The primary configuration file for defining global settings, Discord WebHook integration, and X-Ray detection rules.

```yaml
#### 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
#
##################################################################################

# ! NOTE: DON'T EDIT CONFIG VERSION !
_config-version: 2

# Check for updates on startup (recommended for latest optimizations).
check_update: true
# Available options: stable/beta/alpha. Using the pre-release version will receive updates from more stable versions.
check_update_channel: "stable"

# 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
# Placeholders: %player% %player_uuid% %player_vl% %ore_type% %ore_count% %mined_veins% %pos_x% %pos_y% %pos_z% %world% %timestamp%
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%'
      - ''
      - 'World: %world%'
      - 'Pos: %pos_x% %pos_y% %pos_z%'
      - ''
      - '%timestamp%'
  # 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": {
            "world": %world%',
            "x": %pos_x%,
            "y": %pos_y%,
            "z": %pos_z%
          },
          "timestamp": "%timestamp%"
        }
      }

xray:
  # All worlds not explicitly listed will follow 'all_unnamed_world'
  # If 'all_unnamed_world' not listed, worlds that are not listed do not have XRay detection.
  # Configuration will be loaded from 'Configuration/file_name.yml'
  worlds:
    'overworld': # It means overworld.yml
      - world
      - all_unnamed_world
    'nether':
      - world_nether
    'end':
      - world_the_end

  # 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'
      - 'minertrack notify &f%player% &7was kicked for &fX-Ray'
```

--------------------------------

### Global Configuration Settings

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Core settings for the MinerTrack plugin, including update checks, logging, and bypass permissions.

```yaml
# 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
```

--------------------------------

### Configure Conservative Detection Settings

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Use these settings to reduce false positives by increasing thresholds and enabling natural detection checks.

```yaml
xray:
  veinCountThreshold: 3
  max_vein_distance: 3
  natural-detection:
    enable: true
    cave:
      air-threshold: 18
      CaveAirMultiplier: 3
      check_skip_vl: true
    sea:
      check_skip_vl: true
    lava-sea:
      check_skip_vl: true
```

--------------------------------

### Locate MinerTrack Log Files

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Log files are stored within the plugin directory and can be accessed via the in-game command.

```text
/plugins/MinerTrack/logs/
  2024-01-15.log
  2024-01-16.log
  ...
```

--------------------------------

### View Detection Logs

Source: https://minertrack.pages.dev/wiki/v2/Commands

Accesses and paginates through MinerTrack detection log files.

```text
Usage: /mtrack logs <log name.log> [page]
Permission: minertrack.logs
Description: Views MinerTrack detection log files with pagination.
```

```text
/mtrack logs 2024-01-15.log
/mtrack logs 2024-01-15.log 2
```

```text
2024-01-15 14:30:22 | Notch failed X-Ray check VL:3(+1) Block:diamond_orex3(Veinx1) World: world Pos: X123 Y-45 Z67
```

```text
---- MinerTrack Logs (1/3) ----
2024-01-15 14:30:22 | Notch failed X-Ray check...
2024-01-15 14:31:05 | Steve failed X-Ray check...
...
Use /mtrack logs 2024-01-15.log 2 to view next page.
```

--------------------------------

### Kick Player Command

Source: https://minertrack.pages.dev/wiki/v2/Commands

Kicks a player from the server with a specified reason.

```text
Usage: /mtrack kick <player> <reason>
Permission: minertrack.kick
Description: Kicks the player with a formatted X-Ray kick message.
```

```text
/mtrack kick Notch "X-Ray detected - VL 5"
```

```text
Notch kicked out of the server for allegedly using X-Ray! (X-Ray detected - VL 5)
```

--------------------------------

### Staff Monitoring Workflow Commands

Source: https://minertrack.pages.dev/wiki/v2/Commands

Standard sequence of commands for daily staff monitoring, investigation, and enforcement.

```text
# 1. Enable verbose mode at shift start
/mtrack verbose

# 2. Monitor chat for alerts like:
# [MinerTrack] Notch failed X-Ray check VL:3(+1) Block:diamond_orex3...

# 3. Investigate suspicious players
/mtrack check Notch

# 4. If confirmed X-Ray:
/mtrack kick Notch "X-Ray detected - VL 5"

# 5. If false positive:
/mtrack reset Notch

# 6. Disable verbose at shift end
/mtrack verbose
```

--------------------------------

### Configure language.yml

Source: https://minertrack.pages.dev/wiki/Configuration

Defines the display messages, kick formats, and command responses for the MinerTrack plugin.

```yaml
#### 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
# Placeholders: %player% %reason%
kick-format: '&b%player% &7kicked out of the server for allegedly using X-Ray! &8(%reason%)'

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

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

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

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- 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"
  - "&f/mtrack logs <log name.log> &7- View a MinerTrack log file"

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

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

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

# Placeholders: {player}
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!"

# Placeholders: {current_page} {max_page} {log_file} {next_page}
log-viewer-lines-per-page: 10
log-viewer-header: "&7---- &9&lMiner&c&lTrack &bLogs &7({current_page}/{max_page}) ----"
log-viewer-logs-color: "&7"
log-viewer-not-found: "&cLog file {log_file} not found."
log-viewer-not-log-file: "&cOnly can view log file."
log-viewer-cant-read: "&cFailed to read logs."
log-viewer-page-invalid: "&cPage number out of range (1 - {max_page})"
log-viewer-page-nan: "&cPage number must be a number"
log-viewer-next-page: "&6Use &a/mtrack logs page {next_page} &6to view next page."
log-viewer-empty: "&7No log entries to display."

# Placeholders: %latest_version%
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.'
```

--------------------------------

### /mtrack logs <log name.log> [page]

Source: https://minertrack.pages.dev/wiki/v2/Commands

Views MinerTrack detection log files.

```APIDOC
## /mtrack logs <log name.log> [page]

### Description
Views MinerTrack detection log files with pagination.

### Parameters
- **log name.log** (string) - Required - The name of the log file to view.
- **page** (integer) - Optional - The page number to display.

### Permission
minertrack.logs
```

--------------------------------

### MinerTrack Directory Structure

Source: https://minertrack.pages.dev/wiki/v2/Configuration

The file layout for the MinerTrack plugin directory, including global configuration and world-specific profiles.

```text
/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)
```

--------------------------------

### Configure Nether Rare Ores

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Add specific rare ores to the Nether configuration file to ensure they are tracked correctly.

```yaml
# nether.yml
rare-ores:
  - minecraft:ancient_debris
  # Add modded nether ores if applicable
```

--------------------------------

### /mtrack kick <player> <reason>

Source: https://minertrack.pages.dev/wiki/v2/Commands

Kicks a player with a formatted X-Ray kick message.

```APIDOC
## /mtrack kick <player> <reason>

### Description
Kicks the player with a formatted X-Ray kick message.

### Parameters
- **player** (string) - Required - The player to kick.
- **reason** (string) - Required - The reason for the kick.

### Permission
minertrack.kick
```

--------------------------------

### Customize Log File Format

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Modify the log entry structure in language.yml using available placeholders.

```yaml
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%'
```

--------------------------------

### Default Decay Settings Configuration

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Configuration parameters for violation level decay, including interval timing and decay methods.

```yaml
decay:
  interval: 3        # Check every 3 minutes
  amount: 1          # Reduce VL by 1 per interval
  use_factor: false  # Linear decay
  factor: 0.9        # Exponential decay (if use_factor: true)
```

--------------------------------

### Configure Strict Detection

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Increases detection sensitivity by monitoring all users and disabling cave-specific forgiveness.

```yaml
# 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
```

--------------------------------

### Uninstalling MinerTrack via Command Line

Source: https://minertrack.pages.dev/wiki/v2/Installation

Use these commands to remove the plugin JAR and associated data files from the server directory.

```bash
# 1. Stop server
# 2. Remove plugin
rm /path/to/server/plugins/MinerTrack-*.jar
# 3. (Optional) Remove config & logs
rm -rf /path/to/server/plugins/MinerTrack/
# 4. Start server
```

--------------------------------

### Configure Debug Mode

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Toggle debug mode in config.yml to enable or disable verbose console output for troubleshooting.

```yaml
# config.yml
debug: true
```

```yaml
debug: false
```

--------------------------------

### Grant Bypass Permission

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Commands to grant bypass permissions for server testing using LuckPerms or PermissionEx.

```text
# LuckPerms
/lp user <player> permission set minertrack.bypass true

# PermissionEx
/pex user <player> add minertrack.bypass
```

--------------------------------

### Configure Bypass Monitoring

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Configuration setting to ensure bypass holders are still monitored.

```yaml
# config.yml
disable_bypass_permission: true
```

--------------------------------

### /mtrack check <player>

Source: https://minertrack.pages.dev/wiki/v2/Commands

Shows the target player's current violation level and history.

```APIDOC
## /mtrack check <player>

### Description
Shows the target player's current violation level and history.

### Parameters
- **player** (string) - Required - The name or UUID of the player to check.

### Permission
minertrack.check
```

--------------------------------

### Define Custom JSON Webhook Format

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Enable and define a custom JSON payload structure for Discord webhooks using available placeholders.

```yaml
DiscordWebHook:
  custom-json:
    enable: true
    format: |
      {
        "content": "🚨 X-Ray Alert: %player% (VL: %player_vl%)",
        "embeds": [{
          "color": 16711680,
          "fields": [
            {"name": "Ore", "value": "%ore_type% x%ore_count%", "inline": true},
            {"name": "Location", "value": "%world% %pos_x% %pos_y% %pos_z%", "inline": true}
          ]
        }]
      }
```

--------------------------------

### Define Rare Ores in Configuration

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Specify rare ores using the Minecraft namespace format in world-specific configuration files.

```yaml
rare-ores:
  - minecraft:diamond_ore
  - minecraft:deepslate_diamond_ore
  - minecraft:emerald_ore
  - minecraft:deepslate_emerald_ore
```

```yaml
rare-ores:
  - minecraft:ancient_debris
```

```yaml
rare-ores:
  - minecraft:diamond_ore
  - mymod:rare_ore
  - anothermod:special_gem
```

--------------------------------

### Customize Kick Message

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Modify the kick message format in the language configuration file using available placeholders.

```yaml
kick-format: '&b%player% &7was banned for X-Ray! &8(%reason%)'
```

--------------------------------

### Discord Webhook Configuration

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Settings for Discord webhook integration, including message formatting and custom JSON payload definitions.

```yaml
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%"
        }
      }
```

--------------------------------

### Check Plugin Updates

Source: https://minertrack.pages.dev/wiki/v2/Commands

Manually triggers an update check for the plugin.

```text
Usage: /mtrack update
Permission: minertrack.checkupdate
Description: Manually checks for plugin updates on configured channel (stable/beta/alpha).
```

```text
New stable version 2.5.0 now available!
You are using the latest version.
Failed to check for updates.
```

--------------------------------

### MinerTrack Permission Hierarchy

Source: https://minertrack.pages.dev/wiki/v2/Commands

Visual representation of the MinerTrack permission node tree.

```text
minertrack.use                    # Root - required for ALL commands (default: op)
├── minertrack.help               # /mtrack help
├── minertrack.reload             # /mtrack reload
├── minertrack.verbose            # /mtrack verbose
├── minertrack.check              # /mtrack check
├── minertrack.reset              # /mtrack reset
├── minertrack.kick               # /mtrack kick
├── minertrack.sendnotify         # /mtrack notify
├── minertrack.checkupdate        # /mtrack update
├── minertrack.logs               # /mtrack logs
└── minertrack.notify             # Receive verbose/notify messages
```

--------------------------------

### Configure X-Ray Detection Worlds

Source: https://minertrack.pages.dev/wiki/Configuration

Defines which world files correspond to specific game dimensions for X-Ray monitoring.

```yaml
worlds:
  'overworld': # It means overworld.yml
    - world
    - all_unnamed_world
  'nether':
    - world_nether
  'end':
    - world_the_end
```

--------------------------------

### /mtrack reload

Source: https://minertrack.pages.dev/wiki/v2/Commands

Reloads the plugin configuration files.

```APIDOC
## /mtrack reload

### Description
Reloads config.yml, language.yml, and all Configuration/*.yml files.

### Permission
minertrack.reload
```

--------------------------------

### Violation Level Calculation Logic

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

The step-by-step process for calculating and incrementing violation levels based on mining behavior and environmental checks.

```text
1. Player mines rare ore (from rare-ores list)
2. Check if in natural environment (cave/water/lava)
   - If yes AND check_skip_vl: true → NO VL increase
3. Check vein distance from last vein
   - If ≤ max_vein_distance → SAME vein, no VL increase
4. Increment vein count
5. If vein count ≥ veinCountThreshold → VL++
6. Path analysis runs (turns, branches, Y-changes)
   - Exceeding thresholds → additional VL++
7. VL decays over time (config.yml decay settings)
```

--------------------------------

### /mtrack verbose

Source: https://minertrack.pages.dev/wiki/v2/Commands

Toggles verbose mode for real-time violation notifications.

```APIDOC
## /mtrack verbose

### Description
Toggles verbose mode. When enabled, you receive real-time notifications whenever any player's violation level changes.

### Permission
minertrack.verbose
```

--------------------------------

### Configure Conservative Detection

Source: https://minertrack.pages.dev/wiki/v2/Configuration

Adjusts settings to reduce false positives by allowing staff bypass and enabling cave mining forgiveness.

```yaml
# 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
```

--------------------------------

### /mtrack notify <message>

Source: https://minertrack.pages.dev/wiki/v2/Commands

Sends a custom message to all players with notification permissions.

```APIDOC
## /mtrack notify <message>

### Description
Sends a custom message to all players with `minertrack.notify` permission.

### Parameters
- **message** (string) - Required - The message to send.

### Permission
minertrack.sendnotify
```

--------------------------------

### Set Violation Threshold Commands

Source: https://minertrack.pages.dev/wiki/Configuration

Maps specific violation levels to console or player commands for automated moderation.

```yaml
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'
```

--------------------------------

### Send Staff Notification

Source: https://minertrack.pages.dev/wiki/v2/Commands

Broadcasts a message to all players with the appropriate notification permission.

```text
Usage: /mtrack notify <message>
Permission: minertrack.sendnotify
Description: Sends a custom message to all players with `minertrack.notify` permission.
```

```text
/mtrack notify "Staff: Please check Notch at X:123 Y:45 Z:67"
```

--------------------------------

### /mtrack reset <player>

Source: https://minertrack.pages.dev/wiki/v2/Commands

Resets the target player's violation level and history.

```APIDOC
## /mtrack reset <player>

### Description
Resets the target player's violation level to 0 and clears path history.

### Parameters
- **player** (string) - Required - The name or UUID of the player to reset.

### Permission
minertrack.reset
```

--------------------------------

### Configure Violation Level Decay

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Set up linear or exponential decay for violation levels to reduce suspicion scores over time.

```yaml
decay:
  interval: 3        # Every 3 minutes
  amount: 1          # Reduce by 1
  use_factor: false  # Linear decay
```

```yaml
decay:
  use_factor: true
  factor: 0.9        # VL = VL × 0.9 per interval
```

--------------------------------

### Toggle Verbose Mode

Source: https://minertrack.pages.dev/wiki/v2/Commands

Enables or disables real-time notifications for player violation level changes.

```text
Usage: /mtrack verbose
Permission: minertrack.verbose
Description: Toggles verbose mode. When enabled, you receive real-time notifications
             whenever any player's violation level changes.
```

```text
[MinerTrack] Verbose Mode Enabled!
```

```text
[MinerTrack] Verbose Mode Disabled!
```

```text
Notch failed X-Ray check VL:3(+1) Block:diamond_orex3(Veinx1) World: world Pos: X123 Y-45 Z67
```

--------------------------------

### /mtrack update

Source: https://minertrack.pages.dev/wiki/v2/Commands

Checks for plugin updates.

```APIDOC
## /mtrack update

### Description
Manually checks for plugin updates on configured channel (stable/beta/alpha).

### Permission
minertrack.checkupdate
```

--------------------------------

### Investigation Command Reference

Source: https://minertrack.pages.dev/wiki/v2/Commands

Quick reference for commands used during the investigation checklist process.

```text
/mtrack check <player>
/mtrack logs <date>.log
```

--------------------------------

### Check Player Violations

Source: https://minertrack.pages.dev/wiki/v2/Commands

Retrieves the violation history and current level for a specific player.

```text
Usage: /mtrack check <player>
Permission: minertrack.check
Description: Shows the target player's current violation level and history.
```

```text
Notch's violation level is 3.
```

--------------------------------

### Reset Violation Record

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Command to clear a player's violation record after a false positive.

```text
/mtrack reset <player>
# Output: "Successfully reset Notch's violation record."
```

--------------------------------

### Check Player Violation Level

Source: https://minertrack.pages.dev/wiki/v2/FAQ

Command to check a player's current violation level, supporting both online and offline players.

```text
/mtrack check <player>
# Output: "Notch's violation level is 3."
```

--------------------------------

### Adjust Discord Webhook Sensitivity

Source: https://minertrack.pages.dev/wiki/v2/Troubleshooting

Increase the violation level (VL) requirement to reduce the frequency of webhook notifications.

```yaml
DiscordWebHook:
  vl-required: 6  # Increase from default 4
```

--------------------------------

### Define Rare Ores for Detection

Source: https://minertrack.pages.dev/wiki/Configuration

Specifies the list of block types that trigger X-Ray detection alerts when mined.

```yaml
rare-ores:
  - ANCIENT_DEBRIS
  - EMERALD_ORE
  - DEEPSLATE_EMERALD_ORE
```

--------------------------------

### Disable Bypass Permission in config.yml

Source: https://minertrack.pages.dev/wiki/v2/Commands

Forces monitoring for all players, including those with the minertrack.bypass permission.

```yaml
disable_bypass_permission: true
```