🔥 EnchancedBan (v1.0.0)

---

📖 Overview

EnchancedBan is a next-generation, high-performance punishment and moderation suite built exclusively for modern Paper and Purpur servers (supporting versions 1.20.x through 1.21+).

Engineered from the ground up to replace outdated ban plugins, EnchancedBan merges high-speed asynchronous database architecture with modern Kyori Adventure MiniMessage crimson gradient aesthetics, LibertyBans-inspired multi-tier Alt Account Detection, and comprehensive Network Guard Geolocation Analysis.

---

✨ Key Features

🩸 1. Striking Crimson Gradient UI

• Full native Kyori Adventure MiniMessage rendering (no legacy formatting glitches).
• Stunning crimson & blood-red gradients (<gradient:#ff416c:#8a2387>, <gradient:#ff3333:#8a0000>) that give server discipline an authoritative, premium feel.
• Interactive hover cards (UUIDs, punishers, remaining times) and clickable shortcut actions.

🔍 2. LibertyBans-Style Alt Account Detection (/alts)

• Multi-Tier Detection Levels:
  • NORMAL (Strong Match): Accounts currently sharing the same IP address.
  • STRICT (Historical Match): Accounts that have connected from a shared IP in the past.
• Dynamic Punishment Coloring:
  • 🔴 Banned Alts: Displayed in red italics (<red><i>).
  • 🟡 Muted Alts: Displayed in gold italics (<yellow><i>).
  • 🟢 Clean Alts: Displayed in gray italics (<gray><i>).
• Staff Join Alerts: When a player joins, staff with enchancedban.alts.notify instantly see known alt accounts and their status.
• Privacy IP Masking: IP addresses are masked by default (192.168.***.***) unless staff hold the enchancedban.alts.ip permission.

🛡️ 3. Network Guard Geolocation & Security (/guard analyze)

• Dual-provider fast geolocation lookup (ipwho.is with automatic fallback to ip-api.com).
• Displays Country, City, Region, ISP/Organization, Timezone, and City Accuracy Percentage.
• Proxy / VPN / Hosting Detection: Highlights suspicious connection routes instantly.
• In-memory caching engine to prevent rate limits or server freezes.

⚖️ 4. Comprehensive Punishment Suite

• Bans & Tempbans: /ban, /tempban, /unban.
• IP-Bans & Temp-IP-Bans: /ipban, /tempipban, /unbanip.
• Mutes & Tempmutes: /mute, /tempmute, /unmute (blocks chat and private whispers).
• Kicks: /kick with a stylish custom disconnect banner.
• Warnings & Automated Escalation:
  • Issue formal warnings with /warn, view active warnings with /warns, and clear them with /clearwarns.
  • Auto-Punish Escalation: Configure thresholds (e.g. 3 warns = 2h tempmute, 5 warns = 1d tempban, 7 warns = permanent ban).
• Rollback System (/rollback <staff> <duration>):
  • Instantly undo accidental or rogue moderator ban waves in seconds!
• Silent Flag (-s):
  • Add -s anywhere in punishment commands to suppress public broadcasts and notify staff only.

⚡ 5. Enterprise Asynchronous Performance

• Built on HikariCP high-performance connection pooling.
• Supports zero-setup SQLite (default) and scalable MySQL / MariaDB.
• 100% asynchronous database operations with in-memory caching for zero-tick login checks.

💬 6. Discord Webhook Integration

• Built-in async Discord webhook notification system.
• Sends rich crimson #C21807 embeds featuring target player, staff issuer, duration, and reason.

---

💻 Commands & Permissions

Moderation Commands

Command	Arguments	Permission	Description
/ban	<player> [reason] [-s]	enchancedban.ban	Permanently ban a player.
/tempban	<player> <duration> [reason] [-s]	enchancedban.tempban	Temporarily ban a player (e.g. 30m, 2h, 7d, 1mo).
/ipban	<player|ip> [reason] [-s]	enchancedban.ipban	Permanently ban an IP address.
/tempipban	<player|ip> <duration> [reason] [-s]	enchancedban.tempipban	Temporarily ban an IP address.
/unban	<player|uuid>	enchancedban.unban	Unban a player.
/unbanip	<ip>	enchancedban.unbanip	Unban an IP address.
/mute	<player> [reason] [-s]	enchancedban.mute	Permanently mute a player in chat and whispers.
/tempmute	<player> <duration> [reason] [-s]	enchancedban.tempmute	Temporarily mute a player.
/unmute	<player>	enchancedban.unmute	Unmute a muted player.
/warn	<player> [reason] [-s]	enchancedban.warn	Issue a formal warning to a player.
/warns	<player>	enchancedban.warn	View all active warnings for a player.
/clearwarns	<player>	enchancedban.clearwarns	Clear all active warnings for a player.
/kick	<player> [reason] [-s]	enchancedban.kick	Kick an online player from the server.

Analytics & Investigation Commands

Command	Arguments	Permission	Description
/check	<player>	enchancedban.check	View quick overview of ban, mute, warn count, and alts.
/history	<player> [page]	enchancedban.history	View paginated historical punishment logs.
/alts	<player> [page]	enchancedban.alts	Scan and display associated alt accounts (Normal vs Strict).
/guard	analyze <player>	enchancedban.guard	Run IP geolocation, ISP, and VPN/proxy security scan.
/rollback	<staff> <duration>	enchancedban.rollback	Mass undo active punishments issued by a staff member.
/enchancedban	reload	enchancedban.admin	Reload config.yml and messages.yml.

---

🔐 Permissions Reference

Permission Node	Description	Default
enchancedban.*	Grants full access to all EnchancedBan features.	op
enchancedban.admin	Access to reload configs and administrative commands.	op
enchancedban.exempt	Makes player immune to being banned, muted, warned, or kicked.	false
enchancedban.silent	Allows seeing silent punishment broadcasts (-s).	op
enchancedban.alts.notify	Receives automatic staff notifications when a player joins with alts.	op
enchancedban.alts.ip	Displays unmasked IP addresses in /alts lookup results.	op
enchancedban.guard.ip	Displays unmasked IP addresses in /guard analyze results.	op

---

⚙️ Configuration (config.yml)

# Database Storage Settings
storage:
  type: sqlite # sqlite, mysql, or mariadb
  sqlite:
    file: "enchancedban.db"

# Alt Account Detection
alts:
  alert-on-join: true        # Alert staff when player with alts connects
  alert-only-punished: false # Only alert if at least 1 alt is banned/muted
  alert-limit: 6            # Max alts to show in join alerts
  per-page: 8               # Entries per page in /alts

# Geolocation Guard
guard:
  cache-minutes: 60
  timeout-ms: 4000

# Automated Warn Escalation Actions
warn-actions:
  enabled: true
  actions:
    3: "tempmute {player} 2h Reached 3 warnings"
    5: "tempban {player} 1d Reached 5 warnings"
    7: "ban {player} Permanent ban due to repeated offenses"

# Discord Webhook
discord:
  enabled: false
  webhook-url: ""
  server-name: "Survival"
  embed-color: "#C21807"

---

🔨 Building from Source

Requirements

• JDK 21 or newer
• Maven 3.8+ (or use the included mvnw.cmd wrapper)

Build Steps

git clone https://github.com/DarkIgnite/EnchancedBan.git
cd EnchancedBan
.\mvnw.cmd clean package

The compiled shaded jar will be located at: target/enchancedban-1.0.0.jar

---

👨‍💻 Author & Credits

• Creator & Lead Developer: DarkIgnite
• Inspiration: Developed as an advanced modernization of AdvancedBan and LibertyBans.
• License: GNU General Public License v3.0 (GPL-3.0).