Set up UltraCosmetics on Minecraft

UltraCosmetics gives players a menu of cosmetics: gadgets, pets, mounts, hats, suits, emotes, particle effects and morphs. It is a free, open source plugin that runs on Paper and Purpur, and it installs from the Plugins tab.

Checked against UltraCosmetics 3.16-RELEASE, which lists Minecraft 1.21.11 and 26.2 on its Modrinth page, October 2026. Modrinth also carries a 3.17-DEV-b1 beta.

What you need

• A Paper or Purpur server on Minecraft 1.17.1 or newer, except 1.19.0. The plugin's wiki says any Spigot-based software should run it, and recommends Paper.
• Optional, but useful:
  • A permissions plugin. The wiki highly recommends one.
  • Vault with an economy plugin, or Treasury, PEconomy, PlayerPoints or ExcellentEconomy, for treasure chest keys, gadget ammo and money loot.
  • Libs Disguises, and ProtocolLib with it, if you want morphs.

Install it

1. Open the Plugins tab and pick the Modrinth button.
2. Search for UltraCosmetics and click Install.
3. Restart from the Console tab, then type plugins there to confirm UltraCosmetics is listed.

First settings

On its first start the plugin writes plugins/UltraCosmetics/config.yml. Stop the server, open the file in the File Manager, and check these keys:

• Menu-Item.Enabled is false by default. Set it to true to hand every player an ender chest item that opens the menu.
• Enabled-Worlds lists the worlds where cosmetics work. The default is *, which means all of them.
• Economy is 'Vault' by default. It also accepts 'PlayerPoints', 'Treasury', 'PEconomy' and 'ExcellentEconomy'.

Save and start the server again.

Open the menu and test it

In game, players open the menu with /uc menu main, or with the ender chest if you turned it on. The command is allowed for everyone by default.

To test treasure chests, use an account without operator rights. Operators and anyone holding ultracosmetics.allcosmetics can already use every cosmetic, so a chest only pays them money.

In the Console you can run these:

• uc give key <amount> <player> gives treasure keys.
• uc clear <player> removes a player's active cosmetics.
• uc reload reloads the settings and messages.
• uc troubleshoot runs the plugin's own check for common issues.

Common problems

• Nothing happens on the tripwire hook button. Buying keys needs an economy. Install Vault and an economy plugin, or PlayerPoints, and check Economy in config.yml.
• "Not enough room" when opening a chest. Chests need open space around the player, so move to a clear area.
• A cosmetic from a chest says "no permission". Set TreasureChests.Permission-Add-Command in config.yml to a command that grants permissions in your permissions plugin, then watch the Console for errors from that command.
• "Gadgets not enabled". The player turned gadgets off for themselves. They run /uc gadgets to switch them back on.
• Particle effects do not show. The player's client may be set to minimal particles. Setting Particles to All in the video settings fixes it.
• Config error on start. An unclosed quote is the usual cause. Read the Console log and correct the config file it reports.

For other ways to install plugins, see Install Minecraft plugins on Paper or Purpur. The plugin's own wiki is at github.com/UltraCosmetics/UltraCosmetics/wiki.