?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
PotionCombine

PotionCombine

Shapeless, UI-free potion brewing inside vanilla water cauldrons. No GUIs, no NMS.

3
0
3
0

Compatibility

Minecraft: Java Edition

1.21.x
1.20.x

Platforms

Links

View source

Tags

Creators

Details

Licensed MIT
Published 2 days ago

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.