What is ZenaviaCosmetics?

A 100% config-driven cosmetic system with 6 cosmetic types, GUI menus, database persistence, and packet-based visuals. Server owners define every cosmetic in a simple YAML file - no code changes needed. Players manage their own resource pack.

Add unlimited hats, backpacks, particles, mascots, titles, and kill effects - all from config.


Features

• 6 Cosmetic Types - Hats, Backpacks, Particles, Mascots, Titles, Kill Effects
• 100% Config-Driven - Define all cosmetics in cosmetics.yml, no code needed
• CustomModelData Support - Works with any resource pack
• PacketEvents Visuals - Backpacks and mascots use fake ArmorStands (no real entities)
• TextDisplay Titles - Floating text above the player's head via packet entities
• 4 Particle Patterns - RING, SPIRAL, ORBIT, CLOUD with configurable speed and radius
• 2 Mascot Modes - CMD mode (custom model item) or ARMOR mode (baby armorstand with full gear + custom head)
• Kill Effects - Particles at victim's death location with configurable duration
• GUI Menu - Category-based menu with pagination, rarity colors, and equip status
• SQLite + MySQL - Persistent storage with HikariCP connection pooling
• Dual Unlock System - Permission-based OR command-based (or both)
• 5 Rarity Tiers - COMMON, RARE, EPIC, LEGENDARY, MYTHIC with configurable colors
• Multi-Language - EN and FR built-in, fully editable, runtime switchable
• PlaceholderAPI - Expose equipped cosmetics, counts, and title text
• Tab Completion - Full autocomplete on all commands
• Lightweight - No NMS, pure Spigot API + PacketEvents, works on 1.20+

Cosmetic Types

• HAT - Item with CustomModelData placed in the helmet slot
• BACKPACK - Invisible ArmorStand mounted as passenger on the player (PacketEvents)
• PARTICLE - Particles around the player (4 patterns: RING, SPIRAL, ORBIT, CLOUD)
• MASCOT - Small companion following the player's shoulder (2 modes: CMD item or full armor + custom head)
• TITLE - TextDisplay entity floating above the player's head
• KILL_EFFECT - Particles spawned at the victim's death location

Commands

Player (Permission: cosmetics.use, default: true)

• /cosmetics - Open the cosmetics GUI menu

Admin (Permission: cosmetics.admin, default: OP)

• /cosmetics give <player> <id> - Grant a cosmetic to a player
• /cosmetics remove <player> <id> - Revoke a cosmetic from a player
• /cosmetics reset <player> - Reset all cosmetics for a player
• /cosmetics reload - Reload config, cosmetics, and language files

How to Create Cosmetics

All cosmetics are defined in cosmetics.yml. Add unlimited cosmetics in any category:

Hat Example

• id: crown_gold
• type: HAT
• material: PAPER / custom_model_data: 1001
• rarity: LEGENDARY

Particle Example

• id: flame_ring
• type: PARTICLE
• particle_type: FLAME / pattern: RING
• count: 20 / radius: 1.0 / speed: 0.02

Mascot - CMD Mode

• id: pet_bee
• type: MASCOT
• material: PAPER / custom_model_data: 3001
• offset_x: 0.5 / offset_y: 0.3

Mascot - ARMOR Mode (baby armorstand with gear)

• id: mini_knight
• type: MASCOT / mascot_mode: ARMOR
• mascot_helmet: IRON_HELMET
• mascot_chestplate: IRON_CHESTPLATE
• mascot_leggings: IRON_LEGGINGS
• mascot_boots: IRON_BOOTS
• Can also use mascot_head_texture for custom skull URL

Title Example

• id: title_champion
• type: TITLE
• title_text: "&6&lChampion"
• Displayed as TextDisplay entity floating above the player's head

Kill Effect Example

• id: killeffect_flames
• type: KILL_EFFECT
• particle_type: FLAME / count: 30
• duration_ticks: 40

Unlock System

Cosmetics can be unlocked in two ways (or both):

• Permission-based - Each cosmetic has an optional permission node. Give it via ranks, crates, or any permission plugin.
• Command-based - Use /cosmetics give <player> <id> to unlock. Stored in database. Works with crate plugins, votifier, etc.

If a player has the permission OR the cosmetic in the database, they can equip it.


PlaceholderAPI

• %zcosmetics_equipped_hat% - Equipped hat name
• %zcosmetics_equipped_backpack% - Equipped backpack name
• %zcosmetics_equipped_particle% - Equipped particle name
• %zcosmetics_equipped_mascot% - Equipped mascot name
• %zcosmetics_equipped_title_text% - Title text
• %zcosmetics_equipped_kill_effect% - Equipped kill effect name
• %zcosmetics_count_unlocked% - Total unlocked cosmetics
• %zcosmetics_count_total% - Total available cosmetics

Dependencies

Required:

• PacketEvents 2.x - Required for backpacks, mascots, and titles

Optional:

• PlaceholderAPI - Placeholder expansion

Requirements:

• Spigot or Paper 1.20+
• Java 21+

Storage

• SQLite (default) - Single file, zero config, perfect for single servers
• MySQL - Full HikariCP connection pooling, ideal for networks

Quick Start

1. Install PacketEvents on your server
2. Drop ZenaviaCosmetics.jar into your plugins/ folder
3. Restart the server
4. Edit cosmetics.yml to add your own cosmetics (match your resource pack CustomModelData values)
5. Use /cosmetics give <player> <id> or set permissions to unlock cosmetics
6. Players open the menu with /cosmetics and equip from the GUI