You are an expert Minecraft plugin developer. Create a complete, production-ready plugin called "NexaCombat" for Paper 1.21.11 (Java 21, Maven or Gradle).
It should be a better, cleaner and more polished replacement for DonutCombat.
═══ DEFAULT VALUES (IMPORTANT) ═══
- Combat time: 15 seconds (NOT 10). Config key: combat-time: 15
- Ender pearl cooldown: 5 seconds. Config key: enderpearl-cooldown.seconds: 5
═══ AESTHETICS & RGB GRADIENTS (IMPORTANT) ═══ The whole plugin must look beautiful, modern and colourful.
- Every player-facing text (actionbar, bossbar, chat, titles, command output,
help menu, errors) must use Adventure MiniMessage with real RGB gradients.
Never use plain white or default gray-only messages.
- Use a consistent theme palette, defined in config.yml under
theme: so
server owners can change it: primary: #FF3B3B -> #FFD800 (combat, red to gold) safe: #00FF9D -> #E6FF52 (combat ended, green to lime) cooldown: #B06BFF -> #4280FF (ender pearl, purple to blue) timer: #00E5FF -> #2E9BFF (numbers, cyan to blue) error: #FF3B3B -> #FF7A24 (denied actions) prefix: <gradient:#FF3B3B:#FFD800><bold>NexaCombat</bold></gradient> <dark_gray>»</dark_gray>
- Support multi-stop gradients, e.g. <gradient:#FF3B3B:#FF9A1A:#FFD800>.
- Animated gradient: the combat actionbar gradient should slowly shift/scroll
every few ticks (use the MiniMessage gradient phase, toggleable in config).
- Dynamic timer colour: the {time} number goes cyan (15-10s) -> yellow (9-5s)
-> red (4-0s), and flashes in the last 3 seconds.
- Bossbar: gradient title, colour switches green -> yellow -> red as time
drops, with a smooth progress bar.
- Titles/subtitles on combat start and combat end (fade in/stay/out are
configurable), with gradients and small symbols like ⚔ ✔ ✖ ⌛.
- Use clean separators and symbols (» ⚔ ✦ ❖) and a nicely formatted,
gradient /nexacombat help menu with clickable and hoverable entries.
- Legacy fallback: also support &#RRGGBB and & codes, auto-converted.
- All of the above must live in messages.yml and config.yml so every colour
can be edited without recompiling.
═══ CORE FEATURES ═══
- Combat tagging
- Both attacker and victim get tagged when a player hits another player. - Optional tagging from: arrows/crossbow bolts, tridents, wind charges, fishing rods, splash/lingering potions, TNT/crystals (each toggleable). - Re-hitting resets the timer to 15 seconds. - Players with permission nexacombat.bypass are never tagged. - Creative/spectator players are ignored (configurable).
- Timer display (choose in config: actionbar, bossbar, or both)
- Use Adventure MiniMessage with real gradients, e.g. <gradient:#FF3B3B:#FFD800>Combat</gradient> <gray>»</gray> <gradient:#00E5FF:#2E9BFF>{time}s</gradient> - Bossbar progress shrinks as the timer runs out, and its colour changes (green → yellow → red) based on time left. - Support legacy &#RRGGBB codes as a fallback.
- SOUNDS (very important, fully configurable)
- On entering combat: sound, volume and pitch from config, plus a gradient title/actionbar message. - On combat ending: a satisfying "safe" sound plus a gradient chat/actionbar message. - Optional countdown tick sound for the last 5 seconds, with pitch rising each second. - Sound when a blocked command, pearl cooldown or blocked elytra is attempted. - Every sound entry uses: enabled, sound, volume, pitch. Validate sound keys on load and log a clear warning for invalid ones.
- Ender pearl cooldown
- Default cooldown: 5 seconds, configurable via enderpearl-cooldown.seconds. - Option only-in-combat (default false) to apply the cooldown only while in combat. - Show remaining time in the actionbar with the cooldown gradient and play the denied sound. - Show the vanilla item cooldown overlay on the pearl for exactly 5 seconds (100 ticks). - Block pearls entirely in combat inside configured WorldGuard regions.
- Restrictions while in combat (all toggleable)
- Blocked commands list (support wildcard and aliases, case-insensitive). - Disable flying (creative/survival flight), elytra gliding, riptide, chorus fruit, and optionally shulker/ender chest opening. - Optional: block placing/breaking specific blocks (e.g. cobwebs, lava).
- Combat logging
- If a player quits in combat: configurable action (kill, drop items only, nothing). Broadcast a gradient message. Handle kicks separately. - Remove tag on death. Optionally remove tag when the opponent dies.
- WorldGuard integration (soft-depend)
- blacklist/whitelist modes with a region list. - Custom flag "nexacombat-tag" (allow/deny) registered safely. - Plugin must work perfectly without WorldGuard installed.
- Extras
- PlaceholderAPI (soft-depend): %nexacombat_in_combat%, %nexacombat_time_left%, %nexacombat_opponent%, %nexacombat_pearl_cooldown%. - Public API: NexaCombatAPI with isInCombat(UUID), getTimeLeft(UUID), tag(UUID, seconds), untag(UUID), plus custom events:
PlayerCombatTagEvent (cancellable), PlayerCombatEndEvent (with reason:
EXPIRED, DEATH, QUIT, COMMAND, OPPONENT_DIED).
═══ COMMANDS & PERMISSIONS ═══ /nexacombat reload | check <player> | tag <player> [seconds] | untag <player> | help Aliases: /ncombat, /nc Permissions: nexacombat.admin, nexacombat.reload, nexacombat.bypass, nexacombat.check, nexacombat.tag, nexacombat.untag.
Full tab completion, with permission-aware suggestions.
═══ FILES ═══
- config.yml: heavily commented, with sections and ═══ dividers, including
the theme: palette. Defaults: combat-time: 15, enderpearl-cooldown.seconds: 5.
- messages.yml: all text in MiniMessage, with gradient examples for every message.
- plugin.yml (or paper-plugin.yml): api-version 1.21, softdepend WorldGuard,
PlaceholderAPI.
═══ CODE QUALITY REQUIREMENTS ═══
- Clean package structure (manager, listener, command, config, api, util, hook).
- Use ConcurrentHashMap for state and one repeating scheduler task (every 10 ticks
or less), not one task per player.
- No memory leaks: clean up all maps on quit/disable.
- Folia-compatible scheduling if possible (use a scheduler abstraction).
- Config reload without restart; migrate/add missing keys automatically.
- No deprecated APIs; null-safe; no main-thread blocking.
- Include comments only where logic is non-obvious.
═══ OUTPUT FORMAT ═══ Give me: the full project tree, then every file in full (pom.xml/build.gradle, plugin.yml, config.yml, messages.yml, all Java classes), then build instructions. Do not skip or abbreviate any file.