** \ud83e\uddea PotionLimiter – Complete Plugin Documentation<\/p>\n
\ud83d\udcd6 Description<\/p>\n
**PotionLimiter** is a powerful and lightweight Minecraft plugin for Paper 1.21.1+ that gives server administrators complete control over the brewing system. Whether you want to balance PvP, create custom game modes, or restrict certain potion types for gameplay reasons, PotionLimiter provides an intuitive and flexible solution.<\/p>\n
The plugin allows you to:
\n– **Blacklist specific potion types** from being brewed (including variants like LONG, STRONG)
\n– **Control brewing by world** – enable or disable the plugin in specific worlds
\n– **Notify players** when blocked potions are attempted
\n– **Preserve ingredients** when brewing is blocked
\n– **Easy configuration** with copy-paste reference examples<\/p>\n
Built with modern Java 21, Paper API, and Kyori Adventure (MiniMessage), PotionLimiter offers clean code, performance optimization, and beautiful chat formatting.<\/p>\n
—<\/p>\n
\u2728 Key Features<\/p>\n
\ud83c\udfaf **Granular Potion Control**
\n– Block specific PotionTypes (e.g., `STRENGTH`, `LONG_STRENGTH`, `STRONG_STRENGTH`)
\n– Support for all Minecraft 1.21 potions including new additions:
\n – Wind Charged
\n – Weaving
\n – Oozing
\n – Infested
\n– Easy-to-use configuration with built-in reference list<\/p>\n
\ud83c\udf0d **World-Based Management**
\n– **Blacklist Mode**: Disable plugin in specific worlds (creative, lobby, etc.)
\n– **Whitelist Mode**: Only enable plugin in specific worlds (survival only)
\n– Per-world control for maximum flexibility<\/p>\n
\ud83d\udcac **Player Notifications**
\n– Configurable radius-based notifications
\n– Beautiful MiniMessage formatting with gradients and colors
\n– Toggle notifications on\/off
\n– Custom blocked messages per potion type<\/p>\n
\ud83d\udd04 **Ingredient Preservation**
\n– Brewing events are cancelled before ingredients are consumed
\n– Items remain in brewing stand when blocked
\n– Prevents resource waste<\/p>\n
\u2699\ufe0f **Admin-Friendly**
\n– Simple `\/plimit reload` command – no server restart needed
\n– `\/plimit list` shows all blocked potions and world restrictions
\n– Tab completion for all commands
\n– Clear console logging<\/p>\n
\ud83d\ude80 **Performance & Modern Code**
\n– Java 21 with modern syntax (switch expressions, pattern matching)
\n– No NMS (Native Minecraft Server code) – fully compatible with Paper updates
\n– Dependency injection for clean architecture
\n– Lightweight – minimal server impact<\/p>\n
—<\/p>\n
\ud83d\udce6 Installation<\/p>\n
1. **Requirements:**
\n – Minecraft Server 1.21.1 – 1.21.11
\n – Paper (or Paper-based servers like Purpur, Pufferfish)
\n – Java 21+<\/p>\n
2. **Steps:**
\n “`bash
\n Download PotionLimiter-1.0.0.jar
\n Place in your server’s plugins\/ folder
\n Start\/restart your server
\n Edit plugins\/PotionLimiter\/config.yml
\n Run \/plimit reload in-game
\n “`<\/p>\n
—<\/p>\n
\ud83c\udfae Usage Examples<\/p>\n
**Example 1: Block Strength Potions in All Worlds**
\nPerfect for balanced PvP servers where strength potions are too overpowered.<\/p>\n
“`yaml
\nblacklisted-potions:
\n – STRENGTH
\n – LONG_STRENGTH
\n – STRONG_STRENGTH
\n“`<\/p>\n
**Result:** Players cannot brew any strength potions. The brewing stand will not complete the process.<\/p>\n
—<\/p>\n
**Example 2: Disable Plugin in Creative World**
\nAllow unrestricted brewing in creative\/building worlds while maintaining restrictions in survival.<\/p>\n
“`yaml
\nworld-settings:
\n blacklist-mode: true Blacklist mode
\n blacklisted-worlds:
\n – world_creative
\n – lobby
\n – skyblock_spawn
\n“`<\/p>\n
**Result:** Plugin is **disabled** in `world_creative`, `lobby`, and `skyblock_spawn`. Players can brew anything there. In all other worlds, restrictions apply.<\/p>\n
—<\/p>\n
**Example 3: Only Work in Survival World (Whitelist Mode)**
\nEnable the plugin ONLY in your main survival world, ignoring all other worlds.<\/p>\n
“`yaml
\nworld-settings:
\n blacklist-mode: false Whitelist mode
\n blacklisted-worlds:
\n – world Only active here
\n“`<\/p>\n
**Result:** Plugin is **only active** in the world named `world`. All other worlds have unrestricted brewing.<\/p>\n
—<\/p>\n
**Example 4: Block All Harmful Potions**
\nGreat for peaceful\/roleplay servers.<\/p>\n
“`yaml
\nblacklisted-potions:
\n – HARMING
\n – STRONG_HARMING
\n – POISON
\n – LONG_POISON
\n – STRONG_POISON
\n – WEAKNESS
\n – LONG_WEAKNESS
\n“`<\/p>\n
—<\/p>\n
**Example 5: Block Invisibility for Fair PvP**
\nPrevent invisibility potions in PvP arenas.<\/p>\n
“`yaml
\nblacklisted-potions:
\n – INVISIBILITY
\n – LONG_INVISIBILITY
\n“`<\/p>\n
—<\/p>\n
**Example 6: Block 1.21 New Potions**
\nDisable the new experimental potions added in 1.21.<\/p>\n
“`yaml
\nblacklisted-potions:
\n – WIND_CHARGED
\n – WEAVING
\n – OOZING
\n – INFESTED
\n“`<\/p>\n
—<\/p>\n
**Example 7: Custom Notification Settings**
\nConfigure how players are notified when brewing is blocked.<\/p>\n
“`yaml **Result:** Players within 10 blocks of the brewing stand receive a gradient red message.<\/p>\n —<\/p>\n **Example 8: Disable Notifications (Silent Mode)** “`yaml **Result:** Brewing is blocked silently. Only console logs the event.<\/p>\n —<\/p>\n \ud83c\udfaf Common Use Cases<\/p>\n **1. Competitive PvP Servers** **2. Survival Servers with Custom Mechanics** **3. Minigame Servers** **4. Roleplay\/Peaceful Servers** **5. Economy Servers** —<\/p>\n \ud83d\udd27 Commands<\/p>\n | Command | Description | Permission | **Aliases:** `\/potionlimiter`, `\/pl`<\/p>\n —<\/p>\n \ud83d\udd10 Permissions<\/p>\n | Permission | Description | Default | —<\/p>\n \u2699\ufe0f Configuration Reference<\/p>\n **brewing-settings** **world-settings** **blacklisted-potions** **messages** —<\/p>\n \ud83d\udcca All Available Potion Types (1.21)<\/p>\n Base Potions Swiftness (Speed) Slowness Strength Healing (Instant Health) Harming (Instant Damage) Leaping (Jump Boost) Regeneration Fire Resistance Water Breathing Invisibility Night Vision Weakness Poison Turtle Master Slow Falling 1.21 New Potions \u2728 —<\/p>\n \ud83c\udfa8 MiniMessage Format Examples<\/p>\n PotionLimiter uses MiniMessage for beautiful chat formatting. You can customize all messages in `config.yml`.<\/p>\n Gradient Text Rainbow Text Bold\/Italic\/Underline Hover Text Combined Effects Learn more: MiniMessage Documentation<\/p>\n —<\/p>\n \ud83d\udc1b Troubleshooting<\/p>\n **Potions are still being brewed** **”Invalid PotionType” warnings in console** **Plugin not working in a world** **Players not receiving notifications** —<\/p>\n \ud83d\udcc8 Performance<\/p>\n – **Event Handling:** Optimized brewing recipe prediction Disables potion brewing on your server with potion blacklist and world blacklist system……<\/p>\n","protected":false},"featured_media":124294,"template":"","meta":{"_minecraft_slug":"potionlimiter","_minecraft_project_id":"1GVOhetU","_minecraft_author":"geturplugins","_minecraft_license":"MIT","_minecraft_downloads":747,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"potionlimiter.zip","_minecraft_size_bytes":50050,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-16T09:25:26.824045Z","_minecraft_date_created":"2026-01-24T19:54:30.584491Z","_minecraft_date_modified":"2026-01-18T03:54:11.710140Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/potionlimiter","_minecraft_icon_attachment_id":124294,"_minecraft_imported_at":"2026-06-07T07:22:16+00:00","_minecraft_import_hash":"3cd232a182e07f9a58c6dcd19c675f0d","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[89,126,127,128,92],"mod_loader":[132,133],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-124293","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-game-mechanics","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-utility","mod_loader-paper","mod_loader-purpur","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\nbrewing-settings:
\n notify-players: true
\n notify-radius: 10 10 blocks
\n blocked-message: “
\n“`<\/p>\n
\nBlock potions without notifying players.<\/p>\n
\nbrewing-settings:
\n notify-players: false
\n“`<\/p>\n
\n“`yaml
\n Block overpowered potions for balanced combat
\nblacklisted-potions:
\n – STRONG_STRENGTH
\n – STRONG_HEALING
\n – LONG_INVISIBILITY
\n – TURTLE_MASTER
\n – STRONG_TURTLE_MASTER
\n“`<\/p>\n
\n“`yaml
\n Force players to obtain potions through custom methods (shops, quests, etc.)
\nblacklisted-potions:
\n – REGENERATION
\n – LONG_REGENERATION
\n – STRONG_REGENERATION
\n – HEALING
\n – STRONG_HEALING
\n“`<\/p>\n
\n“`yaml
\n Disable plugin in minigame worlds, enable in lobby
\nworld-settings:
\n blacklist-mode: true
\n blacklisted-worlds:
\n – bedwars
\n – skywars
\n – parkour
\n“`<\/p>\n
\n“`yaml
\n Block all combat\/harmful potions
\nblacklisted-potions:
\n – HARMING
\n – STRONG_HARMING
\n – POISON
\n – LONG_POISON
\n – STRONG_POISON
\n – STRENGTH
\n – LONG_STRENGTH
\n – STRONG_STRENGTH
\n“`<\/p>\n
\n“`yaml
\n Block high-value potions to maintain economy balance
\nblacklisted-potions:
\n – STRONG_HEALING
\n – STRONG_REGENERATION
\n – LONG_NIGHT_VISION
\n – LONG_WATER_BREATHING
\n“`<\/p>\n
\n|———|————-|————|
\n| `\/plimit reload` | Reload configuration without restart | `potionlimiter.admin` |
\n| `\/plimit list` | Show all blacklisted potions and world restrictions | `potionlimiter.admin` |
\n| `\/plimit help` | Display command help | `potionlimiter.admin` |<\/p>\n
\n|————|————-|———|
\n| `potionlimiter.admin` | Access to all commands | OP |<\/p>\n
\n“`yaml
\nbrewing-settings:
\n return-ingredients: true Preserve ingredients when blocked (always true in Paper)
\n notify-players: true Send messages to nearby players
\n notify-radius: 5 Notification radius in blocks
\n blocked-message: “
\n“`<\/p>\n
\n“`yaml
\nworld-settings:
\n blacklist-mode: true true = disable in listed worlds, false = only enable in listed
\n blacklisted-worlds:
\n – world_creative
\n – lobby
\n“`<\/p>\n
\n“`yaml
\nblacklisted-potions:
\n – STRENGTH Add PotionType names here
\n – LONG_STRENGTH
\n – STRONG_STRENGTH
\n“`<\/p>\n
\n“`yaml
\nmessages:
\n prefix: “
\n reload-success: “
\n reload-error: “
\n no-permission: “
\n list-header: “
\n list-item: “
\n list-empty: “
\n list-footer: “
\n“`<\/p>\nClick to expand full potion list<\/b><\/summary>\n
\n– `WATER` – Water Bottle
\n– `MUNDANE` – Mundane Potion
\n– `THICK` – Thick Potion
\n– `AWKWARD` – Awkward Potion<\/p>\n
\n– `SWIFTNESS` – Swiftness I (3:00) \u26a0\ufe0f **Changed from SPEED**
\n– `LONG_SWIFTNESS` – Swiftness I (8:00) \u26a0\ufe0f **Changed from LONG_SPEED**
\n– `STRONG_SWIFTNESS` – Swiftness II (1:30) \u26a0\ufe0f **Changed from STRONG_SPEED**<\/p>\n
\n– `SLOWNESS` – Slowness I (1:30)
\n– `LONG_SLOWNESS` – Slowness I (4:00)
\n– `STRONG_SLOWNESS` – Slowness IV (0:20)<\/p>\n
\n– `STRENGTH` – Strength I (3:00)
\n– `LONG_STRENGTH` – Strength I (8:00)
\n– `STRONG_STRENGTH` – Strength II (1:30)<\/p>\n
\n– `HEALING` – Instant Health I \u26a0\ufe0f **Changed from INSTANT_HEAL**
\n– `STRONG_HEALING` – Instant Health II \u26a0\ufe0f **Changed from STRONG_INSTANT_HEAL**<\/p>\n
\n– `HARMING` – Instant Damage I \u26a0\ufe0f **Changed from INSTANT_DAMAGE**
\n– `STRONG_HARMING` – Instant Damage II \u26a0\ufe0f **Changed from STRONG_INSTANT_DAMAGE**<\/p>\n
\n– `LEAPING` – Jump Boost I (3:00) \u26a0\ufe0f **Changed from JUMP_BOOST**
\n– `LONG_LEAPING` – Jump Boost I (8:00) \u26a0\ufe0f **Changed from LONG_JUMP_BOOST**
\n– `STRONG_LEAPING` – Jump Boost II (1:30) \u26a0\ufe0f **Changed from STRONG_JUMP_BOOST**<\/p>\n
\n– `REGENERATION` – Regeneration I (0:45)
\n– `LONG_REGENERATION` – Regeneration I (1:30)
\n– `STRONG_REGENERATION` – Regeneration II (0:22)<\/p>\n
\n– `FIRE_RESISTANCE` – Fire Resistance (3:00)
\n– `LONG_FIRE_RESISTANCE` – Fire Resistance (8:00)<\/p>\n
\n– `WATER_BREATHING` – Water Breathing (3:00)
\n– `LONG_WATER_BREATHING` – Water Breathing (8:00)<\/p>\n
\n– `INVISIBILITY` – Invisibility (3:00)
\n– `LONG_INVISIBILITY` – Invisibility (8:00)<\/p>\n
\n– `NIGHT_VISION` – Night Vision (3:00)
\n– `LONG_NIGHT_VISION` – Night Vision (8:00)<\/p>\n
\n– `WEAKNESS` – Weakness (1:30)
\n– `LONG_WEAKNESS` – Weakness (4:00)<\/p>\n
\n– `POISON` – Poison I (0:45)
\n– `LONG_POISON` – Poison I (1:30)
\n– `STRONG_POISON` – Poison II (0:21)<\/p>\n
\n– `TURTLE_MASTER` – Turtle Master I (0:40)
\n– `LONG_TURTLE_MASTER` – Turtle Master I (1:20)
\n– `STRONG_TURTLE_MASTER` – Turtle Master II (0:20)<\/p>\n
\n– `SLOW_FALLING` – Slow Falling (1:30)
\n– `LONG_SLOW_FALLING` – Slow Falling (4:00)<\/p>\n
\n– `WIND_CHARGED` – Wind Charged (3:00) \ud83c\udd95
\n– `WEAVING` – Weaving (3:00) \ud83c\udd95
\n– `OOZING` – Oozing (3:00) \ud83c\udd95
\n– `INFESTED` – Infested (3:00) \ud83c\udd95<\/p>\n<\/details>\n
\n“`yaml
\nblocked-message: “
\n“`<\/p>\n
\n“`yaml
\nblocked-message: “
\n“`<\/p>\n
\n“`yaml
\nblocked-message: “
\n“`<\/p>\n
\n“`yaml
\nblocked-message: “
\n“`<\/p>\n
\n“`yaml
\nblocked-message: “
\n“`<\/p>\n
\n1. Check `\/plimit list` to confirm potions are in the blacklist
\n2. Verify you’re using **1.21 potion names** (e.g., `SWIFTNESS` not `SPEED`)
\n3. Run `\/plimit reload` after config changes
\n4. Check console for “Invalid PotionType” warnings
\n5. Verify world restrictions with `\/plimit list`<\/p>\n
\nThis means you’re using old 1.20 names. Update your config:
\n– \u274c `SPEED` \u2192 \u2705 `SWIFTNESS`
\n– \u274c `INSTANT_HEAL` \u2192 \u2705 `HEALING`
\n– \u274c `JUMP_BOOST` \u2192 \u2705 `LEAPING`
\n– \u274c `INSTANT_DAMAGE` \u2192 \u2705 `HARMING`<\/p>\n
\n1. Check `world-settings.blacklist-mode`
\n2. Verify world name matches **exactly** (case-sensitive)
\n3. Use world folder name, not display name<\/p>\n
\n1. Check `notify-players: true` in config
\n2. Increase `notify-radius` value
\n3. Verify MiniMessage syntax is correct<\/p>\n
\n– **Memory Usage:** <5MB typical\n- **CPU Impact:** Negligible (<0.1% on modern hardware)\n- **No NMS:** Future-proof and update-safe\n\n---\n\n \ud83e\udd1d Support\n\n- **Discord:** geturplugins\n- **Issues:** Report bugs with detailed steps to reproduce\n- **Feature Requests:** Suggest improvements with use cases\n- **Questions:** Provide server version, config, and console logs\n\n---\n\n \ud83c\udf89 Credits\n\n**Developer:** geturplugins \n**API:** PaperMC Team \n**Chat Library:** Kyori Adventure Team \n**Built with:** Java 21, Maven, IntelliJ IDEA\n\n---\n\n \ud83d\udcdd Changelog\n\n Version 1.0.0 (Initial Release)\n- \u2705 Granular potion blacklist system\n- \u2705 World-based blacklist\/whitelist\n- \u2705 Player notifications with MiniMessage\n- \u2705 Admin commands (reload, list, help)\n- \u2705 Tab completion\n- \u2705 Ingredient preservation\n- \u2705 Java 21 & Paper 1.21.1 support\n- \u2705 Full configuration examples\n- \u2705 Updated for 1.21 PotionType names (SWIFTNESS, HEALING, LEAPING, HARMING)\n- \u2705 Advanced brewing recipe prediction system\n\n---\n\n \ud83d\udcda Quick Reference Card\n\n Most Common Blocked Potions (PvP Servers)\n\n```yaml\nblacklisted-potions:\n Combat potions\n - STRENGTH Strength I\n - LONG_STRENGTH Strength I (8:00)\n - STRONG_STRENGTH Strength II\n \n Healing potions\n - HEALING Instant Health I (NEW NAME)\n - STRONG_HEALING Instant Health II (NEW NAME)\n \n Movement potions\n - SWIFTNESS Speed I (NEW NAME)\n - LONG_SWIFTNESS Speed I extended (NEW NAME)\n - STRONG_SWIFTNESS Speed II (NEW NAME)\n \n Utility potions\n - INVISIBILITY Invisibility\n - LONG_INVISIBILITY Invisibility extended\n \n Damage potions\n - HARMING Instant Damage I (NEW NAME)\n - STRONG_HARMING Instant Damage II (NEW NAME)\n```\n\n---\n\n**\ud83e\uddea PotionLimiter - Take Control of Your Server's Brewing! \ud83e\uddea**\n\n*Updated for Minecraft 1.21.1 with new PotionType names***\n<\/p>\n","protected":false},"excerpt":{"rendered":"