CustomVillagers is a recreation of a BlissSMP villager event with more customization, custom features and more! Locating Villager Souls is also very simple due to the tracker command. Villager Souls is a enchanted pitcherpod that carries a custom name and a persistent particle aura while being FULLY invisible. The plugin supplies a configuration GUI being able to add custom trades & edit current trades All particle effects are smooth and configurable, and the command set is streamlined under the customvillager namespace.
| Action | Command / Interaction | Result |
|---|---|---|
| Give yourself a Villager Soul | /customvillager <player><name> | You receive a Villager Soul item. Villager Souls also have a built-in currency, which can be toggled off in config.yml. |
| Place the soul | Right-click any solid block while holding the soul | A custom villager spawns at that location. The villager is hidden (no name tag, invisible to other players). Hide the villager wherever you'd like players to find it. |
| Deploy the gyroscope compass | /centerparticlecompass | An animated particle compass appears at the player's current location. The compass starts but does not show any directional beams yet — beams remain hidden until the broadcast finishes. |
| Broadcast the narrative | /villagereventbc | An animated "lost souls" story is broadcast to all online players. While the broadcast is playing, the compass remains idle with no beams visible. |
| Tracking begins | Automatic — triggers when the broadcast finishes | Once the broadcast completes, the compass activates directional particle beams pointing toward every hidden villager. Each beam ends with a dimension-specific particle effect: Overworld — end-rod particles, Nether — fire particles, The End — dragon-breath particles. |
| Locate villagers | Follow the beam | Players can follow the visible beam to reach the villager(s), upon entering the same chunk a chat message is sent to the player which indicates the villager is underground. |
| End the event | /villagereventstop (event removal) | Removes all custom villagers (including souls), removes the compass, and clears villager essence (if toggled on) |
| Feature | Details |
|---|---|
| Custom Villager Souls | Assign a unique name to the villager soul which has default custom trades & Customizable trading options like 1 time trades, Or specific amounts. |
| Particle Auras | Two aura styles: • SPARKLE – slow, orbiting rings. • ROAM – continuous, history‑based trail that stays attached even while sprint‑jumping. |
| Stacked Auras | Holding multiple different souls displays independent, colour‑coded auras simultaneously. |
| Locator UI | The /customvillagerlocator command opens a chat‑based GUI that lists every soul, shows its location, dimension, and online/offline status. Clickable coordinates teleport the player instantly. |
| One‑Time Trade Logic | Trades can be set to “once”. After a successful trade the item becomes unavailable, and the GUI remains open. Switching back to infinite or resetting the trade works correctly. |
| Soul Protection | Souls cannot be fed to parrots/chickens, placed in composters, used on farmland, or used for breeding. Only players with Creative/OP can destroy them. |
| Gyroscope Particle Compass | Souls can be located by this compass creating a particle beam in the direction of the Soul. Works across all dimensions |
| Configurable | All core options (aura style, particle density, permission toggles, etc.) are exposed in config.yml with detailed comments. |
| Command | Description |
|---|---|
| /customvillager | Gives you a Villager Soul item used to spawn a custom villager. |
| /centerparticlecompass | Creates a central particle compass in the sky pointing to all custom villagers. |
| /villagereventbc | Broadcasts the animated "lost souls" narrative event to all players. |
| /villagereventinfo | Opens a clickable chat UI with plugin details and a step-by-step guide. |
| /villagereventstop | Stops the villager event and removes all custom entities. |
| /cvreload | Reloads config.yml without restarting the server. |
| /customvillagerlocator | Opens an interactive clickable chat GUI listing all custom villager souls across all worlds, containers, and inventories. |
| Permission | Default | Covers |
|---|---|---|
| customvillagers.admin | op | Every command listed above. |
CONFIG.YML
(the characters are good in the real config)
# ██████╗ ██╗ ██╗███████╗████████╗ ██████╗ ███╗ ███╗
# ██╔════╝ ██║ ██║██╔════╝╚══██╔══╝██╔═══██╗████╗ ████║
# ██║ ██║ ██║███████╗ ██║ ██║ ██║██╔████╔██║
# ██║ ██║ ██║╚════██║ ██║ ██║ ██║██║╚██╔╝██║
# ╚██████╗╚██████╔╝███████║ ██║ ╚██████╔╝██║ ╚═╝ ██║
# ╚═════╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
#
# ██╗ ██╗██╗██╗ ██╗ █████╗ ██████╗ ███████╗██████╗ ███████╗
# ██║ ██║██║██║ ██║ ██╔══██╗██╔════╝ ██╔════╝██╔══██╗██╔════╝
# ██║ ██║██║██║ ██║ ███████║██║ ███╗█████╗ ██████╔╝███████╗
# ╚██╗ ██╔╝██║██║ ██║ ██╔══██║██║ ██║██╔══╝ ██╔══██╗╚════██║
# ╚████╔╝ ██║███████╗███████╗██║ ██║╚██████╔╝███████╗██║ ██║███████║
# ╚═══╝ ╚═╝╚══════╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝╚══════╝
#
# ██████╗ ██╗ ██╗ ██╗ ██╗ ██████╗ ██╗ ███████╗
# ██╔══██╗ ╚██╗ ██╔╝ ╚██╗██╔╝██╔═████╗██║ ╚══███╔╝
# ██████╔╝ ╚████╔╝ ╚███╔╝ ██║██╔██║ ██║ ███╔╝
# ██╔══██╗ ╚██╔╝ ██╔██╗ ████╔╝██ ██║ ███╔╝
# ██████╔╝ ██║ ██╔╝ ██╗╚██████╔╝ ███████╗ ███████╗ ████████╗
# ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ╚══════╝ ╚═══════╝
#
# Custom Villagers By x0lz_
#
# Contact if ANY issues
# Discord: Biblecampv1ctim
# =========================================================================================
# --- Interaction Settings ---
# How custom villagers are picked up by players
# SHIFT_ATTACK: Sneak and hit with a weapon (Default)
# KILL: Kill the villager with a weapon (relies on vanilla damage, will fail if protected by other plugins)
pickup-method: "SHIFT_ATTACK"
# Behavior of one-time trades after purchase
# REMOVE: Completely removed from the trade list (Enable this if you choose to keep infinite restock enabled)
# MAXED: Stays in the GUI but shows as out of stock (red X). Infinite Restock overrides must be OFF for this to work correctly.
one-time-trade-behavior: "MAXED"
# --- Default Custom Trades ---
# Generated automatically when a fresh Villager Soul is placed.
default-trades:
enabled: true
# Currency used for default trades: "ESSENCE" (Villager Essence) or "EMERALD" (Vanilla Emerald)
global-currency: "ESSENCE"
# Group 1 Trades: Potions. These always appear first but their internal order is randomized.
# The cost is always randomized between 2 and 5 of the chosen currency per villager.
potions:
fire-resistance:
enabled: true
# currency-override: "EMERALD" # Uncomment to override the global currency for this specific trade
speed:
enabled: true
tier: 1 # Options: 1 (Speed I) or 2 (Speed II)
strength:
enabled: true
tier: 1 # Options: 1 (Strength I) or 2 (Strength II)
# Group 2 Trades: Items. These appear after potions, and their internal order is also randomized.
items:
breeze-rod:
enabled: true
cost: 6 # Default cost
enchanted-gapple:
enabled: true
cost: 1
currency-override: "NETHERITE_INGOT" # Special currency for this item
cobwebs:
enabled: true
cost: 12
amount: 64 # How many cobwebs they get
gapple:
enabled: true
cost: 4
amount: 1
# --- Villager Settings ---
villager:
# Whether spawed custom villagers have AI (can move around).
enable_ai: true
# Whether custom villagers are invulnerable to all damage.
# Note: If pickup-method is KILL, this will be bypassed for player damage.
invulnerable: true
# Prevent storing Villager Souls in any form of container
# (Chests, Barrels, Shulkers, Bundles, Item Frames, Droppers, Hoppers, Dispensers, Chiseled Bookshelves, Decorated Pots)
prevent_storage: true
# --- Particle Settings ---
particles:
# The style of the aura around placed villagers.
# Options: "CLUMP" (Dense cloud), "ORBIT" (Standard swirling)
villager_aura_style: "CLUMP"
# The style of the aura around players holding a soul.
# Options: "SPARKLE" (Swirling aura rings), "ROAM" (Unpredictable wandering wisp)
holder_aura_style: "SPARKLE"
# Compass beam end-cap particles per dimension
dimensions:
NETHER: "FLAME"
THE_END: "DRAGON_BREATH"
OVERWORLD: "END_ROD"
# --- Broadcast Settings ---
# Speed of the /villagereventbc animated narrative.
# Lower delay = Faster typing/messages.
broadcast:
char_delay_ticks: 1
message_pause_ticks: 20
# --- Villager Essence Settings ---
villager-essence:
# Whether adult untraded villagers drop essence when killed by a player after the broadcast ends.
drop-enabled: true
# Amount of essence to drop (randomized between min and max)
min-drop: 1
max-drop: 5
