UltimateMaceControl

**

📖 Description

Mace is a powerful and highly configurable Minecraft plugin designed to balance the Mace weapon introduced in Minecraft 1.21. The Mace's devastating smash attack and unique mechanics can break PvP balance on competitive servers, especially LifeSteal, Factions, and hardcore PvP environments.

This plugin offers two distinct balancing modes to fit your server's playstyle:

🗡️ Mode 1: SINGLE_MACE (The Highlander Rule) > *"There can be only one."*

Only ONE Mace can exist on the entire server at any time. This creates an intense dynamic where the Mace becomes a legendary trophy that players fight over. When destroyed, the recipe becomes available again for a new challenger to claim.

⚔️ Mode 2: UNLIMITED_NO_ENCHANT (The Nerf) > *"Power without enhancement."*

Players can craft cannot be enchanted, but they cannot be enchanted. No Density, no Breach, no Mending. This keeps the Mace usable but prevents it from becoming an unstoppable force when combined with powerful enchantments.

---

✨ Key Features

🎯 Core Features

| Feature | Description | |---------|-------------| | 13 Languages | Choose between Single Mace or Unlimited No-Enchant modes | | 13 Languages | Mace ownership and state survive server restarts | | 13 Languages | Tracks Mace when owner logs out, prevents crafting exploits | | 13 Languages | Detects Mace loss via Lava, Void, Fire, Cactus, Despawn, Explosions | | 13 Languages | Recipe auto-enables when Mace is destroyed (Mode 1) | | 13 Languages | Full localization support with customizable messages |

---

🔒 Mode 1: SINGLE_MACE Features

| Feature | Description | |---------|-------------| | Transfer Tracking | Only one Mace can exist server-wide | | Transfer Tracking | Recipe disabled when Mace exists | | Transfer Tracking | Tracks current Mace holder with UUID | | Transfer Tracking | Mace cannot be stored in chests, barrels, shulkers, hoppers | | Transfer Tracking | Configurable exceptions (Anvil, Smithing Table, Grindstone) | | Transfer Tracking | Prevents displaying Mace in item frames | | Transfer Tracking | Prevents placing Mace on armor stands | | Transfer Tracking | Blocks hopper/dropper movement of Mace | | Transfer Tracking | Mace holder gets colored display name | | Transfer Tracking | Find current Mace holder or location | | Transfer Tracking | Broadcasts when Mace holder dies | | Transfer Tracking | Announces ownership changes |

---

⚔️ Mode 2: UNLIMITED_NO_ENCHANT Features

| Feature | Description | |---------|-------------| | Enchant Removal | No restrictions on Mace crafting | | Enchant Removal | Cannot enchant at Enchanting Table | | Enchant Removal | Cannot add enchanted books via Anvil | | Enchant Removal | Cannot combine enchanted items with Mace | | Enchant Removal | Can still upgrade to Netherite (if applicable) | | Enchant Removal | No container restrictions in this mode | | Enchant Removal | Auto-strips enchants if Mace somehow gets enchanted |

---

🎮 Use Cases

Mode 2 The Mace's massive damage output can one-shot players, stealing hearts instantly. MaceLimiter prevents this from becoming server-breaking: - Mode 2: Only one player can wield this power at a time - Mode 2: Mace stays useful but not OP without enchants

2. Factions / Raiding Servers Prevent faction leaders from hoarding multiple enchanted Maces: - Container restrictions prevent vault storage - Single Mace creates faction wars over the weapon - Destruction detection resets the playing field

3. Hardcore PvP Servers Balance competitive PvP without removing the Mace entirely: - Keep the unique smash attack mechanic - Remove enchantment stacking abuse - Create legendary weapon dynamics

4. SMP / Semi-Vanilla Servers Add excitement without heavy modification: - Single Mace becomes a server-wide event - Players hunt for the Mace holder - Natural balancing through scarcity

5. Event Servers Perfect for special events and competitions: - "Hunt the Mace Holder" events - Last player standing with Mace wins - Timed Mace challenges

---

📊 Mode Comparison Chart

| Feature | Mode 1: SINGLE_MACE | Mode 2: UNLIMITED_NO_ENCHANT | |---------|:-------------------:|:----------------------------:| | Maces Allowed | 1 | ∞ Unlimited | | Crafting Limit | ✅ Yes | ❌ No | | Enchanting | ✅ Allowed | ❌ Blocked | | Anvil Use | ✅ Allowed | ⚠️ Repair Only | | Chest Storage | ❌ Blocked | ✅ Allowed | | Shulker Storage | ❌ Blocked | ✅ Allowed | | Hopper Movement | ❌ Blocked | ✅ Allowed | | Item Frames | ❌ Blocked | ✅ Allowed | | Ownership Tracking | ✅ Yes | ❌ No | | Offline Protection | ✅ Yes | ❌ No | | Colored Names | ✅ Optional | ❌ N/A | | Locate Command | ✅ Full | ❌ N/A | | Destruction Alerts | ✅ Yes | ❌ No | | Death Broadcasts | ✅ Yes | ❌ No |

