PotionCombine

PotionCombine 1.1.0 — pollution, heat, hoppers, public API

Shift-click ingredients into a filled water cauldron. After a short grace period the cauldron checks what's inside: exact match → brewing starts; no match → ingredients fail out as sludge. Shapeless recipes — order doesn't matter, only what and how much.

1.0 shipped the core brewing loop. 1.1 adds: cauldron pollution and brush cleaning, heat sources under the cauldron, hopper auto-extract, per-world filter, per-player cooldown, PlaceholderAPI hook, public API, state persistence across restarts.

No breaking changes — every new subsystem defaults to off. A server running 1.0 upgrades to 1.1 and behaves identically until you enable features in config.

Features

• Shapeless recipes. Ingredients matched as a multiset. Order and slot position don't matter.
• Nested recipes. A potion produced by one recipe can be listed as an ingredient in another. The matcher distinguishes a brewed phoenix_elixir from a plain healing potion.
• Heat sources. A campfire, soul campfire, magma block, or lava pool directly under the cauldron reduces brew time and softens the spoil roll from pollution. Lit-state checked by default. Per-material brew_time_multiplier and pollution_resist configurable.
• Pollution. Cauldrons accumulate residue points per outcome. Past the threshold the cauldron refuses new ingredients until right-clicked with a vanilla brush. Optional per-point spoil chance and brew-time penalty. Off by default.
• Hopper auto-extract. A hopper directly under the cauldron pulls finished potions the moment brewing completes. Spoiled brews are not pulled. Off by default.
• Per-world filter. Whitelist or blacklist worlds by name.
• Per-player cooldown. Configurable seconds between brew starts. potioncombine.cooldown.bypass skips it.
• Failure states. Unrecognised combination → immediate fail. Water removed mid-brew → fail. Finished potion left past the overbrew timer → spoils into a configurable material or AIR. Cauldron broken mid-brew → ingredients returned early, sludge mid, tagged unfinished bottle late.
• Failure broadcast. notify_radius_blocks (default 16) — failure, spoil, and break messages reach all players within that radius. Set to 0 for 1.0 behaviour.
• Visuals. Floating MiniMessage progress bar with <filled>, <empty>, <percent> tokens while brewing. Glowing rotating ItemDisplay when done. Eight configurable particle events. Both 1.20 and 1.21 particle name spellings accepted.
• Sounds. Every sound is a string key — minecraft: namespace or a custom resource pack key. Empty string = silent.
• Localisation. Ships with English and Russian. MiniMessage throughout. Missing keys fall back to English and log once.
• State persistence. Pollution levels and partial brew contents survive restarts. Ingredients are dropped above the cauldron on load. Live brew loops are not restored — planned for 1.3.

PlaceholderAPI

Soft-depend. Registers automatically if PAPI is present.

• %potioncombine_active_brews% — brews currently in progress
• %potioncombine_recipe_count% — loaded recipe count
• %potioncombine_cooldown% — your cooldown in seconds (0 if ready)
• %potioncombine_cooldown_ready% — yes / no
• %potioncombine_pollution_here% — pollution level at the block you stand on

If PAPI is reloaded after PotionCombine loads, the expansion does not auto-re-register. Restart PotionCombine to fix that.

Public API

Packages: dev.wndrxz.potioncombine.api.events and dev.wndrxz.potioncombine.api.PotionCombineAPI. No breaking changes across patch versions of 1.x.

Events: BrewStartEvent (cancellable), BrewSuccessEvent (result mutable), BrewFailEvent (Reason enum), BrewCollectEvent (cancellable), PollutionChangeEvent (cancellable, Cause enum).

Static facade: recipe(id) / recipes(), produce(recipeId), give(player, recipeId, amount), pollution(block) / pollutionThreshold() / setPollution(block, n), isBrewing(block), cooldownRemaining(player).

@EventHandler
public void onBrew(BrewSuccessEvent ev) {
    if (ev.recipe().id().equals("phoenix_elixir")) {
        ItemStack glowing = ev.result();
        glowing.addUnsafeEnchantment(Enchantment.LURE, 1);
        ev.result(glowing);
    }
}

Installation

1. Drop PotionCombine-1.1.0.jar into plugins/.
2. Restart. Config, recipes, and lang files generate on first boot.
3. Edit config.yml and recipes.yml.
4. /potioncombine reload to apply changes without a restart.

Upgrading from 1.0: drop the new jar in. Existing config keys are untouched. Every new subsystem defaults to off.

Requirements

• Paper 1.20.4 → 1.21.x. Spigot is not supported — requires Adventure and display entities from the Paper API.
• Java 17.
• PlaceholderAPI: optional.

Commands

• /potioncombine help — command list
• /potioncombine info — version, recipe count, active brew count, PAPI hook state
• /potioncombine reload — reloads config, recipes, and locale; active brews continue under prior settings
• /potioncombine give <player> <recipe_id> [amount] — gives a finished custom potion directly

Tab-completion works for player names and recipe IDs.

Permissions

| Permission | Default | Description |
|---|---|---|
| potioncombine.use | true | Can interact with cauldrons |
| potioncombine.admin | op | /reload, /info, /give |
| potioncombine.cooldown.bypass | op | Skips per-player brew cooldown |

Known limitations in 1.1

• Live brew loops are not restored after a restart or crash. Ingredients re-drop above the cauldron; pollution survives. Full session restoration is planned for 1.3.
• Heat is only checked on the block directly under the cauldron. A fire one block to the side has no effect.
• Hopper extract pulls the potion the instant brewing finishes, bypassing the hover period.
• A /papi reload after PotionCombine has loaded does not re-register the PAPI expansion. Restart PotionCombine to fix it.
• Uses the deprecated PotionData API for base potion types. Wrapped in try/catch; will be migrated before 1.22.
• No in-game recipe discovery or journal. Planned for 1.3.

Roadmap

| Version | Content |
|---|---|
| 1.1 | Pollution, brush cleaning, heat sources, hopper extract, per-world filter, per-player cooldown, PAPI, public API, state persistence (this release) |
| 1.2 | Multi-cauldron synergy, area heat, shared particle ticks |
| 1.3 | SQLite progression, in-game journal, live brew loop persistence |
| 1.4 | Reaction events, mutation outcomes |
| 1.5 | Per-recipe permissions, structural recipe variants |
| 1.6 | Per-world recipe filters, economy hook |

Each version ships as a toggleable subsystem. Existing servers are unaffected until features are enabled.

Feedback, bug reports, and recipe issues welcome in the discussion thread or on the repo.