CosmeticsCore
Trails, kill effects and real pet companions — all controlled with permissions, all configurable. No coding required.
A clean GUI menu, smooth performance, and a config file anyone can edit. Sell cosmetics as VIP perks, lock them behind ranks, and add your own with a few lines.
Features
- Particle Trails — Heart, Flame, Soul, Snow, Rainbow, plus animated shaped trails: Spiral, Halo, Helix
- Kill Effects — Lightning, Explosion, Blood, Soul, Firework, Totem, Heart (all damage-free, visual only)
- Real Pet Companions — Actual entities that follow the player: Bat, Cat, Parrot, Allay, Fox
- Permission-locked GUI — Locked cosmetics show as grayed out, perfect for VIP/rank rewards
- Fully configurable — Add or remove cosmetics straight from the config, no coding
- Lightweight — Trails only spawn when needed; built to avoid lag
- PlaceholderAPI support — Optional, for showing active cosmetics on scoreboards/tab
Requirements
- Server: Paper 1.21.x (Java 21)
- Dependencies: None required
- Optional: PlaceholderAPI (placeholders) · LuckPerms or any permissions plugin (rank-locking)
Installation
- Drop CosmeticsCore.jar into your server's plugins folder.
- Restart the server.
- Done. Type /cosmetics in-game to open the menu.
The config file is generated at plugins/CosmeticsCore/config.yml.
Commands
| Command | Description |
|---|---|
| /cosmetics | Opens the cosmetics menu |
| /cc | Short alias |
| /cosmetics reload | Reloads the config (requires cosmetics.admin) |
Permissions — locking cosmetics to ranks
Every cosmetic has its own permission in the format:
cosmetics.<type>.<id>
So the Spiral trail is cosmetics.trail.spiral, the Lightning kill effect is cosmetics.kill.lightning, the Cat pet is cosmetics.pet.cat, and so on.
If a player doesn't have the permission, the cosmetic shows up locked (grayed out) in the menu — they can see it exists but can't use it. This is what makes it perfect as a VIP reward.
Examples with LuckPerms
Give one cosmetic to a player:
/lp user Steve permission set cosmetics.trail.spiral true
Give a whole category to a rank (e.g. all trails to VIP):
/lp group vip permission set cosmetics.trail.* true
Give every cosmetic to a rank:
/lp group vip permission set cosmetics.trail.* true
/lp group vip permission set cosmetics.kill.* true
/lp group vip permission set cosmetics.pet.* true
Remove a permission:
/lp user Steve permission unset cosmetics.trail.spiral
Permission reference
| Permission | What it unlocks |
|---|---|
| cosmetics.use | Opening the menu (on by default) |
| cosmetics.trail.<id> | A specific trail |
| cosmetics.kill.<id> | A specific kill effect |
| cosmetics.pet.<id> | A specific pet |
| cosmetics.trail.* | All trails |
| cosmetics.kill.* | All kill effects |
| cosmetics.pet.* | All pets |
| cosmetics.admin | Reload command |
Adding your own cosmetics (config)
Everything is defined in config.yml. You don't touch any code — just add a block, then run /cosmetics reload. The permission is created automatically from the id.
Add a new trail
Find the trails: section and add a block. The particle value is any Minecraft particle name:
water:
name: '&3Water Trail'
icon: WATER_BUCKET
particle: DRIPPING_WATER
count: 3
offset: 0.2
speed: 0.0
That's it — this creates the cosmetics.trail.water permission automatically and the trail appears in the menu.
Add a shaped (animated) trail
Use shape: SPIRAL, CIRCLE, or HELIX:
myspiral:
name: '&dMy Spiral'
icon: END_ROD
particle: END_ROD
shape: SPIRAL
radius: 0.7 # how wide the pattern is
height-step: 0.1 # how fast it rises
max-height: 2.0 # how tall before it loops
Add a new kill effect
Find the kills: section. The effect value is one of: LIGHTNING, EXPLOSION, BLOOD, SOUL, FIREWORK, TOTEM, HEART
mykill:
name: '&cMy Effect'
icon: TNT
effect: EXPLOSION
Add a new pet
Find the pets: section. The entity value is any Minecraft entity type:
wolf:
name: '&7Wolf'
icon: WOLF_SPAWN_EGG
entity: WOLF
baby: false
Performance settings
At the top of the config:
settings:
trail-interval: 4 # how often trails spawn (lower = smoother, heavier)
pet-interval: 2 # how often pets update position
save-interval-minutes: 5 # how often player data is saved
Leave these as-is for a good balance. Increase trail-interval if you ever need it even lighter.
PlaceholderAPI (optional)
If PlaceholderAPI is installed, these placeholders become available:
| Placeholder | Shows |
|---|---|
| %cosmetics_trail% | Player's active trail |
| %cosmetics_kill% | Player's active kill effect |
| %cosmetics_pet% | Player's active pet |
Use them in scoreboards, tab lists, or chat. Returns None if nothing is selected.
Support
Found a bug or have a question? Open a ticket and I'll get back to you. Feature suggestions are welcome and considered for future updates.
