Cosmetics (In-Depth)

The Four Core Cosmetic Types

CosmeticsService defines four purely-visual cosmetic slots, each stored in its own column on your player_cosmetics row. You can have one of each active at once, and they are mutually independent — a Hat doesn't conflict with a Trail.

All four definitions live in cosmetics.yml and load on startup, so the catalog grows over time. Every cosmetic carries a display name, a particle/material, optional prestige and kill requirements, and a description.

How to Unlock Cosmetics

Cosmetics are unlocked through five paths. Once unlocked they're permanent — they persist across logins in the unlocked_cosmetics column of your cosmetics row.

The unlock call enforces prestige and kill requirements server-side: if you don't meet them, the unlock is refused with a clear error. Admin grants (unlockFree) bypass both requirements for staff-managed events and compensations.

Equipping and Unequipping

Equip via the /cosmetics menu or /cosmetics equip <id>. The service validates you own the cosmetic, applies the visual effect, and saves your active slot. Unequip with /cosmetics unequip <id> or by slot type — both clear the active column and tear down the visual (e.g. stopping a trail task or restoring a real helmet).

The No-Pay-To-Win Guard

Cosmetics are purely visual, and the plugin enforces it. On config load, every cosmetic is scanned for forbidden stat keys: income_bonus, damage_bonus, defense_bonus, sell_multiplier, xp_multiplier, token_bonus, crystal_bonus, and anything prefixed with stat_. If any are present, the plugin throws on startup and refuses to load that cosmetic — there is no way to ship a stat-bearing cosmetic by accident.

Donor tiers can still grant a higher active cosmetic quota (how many of the four slots you can fill at once), but the cosmetics themselves never affect gameplay.

The Pet System (Cosmetic-Adjacent)

Pets are managed by a separate PetService (open with /pet, not /cosmetics) and are the one cosmetic-adjacent system that does grant real bonuses. A pet spawns as a small marker entity that follows you, and its effect fires as you mine or passively over time. You can own many pets but only one is active at a time; XP goes only to the active pet.

Every active pet gains +1 XP per block mined, and each level multiplies the pet's effect by +25% (formula: 1.0 + (level − 1) × 0.25). The max level is 10. Here are the base effects for every pet in the catalog:

Pets come from crates, prestige rewards, the store, events, and achievements. A maxed mythic pet can more than double a specific income stream, so the pet you pick should match the way you play: Golden Goose for money, Thunder Bird for tokens, Automaton Drone for AFK, Phoenix for long sessions.

The Morph System

Morphs let you transform into one of six sacred Roman beasts. A morph summons a small invisible armor stand riding your player, wearing the morph's emblem as a helmet, and restyles your nameplate to the morph's Latin name. A themed coloured-dust particle trail follows you while the morph is active. Morphs are purely cosmetic — no gameplay effect.

Morphs are unlocked with Civitas. Running /morph <type> on an unowned morph will check your Civitas balance, charge the cost if you can afford it, unlock it, and activate it in one step. Unlocks persist in player_morphs; the active morph persists in player_active_morph and re-applies on login.

Use /morph off (or revert) to return to mortal form. The morph visual is cleaned up on quit and re-applied on your next login if it was active.

The Gadget System

Gadgets are fun cosmetic tools — items you hold and right-click to trigger a purely-visual effect. They live in your inventory (not in a slot) and each carries its gadget id in a PDC tag. Every gadget has its own cooldown to prevent spam. Gadgets never deal damage, never teleport you against your will (except the self-targeted Orb of Mercury), and never affect gameplay — they're toys.

Trail Performance and Low-End Mode

Trail particles spawn every 4 ticks at your location, but only for viewers within a 64-block radius (distance² < 4096). The OptimisationService is consulted per-viewer: players flagged as low-end devices see only 1 particle per tick instead of 3, halving the render cost. If you're on a low-FPS client, enable low-end mode in your settings to soften the trail load.

Persistence and Reload

Your unlocked cosmetics, active trail, active hat, active kill effect, and active mine effect all persist in a single player_cosmetics row keyed by UUID. The row is loaded async on join and saved async on every equip/unequip (a snapshot copy is saved to avoid concurrent mutation). On quit, your in-memory cache is flushed to disk.

Admins can hot-reload the catalog with /ImperiumMC reload — definitions refresh from cosmetics.yml, but per-player DB state (unlocked and active cosmetics) is untouched. A player with a now-removed cosmetic active keeps it until they re-equip.

Command Reference

PlaceholderAPI hooks include %imperiummc_cosmetic_trail%, %imperiummc_cosmetic_hat%, %imperiummc_cosmetic_killeffect%, and %imperiummc_cosmetic_mineeffect% for each active slot.

Tips

1. Match your Trail to your Mine Effect. Two clashing particle effects look noisy — pick a palette and stick to it.
2. Hats don't destroy helmets. Equip freely; your real helmet is backed up and returned on unequip.
3. Save your Civitas for Leo. The Colosseum lion is the priciest morph but the flex is unmatched.
4. Use gadgets for dailies. A party popper per day keeps the USE_GADGETS quest ticking.
5. One pet at a time. Swap pets and you stall XP gains — pick one and commit to maxing it.
6. Donor tiers raise your active quota. Want a Hat AND a Kill Effect AND a Trail AND a Mine Effect? Check your donor tier's cosmetic quota.
7. Low-end client? Turn off trails in your optimisation settings — the particle count drops to a third.
8. Re-equip after a reload. If staff remove a cosmetic you had active, re-equipping a different one clears the stale slot.