Cosmetics

Cosmetics live in cosmetics.yml and use config-version: 3.

AtlasLobby supports three cosmetic types:

Particles.
Hats.
Gadgets.

Cosmetics are organized into categories, tagged with rarities, and shown through an auto-generated cosmetics menu. A player can equip one cosmetic per slot at the same time: one particle, one hat, and one gadget.

File Structure

config-version: 3
enabled: true
gadget-slot: 3            # hotbar slot (0-8) the equipped gadget item occupies
# ... global particle settings ...

rarities:   # tier colour, glow, and sort order
categories: # the tabs shown in the cosmetics menu
status:     # the "click to..." hint line, per state
cosmetics:  # the cosmetics themselves

Global Settings

enabled: true
update-interval-ticks: 4
max-particles-per-player-update: 24
max-preview-particles: 32
disable-while-sneaking: true
disable-while-flying: false
gadget-slot: 3
worlds: []
disabled-worlds: []
select-sound:
  enabled: true
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  volume: 1
  pitch: 1.4

Setting	Meaning
`enabled`	Turns the cosmetics system on or off.
`update-interval-ticks`	How often particle cosmetics update.
`max-particles-per-player-update`	Global particle budget per player update.
`max-preview-particles`	Particle budget for previews.
`disable-while-sneaking`	Stops rendering while sneaking.
`disable-while-flying`	Stops rendering while flying.
`gadget-slot`	Hotbar slot, `0-8`, used by equipped gadgets.
`worlds` / `disabled-worlds`	Optional world filters.
`select-sound`	Sound played when a cosmetic is selected.

Rarities

Rarities define the tier label, whether items glow, and the tier sort order.

rarities:
  common:    { display: "&fCommon",    glow: false, order: 1 }
  rare:      { display: "&bRare",      glow: true,  order: 3 }
  mythic:    { display: "<gradient:#ff5eae:#ffd45c>Mythic</gradient>", glow: true, order: 6 }

Field	Purpose
`display`	Colored label used by `%rarity_display%`.
`glow`	When true, `available` and `selected` cosmetics of this rarity show an enchant glint in the menu.
`order`	Rarity sort reference. Cosmetic menu order still comes from each cosmetic’s `order` field, or file order when omitted.

Status Lines

The status map creates the %cosmetic_status% placeholder shown at the bottom of each cosmetic’s lore.

It supports one entry per state:

available
selected
purchasable
locked
disabled
default

status:
  available:   "&e▶ &7Click to equip &8• &7Shift-Right to preview"
  selected:    "&a✔ Equipped &8• &7Click to unequip"
  purchasable: "&6✦ Click to purchase for %cosmetic_cost%"
  locked:      "&c✖ Locked"
  disabled:    "&8Unavailable"

Cosmetic Definition

Each cosmetic is defined under cosmetics.

cosmetics:
  atlas-ring:
    type: particle          # particle | hat | gadget
    category: particles
    rarity: uncommon
    cost: 0                  # coin price (0 = free / permission only)
    permission: "atlaslobby.cosmetic.atlas-ring"
    # Particle tuning lives at the top level.
    particle: END_ROD
    animation: ring
    radius: 1.25
    speed: 0.2
    max-particles: 14
    # The menu item. For hats/gadgets, this is also the worn/held item.
    icon:
      material: ENDER_EYE
      name: "&bAtlas Ring"
      lore:
        - "&7A crisp orbit at your feet."
        - ""
        - "&8Rarity &7%rarity_display%"
        - "&8Price &7%cosmetic_cost%"
        - ""
        - "%cosmetic_status%"

Field	Purpose
`type`	`particle`, `hat`, or `gadget`. Defaults to `particle`.
`category`	Which tab it appears under. Defaults by type.
`rarity`	One of the configured `rarities` keys.
`cost`	Coin price. `0` means free, or permission-gated only.
`price`	Legacy Vault price fallback. Used only when `cost` is `0`.
`order`	Sort position inside the category.
`permission`	Permission required to equip. Defaults to `atlaslobby.cosmetic.<id>`.
`icon`	The item shown in the menu. For hats and gadgets, this is also the worn or held item.

Inside icon.name and icon.lore, you can use:

Placeholder	Meaning
`%cosmetic_name%`	Cosmetic display name.
`%rarity_display%`	Rarity display text.
`%cosmetic_cost%`	Formatted cosmetic cost.
`%cosmetic_status%`	Status line for the current player.
`%cosmetic_state%`	Current cosmetic state.
`%cosmetic_type%`	Cosmetic type.

Particle Cosmetics

Particles are rendered around the player on a regular update loop. Particle tuning fields live at the cosmetic’s top level.

Supported animations:

aura, ring, spiral, double_helix, orbit, trail, burst, steps, crown, pulse, sphere, glyph, comet, vortex, galaxy, wings, tornado, infinity, fountain, atom, nova, hurricane, heartbeat, star, beam, shield.

Option	Purpose
`particle`	Minecraft particle name.
`animation`	Animation type. Use one of the supported animations above.
`color`	Dust particle color as `#rrggbb`.
`rainbow`	Enables animated rainbow dust.
`size`	Dust particle size.
`radius` / `height` / `speed`	Animation shape and speed.
`bob` / `pulse-size` / `spread`	Per-animation tuning.
`count-per-point` / `max-particles`	Particle budget.
`worlds` / `disabled-worlds`	Optional world filtering.
`disable-while-sneaking` / `disable-while-flying`	Render conditions.

Hat Cosmetics

type: hat equips the cosmetic’s icon item into the player’s helmet slot.

The inventory sanitizer understands cosmetic hats, so it does not strip them. Hats are also re-applied on join and world change.

your-head:
  type: hat
  category: hats
  rarity: epic
  cost: 750
  icon:
    material: PLAYER_HEAD
    head-owner: "%player%"   # or head-texture / head-url
    name: "&dYour Head"
    lore: ["&7Wear your own face.", "", "%cosmetic_status%"]

Head icons support:

head-owner, including player names and %player%.
head-url.
head-texture, as a base64 value.

Gadget Cosmetics

type: gadget gives the player a tagged, right-clickable item in gadget-slot.

Right-clicking a gadget can trigger:

A particle burst, if the cosmetic has particle fields.
A list of actions.
A cooldown-seconds delay before it can be used again.

firework-blast:
  type: gadget
  category: gadgets
  rarity: rare
  cost: 600
  cooldown-seconds: 3
  particle: FIREWORK
  animation: burst
  max-particles: 24
  actions:
    - "sound: ENTITY_FIREWORK_ROCKET_BLAST"
  icon:
    material: FIREWORK_ROCKET
    name: "&eFirework Blast"
    lore: ["&7Right-click for a burst of sparks.", "", "%cosmetic_status%"]

Unlocking and Coins

If cost is greater than 0 and the player does not already own the cosmetic, equipping it purchases it with coins.

AtlasLobby stores:

Owned cosmetics in data/players.yml under unlocked-cosmetics.
Equipped cosmetics per slot under equipped.

If cost is 0 but a legacy price is set, AtlasLobby falls back to Vault for that cosmetic.

The cosmetics menu in menus.yml is dynamic. It declares a content provider instead of listing cosmetics by hand.

See Menus and Actions for the menu layout, tabs, and pagination actions.

Performance and Validation

AtlasLobby renders equipped particles through one shared update system.

It skips:

Players with no equipped particle.
Players outside allowed worlds.
Players without permission.
Players who disabled particles.

Global particle budgets cap both configured points and count-per-point. Invalid particles, materials, or head textures are warned once and skipped instead of stopping cosmetic rendering.