Frequently Asked Questions

2026-07-30

Comprehensive answers to common MinerTrack questions.

📥 Installation & Setup

How do I install MinerTrack?

See the Installation Guide for complete steps. Quick version:

Download from Modrinth, Hangar, or CurseForge
Place JAR in plugins/ folder
Start server → configs generate automatically
Run /mtrack reload after any config changes

What server software is supported?

Software	Supported?
Paper	✅ Yes (primary target)
Purpur	✅ Yes
Folia	✅ Yes (region-aware)
Paper Forks (Pufferfish, etc.)	✅ Mostly
Spigot / CraftBukkit	❌ No
Forge / Fabric (server)	⚠️ Use Fabric mod version
Vanilla	❌ No

What Java version do I need?

Minecraft Version	Minimum Java	Recommended
1.18.x – 1.20.x	Java 17	Java 17
1.21.x	Java 21	Java 21
26.x (1.21.4+)	Java 21	Java 21

Does MinerTrack work on Spigot?

No. MinerTrack requires Paper-specific APIs for performance and async chunk access. Spigot lacks these APIs. Please migrate to Paper, Purpur, or Folia — they're drop-in replacements with better performance.

⚙️ Configuration

How do I configure MinerTrack?

See the Configuration Guide for complete reference. Three config layers:

config.yml — Global settings, webhooks, decay, commands
Configuration/<world>.yml — Per-dimension detection tuning
language.yml — Messages, prefixes, formatting

What are the default rare ores?

Overworld (overworld.yml):

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

Nether (nether.yml):

rare-ores:
  - minecraft:ancient_debris

End (end.yml): Detection disabled by default.

How do I add modded ores?

Use Minecraft namespace format (namespace:path):

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

Find the namespace with /mtrack check while mining the ore, or check the mod's documentation.

What is Violation Level (VL)?

VL is a cumulative score representing suspicion level:

Starts at 0
Increases when rare ore mining patterns match X-ray behavior
Decreases over time when mining normally (decay)
Triggers commands/webhooks at thresholds (configurable)

How does VL decay work?

Default (config.yml):

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

Example: Player at VL 5 mines normally → 15 minutes later VL = 0.

Exponential decay (optional):

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

How do I disable detection in a world?

Edit Configuration/<world>.yml:

xray:
  enable: false

How do I change the kick message?

Edit language.yml:

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

Placeholders: %player%, %reason%

🎮 Commands & Permissions

What permissions do staff need?

Role	Permissions
Admin	`minertrack.*` (all)
Moderator	`minertrack.use`, `check`, `verbose`, `notify`, `logs`, `sendnotify`
Helper	`minertrack.use`, `notify`
Investigator	`minertrack.use`, `check`, `logs`, `verbose`

See Commands & Permissions for full list.

How do I give a player bypass permission?

⚠️ Use sparingly! Only for server owners testing.

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

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

To monitor everyone including bypass holders:

# config.yml
disable_bypass_permission: true

How do I check a player's VL?

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

Works for offline players too (UUID lookup).

How do I reset a false positive?

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

🔍 Detection Logic

How does MinerTrack detect X-ray?

Multi-dimensional analysis (not ore hiding):

Factor	What It Checks
Ore Rarity	Only configured rare ores trigger checks
Vein Count	Distinct veins mined in session
Path Analysis	Turns, branches, Y-changes, directness
Natural Context	Cave air, water, lava → reduces false positives
VL Accumulation	Score that decays with normal behavior

Why doesn't it hide ores like Paper Anti-XRay?

Ore hiding (Orebfuscator/Paper Anti-XRay) consumes significant CPU/RAM — it modifies chunk packets for every player. MinerTrack uses behavioral analysis which is:

Lightweight — minimal performance impact
Accurate — catches X-rayers who mine "too perfectly"
Flexible — you decide punishment (kick, ban, warn, log)

Can X-ray users bypass detection?

Two choices for X-rayers:

Mine like a normal player → Defeats purpose of X-ray (no advantage)
Use X-ray obviously → Caught by MinerTrack

No perfect bypass exists — the algorithm analyzes patterns humans can't consistently fake.

Why am I getting false positives?

Common causes:

