I. Enabling and Usage

Mob capture requires server 1.20.5+ and is disabled by default. Set enabled: true in capture.yml, save, then use /cpp reload to reload.

/cpp giveCapture playerName example 1

With the capture item in the main hand, melee attack the target mob directly. Right-click, throwing, ranged attacks and sweep damage do not trigger capture; ordinary items with the same appearance cannot replace items given by the plugin.

1. The attack must deal damage, and after subtracting this hit's final damage, the target must still be alive with remaining health not higher than the percentage set by healthPercent.
2. The mob type must match mobs and blacklist, and the base companion companion must be configured. Players and the Ender Dragon cannot be captured.
3. When the conditions are met, the success rate is determined by chance: both success and a chance failure consume one item.
4. On success, that hit's damage is cancelled, the original mob is removed, and the companion is added to the warehouse; on a chance failure, the attack damage is still dealt normally.
5. When health does not match, the attack is lethal, the type does not match, the warehouse is full or adding fails, the capture item is not consumed; the attack is still handled as a normal attack.

The captured companion's attributes and abilities come from the base companion specified by companion, and its appearance uses the captured mob type; the original mob's custom name, equipment, color, age and other individual data are not saved, and it is not automatically selected.

II. Configuration Example

Below is an example capture.yml; more items can be added under captures.

enabled: true
mobScale:
  pig: 0.5
captures:
  example:
    material: LEAD
    name: "&aCapture Item &ePig"
    custom-model-data: 0
    isEnchant: true
    tooltipStyle: ""
    itemModel: ""
    description:
      - "&7Hold the item and melee attack a pig"
      - "&7After attacking, when health is at most 10%, 80% chance to capture"
    companion: reaper
    mobs:
      - pig
    blacklist:
      - ender_dragon
    healthPercent: 10
    chance: 80

• example: capture item key, used by /cpp giveCapture.
• material: the item material used for melee; avoid materials that throw or consume on right-click.
• companion: base companion key, which must exist in companions/*.yml.
• mobs: allowed mob types, supporting pig and minecraft:pig; an empty list or all means no type restriction.
• blacklist: forbidden mob types, with higher priority than mobs; the Ender Dragon is never supported.
• healthPercent: upper limit of remaining health percentage after the attack, range 0–100, 0 means capture is impossible.
• chance: success rate once the health condition is met, range 0–100.
• isEnchant: whether to show the enchant glow; custom-model-data requires 1.14+, and tooltipStyle, itemModel require 1.21.2+.

III. Captured Companion Scaling

The top-level mobScale in capture.yml sets the capture appearance multiplier per mob type, e.g. pig: 0.5 means half the original size.

A captured mob without its own multiplier is automatically scaled down to about 0.9875 blocks if its original height exceeds that; smaller mobs keep their original size. When a multiplier is explicitly configured, the configured value is used.

The mobScale in a normal companion config defaults to 0.5; captured instances use the scaling rules on this page, see Companion Models (opens new window) for details.