PotionCombine

PotionCombine 1.1.0 — The Integration Release

The big one. 1.1 started as "pollution + particles" and grew into the version that actually lets PotionCombine live in a mixed-server ecosystem. You get consequence mechanics (pollution + brushes), environmental interaction (heat sources under the cauldron), automation (hopper auto-extract), server integration (PlaceholderAPI hook + public API for other plugins), and quality-of-life (per-world filter, per-player cooldown, state persistence across restarts).

No breaking changes. Every new subsystem lands behind its own toggle and defaults to the safest, most boring value — a 1.0 server upgrades to 1.1 and behaves identically until you opt into the new features.

What's New

Pollution & Cleaning

• Cauldrons gather residue with use. Successes dirty them a little, failures more, spoiled brews worst. Past the threshold (configurable, default 10) the cauldron refuses new ingredients until you scrub it with a brush.
• Each pollution point adds a small chance the next brew fails on startup (default 2% per point). Optional per-point brew-time penalty for servers that want grime to slow things down.
• Polluted cauldrons periodically emit smoke particles, scaling with the level.
• OFF by default — fresh installs brew forever without consequences. Flip pollution.enabled: true when you want the mechanic.

Heat Sources

• A block under the cauldron now matters: campfire, soul campfire, magma block, or lava speeds brewing up and softens pollution-driven spoil rolls.
• Fully configurable in config.yml: each material gets a brew_time_multiplier (< 1.0 = faster) and pollution_resist (0..1, softens spoil chance).
• Lit-state aware by default — an extinguished campfire does nothing unless you toggle heat.require_lit: false.

Hopper Auto-Extract

• A hopper directly under the cauldron pulls finished potions automatically. Spoiled brews are deliberately left alone.
• Disabled by default (automation.hopper_extract: false).

Per-World Filter & Per-Player Cooldown

• settings.worlds takes a whitelist or blacklist to restrict brewing to specific worlds.
• settings.cooldown_seconds throttles how often a player can start a new brew. 0 disables it. Players with potioncombine.cooldown.bypass walk past it.

PlaceholderAPI Hook

• Soft-depend. If PAPI is on the server, the plugin registers %potioncombine_active_brews%, %potioncombine_recipe_count%, %potioncombine_cooldown%, %potioncombine_cooldown_ready%, and %potioncombine_pollution_here%.

Public API

• Events: BrewStartEvent, BrewSuccessEvent, BrewFailEvent, BrewCollectEvent, PollutionChangeEvent.
• Static facade PotionCombineAPI for reading recipes, producing items, checking pollution, and querying cooldowns.
• Stability promise: no breaking changes across patch versions of 1.x.

State Persistence

• Pollution levels and ingredients in cauldrons now survive restarts. Ingredients are dropped above the cauldron on load so players recover them naturally.
• Live brew loops (the spinning display + timer) are still in-memory only — full session restoration is 1.3 work.

Configurable Particles

• Every particle burst is now configurable: insert, brewing_bubble, brew_start, brew_success, brew_fail, collect, pollution_idle, cleaning_brush.
• Each event is a list of { name, count, offset_x/y/z, speed }. Set display.particles.enabled: false to silence them all at once.
• Accepts both 1.20 and 1.21 particle names; the resolver picks whichever your server has at runtime.

Polish & UX Improvements

• Failure messages now broadcast to nearby players (configurable radius, default 16 blocks). Set to 0 for the old "only the brewer sees it" behaviour.
• Breaking a cauldron mid-brew now drops something sensible: early → ingredients back, mid → sludge, late → a tagged "unfinished" bottle. All thresholds configurable.
• Configurable progress bar template (display.progress.template) with MiniMessage support.
• More sounds, all configurable: cleaning_brush, pollution_idle, cauldron_broken. Empty string = silent.
• Friendlier first-run defaults: pollution off, cooldowns off, hopper extract off, heat sources on, simple_glow bundled as the first test recipe (redstone + glowstone dust → night vision + speed).
• New /potioncombine info command — prints version, recipe count, active brew count, and PAPI hook state.

Known Limitations

• Live brew loops still don't survive hard crashes (pollution and ingredients do). Full session restoration is 1.3 work.
• Heat sources only check the block directly under the cauldron. Multi-cauldron synergy and area heat are 1.2 ideas.
• The PAPI hook resolves lazily — if PAPI is reloaded after PotionCombine, the hook won't auto-re-register. Restart the plugin if that happens.

Requirements

• Paper 1.20.4 → 1.21.x (no NMS, no reflection, survives Mojang minor updates)
• Java 17
• Spigot / CraftBukkit not supported (we rely on Adventure, MiniMessage, and display entities)
• PlaceholderAPI optional (auto-registers if present)

---

Built because every "advanced brewing" plugin felt like a spreadsheet wearing a wizard hat. This one tries to feel like brewing. Feedback, bug reports, and edge cases all welcome.