> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xplayercurrencies/configuration/default-configuration-files/default-currency-coins.md). # Default currency: coins.yml The exact `currencies/coins.yml` shipped with the plugin - a fully-featured example currency with shop, bank, sell sticks, kill coins, boosters and black market all enabled, so a fresh install already has something to test. See [Currency Basics](/home/xplayercurrencies/configuration/currency-basics.md) and each feature page under [Features](/home/xplayercurrencies/features/bank.md) for what every section does. ```yaml # ============================================================ # XPlayerCurrencies # Currency definition - "coins" # ============================================================ # The filename (without ".yml"), "coins", IS this currency's internal id - used in commands # (e.g. "/currencies give coins Steve 100") and in PlaceholderAPI placeholders (e.g. # %xplayercurrencies_coins_balance%). Keep ids lowercase with no spaces (use "_" instead). # # To create another currency, duplicate this file under a new name (e.g. "gems.yml") and # adjust the values below - there is no limit on how many currency files you can have. # Master toggle. A disabled currency is completely ignored: its commands reply as if it didn't # exist and its placeholders return an empty string, but any balance already stored for it is # kept on disk untouched (re-enable it later and the data is still there). enabled: true # Display name shown in messages and placeholders. name-display: "Coin" name-display-plural: "Coins" # Shown next to the currency name wherever you reference {icon} in a message (an emoji, a # color tag, whatever fits your server - purely cosmetic, not tied to any in-game item). icon-display: "🪙" # Symbol glued to a formatted balance, e.g. "1,000 Coins" (symbol-position: AFTER) or # "$1,000" (symbol-position: BEFORE). symbol: "Coins" symbol-position: AFTER # Number of decimal places kept for this currency's balances (0 for a whole-number currency # like coins, 2 for something meant to feel like real money). decimals: 0 # Adds a "," every 3 digits when formatting a balance (1000 -> "1,000"). Purely cosmetic. thousands-separator: true # Balance a player starts with the first time they're seen with this currency. default-balance: 2500 # Balance boundaries enforced on every give/take/set (including through the PAPI placeholders # and any future API/other plugin hooking in). max-balance: -1 means unlimited. min-balance: 0 max-balance: -1 # Where this currency shows up relative to the others (lower first) in "/currencies list" and # a player's own "/currencies" balance overview. Purely cosmetic; currencies sharing the same # priority fall back to alphabetical order. priority: 0 # Vanilla Material used as this currency's icon in the "/currencies gui" admin menus only # (not related to icon-display above, which is just text). Any valid Material name. gui-material: GOLD_NUGGET # Gives this currency its own dedicated command on top of "/currencies ... coins ...", e.g. # "coins" registers "/coins" with the same actions but without needing to repeat the currency # id: "/coins" alone shows your own balance, "/coins give " (also take/set/ # reset/balance/pay) work exactly like their "/currencies ... coins ..." equivalent. Leave blank # ("") for no custom command. Takes effect on "/currencies reload" - note that already-connected # players may need to reconnect for the new/renamed command to show up in tab-completion (the # command itself works right away either way). command: coins # Whether players can send this currency to each other with "/currencies pay coins # " (or "/coins pay " if "command" above is set). Set to false for a # currency that should only ever be granted by an admin/another plugin (e.g. a premium currency # bought with real money, to avoid player-to-player trading of it). allow-pay: true # The leaderboard menu ("/currencies top coins" or "/coins top"/"/coins leaderboard" if # "command" above is set). Ranks the top balances for this currency only. leaderboard-enabled: true # How many players to rank. Note for large servers on YAML storage specifically: building the # leaderboard means scanning every playerdata/*.yml file, which gets slow with many thousands # of players - SQLite/MySQL (config.yml "storage.type") query this instantly instead. leaderboard-size: 10 # Appearance of this currency's leaderboard and logs menus (see currencies/gems.yml for an # example that changes both). # # menu-size: total inventory size - must be a multiple of 9 between 27 and 54 (3 to 6 rows); # anything else is rounded to the nearest valid size. More rows = more entries visible per page. menu-size: 54 # menu-border-material: the glass (or any Material, really) framing the menu. Minecraft glass # panes only come in 16 fixed colors (no arbitrary hex here - that's a block, not text) - any # of BLACK/WHITE/RED/ORANGE/YELLOW/LIME/GREEN/CYAN/LIGHT_BLUE/BLUE/PURPLE/MAGENTA/PINK/BROWN/ # GRAY/LIGHT_GRAY, each as "_STAINED_GLASS_PANE". menu-border-material: BLACK_STAINED_GLASS_PANE # ------------------------------------------------------------------ # Cheques - let a player convert part of THEIR OWN balance into a physical item via # "/currencies cheque coins " (or "/coins cheque ", since "command" is set # above). Right-clicking the item credits whoever holds it with the amount printed on it, then # consumes it. Disabled by default. Separate permissions gate creating one # ("xplayercurrencies.cheque.create") and redeeming one ("xplayercurrencies.cheque.use") - both # default to true. See gems.yml for a fully configured, enabled example. # ------------------------------------------------------------------ cheque: enabled: true # Bounds on the amount a single cheque can be created for, on top of the player actually # having that much - a cheque can never create money out of thin air. max-amount: -1 = no cap # besides the player's own balance. min-amount: 1000 max-amount: 250000 # If false (default), the item's max stack size is forced to 1 - so what you see in an # inventory (1 cheque = 1 slot) always matches its face value, never several merged together. stackable: false # Adds an enchant-glint shimmer (no visible enchantment) so a cheque stands out at a glance. glow: true item: PAPER # {amount}/{amount_formatted}/{formatted}/{currency}/{icon_display} are replaced once, when # the cheque is created - the item keeps that exact wording afterward even if these settings # change later. name: "&e&lCheque &7- &f{amount_formatted} {icon_display}" lore: - "&7A cheque worth &f{amount_formatted} {currency}." - "" - "&eRight-click to redeem." # ------------------------------------------------------------------ # Lets this ONE currency also act as an external economy plugin's currency, on top of its own # commands/GUI/PAPI (which keep working normally either way). If more than one currency file # requests the same integration, only the first one (by "priority" then id, same ordering as # everywhere else) actually gets it - the rest are skipped with a warning in the console. # # - NONE (default): nothing extra, this currency only exists within XPlayerCurrencies. # - VAULT: registers as the server's Vault economy (net.milkbowl.vault.economy.Economy), so # shops/jobs/every other Vault-aware plugin reads and writes THIS currency's balances too. # Needs the Vault plugin installed - safely ignored (with a console message) if it isn't. plugin-integration: NONE # ------------------------------------------------------------------ # Lets a player convert part of THIS currency's balance into another one, via # "/currencies exchange coins " (or "/coins exchange ", since # "command" is set above) or the "/currencies exchange" menu. Every pair is one-way and opt-in: # this currency can convert INTO whatever's listed below, at that rate, regardless of whether # the other currency allows converting back (see gems.yml for an example with a deliberately # different rate each way - a "spread", same idea as a real currency exchange). # # rates: : . Only currencies # listed here (and enabled) are valid destinations - there's no "convert to anything" mode. exchange: enabled: false rates: gems: 0.01 #other: 0.02 # ------------------------------------------------------------------ # Gates this currency to (or blocks it from) specific worlds and/or WorldGuard regions. Only # checked on self-service actions (pay/cheque/exchange, this currency's own custom command) for # the PLAYER DOING them - never blocks admin give/take/set/reset via "/currencies", since those # are explicit overrides that should work from anywhere. # # - mode: NONE (default, usable everywhere), WHITELIST (ONLY usable in worlds/regions below) or # BLACKLIST (usable everywhere EXCEPT worlds/regions below). # - worlds: exact world names (Bukkit.getWorlds() names, e.g. "world_nether") - always works, no # dependency needed. # - regions: WorldGuard region ids - only actually enforced if WorldGuard is installed; silently # ignored (with a console notice) otherwise. Leave empty to restrict by world only. restrictions: mode: NONE worlds: [] regions: [] # ------------------------------------------------------------------ # On death, takes "percent"% off the player's ON-HAND balance for this currency - NEVER their bank # balance (entirely separate storage, untouched no matter what). Off by default. A player with # "xplayercurrencies.deathpenalty.bypass" (staff, typically) is never affected. # ------------------------------------------------------------------ death-penalty: enabled: false percent: 10 # Only applies if the player is carrying at least this much when they die - 0 means always apply # (down to whatever they're carrying, however little). min-balance-to-apply: 0 # ------------------------------------------------------------------ # Pays this currency to whoever lands the killing blow on a player or mob - only a kill actually # credited to a PLAYER attacker ever pays out (fall damage, other mobs, environment, etc. never # do). Off by default. Several currencies can each have their own "kill-coins" turned on # independently - a kill then pays every one of them that applies, not just one, so this is also # how you "choose which currency(ies)" get paid: just enable it on each one you want. # # - permission: blank = anyone can earn this currency's kill-coins. Set to gate it, e.g. only # donors/a specific rank earning money from kills. # - player-kill-amount: paid for killing another PLAYER (PvP). # - default-mob-kill-amount: fallback for any mob NOT listed under "mob-amounts" below (0 = only # explicitly listed mobs pay anything). # - mob-amounts: per-mob overrides (Bukkit EntityType names, e.g. ZOMBIE, ENDER_DRAGON, WITHER). # ------------------------------------------------------------------ kill-coins: enabled: true permission: "" player-kill-amount: 50 default-mob-kill-amount: 0 mob-amounts: ZOMBIE: 2 SKELETON: 2 SPIDER: 2 ENDERMAN: 5 WITHER_SKELETON: 10 WITHER: 300 ENDER_DRAGON: 500 # ------------------------------------------------------------------ # Lets players open NPC-style shop menus (buy/sell items for this currency, Hypixel/RoyaleEconomy # style) via "/currencies shop coins" (or "/coins shop", since "command" is set above). The menus # themselves - which items, at what price, how many shops - live under shops/coins/*.yml, not # here, since a currency can have several. Enabled here (with a one-item demo auto-created the # first time this loads with an empty shops/coins/ folder) so a fresh install already has a # working example; see gems.yml, which leaves this off. # ------------------------------------------------------------------ shop: enabled: true # Extra top-level command(s) that open THIS currency's shop directly, e.g. "shop" (used below, # for "/shop") instead of (or alongside) "/currencies shop coins" / "/coins shop" - same # convention as "command" above, no leading "/". The first entry is the primary command name, # any further ones are aliases. Empty (default) registers none - handy to leave off if another # plugin already claims a common name like "shop" on your server. commands: - "shop" # ------------------------------------------------------------------ # Lets players stash part of their coins in a separate bank account via "/currencies bank coins" # (or "/coins bank", since "command" is set above) - deposit/withdraw against their normal wallet # balance, with money left in the bank slowly earning interest over time, up to a cap. Everyone # starts on the free "base-*" tier below; "tiers" is an ORDERED list of paid upgrades (tier 1 = # first entry, tier 2 = second...) - each raises the rate/cap further, optionally gated behind a # permission on top of its cost. Reaching tier N always means having paid for every tier below it # first - there's no skipping ahead. Enabled here (with two example tiers) so a fresh install # already has something to test; see gems.yml, which leaves this off. # ------------------------------------------------------------------ bank: enabled: true # Extra top-level command(s) that open THIS currency's bank directly, e.g. "bank" (used below, # for "/bank") - same convention as "shop.commands" above. commands: - "bank" # How often (in minutes) money sitting in the bank earns interest - applied in whole-interval # jumps, so a player who was offline through several intervals still gets it all in one lump sum # next time they're touched (join, deposit/withdraw/upgrade...), never lost just for being away. interest-interval-minutes: 60 # Rate (%) and cap for the free base tier (tier 0) - everyone has this from the start, no # upgrade needed. base-interest-rate-percent: 0.5 base-max-balance: 10000 tiers: - name: "Bronze Vault" upgrade-cost: 5000 # Blank ("") means no permission needed - just the cost above. See "Silver Vault" below for # a tier that ALSO requires one, on top of its cost. required-permission: "" interest-rate-percent: 1.5 max-balance: 50000 - name: "Silver Vault" upgrade-cost: 25000 required-permission: "xplayercurrencies.bank.silver" interest-rate-percent: 3.0 max-balance: 250000 # ------------------------------------------------------------------ # Physical items that sell an ENTIRE container's contents (against this currency's shop(s)) # instead of opening/breaking it, when clicked on one - which block types count as a "container" # for this is set once globally in config.yml "sell-sticks.container-types" (chests/barrels by # default, listable in-game with "/currencies admin sellstick containers"). Hand one out with # "/currencies admin sellstick give coins [amount]". "id" is only ever used to look # this entry back up at click time - editing name/boost/permission/max-uses/click-type here # updates every copy already handed out immediately, nothing needs reissuing. See also # "/currencies sellall coins" (or "/coins sellall"), which does the same sweep over a PLAYER'S OWN # inventory instead of a container, no stick needed. # # - "click-type": which click triggers it - RIGHT (plain right-click, the default), SHIFT_RIGHT, # LEFT, or SHIFT_LEFT. Any other click on the container falls through to its normal vanilla # behavior instead (opening/breaking it) - so e.g. a SHIFT_RIGHT stick still lets a plain # right-click just open the chest. # - "max-uses": 0 (the default) means unlimited - the stack just stays a normal stack. Above 0, # every handed-out copy is unstackable and tracks its OWN remaining uses (shown via the # "{uses_left}"/"{max_uses}" lore placeholders below); it's deleted automatically once that # count reaches 0. # ------------------------------------------------------------------ sell-sticks: - id: basic material: STICK name: "&6Sell Stick" lore: - "&7Right-click a chest or barrel to" - "&7sell its ENTIRE sellable contents" - "&7for {currency}." - "" - "&7Boost: &a+{boost}%" boost-percent: 0 # Blank = every shop this currency has (that the player can see). Set to one shop's id to # restrict this stick to just that shop's prices instead. shop: "" # Blank = anyone with "xplayercurrencies.sellall" can use it. permission: "" click-type: RIGHT max-uses: 0 - id: golden material: BLAZE_ROD name: "&e&lGolden Sell Stick" lore: - "&7Shift + right-click a chest or barrel" - "&7to sell its ENTIRE sellable contents" - "&7for {currency}." - "" - "&7Boost: &a+{boost}%" - "&7Uses left: &e{uses_left}&7/&e{max_uses}" boost-percent: 15 shop: "" permission: "xplayercurrencies.sellstick.golden" # Demonstrates both new options: only triggers on shift + right-click, and is consumed after # 20 uses (deleted once it hits 0 - see the note above). click-type: SHIFT_RIGHT max-uses: 20 # ------------------------------------------------------------------ # Drinkable potions that grant the drinker a temporary earnings booster for THIS currency - right- # click to drink, standard vanilla potion mechanic. Hand one out with # "/currencies admin boosterpotion give coins [amount]", or sell it in a shop by # sampling one into a ShopItem's give-item slot in the shop editor (it's just a physical item, no # separate "shop" integration needed). See also "/currencies admin booster event/give", which # grant the exact same kind of boost directly (server-wide or to one player) without any item. # # - "scope": what the boost affects - BUY (discount on shop purchase prices), SELL (bonus on shop/ # sellall/sell-stick sale prices), KILL (bonus on kill coins), or ALL (all three at once). # - "percent": always a POSITIVE bonus, e.g. 20 = 20% cheaper for BUY, or 20% more money for # SELL/KILL/ALL. Multiple active boosts (global event + personal potion, etc.) stack additively. # - "duration-minutes": how long the boost lasts once drunk. # ------------------------------------------------------------------ booster-potions: - id: sell_boost material: POTION name: "&d&lSelling Frenzy" lore: - "&7Drink to boost your {currency}" - "&7selling price by &a+{percent}%" - "&7for &f{duration} &7minute(s)." scope: SELL percent: 25 duration-minutes: 15 permission: "" - id: kill_boost material: POTION name: "&c&lBloodlust" lore: - "&7Drink to boost your {currency}" - "&7kill coins by &a+{percent}%" - "&7for &f{duration} &7minute(s)." scope: KILL percent: 50 duration-minutes: 10 permission: "" # ------------------------------------------------------------------ # PERMANENT earnings boosts for whoever holds "permission" - granted through your permissions # plugin (LuckPerms etc.), not an in-game command, and re-checked live on every price/reward # calculation: granting/revoking the permission takes effect immediately, nothing to reload. Same # "scope"/"percent" meaning as "booster-potions" above, but with no duration - it lasts exactly as # long as the permission does. Typically used for a rank perk (e.g. VIP always sells 10% higher). # ------------------------------------------------------------------ permission-boosters: - permission: "xplayercurrencies.booster.vip" scope: SELL percent: 10 - permission: "xplayercurrencies.booster.mvp" scope: ALL percent: 20 # ------------------------------------------------------------------ # Black market - a rotating shop of rare/exclusive items ("/currencies blackmarket coins", or # "/coins blackmarket" since "command" is set above). Every "refresh-interval-hours", a random # weighted "rotation-size" subset of "pool" below becomes buyable, each with its own limited # "stock-per-rotation" - once sold out, that item's gone until the NEXT refresh (or an admin's # forced one, "/currencies admin blackmarket refresh coins"). Off by default. # # Per pool entry: # - stock-per-rotation: how many times it can be bought (in units of "amount") before it's sold # out for that rotation. # - amount: how many of "material" one purchase gives. # - weight: relative odds of being picked into a rotation - a weight-2 entry is roughly twice as # likely to show up as a weight-1 one. Doesn't affect anything once it's already in rotation. # - permission: blank = anyone with "xplayercurrencies.blackmarket" (and the market's own # "permission" below, if set) can buy it. Set to gate one specific rare entry further. # ------------------------------------------------------------------ black-market: enabled: true refresh-interval-hours: 6 rotation-size: 3 # Blank = anyone with "xplayercurrencies.blackmarket" can open it at all. permission: "" # The glass framing the menu - any *_STAINED_GLASS_PANE color. All of this (including the pool # below) is also editable in-game via "/currencies gui" -> a currency -> Features -> Black # Market, no need to hand-edit this file. border-material: BLACK_STAINED_GLASS_PANE pool: - id: netherite_scrap material: NETHERITE_SCRAP name: "&5&lNetherite Scrap" lore: - "&7A rare find, straight off" - "&7the black market." price: 5000 stock-per-rotation: 3 amount: 1 weight: 3 permission: "" - id: elytra material: ELYTRA name: "&5&lElytra" lore: - "&7No questions asked." price: 50000 stock-per-rotation: 1 amount: 1 weight: 1 permission: "" - id: totem material: TOTEM_OF_UNDYING name: "&5&lTotem of Undying" lore: - "&7Cheat death once." price: 15000 stock-per-rotation: 2 amount: 1 weight: 2 permission: "" - id: diamond_bundle material: DIAMOND name: "&5&lDiamond Bundle" lore: - "&7A bulk deal." price: 2000 stock-per-rotation: 5 amount: 16 weight: 4 permission: "" ``` Next: [Default currency: gems.yml](/home/xplayercurrencies/configuration/default-configuration-files/default-currency-gems.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xandtech.fr/home/xplayercurrencies/configuration/default-configuration-files/default-currency-coins.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.