CaptureBall

Capture mobs into a ball, carry them around, and release them somewhere else.

CaptureBall is a lightweight Paper plugin for survival servers. Admins hand out capture balls, players use them to move mobs, and the plugin makes sure nobody uses them to get around land protection.

English | 繁體中文

---

English

How it works

1. An admin gives a player an empty capture ball.
2. The player right-clicks a mob while holding it. The mob is stored in the ball.
3. The player right-clicks a block with the filled ball. The mob is released and the ball is used up.

Capture and release are both single use.

Features

• Keeps full mob data: name, health, equipment, age, and more.
• Not a spawn egg: filled balls cannot be placed into a spawner.
• Admin-only creation: no crafting recipe, no shop, not usable as a crafting ingredient.
• Filled balls never stack.
• Works alongside other interactions: item frames, chests, doors and more behave normally.
• Capture chance: optionally make captures fail with a set probability.
• Mob blacklist and disabled worlds.
• Pet protection: tamed pets can only be captured by their owner.
• Customizable names, lore, item model and messages using MiniMessage colors.

Land protection

Applies to both capturing and releasing:

• WorldGuard: inside any region (for example spawn), only OPs can use balls.
• Residence: inside a residence, the player must be the owner or have the build flag.

Both are optional. If a plugin isn't installed, its rule is skipped. When a player is denied, the ball is not consumed.

Commands

Command	Description
/captureball give <player> [amount]	Give empty capture balls
/captureball reload	Reload the config

Permissions

Permission	Description
captureball.use	Use capture balls
captureball.bypass	Skip the Residence and pet-owner checks

Don't forget to grant captureball.use to your players, for example with LuckPerms:

/lp group default permission set captureball.use true

Requirements

• Paper (or a fork such as Purpur), Minecraft 1.21.4+, Java 21
• Optional: WorldGuard, Residence

Spigot is not supported.

---

繁體中文

使用方式

1. 管理員給玩家空的捕捉球。
2. 玩家手持空球，對生物按右鍵，生物就會被收進球裡。
3. 手持滿球對方塊按右鍵，生物會被放出來，球同時被消耗。

捕捉與釋放都是單次使用。

特性

• 完整保留生物資料：名字、血量、裝備、年齡等。
• 不是生怪蛋：滿球無法放進刷怪籠。
• 只有管理員能發放：沒有合成配方、沒有商店，也不能當合成材料。
• 滿球不能堆疊。
• 不干擾其他互動：展示框、箱子、門等照常運作。
• 捕捉成功率：可設定捕捉失敗的機率。
• 生物黑名單與停用世界。
• 寵物保護：已馴服的寵物只有主人能捕捉。
• 高度可自訂：名稱、lore、物品模型和訊息都可以用 MiniMessage 調整顏色。

領地與保護區

捕捉與釋放都適用：

• WorldGuard：在任何區域（例如 spawn）內，只有 OP 能使用。
• Residence：在領地內，必須是領地主人或擁有 build 權限。

兩者都是選用，沒安裝就會略過對應規則。被拒絕時，球不會被消耗。

指令與權限

• /captureball give <玩家> [數量]：給予空的捕捉球
• /captureball reload：重新載入設定
• captureball.use：使用捕捉球
• captureball.bypass：略過 Residence 與寵物主人檢查

請記得把 captureball.use 給玩家，例如用 LuckPerms：

/lp group default permission set captureball.use true

需求

Paper（或 Purpur 等分支）、Minecraft 1.21.4 以上、Java 21。選用：WorldGuard、Residence。不支援 Spigot。

---

Source code & issues: GitHub · Licensed under GPL-3.0