Magic Leads
A Paper plugin that makes leads magical:
- Teleport with you — mobs you hold on a lead follow you through ender pearls,
/tp, plugins, nether/end portals, and end gateways instead of being left behind. Full convoys come too: a happy ghast towing boats (1.21.6+ sneak-click lead transfers) arrives with every link intact. - Unbreakable — leads never snap from distance; the mob is pulled back to its holder instead. Applies to mob-held links in your convoy as well.
- Attach to any mob — right-click any mob with a lead: villagers, zombies, iron golems, anything (configurable blacklist). Vanilla's sneak + right-click lead transfer gesture is left untouched.
- Damage protection (optional) — leashed mobs can't be hurt, except by players if you allow it.
- No lead duplication — lead totals stay honest across every teleport and portal.
Download Magic Leads on SpigotMC
The Chain Rule
All of the above applies to a leashed entity only when following its holder chain upward reaches a player (you → ghast → boat = magic, end to end). Two mobs tied to each other with no player involved — or a mob tied to a fence post — behave purely vanilla, including damage.
Requirements
- Paper (or a Paper fork) 1.21.11
- Java 21
- Folia is supported — all scheduling and teleporting is region-aware, so the plugin runs on Folia builds as well as regular Paper.
Installation
- Add the Magic Leads jar into your
pluginsfolder. - Restart your server.
- Edit
config.ymlto your liking. - Type
/magicleads reload.
Commands
| Command | Permission | Default |
|---|---|---|
/magicleads (alias /ml) — show feature status | — | everyone |
/magicleads reload — reload config.yml + messages.yml | magicleads.reload | op |
/magicleads debug <scenario> — run built-in test scenarios (also requires debug.enabled) | magicleads.debug | op |
Permissions
| Permission | Default | Meaning |
|---|---|---|
magicleads.leashany.* | everyone | Attach a lead to any mob type. |
magicleads.leashany.<type> | unset | Attach a lead to one mob type, e.g. magicleads.leashany.villager. |
magicleads.leashany | unset | Legacy catch-all for any mob type. |
magicleads.reload | op | Reload the plugin. |
magicleads.debug | op | Run debug scenarios. |
To restrict leashing per mob type, negate magicleads.leashany.* in your permissions plugin and grant
the specific magicleads.leashany.<type> nodes you allow.
Player-facing text lives in messages.yml
(MiniMessage format) — restyle or translate freely.
Configuration
All settings live in config.yml. Run /magicleads reload after editing.
| Key | Default | Meaning |
|---|---|---|
disabled-worlds | [] | Worlds where Magic Leads is disabled — a YAML list of real world (folder) names, case-insensitive; an empty list keeps it active everywhere. Run /magicleads to see the effective list; entries matching no loaded world are warned about in the console on reload. |
teleport-with-player.enabled | true | Leashed mobs teleport along with you. |
teleport-with-player.causes | pearls, commands, plugins, nether portals, end portals, end gateways, chorus fruit | Which teleport causes bring mobs along. Valid values are Bukkit TeleportCause names. |
teleport-with-player.min-distance | 8.0 | Same-world teleports shorter than this are ignored — the vanilla leash survives anything under 12 blocks anyway. |
teleport-with-player.reattach-delay-ticks | 10 | Delay before re-attaching the leash after arrival. |
teleport-with-player.block-mob-portals | true | Leashed mobs can't wander through portals alone. |
teleport-with-player.include-convoys | true | Entities leashed to your mobs (towed boats etc.) teleport along too. |
unbreakable.enabled | true | Distance never snaps a lead; the mob is pulled to you. |
unbreakable.mob-held-leads | true | Mob-held links in a player-rooted chain never snap either. |
leash-anything.enabled | true | Leads attach to any mob. |
leash-anything.blacklist | ENDER_DRAGON, WITHER | Entity types that can never be leashed. |
damage-protection.enabled | true | Leashed mobs can't be damaged. |
damage-protection.allow-player-damage | true | …except by players (melee or projectile). |
debug.enabled | false | Enables the /magicleads debug test scenarios. Leave off in production. |
Developer API
Other plugins can hook Magic Leads via events in fun.sunrisemc.magicleads.api. Add the Magic Leads jar
to your project as a provided scope dependency.
ConvoyTeleportEvent(cancellable) — fires before a player's convoy is escorted through a teleport; cancel it to leave the leads vanilla for that teleport.LeadPullEvent(cancellable) — fires before a stray mob is pulled back to its holder instead of the lead snapping; cancel it to allow the vanilla snap.MobStrandEvent— fires when an escort fails and a mob is freed; callsetDropLead(false)to suppress the lead-item refund.
Metrics
The plugin reports anonymous usage statistics to bStats — server count, platform, and which of the four config-gated features (teleport-with-player, unbreakable, leash-anything, damage-protection) are enabled. Nothing identifying is collected.
To opt out, set enabled: false in plugins/bStats/config.yml, which disables bStats for every plugin
on the server at once.