MobRepeller

MobRepeller is a lightweight Bukkit/Spigot plugin that keeps your base peaceful in heavily-modded worlds. Players build small "Totems" — a 2D cross made from a single core block — that block natural hostile spawns in a configurable radius and gently push hostiles outward, without disturbing villagers, CustomNPCs, MineColonies citizens, pets, or neutral wildlife.

Starter cores (Clay, Coal, Hay) give 25m protection, then Iron 50m, Gold 100m, Diamond 150m. A floating hologram shows the tier and range. Totems register automatically when you finish the cross; breaking any block removes it and its hologram.

Works on Spigot, Paper, and hybrid servers like Mohist and Arclight. Requires Java 17+ and Minecraft 1.20.1.

Server-friendly. New-player proof.

Features

Totem Fields

Six tiers: Clay 25m, Coal 25m, Hay 25m, Iron 50m, Gold 100m, Diamond 150m
Hologram label shows tier + range (height configurable)
Auto-registers when you complete the cross shape
Removes when any part of the cross is broken (hologram despawns)
Per-player limit — configurable max totems per player (default 5, creative exempt)
Totem decay — optional expiration timer (default 48h, disabled by default)
Totem linking — overlapping fields show glowing particle beams between centers
Radius visualization — /mobrepeller show draws a particle circle at the field edge for 10 seconds
Break warning — breaking an arm block warns you first; break again within 5s to confirm

Spawn Control

Cancels natural-ish hostile spawns: NATURAL, CHUNK_GEN, REINFORCEMENTS, NETHER_PORTAL, PATROL
Does not affect spawners, spawn eggs, commands, or scripted spawns
Hostiles inside the field are nudged outward; lingerers can be hard-ejected or killed after 15 seconds

Ambient Effects

Inward-flowing enchantment particles when players are within 5 blocks
Randomized enchanting sound at varying pitch (organic, not mechanical)
All configurable in config.yml

New-Player Onboarding

First-join guide book ("MobRepeller")
One-time build tip when placing the first core block

Supported Mods

Hostile Recognition

Anything that is a vanilla Monster, plus creatures from popular 1.20.1 packs:

Alex's Mobs (22 friendly species whitelisted)
Ice and Fire: Dragons
Advent of Ascension (AoA3)
The Twilight Forest
Mowzie's Mobs
Grimoire of Gaia
The Betweenlands
L_Ender's Cataclysm
Mutant Monsters
Born in Chaos
Creeper Overhaul

Each mod can be toggled on/off at runtime with /mobrepeller modprotection <mod> <on|off>.

Extendable through hostile.packages / hostile.types in config.yml.

Neutral / NPC Whitelist (never pushed)

Mod frameworks:

CustomNPCs
Citizens
MineColonies
Friends & Foes
Naturalist
Better Animals Plus
MyPet

Vanilla types:

Villager, Iron Golem, Snow Golem
Horse, Donkey, Mule, Llama, Trader Llama, Wandering Trader
Wolf, Cat, Ocelot, Parrot, Fox
Rabbit, Chicken, Cow, Sheep, Pig, Mooshroom
Squid, Glow Squid, Axolotl, Frog, Tadpole
Bat, Bee, Polar Bear, Strider, Goat
Allay, Camel, Sniffer

You can add or remove additional neutral packs in config.yml.

Building a Totem

Shape: a 2D vertical cross (6 blocks total) made from one core material.

Clay — 25m
Coal — 25m
Hay — 25m
Iron — 50m
Gold — 100m
Diamond — 150m

Commands

Command	Description
`/mobrepeller ping`	Check plugin is active
`/mobrepeller count`	Total totems across all worlds
`/mobrepeller list`	List totems in your current world
`/mobrepeller register`	Manually register a cross you're looking at
`/mobrepeller show`	Visualize nearest totem radius for 10 seconds
`/mobrepeller remove`	Remove the totem you're looking at
`/mobrepeller rescan [radius]`	Auto-detect and register all crosses nearby
`/mobrepeller modprotection list`	Show per-mod toggle status
`/mobrepeller modprotection <mod> <on/off>`	Toggle a mod's hostile detection
`/mobrepeller save`	Force save to disk
`/mobrepeller removehere`	Remove nearest hologram + its totem
`/mobrepeller cleanup`	Remove nearby orphaned holograms (24m)
`/mobrepeller cleanupall`	Remove all holograms in the world
`/mobrepeller nukeholo`	Remove all label-like armor stands (fallback)
`/mobrepeller refreshholo`	Refresh all hologram labels
`/mobrepeller reload`	Reload config, matcher, and holograms
`/mobrepeller debug`	Plugin and manager diagnostics

Alias: /repel

Permissions

Player-Friendly Basics

Permission	Description	Default
`mobrepeller.use`	Basic commands (ping, count, list, register)	everyone
`mobrepeller.ping`	Check plugin is active	everyone
`mobrepeller.count`	Show total totems	everyone
`mobrepeller.list`	List totems in current world	everyone
`mobrepeller.register`	Manually register a nearby cross	everyone

Admin / Cleanup / Config

Permission	Description	Default
`mobrepeller.manage`	All admin commands	op
`mobrepeller.save`	Save totems to disk	op
`mobrepeller.removehere`	Remove nearest hologram	op
`mobrepeller.cleanup`	Remove nearby holograms (24m)	op
`mobrepeller.cleanupall`	Remove all holograms in world	op
`mobrepeller.reload`	Reload config and matcher	op
`mobrepeller.debug`	Show diagnostics	op

mobrepeller.* grants all permissions.

Configuration

All hostile/neutral mod sets, vanilla types, tier radii, repel strength, ambient effects, totem limits, decay, and hologram height are editable in config.yml. The file generates with sensible defaults on first run.

Compatibility


Minecraft	1.20.1
Server	Spigot, Paper, Mohist, Arclight
Java	17 or newer

Works cleanly alongside Forge mods on hybrid servers.

License & Credit

License: BSD 3-Clause (see LICENSE)
Keep copyright/notice headers and credit: "MobRepeller by Luc Bellefeuille"
Commercial redistribution is permitted by the license; attribution is required

Credits

Design & code: Luc Bellefeuille — PRs for additional presets welcome.