** 🧪 PotionLimiter - Complete Plugin Documentation

📖 Description

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.

The plugin allows you to:

Blacklist specific potion types from being brewed (including variants like LONG, STRONG)
Control brewing by world - enable or disable the plugin in specific worlds
Notify players when blocked potions are attempted
Preserve ingredients when brewing is blocked
Easy configuration with copy-paste reference examples

Built with modern Java 21, Paper API, and Kyori Adventure (MiniMessage), PotionLimiter offers clean code, performance optimization, and beautiful chat formatting.

✨ Key Features

🎯 Granular Potion Control

Block specific PotionTypes (e.g., STRENGTH, LONG_STRENGTH, STRONG_STRENGTH)
Support for all Minecraft 1.21 potions including new additions:
- Wind Charged
- Weaving
- Oozing
- Infested
Easy-to-use configuration with built-in reference list

🌍 World-Based Management

Blacklist Mode: Disable plugin in specific worlds (creative, lobby, etc.)
Whitelist Mode: Only enable plugin in specific worlds (survival only)
Per-world control for maximum flexibility

💬 Player Notifications

Configurable radius-based notifications
Beautiful MiniMessage formatting with gradients and colors
Toggle notifications on/off
Custom blocked messages per potion type

🔄 Ingredient Preservation

Brewing events are cancelled before ingredients are consumed
Items remain in brewing stand when blocked
Prevents resource waste

⚙️ Admin-Friendly

Simple /plimit reload command - no server restart needed
/plimit list shows all blocked potions and world restrictions
Tab completion for all commands
Clear console logging

🚀 Performance & Modern Code

Java 21 with modern syntax (switch expressions, pattern matching)
No NMS (Native Minecraft Server code) - fully compatible with Paper updates
Dependency injection for clean architecture
Lightweight - minimal server impact

📦 Installation

Requirements:
- Minecraft Server 1.21.1 - 1.21.11
- Paper (or Paper-based servers like Purpur, Pufferfish)
- Java 21+

Steps:

 Download PotionLimiter-1.0.0.jar
 Place in your server's plugins/ folder
 Start/restart your server
 Edit plugins/PotionLimiter/config.yml
 Run /plimit reload in-game

🎮 Usage Examples

Example 1: Block Strength Potions in All Worlds
Perfect for balanced PvP servers where strength potions are too overpowered.

blacklisted-potions:
  - STRENGTH
  - LONG_STRENGTH
  - STRONG_STRENGTH

Result: Players cannot brew any strength potions. The brewing stand will not complete the process.

Example 2: Disable Plugin in Creative World
Allow unrestricted brewing in creative/building worlds while maintaining restrictions in survival.

world-settings:
  blacklist-mode: true   Blacklist mode
  blacklisted-worlds:
    - world_creative
    - lobby
    - skyblock_spawn

Result: Plugin is disabled in world_creative, lobby, and skyblock_spawn. Players can brew anything there. In all other worlds, restrictions apply.

Example 3: Only Work in Survival World (Whitelist Mode)
Enable the plugin ONLY in your main survival world, ignoring all other worlds.

world-settings:
  blacklist-mode: false   Whitelist mode
  blacklisted-worlds:
    - world   Only active here

Result: Plugin is only active in the world named world. All other worlds have unrestricted brewing.

Example 4: Block All Harmful Potions
Great for peaceful/roleplay servers.

blacklisted-potions:
  - HARMING               
  - STRONG_HARMING       
  - POISON
  - LONG_POISON
  - STRONG_POISON
  - WEAKNESS
  - LONG_WEAKNESS

Example 5: Block Invisibility for Fair PvP
Prevent invisibility potions in PvP arenas.

blacklisted-potions:
  - INVISIBILITY
  - LONG_INVISIBILITY

Example 6: Block 1.21 New Potions
Disable the new experimental potions added in 1.21.

blacklisted-potions:
  - WIND_CHARGED
  - WEAVING
  - OOZING
  - INFESTED

Example 7: Custom Notification Settings
Configure how players are notified when brewing is blocked.

brewing-settings:
  notify-players: true
  notify-radius: 10   10 blocks
  blocked-message: "<gradient:ff0000:ff6666>⚠ You cannot brew <potion> on this server!</gradient>"

Result: Players within 10 blocks of the brewing stand receive a gradient red message.

Example 8: Disable Notifications (Silent Mode)
Block potions without notifying players.

brewing-settings:
  notify-players: false

Result: Brewing is blocked silently. Only console logs the event.

🎯 Common Use Cases

1. Competitive PvP Servers

 Block overpowered potions for balanced combat
blacklisted-potions:
  - STRONG_STRENGTH
  - STRONG_HEALING        
  - LONG_INVISIBILITY
  - TURTLE_MASTER
  - STRONG_TURTLE_MASTER

2. Survival Servers with Custom Mechanics

 Force players to obtain potions through custom methods (shops, quests, etc.)