Custom ore generation — Rare ores more common than vanilla
Cave mining — Natural detection not tuned for your world
Branch mining — Path detection flags efficient patterns
Lucky streaks — Statistical anomalies happen

Solutions: See Troubleshooting → False Positives

Why are X-rayers not being caught?

Common causes:

Wrong rare ores configured — Missing the ores they're targeting
VL thresholds too high — veinCountThreshold too large
Natural detection too forgiving — check_skip_vl: true in caves
Bypass permission — They have minertrack.bypass
Detection disabled — xray.enable: false for that world

Solutions: See Troubleshooting → False Negatives

🔔 Discord Webhooks

How do I set up Discord alerts?

Create webhook in Discord: Server Settings → Integrations → Webhooks → New Webhook
Copy webhook URL
Edit config.yml:

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

/mtrack reload

What placeholders work in webhooks?

Placeholder	Example
`%player%`	`Notch`
`%player_uuid%`	`069a79f4-...`
`%player_vl%`	`5`
`%ore_type%`	`minecraft:diamond_ore`
`%ore_count%`	`3`
`%mined_veins%`	`2`
`%world%`	`world`
`%pos_x%`, `%pos_y%`, `%pos_z%`	`123`, `-45`, `67`
`%timestamp%`	`2024-01-15 14:30:22`

Can I use custom JSON?

Yes! Enable in config.yml:

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}
          ]
        }]
      }

🐛 Issues & Support

Plugin not loading / errors in console

Error	Fix
`Unsupported class version`	Upgrade to Java 17+ (21 for 1.21+)
`Could not load plugin`	Wrong server type — use Paper/Purpur/Folia
`Invalid config version`	Delete config folder, restart (backup first!)
`NoSuchMethodError`	Version mismatch — update MinerTrack + Paper

Where are log files?

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

View in-game: /mtrack logs 2024-01-15.log

How do I report a bug?

Check Troubleshooting and this FAQ
Enable debug: true in config.yml temporarily
Collect:
- Server: Paper 1.21.1 #123 (from /version)
- Java: java -version
- MinerTrack: /mtrack update or JAR filename
- Config snippets (redact webhook URLs)
- Console logs (pastebin.com)
Open issue: https://github.com/At87668/MinerTrack/issues

Where can I get help?

Channel	Link	Best For
Discord	https://discord.gg/MzTea2W9cb	Quick questions, real-time help
GitHub Issues	https://github.com/At87668/MinerTrack/issues	Bug reports, feature requests
GitHub Discussions	https://github.com/At87668/MinerTrack/discussions	Config help, general questions

🔄 Updates & Compatibility

How do I update MinerTrack?

Backup /plugins/MinerTrack/
Download new JAR
Replace old JAR
Restart server or /mtrack reload
Check console for config migration notes

Is MinerTrack compatible with other anti-cheat plugins?

Generally yes. MinerTrack only listens to BlockBreakEvent and doesn't modify gameplay. Known compatible:

AAC, Matrix, Vulcan, NoCheatPlus — no conflicts
Paper Anti-XRay — can run together (redundant but safe)
Orebfuscator — redundant, not needed

Potential conflicts: Plugins that cancel BlockBreakEvent or modify mining speed significantly.

Does it work with WorldGuard / GriefPrevention?

Yes — MinerTrack doesn't interact with region plugins. Detection runs regardless of claims.

Does it work with custom world generators (Terralith, etc.)?

Yes, but you may need to adjust rare-ores if the generator changes ore rarity/distribution. Test and tune.

💰 Licensing & Support

Is MinerTrack free?

Yes — GPLv3 licensed, completely free. Source: https://github.com/At87668/MinerTrack

Can I support the developer?

Yes! Options:

Patreon: https://patreon.com/Author87668
GitHub Sponsors: https://github.com/sponsors/At87668
Star the repo: https://github.com/At87668/MinerTrack

Can I use MinerTrack on my commercial server?

Yes — GPLv3 allows commercial use. You must provide source code if you modify the plugin.

Installation — Setup guide
Configuration — All config options
Commands — Staff commands & permissions
Troubleshooting — Issue resolution

Troubleshooting

Legacy v1 Wiki

MinerTrack Wiki