config.yml

Global settings. After editing, run /cosmeticsadmin reload. Changing Settings.Database or the MySQL section needs a full restart.

Keep every section

config.yml is created once and not merged with new defaults. A missing single setting falls back to the default listed below, but Settings, Categories, Sort-Types, Sort-Types-Market, Rarity-Colors, Lore-Addons, Market-Listing-Lore, Filter-Item, Sort-Item and Sort-Item-Market must exist, or the plugin fails to load.

Settings

Settings:
  Save-Interval: 60
  Show-Locked: true
  Database: "SQLite"
  Economy: "Vault"
  Placeholder-Format: "Legacy"
  Paint-Chat-Message: true
  Rank-Placeholder: "%luckperms_prefix%"

Key	Shipped value	If missing	Description
Save-Interval	60	60	Seconds between flushes of unsaved player profiles. Equips are saved straight away regardless. 0 turns the timer off.
Show-Locked	true	true	Show cosmetics the player does not own (with the Locked lore). false shows owned cosmetics only.
Database	SQLite	SQLite	SQLite (data/data.db) or MySQL (the MySQL section).
Economy	Vault	Vault	The market currency: Vault, PlayerPoints, RivalCredits or None. An unknown name fails the load.
Placeholder-Format	Legacy	MiniMessage	Output of the PlaceholderAPI placeholders: MiniMessage or Legacy (§ codes). Match it to your chat or nametag plugin.
Paint-Chat-Message	true	false	Repaint the player’s chat message with their equipped chat color directly, without a chat plugin. The message’s own formatting is stripped first. Skipped while the player is answering a market prompt.
Rank-Placeholder	%luckperms_prefix%	""	The PlaceholderAPI placeholder that holds the player’s rank, repainted by Rank Color cosmetics in %optimalcosmetics_rankcolor%. Blank turns that placeholder off.

Chat plugins and Paint-Chat-Message

If your chat plugin already uses %optimalcosmetics_chatcolor% around the message, set Paint-Chat-Message: false so the message is not painted twice.

Currency-Formats

How amounts are printed for each economy provider ({price}, {fee} and so on). The key is the provider name, the same as in Settings.Economy and a case’s Currency.

Currency-Formats:
  Vault:
    Format: "&a{amount} &2Money"
    Amount-Format: "comma"
  PlayerPoints:
    Format: "&e{amount} &6Points"
    Amount-Format: "abbreviated"
  RivalCredits:
    Format: "&c{amount} &4Credits"
    Amount-Format: "plain"

Key	Default	Description
Format	{amount}	The text, with {amount} where the number goes.
Amount-Format	comma	plain (1500), comma (1,500) or abbreviated (1.5k, units k, M, B, T, Q with one decimal). Plain and comma show up to two decimals when the amount has them. An unknown value is treated as comma.

A provider with no entry prints the bare number with commas.

MySQL

Used only when Settings.Database is MySQL. Point every server at the same database to share ownership, equips, listings and case winners across the network.

MySQL:
  Host: "localhost"
  Port: 3306
  Database: "optimalcosmetics"
  Username: "root"
  Password: ""

Key	Default	Description
Host	localhost	Database host.
Port	3306	Database port.
Database	optimalcosmetics	Schema name. It must already exist; the tables are created on startup.
Username	root	Login user.
Password	""	Login password.

The connection is opened with SSL off.

Market

Market:
  Listing-Fee: 0
  Sale-Tax: 0.0
  Min-Price: 1
  Max-Price: 1000000
  Max-Listings: 10
  Expiry-Days: 7
  Confirm-Purchase: true

Key	Shipped value	If missing	Description
Listing-Fee	0	0	Charged to the seller when a listing is created. Not refunded on removal or expiry. 0 is free.
Sale-Tax	0.0	0	Percent taken from the seller’s payout. 5.0 pays the seller 95% of the price.
Min-Price	1	1	Lowest allowed price. 0 removes the minimum.
Max-Price	1000000	0	Highest allowed price. 0 removes the maximum.
Max-Listings	10	0	Active listings per player. 0 is unlimited. Overridden per player with /cosmeticsadmin maxlistings.
Expiry-Days	7	0	Days before a listing is returned to its seller. 0 never expires.
Confirm-Purchase	true	true	Open guis/market-confirm.yml before buying. false buys on the click.

