---

CompatGuard

The intelligent plugin manager for Paper 1.21.x servers.

CompatGuard helps server administrators instantly see which plugins are outdated or incompatible — with zero configuration required. It auto-detects update sources, estimates compatibility risk, and lets you update plugins with a single click, right from the game.

---

✨ Features

🔍 Plugin Compatibility Scanning

• Scans every installed plugin's metadata on startup (or on demand)
• Classifies each plugin into five risk levels:
  • ✅ SAFE — current api-version, no issues detected
  • 🟩 LIKELY SAFE — slightly old api-version but stable
  • 🟡 REVIEW NEEDED — old api-version or missing metadata
  • 🟠 HIGH RISK — very old api-version, high incompatibility chance
  • 🔴 FAILED / DISABLED — plugin failed to load
• Configurable scoring rules in rules.yml
• Detailed per-plugin reports with /cg report <name>

🔄 Intelligent Auto-Update Detection

• Zero manual configuration — automatically finds update sources:
  1. Parses the plugin's website field for a GitHub URL
  2. Searches Modrinth by plugin name (fuzzy match)
  3. Searches Spiget (SpigotMC) by plugin name
  4. Probes common GitHub release filename patterns as a fallback
• Manual overrides available via sources.yml for niche or private plugins

⬆️ Safe In-Game Updates

• Clickable [✔ Update Now] / [✘ Skip] buttons when you join (if updates exist)
• Updates are staged in plugins/update/ — the running server JAR is never touched
• Applied on the next server restart via Paper's built-in update mechanism
• Clickable [✔ Restart Now] / [✘ Later] prompt after staging
• Backup old JAR to plugins/backup/ before downloading (configurable, on by default)

🤖 Auto-Update on Startup

• Enable auto-update: true to automatically download all available updates on startup
• Optional auto-restart-after-update: true for fully hands-off update cycles
• Configurable delay so async checks complete before downloads begin

🔔 Discord Webhook Notifications

• Posts a rich embed to your Discord channel when updates are found
• Colour-coded: 🟠 orange for updates, 🟢 green for all-clear
• Lists each outdated plugin with old → new version and source type
• Configurable per-server name in footer

📋 Admin Tools

Command	Description
/cg	Open paginated GUI or console summary
/cg scan	Re-scan all plugins immediately
/cg checkupdates	Check updates (async) and print results
/cg update <name>	Download & stage update for a specific plugin
/cg debug <name>	Full update status: version, source, URL, JAR path
/cg report [name]	Server-wide or per-plugin report + JSON export
/cg reload	Reload all config files

📁 Reports

• JSON reports saved to plugins/CompatGuard/reports/
• Includes version, status, score, warnings, and update result per plugin

---

⚙️ Configuration Highlights

# Auto-detect sources (GitHub, Modrinth, Spiget) — no manual setup needed
auto-detect-sources: true

# Plugins to exclude from all checks
ignore:
  - SomePrivatePlugin

# Download updates automatically on startup
auto-update: false

# Notify OPs with clickable update prompts when they join
notify-ops-on-join: true

# Backup old JAR before staging new version (strongly recommended)
backup-before-update: true

# Re-scan every N hours automatically (0 = off)
auto-scan-interval-hours: 0

# Discord webhook for update reports
discord:
  enabled: false
  webhook-url: ""
  server-name: "My Server"

---

🛡️ Safety Guarantees

• Read-only by default — no files are touched unless you use the update feature
• HTTPS-only downloads — HTTP URLs are refused
• 50 MB download cap — prevents accidental large file downloads
• Atomic staging — files are written to a temp file then renamed, preventing corruption
• Backup before update — old JAR saved to plugins/backup/ for easy rollback

---

📋 Requirements

• Paper 1.21.x (Purpur should work too)
• Java 21+

---

🤝 Contributing & Support

• Discord: [https://discord.com/invite/pDPJ92VVv8]

---