{"id":37228523,"url":"https://github.com/cavarest/papermc-plugin-dragon-egg","last_synced_at":"2026-01-15T03:28:09.513Z","repository":{"id":330708156,"uuid":"1121799649","full_name":"cavarest/papermc-plugin-dragon-egg","owner":"cavarest","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-11T12:43:15.000Z","size":1826,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:52:14.786Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cavarest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T15:17:43.000Z","updated_at":"2026-01-11T12:42:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cavarest/papermc-plugin-dragon-egg","commit_stats":null,"previous_names":["ronaldtse/papermc-plugin-dragon-egg"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/cavarest/papermc-plugin-dragon-egg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavarest%2Fpapermc-plugin-dragon-egg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavarest%2Fpapermc-plugin-dragon-egg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavarest%2Fpapermc-plugin-dragon-egg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavarest%2Fpapermc-plugin-dragon-egg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cavarest","download_url":"https://codeload.github.com/cavarest/papermc-plugin-dragon-egg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavarest%2Fpapermc-plugin-dragon-egg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-15T03:28:08.499Z","updated_at":"2026-01-15T03:28:09.504Z","avatar_url":"https://github.com/cavarest.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ Elemental Dragon Plugin\n\n\u003cdiv align=\"center\"\u003e\n\n![Dragon Egg Lightning Banner](https://img.shields.io/badge/Minecraft-Paper%201.21.8-blue?logo=minecraft\u0026style=for-the-badge)\n![Java](https://img.shields.io/badge/Java-21+-ED8B00?logo=openjdk\u0026logoColor=white\u0026style=for-the-badge)\n![Version](https://img.shields.io/badge/Version-1.1.0-green?style=for-the-badge)\n![Build](https://img.shields.io/badge/Build-Passing-brightgreen?style=for-the-badge)\n\n**Transform your server with elemental powers from ancient dragon fragments!**\n\n[![Download Latest Release](https://img.shields.io/badge/Download-Latest%20Release-ff6b6b?style=for-the-badge\u0026logo=github)](https://github.com/cavarest/papermc-plugin-dragon-egg/releases/latest)\n[![GitHub Stars](https://img.shields.io/github/stars/cavarest/papermc-plugin-dragon-egg?style=social)](https://github.com/cavarest/papermc-plugin-dragon-egg)\n[![GitHub Forks](https://img.shields.io/github/forks/cavarest/papermc-plugin-dragon-egg/fork?style=social)](https://github.com/cavarest/papermc-plugin-dragon-egg/fork)\n\n\u003c/div\u003e\n\n## 🌟 Quick Start (5 Minutes)\n\n### **Step 1: Install Plugin**\n```bash\n# Download the latest JAR from releases\n# Place in your Paper server's plugins directory\ncp ElementalDragon-1.1.0.jar /path/to/your/paper-server/plugins/\n\n# Restart your Paper 1.21.8+ server\njava -Xms2G -Xmx2G -jar paper-1.21.8-latest.jar nogui\n```\n\n### **Step 2: Use Lightning Ability**\n\n```bash\n# Give yourself a Dragon Egg\n/give @p minecraft:dragon_egg\n\n# Move to offhand (press F key)\n\n# Strike with lightning!\n/lightning 1\n\n# Watch the magic happen! ⚡\n```\n\n### **Step 3: Get Your First Fragment**\n```bash\n# Operators can give ingredients to players to craft fragments\n/ed give \u003cplayer\u003e ingredients fire\n\n# Operators can give fragments to players\n/ed give \u003cplayer\u003e equipment fire\n\n# Or show the recipe to craft them (requires Heavy Core)\n/craft heavy_core\n/craft fire\n```\n\n### **Step 4: Use Fragment Abilities**\n```bash\n# Once you have a fragment, you can equip it by:\n# a) hold on main hand and \"right-click\" to equip\n# b) or use command:\n/fire equip\n\n# Use abilities\n/fire 1    # Dragon's Wrath (fireball attack)\n/fire 2    # Infernal Dominion (fire ring)\n\n# Check status\n/fire status\n\n# Get help\n/fire help\n```\n\n---\n\n## 📖 Command Reference\n\n### **🎮 Player Commands**\n\nPlayers can use these commands to manage and activate their fragments.\n\n#### **Fragment Commands**\n```bash\n# Burning Fragment (Fire Element)\n/fire equip         # Equip Burning Fragment\n/fire 1            # Dragon's Wrath (fireball attack, 40s cooldown)\n/fire 2            # Infernal Dominion (area fire, 60s cooldown)\n/fire status       # Show fragment status and cooldowns\n/fire help         # Show available commands\n\n# Agility Fragment (Wind Element)\n/agile equip       # Equip Agility Fragment\n/agile 1           # Draconic Surge (speed boost, 30s cooldown)\n/agile 2           # Wing Burst (levitation jump, 45s cooldown)\n/agile status      # Show fragment status and cooldowns\n/agile help        # Show available commands\n\n# Immortal Fragment (Earth Element)\n/immortal equip    # Equip Immortal Fragment\n/immortal 1        # Draconic Reflex (damage reduction, 90s cooldown)\n/immortal 2        # Essence Rebirth (death protection, 5min cooldown)\n/immortal status   # Show fragment status and cooldowns\n/immortal help     # Show available commands\n\n# Corrupted Core (Void Element)\n/corrupt equip     # Equip Corrupted Core\n/corrupt 1         # Dread Gaze (blindness \u0026 slow, 60s cooldown)\n/corrupt 2         # Life Devourer (health steal, 90s cooldown)\n/corrupt status    # Show fragment status and cooldowns\n/corrupt help      # Show available commands\n```\n\n#### **Lightning Command (Legacy)**\n```bash\n/lightning 1       # Core lightning ability (60s cooldown)\n```\n\n#### **Utility Commands**\n```bash\n/craft \u003crecipe\u003e    # View crafting recipes\n/chronicle \u003ccmd\u003e   # Access lore and achievements\n```\n\n**Enhanced `/craft` Command Features**:\n\nThe `/craft` command dynamically generates recipe displays from the actual crafting system (single source of truth):\n\n```bash\n# View all available recipes\n/craft heavy_core          # Show Heavy Core crafting recipe\n/craft fire                # Show Burning Fragment recipe\n/craft agile               # Show Agility Fragment recipe\n/craft immortal            # Show Immortal Fragment recipe\n/craft corrupt             # Show Corrupted Core recipe\n```\n\n**Architecture Benefits**:\n- ✅ **Auto-generated displays**: Recipe text generated from actual `CraftingManager` recipes\n- ✅ **Always accurate**: Single source ensures displays match reality\n- ✅ **DRY principle**: Zero duplicate recipe definitions\n- ✅ **Easy maintenance**: Recipe changes only need one update location\n\n### **👑 Operator Commands**\n\nOperators have access to administrative functions for managing fragments, cooldowns, and player abilities.\n\n#### **Give Items**\n```bash\n# Give crafting ingredients\n/ed give \u003cplayer\u003e ingredients \u003celement\u003e\n/ed give @p ingredients fire      # Give materials to craft Burning Fragment\n/ed give @p ingredients agile     # Give materials to craft Agility Fragment\n\n# Give crafted equipment\n/ed give \u003cplayer\u003e equipment \u003celement\u003e\n/ed give @p equipment fire        # Give Burning Fragment directly\n/ed give @a equipment immortal    # Give Immortal Fragment to all players\n```\n\n**Supported Elements**: `fire`, `agile`, `immortal`, `corrupt`\n\n#### **Player Information**\n```bash\n# View individual player info\n/ed info player \u003cplayer\u003e\n/ed info player @p              # Current player\n/ed info player Steve           # Specific player\n\n# List all players\n/ed info list                   # Shows all online players with fragment status\n```\n\n#### **Cooldown Management**\n```bash\n# Set individual player cooldown\n/ed setcooldown \u003cplayer\u003e \u003celement\u003e \u003cability\u003e \u003cseconds\u003e\n/ed setcooldown @p fire 1 5               # Fire ability 1: 5s cooldown\n/ed setcooldown Steve agile 2 30          # Steve's agile ability 2: 30s\n\n# Clear player cooldowns\n/ed clearcooldown \u003cplayer\u003e [element]\n/ed clearcooldown @p                      # Clear all cooldowns\n/ed clearcooldown @p fire                 # Clear fire cooldowns only\n\n# Get player cooldowns\n/ed getcooldown \u003cplayer\u003e\n/ed getcooldown @p                        # View current player's cooldowns\n/ed getcooldown Steve                     # View Steve's cooldowns\n```\n\n**Elements**: `lightning`, `fire`, `agile`, `immortal`, `corrupt`\n**Abilities**: `1` or `2` (each element has 2 abilities)\n\n#### **Global Cooldown Configuration**\n```bash\n# Set default cooldown for an ability (affects all players)\n/ed setglobalcooldown \u003celement\u003e \u003cability\u003e \u003cseconds\u003e\n/ed setglobalcooldown fire 1 10           # Fire ability 1: 10s default\n/ed setglobalcooldown agile 2 60          # Agile ability 2: 60s default\n\n# Disable cooldowns (clears all active cooldowns)\n/ed setglobalcooldown fire 1 0            # Disables fire ability 1 cooldown\n/ed setglobalcooldown lightning 1 0       # Disables lightning cooldown\n\n# View all global cooldown settings\n/ed getglobalcooldown\n```\n\n**How Global Cooldowns Work**:\n1. Each ability has a default cooldown (e.g., Fire ability 1 = 40s)\n2. Operators can override defaults with `/ed setglobalcooldown`\n3. When players use abilities, the global cooldown is applied\n4. Individual player cooldowns can be managed with `/ed setcooldown`\n\n**Cooldown Adjustment Mechanics**:\n\nWhen you change a global cooldown, the system intelligently adjusts active player cooldowns using the **MIN formula**: `min(current_remaining, new_max)`\n\n- **Increasing cooldown**: Players with time remaining get capped at new maximum (fair to all)\n  - Example: Player has 30s left, you set 20s → Player gets 20s (capped fairly)\n  - Example: Player has 10s left, you set 20s → Player keeps 10s (no penalty)\n\n- **Decreasing cooldown**: Uses same MIN formula for consistency\n  - Example: Player has 60s left, you set 30s → Player gets 30s (capped)\n  - Example: Player has 20s left, you set 30s → Player keeps 20s\n\n- **Disabling cooldown (0 seconds)**: **Clears ALL active cooldowns** for that ability\n  - Example: `/ed setglobalcooldown fire 1 0` → All players can use fire ability 1 immediately\n  - Useful for: Events, testing, emergency cooldown resets\n\n**Real-World Examples**:\n```bash\n# Speed up cooldowns during server event\n/ed setglobalcooldown fire 1 10          # Faster fire attacks for everyone\n\n# Restore normal cooldowns after event (players capped fairly)\n/ed setglobalcooldown fire 1 40          # Players with \u003c 40s keep their time\n\n# Emergency cooldown clear for server issues\n/ed setglobalcooldown lightning 1 0      # Instant clear for all players\n/ed setglobalcooldown lightning 1 60     # Re-enable with normal cooldown\n```\n\n#### **Player References**\nAll commands support these player selectors:\n- `@p` - Nearest player (usually yourself)\n- `@s` - Command sender (yourself)\n- `@a` - All online players\n- `PlayerName` - Specific player by username\n\n---\n\n## 💎 Elemental Fragments System\n\nThe Elemental Dragon plugin features **4 complete elemental fragments**, each\nwith unique abilities, passive bonuses, and visual themes.\n\n### **🔥 Burning Fragment (Fire Element)**\n**Material**: Blaze Powder (red/orange visual)\n**Theme Color**: Red\n**Permission**: `elementaldragon.fragment.burning`\n\n**Abilities**:\n- **Dragon's Wrath** (`/fire 1`): Launch explosive fireball (40s cooldown)\n  - Damage: 4 hearts on impact\n  - Explosion power: 2.0 blocks radius\n  - Fire spread: Ignites targets\n  - Aliases: `wrath`, `dragons-wrath`\n\n- **Infernal Dominion** (`/fire 2`): Create fire ring around player (60s cooldown)\n  - Radius: 8 blocks\n  - Duration: 5 seconds\n  - Damage: 1 heart per tick to enemies in range\n  - Aliases: `dominion`, `infernal-dominion`\n\n**Passive Bonus**: Fire Resistance when equipped\n\n### **💨 Agility Fragment (Wind Element)**\n**Material**: Feather (light/swift visual)\n**Theme Color**: Aqua\n**Permission**: `elementaldragon.fragment.agility`\n\n**Abilities**:\n- **Draconic Surge** (`/agile 1`): Speed II + Jump II boost (30s cooldown)\n  - Speed: Level II for 10 seconds\n  - Jump Boost: Level II for 10 seconds\n  - Aliases: `surge`, `draconic-surge`\n\n- **Wing Burst** (`/agile 2`): Vertical launch with fall protection (45s cooldown)\n  - Vertical force: 1.5 blocks/tick\n  - Levitation: 2 seconds\n  - Slow Falling: 3 seconds (prevents fall damage)\n  - Aliases: `burst`, `wing-burst`\n\n**Passive Bonus**: Permanent Speed I when equipped\n\n### **🛡️ Immortal Fragment (Earth Element)**\n**Material**: Totem of Undying (golden/life visual)\n**Theme Color**: Green\n**Permission**: `elementaldragon.fragment.immortal`\n\n**Abilities**:\n- **Draconic Reflex** (`/immortal 1`): 75% damage reduction + reflection (90s cooldown)\n  - Damage reduction: 75% for 5 seconds\n  - Reflection: 25% melee damage reflected\n  - Aliases: `reflex`, `draconic-reflex`\n\n- **Essence Rebirth** (`/immortal 2`): Enhanced respawn benefits (5min cooldown)\n  - Diamond armor piece: Random piece on respawn\n  - Full hunger: 20 food level\n  - Arrows: 32 arrows if bow in inventory\n  - Aliases: `rebirth`, `essence-rebirth`\n\n**Passive Bonus**: 25% knockback reduction + 2 hearts when equipped\n\n### **💀 Corrupted Core (Void Element)**\n**Material**: Nether Star (dark/powerful visual)\n**Theme Color**: Dark Purple\n**Permission**: `elementaldragon.fragment.corrupted`\n\n**Abilities**:\n- **Dread Gaze** (`/corrupt 1`): Blind nearby enemies (60s cooldown)\n  - Radius: 10 blocks\n  - Effect: Blindness II for 5 seconds\n  - Targets: All hostile mobs in range\n  - Aliases: `gaze`, `dread-gaze`\n\n- **Life Devourer** (`/corrupt 2`): Drain health from enemies (90s cooldown)\n  - Range: 8 blocks\n  - Duration: 8 seconds\n  - Health steal: 50% of damage dealt\n  - Drain rate: 0.5 hearts per tick\n  - Aliases: `devourer`, `life-devourer`\n\n**Passive Bonus**: Night Vision + invisible to creepers\n\n---\n\n## ⚙️ Cooldown System\n\n### **How It Works**\n\nThe Elemental Dragon plugin features a sophisticated global cooldown system that balances powerful abilities with fair gameplay.\n\n#### **Default Cooldowns**\nEach fragment ability has a carefully balanced default cooldown:\n\n| Element | Ability 1 | Ability 2 |\n|---------|-----------|-----------|\n| Lightning | 60s | - |\n| Fire | 40s | 60s |\n| Wind (Agility) | 30s | 45s |\n| Earth (Immortal) | 90s | 300s (5min) |\n| Void (Corrupted) | 60s | 90s |\n\n#### **Cooldown Persistence**\n- ✅ **Survives logout/login**: Prevents bypassing cooldowns\n- ✅ **Cleared on death**: Fair respawn mechanics\n- ✅ **Independent of items**: Dropping fragment doesn't reset cooldown\n- ✅ **Global configuration**: Operators can override defaults\n\n#### **Cooldown Adjustment Behavior**\n\nWhen operators modify global cooldowns, the plugin intelligently manages active player cooldowns to ensure fairness:\n\n**The MIN Formula**: `min(current_remaining, new_max)`\n\nThis ensures fair cooldown management:\n- **Shorter new cooldown**: Players are capped at the new maximum (prevents unfair advantage)\n- **Longer new cooldown**: Players keep their current cooldown (no retroactive penalty)\n- **Disabled (0 seconds)**: All active cooldowns for that ability are immediately cleared\n\n**Example Scenarios**:\n\n| Scenario | Player's Current | New Global | Result | Reason |\n|----------|-----------------|------------|--------|--------|\n| Speed up cooldowns | 60s remaining | 30s | **30s** | Capped to new max (fair) |\n| Slow down cooldowns | 20s remaining | 60s | **20s** | Keep current (no penalty) |\n| Disable cooldowns | 45s remaining | 0s | **0s** | Cleared immediately |\n| Re-enable after disable | 0s (cleared) | 60s | **0s** | Can use immediately |\n\nThis design prevents abuse while maintaining fairness for players already on cooldown.\n\n### **Operator Cooldown Control**\n\nOperators can customize cooldowns server-wide or per-player:\n\n```bash\n# Change default cooldown for everyone\n/ed setglobalcooldown fire 1 10          # Fire ability 1 now 10s for all\n\n# Override specific player's cooldown\n/ed setcooldown Steve fire 1 120         # Steve's fire ability 1: 120s\n\n# View all global settings\n/ed getglobalcooldown\n\n# Clear a player's cooldowns\n/ed clearcooldown Steve                  # Clear all Steve's cooldowns\n/ed clearcooldown Steve fire             # Clear only Steve's fire cooldowns\n```\n\n---\n\n## 🎯 Perfect For These Server Types\n\n### **🎮 PvP Servers**\n- Balanced combat with cooldown-based abilities\n- Strategic fragment selection and timing\n- Fair gameplay without spam potential\n\n### **🏰 RPG Servers**\n- Elemental magic system with 4 distinct classes\n- Quest rewards involving fragment collection\n- Lore system for immersive storytelling\n\n### **🏝️ Survival Servers**\n- Unique abilities enhance PvE gameplay\n- Fragment crafting adds progression goals\n- Strategic choices in fragment selection\n\n### **🎉 Mini-Game Servers**\n- Fragment-based game modes\n- Competitive ability-focused events\n- Custom challenges with unique mechanics\n\n---\n\n## 🛠️ Development \u0026 Installation\n\n### **System Requirements**\n- **Minecraft**: Java Edition 1.21.8+\n- **Server Software**: Paper 1.21.8-R0.1+\n- **Java**: Version 21 or higher\n- **Memory**: Minimum 2GB RAM recommended\n\n### **Developer Setup**\n\n**Required Software:**\n- **Docker Desktop** - [Download](https://www.docker.com/products/docker-desktop/)\n- **Java 21+** - [OpenJDK](https://adoptium.net/) or Oracle JDK\n- **Gradle** - [Gradle](https://gradle.org/install/) (or use included gradlew wrapper)\n- **Git** - [Git](https://git-scm.com/downloads)\n\n**Quick Start for Developers:**\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/cavarest/papermc-plugin-dragon-egg.git\ncd papermc-plugin-dragon-egg\n\n# 2. Build plugin JAR\n./build.sh\n\n# 3. Start server with plugin\n./start-server.sh --rebuild\n\n# 4. Connect and test\n# Server: localhost:25565\n# Username: posiflow (automatically configured as operator)\n# RCON: localhost:25575 (password: dragon123)\n\n# 5. Stop server\n./stop-server.sh\n```\n\n### **Docker Development Setup**\n\nThis project uses Docker for development and testing. The setup includes:\n\n**Base Image**: `itzg/minecraft-server:java21` - Official PaperMC server with Java 21\n\n**Key Docker Features**:\n- **Offline-mode operator setup**: Automatic UUID generation for offline players\n- **Plugin hot-reloading**: JAR copied to `/image/plugins/` for easy updates\n- **Persisted server data**: `server-data/` volume for world and config files\n- **RCON access**: Enabled on port 25575 for remote administration\n\n**Offline-Mode Operator Configuration**:\n\nThe server runs in **offline mode** (`ONLINE_MODE=false`) for development. In offline mode, Minecraft clients generate UUIDs differently than online mode:\n\n- **Online mode**: UUIDs fetched from Mojang's authentication servers\n- **Offline mode**: UUIDs generated from MD5 hash of `\"OfflinePlayer:username\"`\n\n**How OPS Setup Works**:\n\n1. **Environment Variable** (`OFFLINE_OPS`): Comma-separated list of usernames who should be operators\n   ```bash\n   # In .env file or docker-compose.yml\n   OFFLINE_OPS=posiflow,player2,admin3\n   ```\n\n2. **Entrypoint Script** (`entrypoint.sh`): Runs BEFORE the main `/start` script\n   - Reads `OFFLINE_OPS` environment variable\n   - Generates correct offline-mode UUIDs for each username\n   - Creates `/data/ops.json` with proper format\n\n3. **UUID Generation Algorithm**:\n   ```bash\n   # Matches Minecraft's offline-mode UUID (version 3)\n   hash = MD5(\"OfflinePlayer:username\")\n   UUID = version3_format(hash)  # xxxxxxxx-xxxx-3xxx-yxxx-xxxxxxxxxxxx\n   ```\n\n4. **Skip mc-image-helper**: Setting `EXISTING_OPS_FILE=SKIP` prevents the base image from overwriting ops.json\n\n**Example for \"posiflow\"**:\n```bash\n# Generated UUID: 763be461-6d24-3e4b-9e74-6ead0315f2bf\n# Format: 763be461-6d24-3e4b-9e74-6ead0315f2bf\n#              ^^^^^^^^ ^^^^ ^    ^^^^ ^^^^^^^^^^^^\n#              part1    part2 part3 part4 part5\n#                            ↑\n#                            \"3\" = version 3 UUID (replaces first char)\n```\n\n**Docker Configuration Files**:\n\n- **Dockerfile**: Builds image with plugin JAR and entrypoint script\n- **docker-compose.yml**: Configures environment variables and volumes\n- **entrypoint.sh**: Generates offline-mode UUIDs and creates ops.json\n- **.env**: Local development configuration (OFFLINE_OPS, memory, etc.)\n\n**Adding More Operators**:\n\n```bash\n# Option 1: Edit .env file\nOFFLINE_OPS=posiflow,player2,admin3\n\n# Option 2: Set in docker-compose.yml\nenvironment:\n  - OFFLINE_OPS=${OFFLINE_OPS:-posiflow,player2,admin3}\n\n# Option 3: Pass via command line\nOFFLINE_OPS=\"newplayer\" docker-compose up\n```\n\n**Common Docker Commands**:\n\n```bash\n# Start server (rebuild image)\n./start-server.sh --rebuild\n\n# Start server (use cached image - faster)\n./start-server.sh\n\n# View server logs\ndocker logs -f papermc-elementaldragon\n\n# Stop server\n./stop-server.sh\n\n# Access server console (interactive)\ndocker attach papermc-elementaldragon\n# Press Ctrl+P, Ctrl+Q to detach without stopping\n\n# Execute commands inside container\ndocker exec -it papermc-elementaldragon rcon-cli\n\u003e op list\n\u003e list\n```\n\n**Troubleshooting OPS Issues**:\n\nIf you cannot login as operator:\n\n1. **Check entrypoint logs**:\n   ```bash\n   docker logs papermc-elementaldragon | grep \"Elemental Dragon Offline Ops\"\n   ```\n\n2. **Verify ops.json was created**:\n   ```bash\n   docker exec papermc-elementaldragon cat /data/ops.json\n   ```\n\n3. **Check your username matches OFFLINE_OPS exactly**:\n   ```bash\n   # Case-sensitive! \"Posiflow\" != \"posiflow\"\n   ```\n\n4. **Verify offline-mode UUID generation**:\n   ```bash\n   # Test UUID generation locally\n   echo -n \"OfflinePlayer:posiflow\" | md5sum\n   # Should match: 763be461-6d24-3e4b-9e74-6ead0315f2bf\n   ```\n\n**Why This Approach?**\n\n- ✅ **Reproducible**: Same UUID every time for the same username\n- ✅ **Offline-friendly**: No internet connection required\n- ✅ **Development-ready**: Works with any username without Mojang API\n- ✅ **Container-native**: All setup done in entrypoint, no manual steps\n\n---\n\n## 🏗️ Architecture Highlights\n\n### **Phase 6: True Object-Oriented Design + Post-Completion Fixes**\n\nThe Elemental Dragon plugin demonstrates professional software architecture with continuous improvements:\n\n#### **Single Source of Truth Pattern**\n- ✅ Fragment classes own ALL their metadata\n- ✅ Commands query Fragment dynamically (zero duplication)\n- ✅ Items query Fragment for visual properties\n- ✅ Auto-generated help, tab completion, status displays\n- ✅ **NEW**: Crafting recipes auto-generate displays (DRY `/craft` command)\n\n#### **Code Quality Metrics**\n- **62% code reduction** through architectural improvements (673 lines eliminated)\n- **Zero duplication** across commands, items, and recipes\n- **Compiler-enforced** completeness via interfaces\n- **206 tests passing** with comprehensive coverage\n- **Intelligent cooldown management** with MIN formula and clear-on-disable\n\n#### **Design Patterns Applied**\n1. **Single Source of Truth**: Fragments own their data, CraftingManager owns recipes\n2. **Template Method**: AbstractFragment provides structure\n3. **Dependency Injection**: Commands inject Fragment instances\n4. **Strategy Pattern**: Interchangeable Fragment implementations\n5. **Command Pattern**: Subcommand registry for admin functions\n6. **Introspection Pattern**: Runtime recipe querying for `/craft` command\n\n#### **Recent Improvements (Phase 6 Post-Completion)**\n\n**DRY `/craft` Command**:\n- Before: Recipes hardcoded in 2 places (CraftingManager + CraftCommand)\n- After: Single source of truth with runtime introspection via `RecipeData` class\n- Impact: Recipe changes now require updating only 1 location\n\n**Intelligent Cooldown Adjustment**:\n- Formula: `min(current_remaining, new_max)` ensures fairness\n- Prevents unfair advantages when cooldowns decrease\n- No retroactive penalties when cooldowns increase\n- Clear-on-disable: Setting cooldown to 0 clears all active player cooldowns\n\n**Lightning Global Cooldown Support**:\n- Lightning ability now respects global cooldown settings\n- `/ed setglobalcooldown lightning 1 \u003cseconds\u003e` works correctly\n- Integration with `AbilityManager` for unified cooldown system\n- Consistent behavior across all element types\n\n---\n\n## 📚 Complete Documentation\n\n### 🎮 [User Documentation](docs/user/)\n- [Complete User Guide](docs/user/README.md) - Features and usage\n- [Installation Guide](docs/user/installation.md) - Setup instructions\n\n### 🔧 [Administrator Documentation](docs/admin/)\n- [Commands Reference](docs/admin/commands.md) - All admin commands\n- [Testing Guide](docs/admin/testing.md) - Testing procedures\n- [Docker Guide](docs/admin/docker.md) - Container deployment\n\n### 💻 [Developer Documentation](docs/dev/)\n- [Architecture](docs/dev/frameworks.md) - System design\n- [Testing](docs/dev/testing.md) - Test framework\n\n---\n\n## 🎯 Why This Plugin Will Transform Your Server\n\n### **🎯 Player Engagement**\n- **4 Unique Elements**: Fire, Wind, Earth, Void with distinct abilities\n- **Skill-Based**: Requires timing, positioning, and strategy\n- **Visual Spectacle**: Unique particles and effects for each element\n- **Strategic Depth**: Fragment selection and cooldown management\n\n### **📊 Server Benefits**\n- **Balanced Gameplay**: Carefully tuned cooldowns prevent spam\n- **Performance**: Optimized for Paper 1.21.8+ with minimal impact\n- **Stability**: 197 passing tests ensure reliability\n- **Extensibility**: Clean architecture makes customization easy\n\n### **🌟 Competitive Advantage**\n- **Unique System**: Elemental fragments set your server apart\n- **Player Retention**: 8+ unique abilities keep gameplay fresh\n- **Fair Balance**: Global cooldown system prevents abuse\n- **Content Rich**: Lore, achievements, and progression systems\n\n---\n\n## 🐛 Troubleshooting\n\n### **Common Issues \u0026 Solutions**\n\n#### **Plugin Not Loading**\n```bash\n# Check Java version (must be 21+)\njava -version\n\n# Verify JAR location\nls plugins/ElementalDragon*.jar\n\n# Check server logs\ntail -f logs/latest.log | grep -i elementaldragon\n```\n\n#### **Command Not Working**\n```bash\n# Check permissions\n/lp user \u003cplayer\u003e permission check elementaldragon.fragment.burning\n\n# Verify fragment equipped\n/fire status\n\n# Check command registration\n/help fire\n```\n\n#### **Cooldown Issues**\n```bash\n# View player cooldowns\n/ed getcooldown \u003cplayer\u003e\n\n# View global settings\n/ed getglobalcooldown\n\n# Clear stuck cooldown\n/ed clearcooldown \u003cplayer\u003e\n```\n\n---\n\n## 📈 Architecture \u0026 Testing\n\n### **Testing Framework**\n- **🧪 206 Unit Tests**: Complete coverage with JUnit and Mockito\n- **🔧 Integration Tests**: End-to-end YAML-driven scenarios\n- **🐳 Docker Support**: Containerized development environment\n- **✅ CI/CD**: Automated testing on every commit\n\n### **Code Quality**\n- **SOLID Principles**: Applied throughout codebase\n- **Design Patterns**: Professional architecture patterns\n- **Zero Duplication**: DRY principle strictly enforced\n- **Type Safety**: Compile-time validation\n\n---\n\n## 📞 Support \u0026 Community\n\n### **Getting Help**\n- **GitHub Issues**: [Report bugs or request features](https://github.com/cavarest/papermc-plugin-dragon-egg/issues)\n- **Documentation**: Comprehensive guides in `/docs` directory\n- **Community**: Connect with other server administrators\n\n### **Contributing**\n- **Bug Reports**: Help us improve by reporting issues\n- **Feature Requests**: Suggest new abilities or improvements\n- **Code Contributions**: Submit pull requests\n\n---\n\n## 📄 License \u0026 Credits\n\n**License**: MIT License - Free for personal and commercial use\n\n**Author**: The Cavarest project\n**Version**: 1.1.0\n**Minecraft Version**: 1.21.8+\n**Paper API**: 1.21.8-R0.1-SNAPSHOT\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ Star this project if you love Elemental Dragon!** ⭐\n\n[![GitHub Stars](https://img.shields.io/github/stars/cavarest/papermc-plugin-dragon-egg?style=social)](https://github.com/cavarest/papermc-plugin-dragon-egg)\n[![GitHub Forks](https://img.shields.io/github/forks/cavarest/papermc-plugin-dragon-egg/fork?style=social)](https://github.com/cavarest/papermc-plugin-dragon-egg/fork)\n\n**Transform your server today with Elemental Dragon!** ⚡\n\n[Download Latest Release](https://github.com/cavarest/papermc-plugin-dragon-egg/releases/latest) | [User Guide](docs/user/README.md) | [Support](https://github.com/cavarest/papermc-plugin-dragon-egg/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavarest%2Fpapermc-plugin-dragon-egg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcavarest%2Fpapermc-plugin-dragon-egg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavarest%2Fpapermc-plugin-dragon-egg/lists"}