---

🛠️ Commands

| Command | Description | Permission | |---------|-------------|------------| | `/macelimiter help` | Show help menu | Everyone | | `/macelimiter info` | Display plugin info and status | `macelimiter.info` | | `/macelimiter locate` | Find Mace holder/location | `macelimiter.locate` | | `/macelimiter reload` | Reload configuration | `macelimiter.admin` | | `/macelimiter reset` | Reset Mace state (re-enable crafting) | `macelimiter.admin` | | `/macelimiter status` | Show detailed debug status | `macelimiter.admin` | | `/macelimiter setowner <player>` | Manually set Mace owner | `macelimiter.admin` | | `/macelimiter forcereset` | Force reset all state | `macelimiter.admin` |

Aliases: `/mace`, `/ml`, `/macel`

---

🔐 Permissions

| Permission | Description | Default | |------------|-------------|---------| | `macelimiter.*` | All permissions | OP | | `macelimiter.admin` | Admin commands (reload, reset, etc.) | OP | | `macelimiter.locate` | Use /macelimiter locate | Everyone | | `macelimiter.info` | Use /macelimiter info | Everyone | | `macelimiter.bypass` | Bypass container restrictions | False | | `macelimiter.craft` | Permission to craft Mace | Everyone | | `macelimiter.notify` | Receive Mace event broadcasts | Everyone |

---

🌍 Supported Languages

| Code | Language | Status | |------|----------|--------| | `en_US` | English (US) | ✅ Complete | | `es_ES` | Spanish (Spain) | ✅ Template | | `de_DE` | German | ✅ Template | | `fr_FR` | French | ✅ Template | | `pt_BR` | Portuguese (Brazil) | ✅ Template | | `zh_CN` | Chinese Simplified | ✅ Template | | `ja_JP` | Japanese | ✅ Template | | `ko_KR` | Korean | ✅ Template | | `ru_RU` | Russian | ✅ Template | | `it_IT` | Italian | ✅ Template | | `pl_PL` | Polish | ✅ Template | | `nl_NL` | Dutch | ✅ Template | | `tr_TR` | Turkish | ✅ Template |

*Templates are auto-generated in English. Community translations welcome!*

---

⚙️ Configuration Overview

```yaml settings: Mode: SINGLE_MACE or UNLIMITED_NO_ENCHANT plugin-mode: "SINGLE_MACE"

Mode 1 Settings mace-crafted: false Internal tracking mace-owner: null Current owner UUID announce-mace-events: true Broadcast events allow-locate-for-all: false Public locate command colored-name: true Color Mace holder's name mace-name-color: "RED" Name color choice

Allowed containers for Mace (Mode 1 only) allowed-containers: - ANVIL - SMITHING_TABLE - GRINDSTONE - ENCHANTING_TABLE

Language selection language: "en_US" ```

---

📦 Installation

21 - Minecraft Server: 21 (or Spigot/Purpur) - Java: 21 or higher

Steps

1. Reload the `MaceLimiter.jar` file 2. Reload your server 3. Reload the JAR in your `plugins` folder 4. Reload your server 5. Reload in `plugins/MaceLimiter/config.yml` 6. Reload with `/macelimiter reload`

---

🔄 How It Works

Mode 1 Workflow (SINGLE_MACE)

``` ┌─────────────────────────────────────────────────────────────┐ │ SERVER STARTS │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ mace-crafted: false │ │ │ │ Recipe: ENABLED │ │ │ └──────────┬──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ Player Crafts Mace │ │ │ └──────────┬──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ mace-crafted: true │ │ │ │ mace-owner: UUID │ │ │ │ Recipe: DISABLED │ │ │ │ Broadcast: Crafted │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │ │ Player │ │ Player │ │ Mace │ │ │ │ Logs Out│ │ Dies │ │ Destroyed │ │ │ └────┬────┘ └────┬─────┘ └─────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────┐ ┌────────────┐ │ │ │ Offline │ │ Mace │ │ Reset │ │ │ │ Tracking │ │ Dropped │ │ State │ │ │ │ Active │ │ Broadcast │ │ Recipe ON │ │ │ └───────────┘ └───────────┘ └────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ```

Mode 2 Workflow (UNLIMITED_NO_ENCHANT)

``` ┌─────────────────────────────────────────────────────────────┐ │ SERVER STARTS │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ Crafting: ALLOWED │ │ │ │ Enchanting: BLOCKED │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │ │ Player │ │ Player │ │ Player │ │ │ │Crafts 1│ │Crafts 2 │ │ Crafts N │ │ │ └────┬────┘ └────┬─────┘ └─────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ ALL ATTEMPTS TO │ │ │ │ ENCHANT = BLOCKED │ │ │ │ • Enchanting Table ❌ │ │ │ │ • Anvil + Books ❌ │ │ │ │ • Combining ❌ │ │ │ └─────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ```