blacklisted-potions:
  - REGENERATION
  - LONG_REGENERATION
  - STRONG_REGENERATION
  - HEALING               
  - STRONG_HEALING

3. Minigame Servers

 Disable plugin in minigame worlds, enable in lobby
world-settings:
  blacklist-mode: true
  blacklisted-worlds:
    - bedwars
    - skywars
    - parkour

4. Roleplay/Peaceful Servers

 Block all combat/harmful potions
blacklisted-potions:
  - HARMING               
  - STRONG_HARMING        
  - POISON
  - LONG_POISON
  - STRONG_POISON
  - STRENGTH
  - LONG_STRENGTH
  - STRONG_STRENGTH

5. Economy Servers

 Block high-value potions to maintain economy balance
blacklisted-potions:
  - STRONG_HEALING        
  - STRONG_REGENERATION
  - LONG_NIGHT_VISION
  - LONG_WATER_BREATHING

🔧 Commands

Command	Description	Permission
`/plimit reload`	Reload configuration without restart	`potionlimiter.admin`
`/plimit list`	Show all blacklisted potions and world restrictions	`potionlimiter.admin`
`/plimit help`	Display command help	`potionlimiter.admin`

Aliases: /potionlimiter, /pl

🔐 Permissions

Permission	Description	Default
`potionlimiter.admin`	Access to all commands	OP

⚙️ Configuration Reference

brewing-settings

brewing-settings:
  return-ingredients: true       Preserve ingredients when blocked (always true in Paper)
  notify-players: true           Send messages to nearby players
  notify-radius: 5               Notification radius in blocks
  blocked-message: "<red>⚗ Brewing of <potion> has been disabled!</red>"

world-settings

world-settings:
  blacklist-mode: true           true = disable in listed worlds, false = only enable in listed
  blacklisted-worlds:
    - world_creative
    - lobby

blacklisted-potions

blacklisted-potions:
  - STRENGTH                     Add PotionType names here
  - LONG_STRENGTH
  - STRONG_STRENGTH

messages

messages:
  prefix: "<gradient:00ffff:0080ff>[PotionLimiter]</gradient> "
  reload-success: "<green>Configuration reloaded successfully!</green>"
  reload-error: "<red>Error reloading configuration! Check console.</red>"
  no-permission: "<red>You don't have permission to use this command.</red>"
  list-header: "<gradient:ff0000:ff6666>===== Blacklisted Potions =====</gradient>"
  list-item: "<red>• <potion></red>"
  list-empty: "<yellow>No potions are currently blacklisted.</yellow>"
  list-footer: "<gray>Total: <count> potion(s) blocked</gray>"

📊 All Available Potion Types (1.21)

Click to expand full potion list

Base Potions

WATER - Water Bottle
MUNDANE - Mundane Potion
THICK - Thick Potion
AWKWARD - Awkward Potion

Swiftness (Speed)

SWIFTNESS - Swiftness I (3:00) ⚠️ Changed from SPEED
LONG_SWIFTNESS - Swiftness I (8:00) ⚠️ Changed from LONG_SPEED
STRONG_SWIFTNESS - Swiftness II (1:30) ⚠️ Changed from STRONG_SPEED

Slowness

SLOWNESS - Slowness I (1:30)
LONG_SLOWNESS - Slowness I (4:00)
STRONG_SLOWNESS - Slowness IV (0:20)

Strength

STRENGTH - Strength I (3:00)
LONG_STRENGTH - Strength I (8:00)
STRONG_STRENGTH - Strength II (1:30)

Healing (Instant Health)

HEALING - Instant Health I ⚠️ Changed from INSTANT_HEAL
STRONG_HEALING - Instant Health II ⚠️ Changed from STRONG_INSTANT_HEAL

Harming (Instant Damage)

HARMING - Instant Damage I ⚠️ Changed from INSTANT_DAMAGE
STRONG_HARMING - Instant Damage II ⚠️ Changed from STRONG_INSTANT_DAMAGE

Leaping (Jump Boost)

LEAPING - Jump Boost I (3:00) ⚠️ Changed from JUMP_BOOST
LONG_LEAPING - Jump Boost I (8:00) ⚠️ Changed from LONG_JUMP_BOOST
STRONG_LEAPING - Jump Boost II (1:30) ⚠️ Changed from STRONG_JUMP_BOOST

Regeneration

REGENERATION - Regeneration I (0:45)
LONG_REGENERATION - Regeneration I (1:30)
STRONG_REGENERATION - Regeneration II (0:22)

Fire Resistance

FIRE_RESISTANCE - Fire Resistance (3:00)
LONG_FIRE_RESISTANCE - Fire Resistance (8:00)

Water Breathing

WATER_BREATHING - Water Breathing (3:00)
LONG_WATER_BREATHING - Water Breathing (8:00)

Invisibility

INVISIBILITY - Invisibility (3:00)
LONG_INVISIBILITY - Invisibility (8:00)

