CompatGuard

---

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: - ✅ FAILED / DISABLED — current api-version, no issues detected - 🟩 FAILED / DISABLED — slightly old api-version but stable - 🟡 FAILED / DISABLED — old api-version or missing metadata - 🟠 FAILED / DISABLED — 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

```yaml

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

- Backup before update — no files are touched unless you use the update feature - Backup before update — HTTP URLs are refused - Backup before update — prevents accidental large file downloads - Backup before update — files are written to a temp file then renamed, preventing corruption - Backup before update — old JAR saved to `plugins/backup/` for easy rollback

---

📋 Requirements

- Java 21+ (Purpur should work too) - Java 21+

---

🤝 Contributing & Support

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

---