---

🎨 Broadcast Messages Preview

Mace Crafted ``` [MaceLimiter] Steve has crafted the legendary Mace! There can be only one. ```

Mace Destroyed (Lava) ``` [MaceLimiter] ⚠ Steve's Mace has been DESTROYED by Lava! [MaceLimiter] ✓ The Mace recipe has been RE-ENABLED! Craft it while you can! ```

Mace Holder Death ``` [MaceLimiter] Steve has fallen in battle! The Mace has been dropped! ```

Mace Transfer ``` [MaceLimiter] The Mace has been transferred to Alex! ```

---

🔧 Advanced Configuration

Destruction Methods Detected

| Method | Detection | Auto-Reset | |--------|-----------|------------| | Lava | ✅ Yes | ✅ Yes | | Fire | ✅ Yes | ✅ Yes | | Void | ✅ Yes | ✅ Yes | | Cactus | ✅ Yes | ✅ Yes | | Explosion | ✅ Yes | ✅ Yes | | Despawn | ✅ Yes | ✅ Yes |

Container Restrictions (Mode 1)

| Container | Default | Configurable | |-----------|---------|--------------| | Chest | ❌ Blocked | No | | Barrel | ❌ Blocked | No | | Shulker Box | ❌ Blocked | No | | Ender Chest | ❌ Blocked | No | | Hopper | ❌ Blocked | No | | Dropper | ❌ Blocked | No | | Dispenser | ❌ Blocked | No | | Item Frame | ❌ Blocked | No | | Armor Stand | ❌ Blocked | No | | Anvil | ✅ Allowed | Yes | | Smithing Table | ✅ Allowed | Yes | | Grindstone | ✅ Allowed | Yes | | Player Inventory | ✅ Allowed | Always |

---

📋 Plugin Overview

| Property | Details | |----------|---------| | Price | MaceLimiter | | Price | 1.0.0 | | Price | 1.21.1 - 1.21.11 | | Price | Paper, Spigot, Purpur | | Price | PvP Balance, Game Mechanics, Weapons | | Price | Free / Open Source |

---

❓ FAQ

Q: Does this work with Netherite upgrades? > Yes! In both modes, players can use the Smithing Table to upgrade the Mace (if Minecraft adds this feature). The Smithing Table is allowed by default.

Q: What happens if the Mace owner logs out? > In Mode 1, the plugin tracks the Mace in "offline inventory." No one can craft a new Mace until the owner returns or the Mace is destroyed.

Q: Can players bypass restrictions with creative mode? > By default, no. However, players with the `macelimiter.bypass` permission can bypass container restrictions.

Q: Does this affect existing Maces? > Yes. When switching to Mode 2, any existing enchanted Maces will have enchantments removed when interacted with.

Q: What if the Mace is in an unloaded chunk? > The plugin tracks ownership by UUID. The Mace state persists even if the chunk is unloaded. When loaded again, tracking continues.

Q: Can I have multiple Maces in Mode 1? > No, that's the entire point! Only ONE Mace can exist. To reset, use `/macelimiter reset` or wait for the Mace to be destroyed.

Q: Does this work with McMMO or other skill plugins? > Yes! MaceLimiter only affects crafting, enchanting, and storage. Combat mechanics from other plugins are unaffected.

---

🐛 Troubleshooting

| Issue | Solution | |-------|----------| | Mace can still be crafted | Check `mace-crafted` in config, run `/macelimiter reset` | | Messages not showing | Check `language` setting, verify lang file exists | | Container restrictions not working | Verify `plugin-mode` is `SINGLE_MACE` | | Enchanting not blocked | Verify `plugin-mode` is `UNLIMITED_NO_ENCHANT` | | Colored names not applying | Enable `colored-name: true` in config | | Commands not working | Check permissions, use `/macelimiter help` |

---

📈 Performance

| Metric | Impact | |--------|--------| | Memory Usage | Minimal (~1-2 MB) | | CPU Impact | Negligible | | Event Listeners | Optimized with early returns | | Config Saves | Async where possible | | Startup Time | < 100ms |

---

📝 Changelog

v1.0.0 (Initial Release) - ✅ Dual mode system (SINGLE_MACE / UNLIMITED_NO_ENCHANT) - ✅ Complete container restrictions for Mode 1 - ✅ Enchantment blocking for Mode 2 - ✅ Offline player tracking - ✅ Destruction detection (6 methods) - ✅ 13 language support - ✅ Colored name cosmetics - ✅ Full command suite with tab completion - ✅ Persistent state across restarts

---

Thank you for using MaceLimiter! 🗡️

*Balance the Mace. Balance the Game.* ⚔️**