Prices are whole numbers. The whole section is optional; without it every value above uses its “If missing” default. More on how these play out: The Market.

Voucher

The global voucher template, used for every cosmetic that has no Voucher block of its own. Remove the section to allow vouchers only for cosmetics with their own block; without either, givevoucher reports VOUCHER-NOT-CONFIGURED and a duplicate case win is refunded.

Voucher:
  Material: PAPER
  Name: "&f{cosmetic}"
  Lore:
    - "&8Cosmetic [{count} exist]"
    - ""
    - "&7You can claim this cosmetic voucher"
    - "&7and equip this cosmetic in &f/cosmetics&7."
    - ""
    - "{primary}Information:"
    - "{secondary} - &7Type: &f{type}"
    - "{secondary} - &7Created: &f{date}"
    - ""
    - "&e➥ Click to redeem!"
  Item-Flags: [HIDE_ATTRIBUTES]

It is a standard item. Tokens:

Token	Value
{cosmetic}	The cosmetic’s Name.
{type}	The type label from Cosmetic-Format.Type-Labels.
{rarity}	The cosmetic’s rarity.
{count}	Enabled cosmetics of that type.
{date}	The date the voucher was made, MM/dd/yyyy.
{primary}, {secondary}	The rarity’s colors.

Categories

The two fixed filter entries. The filter then continues with every enabled type’s Name from Types.

Categories:
  All: "All"
  Owned: "Owned Cosmetics"

Key	Default	Description
All	All	Every enabled type.
Owned	Owned Cosmetics	Only what the viewer owns (in the market: listings of cosmetics the viewer owns).

Types

Turn whole types on or off and name their filter entry.

Types:
  Chat-Colors:
    Enabled: true
    Name: "Chat Colors"
  Tags:
    Enabled: true
    Name: "Tags"
  Name-Paints:
    Enabled: true
    Name: "Name Paints"
  Rank-Colors:
    Enabled: true
    Name: "Rank Colors"
  Glow:
    Enabled: true
    Name: "Glow"
  Tab-Icon:
    Enabled: true
    Name: "Tab Icon"
  Join-Message:
    Enabled: true
    Name: "Join Message"
  Leave-Message:
    Enabled: true
    Name: "Leave Message"

Key	Default	Description
Enabled	true	false hides the type from the cosmetics menu, the market and the filter.
Name	as shipped	The filter label for that type, shown as {category}.

A missing type entry counts as enabled with its shipped name. The singular label used in lore and messages ({type}, {cosmetic-type}) is set separately in messages.yml → Cosmetic-Format.

Sort-Types and Sort-Types-Market

The sort modes of the cosmetics menu and of the market. The key picks the behavior, the value is the name shown in the menu. Reorder or remove entries to change the cycle; at least one must stay.

Sort-Types:
  Item: "Item"
  Rarity: "Rarity"
  Alphabetical: "Alphabetical"

Sort-Types-Market:
  Recent: "Recent"
  Price-Low: "Price Low to High"
  Price-High: "Price High to Low"
  Alphabetical: "Alphabetical"

Menu	Key	Order
Cosmetics	Item	File order.
Cosmetics	Rarity	By Rarity-Colors order, highest first.
Cosmetics	Alphabetical	By cosmetic id.
Market	Recent	Newest listing first.
Market	Price-Low	Cheapest first.
Market	Price-High	Most expensive first.
Market	Alphabetical	By cosmetic id.

An unknown key keeps file order (cosmetics) or newest first (market).

Rarity-Colors

Every rarity, fully dynamic. The order is the rank: the first entry is the highest and sorts first. Add, rename or remove entries freely, then use the names in each cosmetic’s Rarity.

Rarity-Colors:
  Exotic:
    Primary: "<#fa2590>"
    Secondary: "<#9c1357>"
  Legendary:
    Primary: "&e"
    Secondary: "&6"
  Epic:
    Primary: "&d"
    Secondary: "&5"
  Rare:
    Primary: "&b"
    Secondary: "&3"
  Common:
    Primary: "&a"
    Secondary: "&2"

Key	Default	Description
Primary	<gray>	Fills {primary}.
Secondary	<dark_gray>	Fills {secondary}.

