> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/edcosmetics/cosmetics/unlocking.md).

# Unlocking, Vouchers & Limited Editions

## Unlocking

A cosmetic is unlocked by:

* its permission: `permission:` in the category file, by default `edcosmetics.cosmetic.<category>.<cosmetic>` (the prefix is `config.yml` → `permissions.cosmetic-prefix`);
* or `/cosmetics give <player> <category> <cosmetic>` (works for offline players): what crates, shops and votes should run. `/cosmetics giveall <player> [category]` gives everything (or a whole category), `/cosmetics take ...` takes one away.

Equipped cosmetics are re-checked on join and every `permission-recheck-seconds` (default 30, `0` = only on join): a cosmetic the player lost access to is taken off.

Example crate reward command: `cosmetics give {player} wings demon-wings`.

## Vouchers

Shift-clicking a cosmetic in its category menu (or right-clicking it twice in the wardrobe) turns it into a voucher item: the cosmetic is taken away (and off) and the item can be traded, sold or stored. Right-clicking the voucher unlocks the cosmetic for whoever uses it; if they already have it nothing happens and the item is kept.

* Only cosmetics given with `/cosmetics give` can be withdrawn. One the player has the permission for (ranks) can't: they would keep it and get a voucher too.
* Needs one free inventory slot. Withdrawals and redeems are logged in the console.

```yaml
vouchers:
  enabled: true
  blocked: []            # a category id ('hats') or one cosmetic ('tags:owner')
  item:
    material: PAPER      # or itemsadder:ns:id, oraxen:id, nexo:id
    custom-model-data: 0
    item-model: ''
    tooltip-style: ''
    glow: true
    name: '{name} &7Voucher'
    lore: ['&7Category: {category}', '&r', '{description}', '&r', '&eRight-click to unlock it.', '&8Can be traded.']
```

The menu token `{withdrawable}` is `true` when a shift-click would withdraw the cosmetic, e.g. `'[if {withdrawable} = true] &6Shift-click to withdraw as a voucher'` in an entry's lore.

## Limited editions

A cosmetic with `limited:` shows who owns it in its menu entry, oldest first (Holder #1, #2...). Only players it was given to count (`/cosmetics give`, vouchers), never a permission, and a withdrawn voucher frees the place.

```yaml
    limited: 5                                # at most 5 owners: the menu shows 5 places and AVAILABLE / SOLD OUT
    limited: true                             # no cap: the menu lists whoever owns it
    limited: { max: 5, color: '&#F9696D' }    # with its own accent ({color})
```

The cap is only shown: hand a limited cosmetic out through something that enforces it (e.g. a crate reward with a maximum number of winners). `config.yml` → `limited` holds every text: `lore` (with a cap) and `lore-no-max`, with `{only}` `{holders}` `{status}` `{max}` `{count}` `{left}` `{color}`; `only-one` / `only-many`, `holder-line` (`{position}` `{player}` `{color}`), `empty-name`, `none-line`, `max-listed` / `more-line`, `status-available` / `status-sold-out` and the default `color`. Menus show it with `'[if {limited} = true] {limited-lore}'`.