Night Vision

NIGHT_VISION - Night Vision (3:00)
LONG_NIGHT_VISION - Night Vision (8:00)

Weakness

WEAKNESS - Weakness (1:30)
LONG_WEAKNESS - Weakness (4:00)

Poison

POISON - Poison I (0:45)
LONG_POISON - Poison I (1:30)
STRONG_POISON - Poison II (0:21)

Turtle Master

TURTLE_MASTER - Turtle Master I (0:40)
LONG_TURTLE_MASTER - Turtle Master I (1:20)
STRONG_TURTLE_MASTER - Turtle Master II (0:20)

Slow Falling

SLOW_FALLING - Slow Falling (1:30)
LONG_SLOW_FALLING - Slow Falling (4:00)

1.21 New Potions ✨

WIND_CHARGED - Wind Charged (3:00) 🆕
WEAVING - Weaving (3:00) 🆕
OOZING - Oozing (3:00) 🆕
INFESTED - Infested (3:00) 🆕

🎨 MiniMessage Format Examples

PotionLimiter uses MiniMessage for beautiful chat formatting. You can customize all messages in config.yml.

Gradient Text

blocked-message: "<gradient:ff0000:ffff00>⚠ This potion is banned!</gradient>"

Rainbow Text

blocked-message: "<rainbow>You cannot brew <potion>!</rainbow>"

Bold/Italic/Underline

blocked-message: "<bold><red>BREWING BLOCKED:</red></bold> <italic><potion></italic>"

Hover Text

blocked-message: "<hover:show_text:'Contact admin for help'><red>Brewing disabled!</red></hover>"

Combined Effects

blocked-message: "<gradient:ff0000:ff6666><bold>⚠ BLOCKED</bold></gradient> <gray>-</gray> <yellow><potion></yellow>"

Learn more: MiniMessage Documentation

🐛 Troubleshooting

Potions are still being brewed

Check /plimit list to confirm potions are in the blacklist
Verify you're using 1.21 potion names (e.g., SWIFTNESS not SPEED)
Run /plimit reload after config changes
Check console for "Invalid PotionType" warnings
Verify world restrictions with /plimit list

"Invalid PotionType" warnings in console
This means you're using old 1.20 names. Update your config:

❌ SPEED → ✅ SWIFTNESS
❌ INSTANT_HEAL → ✅ HEALING
❌ JUMP_BOOST → ✅ LEAPING
❌ INSTANT_DAMAGE → ✅ HARMING

Plugin not working in a world

Check world-settings.blacklist-mode
Verify world name matches exactly (case-sensitive)
Use world folder name, not display name

Players not receiving notifications

Check notify-players: true in config
Increase notify-radius value
Verify MiniMessage syntax is correct

📈 Performance

Event Handling: Optimized brewing recipe prediction
Memory Usage: <5MB typical
CPU Impact: Negligible (<0.1% on modern hardware)
No NMS: Future-proof and update-safe

🤝 Support

Discord: geturplugins
Issues: Report bugs with detailed steps to reproduce
Feature Requests: Suggest improvements with use cases
Questions: Provide server version, config, and console logs

🎉 Credits

Developer: geturplugins
API: PaperMC Team
Chat Library: Kyori Adventure Team
Built with: Java 21, Maven, IntelliJ IDEA

📝 Changelog

Version 1.0.0 (Initial Release)

✅ Granular potion blacklist system
✅ World-based blacklist/whitelist
✅ Player notifications with MiniMessage
✅ Admin commands (reload, list, help)
✅ Tab completion
✅ Ingredient preservation
✅ Java 21 & Paper 1.21.1 support
✅ Full configuration examples
✅ Updated for 1.21 PotionType names (SWIFTNESS, HEALING, LEAPING, HARMING)
✅ Advanced brewing recipe prediction system

📚 Quick Reference Card

Most Common Blocked Potions (PvP Servers)

blacklisted-potions:
   Combat potions
  - STRENGTH               Strength I
  - LONG_STRENGTH          Strength I (8:00)
  - STRONG_STRENGTH        Strength II
  
   Healing potions
  - HEALING                Instant Health I (NEW NAME)
  - STRONG_HEALING         Instant Health II (NEW NAME)
  
   Movement potions
  - SWIFTNESS              Speed I (NEW NAME)
  - LONG_SWIFTNESS         Speed I extended (NEW NAME)
  - STRONG_SWIFTNESS       Speed II (NEW NAME)
  
   Utility potions
  - INVISIBILITY           Invisibility
  - LONG_INVISIBILITY      Invisibility extended
  
   Damage potions
  - HARMING                Instant Damage I (NEW NAME)
  - STRONG_HARMING         Instant Damage II (NEW NAME)

🧪 PotionLimiter - Take Control of Your Server's Brewing! 🧪

Updated for Minecraft 1.21.1 with new PotionType names**

PotionLimiter

📖About PotionLimiter