Rarity names match case-insensitively. A cosmetic whose rarity is not listed gets <gray> / <dark_gray> and sorts last.

Lore-Addons

The lore added under every cosmetic icon in the cosmetics menu and the equip menu, depending on its state. The cosmetic’s own Lore comes first.

Key	Shown when
Equipped	The viewer owns it and has it equipped.
Unequipped	The viewer owns it but it is not equipped.
Locked	The viewer does not own it.

Lore-Addons:
  Equipped:
    - "&7This cosmetic is currently equipped."
    - ""
    - "{primary}Information:"
    - "{secondary} - &7Type: &f{type}"
    - "{secondary} - &7Rarity: &f{rarity}"
    - "{secondary} - &7Exists: &f{count}"
    - ""
    - "&e➥ Click to unequip!"

Tokens: {primary}, {secondary}, {type}, {rarity}, {count} (enabled cosmetics of that type).

Market-Listing-Lore

The lore of a listing in the market, depending on who is looking. The icon’s name is the cosmetic’s Name. The Buyable lore is also used on the preview in the purchase confirm menu.

Key	Shown when
Own-Listing	The viewer is the seller. Clicking removes the listing.
Already-Owned	The viewer already owns that cosmetic.
Buyable	Anyone else.

Market-Listing-Lore:
  Buyable:
    - "&6&m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    - "&8Cosmetic Market"
    - ""
    - "&eInformation:"
    - "&6 - &7Seller: &f{seller}"
    - "&6 - &7Price: &f{price}"
    - "&6 - &7Type: &f{type}"
    - "&6 - &7Expires in: &c{expires}"
    - ""
    - "&e➥ Click to buy!"

Tokens: {seller}, {price} (formatted with the market’s currency format), {type}, {rarity}, {count}, {expires} (time left, or the Cosmetic-Format.Never label when listings never expire), {primary}, {secondary}.

Filter-Item, Sort-Item and Sort-Item-Market

How each option is printed inside the filter and sort buttons, where the button’s lore has {print-categories}, {print-sort-types} or {print-sort-types-market}. One line is printed per option.

Filter-Item:
  Selected: "&3 - &3> &f{category} &3<"
  Unselected: "&3 - &7{category}"

Sort-Item:
  Selected: "&5 - &5> &f{sort} &5<"
  Unselected: "&5 - &7{sort}"

Sort-Item-Market:
  Selected: "&5 - &5> &f{sort-market} &5<"
  Unselected: "&5 - &7{sort-market}"

Section	Used by	Token
Filter-Item	Filter buttons in both menus	{category}
Sort-Item	Sort button in the cosmetics menu	{sort}
Sort-Item-Market	Sort button in the market	{sort-market}

Inventories-Sounds

Named sounds in "NAME;volume;pitch" form (volume and pitch optional). Names are XSound names, which stay stable across Minecraft versions. Set a key to "" to silence it.

Inventories-Sounds:
  "MENU-OPEN": "ENTITY_BAT_TAKEOFF;1;0.5"
  "MARKET-OPEN": "ENTITY_BAT_TAKEOFF;1;0.5"
  "PAGE-CHANGED": "ENTITY_CHICKEN_EGG;1;1"
  "NO-PAGE-FOUND": "BLOCK_NOTE_BLOCK_PLING;1;0.5"
  "FILTER-CYCLE": "ENTITY_CHICKEN_EGG;1;1"
  "SORT-CYCLE": "ENTITY_CHICKEN_EGG;1;1"
  "EQUIP": "ENTITY_PLAYER_LEVELUP;1;1.5"
  "UNEQUIP": "BLOCK_NOTE_BLOCK_BASS;1;1"
  "DENY": "ENTITY_VILLAGER_NO;1;0.5"

Key	Played when
MENU-OPEN	The cosmetics menu, equip menu, a confirm menu or a case menu opens.
MARKET-OPEN	The market opens.
PAGE-CHANGED	A page turn succeeds.
NO-PAGE-FOUND	A page turn is blocked (first or last page).
FILTER-CYCLE	The filter changes.
SORT-CYCLE	The sort changes.
EQUIP	A cosmetic is equipped, listed, bought, won from a case or redeemed from a voucher.
UNEQUIP	A cosmetic is unequipped or a listing is removed.
DENY	Any refused click or action.