Commands:

• /medusa reload
  Description: Reloads the plugin configuration.
  Permission required: medusa.admin
  
• /medusa check <player>
  Description: View live mining statistics for a specific player (score, mined block count, and suspicion ratio).
  Permission required: medusa.admin

Permissions:

• medusa.admin - Allows execution of all /medusa administrative commands. (Default: OP)
• medusa.staff - Allows receiving real-time X-ray alerts when a player triggers the ratio threshold. (Default: OP)
• medusa.bypass - Exempts trusted players/staff from being tracked or evaluated by the detection system. (Default: False)

# =============================================
# Medusa-Anti-Xray Configuration
# Author: PerseusJ | API: 1.20+
# =============================================

detection:
# Minimum blocks mined before ratio is evaluated (prevents early false flags)
min-sample-size: 64

# Ratio of (weighted suspicious ore score / total blocks) to trigger alert
# 0.08 = ~8% of mined blocks are high-value, well above natural ~1-2%
alert-threshold: 0.08

# Sliding window duration in minutes
window-minutes: 30

# Weight applied to ores that had NO exposed face (fully hidden = suspicious)
hidden-ore-weight: 1.0

# Weight applied to ores that had at least one face exposed to air (cave mining)
exposed-ore-weight: 0.25

worlds:
overworld:
enabled: true
# The exact world name(s) treated as Overworld. Supports multiple entries.
names:
- "world"
tracked-ores:
- DIAMOND_ORE
- DEEPSLATE_DIAMOND_ORE
- GOLD_ORE
- DEEPSLATE_GOLD_ORE
- EMERALD_ORE
- DEEPSLATE_EMERALD_ORE
# All stone-family blocks counted as "filler" for ratio denominator
filler-blocks:
- STONE
- DEEPSLATE
- TUFF
- COBBLESTONE
- COBBLED_DEEPSLATE
- GRAVEL
- DIRT
- ANDESITE
- DIORITE
- GRANITE

nether:
enabled: true
names:
- "world_nether"
tracked-ores:
- ANCIENT_DEBRIS
filler-blocks:
- NETHERRACK
- BASALT
- BLACKSTONE
- SOUL_SAND
- SOUL_SOIL

alerts:
# Seconds between repeated alerts for the same player (prevents chat spam)
cooldown-seconds: 60

# Permission required to receive alerts
staff-permission: "medusa.staff"

# Message prefix (supports & color codes and hex #RRGGBB)
prefix: "&8[&4Medusa&8]&r"

# Alert message placeholders: {player}, {ratio}, {score}, {total}
alert-message: "{prefix} &c⚠ {player} &7may be X-raying! &cRatio: &f{ratio}% &7({score} pts / {total} blocks)"

# Message sent to /medusa check executor
check-message: "&7Player &f{player} &7| Score: &c{score} &7| Total: &f{total} &7| Ratio: &c{ratio}% &7| Window: &f{window}m"

messages:
no-permission: "&cYou don't have permission to use this command."
reload-success: "&aConfiguration reloaded successfully."
player-not-found: "&cPlayer &f{player} &cnot found or has no data."
usage-check: "&cUsage: /medusa check <player>"

1. Block Break Event: When a player mines a block in a configured world, Medusa checks if it is a Tracked Ore or a Filler Block.
2. Exposure Checks: If it is a tracked ore, the system checks all 6 neighboring block faces. If any face touches air (AIR, CAVE_AIR, VOID_AIR), the ore is marked as Exposed; otherwise, it is Hidden.
3. Score Assignment:
   • Exposed Ore = 0.25 points (likely mined during normal cave exploration)
   • Hidden Ore = 1.00 points (mined straight through solid rock, highly suspicious)
   • Filler Blocks = 0.00 points
4. Window & Sample Size Evaluation: As blocks are mined, they are pushed into a sliding window (default: 30 minutes). Once a player mines at least 64 blocks (min-sample-size) of tracked/filler blocks combined, their ratio is calculated:
   
   Suspicion Ratio = Total Ore Points / Total Blocks Mined​
5. Alert Dispatch: If the ratio exceeds 0.08 (8% score-to-block ratio), and the player is not on cooldown, a real-time warning is broadcasted to all staff members with medusa.staff.