What It Does

• Throw an empty Pokeball at an allowed mob to capture it.
• Throw a filled Pokeball to release at the impact point - smart placement puts mobs just outside walls.
• Configurable effects: subtle or flashy particles and a neat flight trail.
• Admins can live-tune storage cap, capture allowlist, and refund mode from in-game commands.
• Uses real "stasis" entities (no fragile NBT); cleanups run automatically on startup.

See It In Action

• Video demo: Watch on GitHub

Screenshots

• Empty ball
  
• Caught a Sheep
  
• Special capture (bypass allowlist)
  

Downloads & Source

• Latest releases: GitHub Releases
• Source & issues: GitHub Repository

Requirements

• Server: Paper 1.21.x (uses modern Paper APIs; not Spigot)
• Java: 21 (LTS)
• Folia: not supported (for now)
• Dependencies: none to install (MiniMessage is auto-provisioned via Paper's libraries)

Installation

1. Drop the JAR into your server's plugins/ folder.
2. Start the server once to generate plugins/Pokeball/config.yml.
3. Tweak config.yml (allowlist, effects, worlds, refund mode).
4. Reload in-game with /pokeball reload.

Commands

• /pokeball - Show contextual help (alias: /pb)
• /pokeball help - Help
• /pokeball version - Plugin version
• /pokeball reload - Reload config (perm: pokeball.admin.reload)
• /pokeball give <player> [amount] - Give balls (perm: pokeball.admin.give)
• /pokeball admin list - List stored (first 20)
• /pokeball admin tp <id> - Teleport to stasis entry
• /pokeball admin clean <id|all> - Remove entries
• /pokeball admin cap [maxTotal] - Show/set storage cap (0 = unlimited)
• /pokeball admin refund [GIVE|DROP] - Show/set refund mode
• /pokeball admin capture list - Show allowed capture types
• /pokeball admin capture allow <type> - Add type to allowlist
• /pokeball admin capture remove <type> - Remove type (keeps at least 1)

Permissions

• pokeball.admin - admin subcommands (list, tp, clean, cap, refund, capture ...)
• pokeball.admin.give - allow /pokeball give
• pokeball.admin.reload - allow /pokeball reload
• pokeball.capture.any - bypass capture allowlist (ops by default)
• Players do NOT need extra permissions to use balls - just the item.

Configuration Highlights

• Allowlist: Only listed entity types can be captured.
• Worlds: compat.worlds gates both capture and release (empty = all worlds).
• Refunds: refund.mode = GIVE (to inventory, drop on overflow) or DROP (always drop).
• Effects: Tune particles and sounds for capture/release, plus a flight trail while the ball travels.
• Consume on release: capture.consume-on-release = false refunds an empty ball; true consumes it.

FAQ

• Does this work on Spigot? No - it uses modern Paper APIs (Brigadier + lifecycle). Use Paper 1.21.x (forks may work but are not tested).
• Players can't capture in my world. Add the world name under compat.worlds or leave it empty to allow all worlds.
• Can I capture players? No.
• Can I make the effects quieter? Yes - tune the effects section in the config.

Bugs, Requests, Help
If something's off, please open a GitHub issue - it's the fastest way to get help:
https://github.com/stdNullPtr/Pokeball/issues

When reporting, include:

• Server version (/version) and Pokeball version
• Steps to reproduce (what you did, what happened, what you expected)
• Relevant logs (errors/warnings) and your config.yml if helpful

License
AGPL-3.0 - full source available on GitHub. Contributions welcome!

• Repo: https://github.com/stdNullPtr/Pokeball
• Issues: https://github.com/stdNullPtr/Pokeball/issues