How it works

Pack drops

When a player kills a mob listed in a collection, the plugin rolls a "1 in X" chance (package_drop_chance in groups.yml). On success, the pack goes into the player's inventory (overflow drops on the ground).

No pack is given if the mob dies from a fall, fire, lava, another mob, a command or a plugin. By default (require_direct_player_damage: true), the killing blow must come from the player (melee or projectile). A single death event can never give two packs.

A mob that belongs to several collections (e.g. the Enderman in Monsters and End) gets one roll per collection. The environments field restricts a collection to certain dimensions: End packs only drop in the End, Monsters packs only in the Overworld and the Nether.

Opening a pack (right-click)

1. The rarity is drawn using the chances from config.yml.
2. A random card of that rarity is drawn from the pack's collection.
3. If the collection has no card of the drawn rarity (draw.fallback):
   • RENORMALIZE (default): only the rarities present are drawn, keeping their proportions. This is equivalent to "reroll until you hit a rarity that exists", without a loop.
   • NEAREST: the closest rarity present is used, first towards more common, then towards rarer.
4. The pack is consumed, the card is recorded in the collection and then given to the player. All of this happens in the same tick, in this order.
5. Full-screen opening animation (with ItemsAdder: the pack shakes, glows, tears open, then each card is shown back first, glows in its rarity color and flips over; sneak to skip), then the summary messages. Without ItemsAdder or if an image is missing, the simpler text animation is used (rarities scroll by, then the card is revealed). The animation is purely visual: the card is already in the inventory, so disconnecting or a crash during the animation loses nothing and duplicates nothing.

Duplicates

A card can be obtained several times. Copies are real items that stack in the inventory. The binder shows "Owned: x3": the number of copies obtained (packs, boosters, shop, received trades, /tcg givecard) minus the copies given in trades (/tcg trade) or recycled (/tcg recycle).

• A discovered card stays discovered forever: trading or recycling it does not remove it from the binder or the progress (it then shows "x0").
• A copy that is dropped, put in a chest or handed over directly is not tracked (there is no reliable way to follow an item through chests and deaths). To give a card, use /tcg trade: the counter follows.
• Holo versions have their own counter ("Holo: x1").

Binder

• /tcg: main menu, one icon per collection with owned / total, the percentage and a progress bar.
• Click a collection (or /tcg collection nature): grid of cards sorted by number. An owned card is shown as the real card with its number of copies. A card never obtained never shows the card image: it uses the placeholder item. Your choice (gui.collection.undiscovered_display):
  • HIDDEN (default): ???, name and info hidden (unknown_show_rarity: true shows the rarity);
  • INFO: name, rarity, number, collection and description visible, with the mention "Not discovered yet".
• Three layouts (gui.collection.mode):
  • GRID (default): full grid, 45 cards per page;
  • BINDER: one big card in the center, taking 3x3 slots; arrow on the right for the next card, on the left for the previous one. With ItemsAdder, the card image is drawn large (44x60 px, 1:1) in the menu background and the area is covered by an invisible item that shows the tooltip (name, rarity, copies); an undiscovered card shows a card back in its rarity color (gray, blue, purple, gold; big_card_back_by_rarity, empty = a single back that reveals nothing). Without ItemsAdder, the normal item is placed in the center of the area. Settings in gui.collection.binder (card_width, card_height, card_slots = corner of each card); display options missing from this section are taken from the GRID mode.
  • DOUBLE: two big cards 3x3 side by side (columns 1-3 and 5-7, the middle column stays empty), one arrow on each side (columns 0 and 8). Works like BINDER, settings in gui.collection.double.
• Automatic pagination if the collection exceeds the number of slots (card_slots), with a page-turn sound.
• Menus are locked: click, shift-click, double-click, number keys and drag are all cancelled. Displayed items carry a tcg:display mark: even if extracted from a menu by a modified client, they are worthless and get deleted.

First discovery and rewards

Obtaining a card for the first time shows "✨ NEW CARD!" with a dedicated title and sound.

Two rewards, each given only once per player (table tcg_completions), even if cards are added later:

# groups.yml
  nature:
    completion:
      broadcast: true                                  # server announcement
      message: ["<gray>Reward: <gold>5 diamonds"]      # lines sent to the player
      commands:                                        # console commands (%player%, %uuid%, %group%)
        - "give %player% diamond 5"
        - "tcg givepack %player% nature_pack 3"

# config.yml
binder_completion:
  enabled: true
  retroactive: true    # on join: rewards a player who had already completed everything before
  broadcast: true
  message: ["<gold>Collector title unlocked!"]
  commands:
    - "give %player% nether_star 1"
    - "lp user %player% permission set tag.collector true"

Rewards run through console commands: items, money (eco give), permissions, ranks, TCG packs, anything a plugin allows. The standard messages ("COLLECTION COMPLETE", "BINDER COMPLETE") are in messages.yml (collection.completed, binder.completed).

Secret cards

secret: true on a card: it is invisible in the binder and excluded from the total until it is obtained, then shows up as a bonus. It is drawn normally from packs, according to its rarity.

Trades (/tcg trade <player>)

1. /tcg trade Bob sends a request; Bob gets a clickable message [ACCEPT] [DECLINE] (or /tcg trade accept Alice). If Bob had already sent you a request, the trade opens directly.
2. A two-column menu opens for both players: your offer on the left, the other player's on the right.
3. Click a card in your inventory: it is offered (left click: the whole stack, right click: one more copy). Click a card in your offer: it is removed. Packs and boosters can be traded too (trade.allow_packs).
4. Each player clicks Confirm. When both have confirmed, a 3-second countdown starts (trade.countdown_seconds), then the trade happens.

Safety:

• Offered items stay in your inventory until the last second: closing the menu, disconnecting, reloading the plugin or a server crash cancels the trade without losing or duplicating anything.
• Any change to an offer cancels both confirmations and the countdown.
• At trade time, every offered slot is checked again (same item, enough quantity). Both players' items are removed and then given in the same tick; overflow drops at the player's feet if the inventory is full.
• Cards are identified by their internal mark (PDC): a display copy or a renamed item does not go through.
• Every trade is written to the console (Trade Alice -> Bob: 1x nature_pig | Bob -> Alice: 1x end_ender_dragon).
• Counters follow: the card leaves the giver's counter and enters the receiver's (with "New card" and milestones if it is a discovery).

Recycling and shop (/tcg recycle, /tcg shop)

Recycling: a menu where you pick cards from your inventory (left click: the stack, right click: one copy). The Add all duplicates button selects everything except one copy of each card (never holo cards). Recycle confirms: the cards are destroyed and give dust.

A holo copy is worth 10 times more dust (dust.holo_multiplier) and always gives a pack (dust.holo_pack_chance). The pack won is the classic pack (1 card) of the recycled card's collection: recycling 8 cows gives 2 Nature Packs on average. The Recycle button shows the dust and the average number of packs expected. To give packs only, set recycle_value to 0.

Balance: with these values, a pack opened then recycled gives back about 0.36 pack on average. Keep this yield below 1, otherwise recycling in a loop would produce infinite packs.

Shop: dust buys a specific card (price by rarity, shop.card_price: 10 / 40 / 200 / 800), a collection pack (shop.pack_price, 30; per collection groups.yml > shop_price) or a booster (boosters.yml > price). A purchase is confirmed with a second click on the item. shop.allow_undiscovered: false limits sales to cards already discovered; undiscovered secret cards are never sold, and holo cards never are.

Admins credit dust with /tcg givedust <player> <amount> (vote reward, server store...).

Boosters (boosters.yml)

Packs of several cards, to sell in the shop or to give away (/tcg givebooster <player> <booster>, e.g. as a vote reward):

boosters:
  booster_5:
    name: "<light_purple>Premium Booster x5"
    itemsadder: "tcg:booster_5"
    cards: 5                     # 1 to 9 cards
    collections: []              # [] = all, except event collections
    guaranteed_rarity: EPIC      # at least one Epic OR BETTER
    price: 250                   # dust, 0 = not for sale

• Each card is drawn like in a pack (rarity, then card), with its chance to be holo. If none of the first cards reaches the guaranteed rarity, the last one is drawn among equal or higher rarities, keeping their proportions.
• rarities gives the booster its own chances (sum 100); extra_cards adds specific cards to the draw.
• Seasonal: sale: { from: "10-15", until: "11-05" } (every year, can span December 31st) or full dates YYYY-MM-DD. Outside the period, the booster disappears from the shop; a booster already obtained can be opened at any time.
• Limited-time cards: an event: true collection (e.g. Halloween, package_drop_chance: 0, cards without entity) is only drawn by the boosters that list it. It stays out of the complete binder and out of "all collections" boosters. A full example is commented in groups.yml, cards.yml and boosters.yml.

Holo cards

Each card drawn from a pack or a booster has a 1% chance to be holo (holo.chance, 0.01% precision). With ItemsAdder, it uses the item <card id>_holo (iridescent frame, reflections: all 90 are provided in the ItemsAdder packs); without it, the normal texture with the enchantment glint and an iridescent name. It does not stack with the normal version, has its own counter in the binder ("✦ Holo: x1"), counts as a discovery of the card, is worth 10 times more when recycled and is never sold. To test: /tcg give nature_cow 1 holo.

Milestones and titles

• Milestones (config.yml > milestones): rewards at 25, 50 and 75% of each collection (by default 1, 2 and 3 packs of the collection), given only once. groups.yml > <collection>.milestones replaces the list for one collection ({} = no milestones). Console commands with %player%, %uuid%, %group%, %pack%. milestones_retroactive: true gives already reached milestones on join (e.g. added afterwards).
• Titles (config.yml > titles): unlocked by progress ("Nature Apprentice" at 50%, "Nature Collector" at 100%, "Binder Master" for the complete binder). /tcg title lists them (clickable), /tcg title <id> picks one, /tcg title off removes it. The title is shown in chat, the tab list or a scoreboard through %tcg_title% (PlaceholderAPI).

Leaderboards, statistics, other players' binders

• /tcg top [cards|legendaries|holos|packs|firsts]: discovered cards, legendaries, holo cards, packs opened, and the first player to complete each collection. Computed in the database off the main thread every 5 minutes (leaderboards.refresh_seconds).
• /tcg stats [player]: discovered cards, completed collections, packs and boosters opened, best card (the rarest, holo first), legendaries, holo cards, favorite collection (the most opened), dust, trades, cards recycled and bought, title. Also works for an offline player.
• /tcg view <player>: their binder in read-only mode (main menu then collections), online or not.

Holo binder

The ✦ button in the main menu (gui.main.holo_slot, slot 26) switches to the holo binder: same collections and same menus, but a card only appears if its holo version has been obtained (large holo image with ItemsAdder, holo counter). Its progress is separate ("Holo: 3/35"). When all the holo cards of a collection are gathered, config.yml > holo.completion gives a reward (once per collection). Titles accept holo: true (e.g. "✦ Holo Binder Master").

Auction house (/tcg ah)

• /tcg ah sell <price> [dust|money] lists the stack held in hand (card, pack or booster), for dust or money (Vault).
• /tcg ah lists the offers (newest first); click then click again to buy. "My listings" lets you withdraw your own.
• The seller receives the price minus the tax (market.tax_percent, 5%). A listing expires after market.duration_hours (48 h): the item goes back to the seller.
• Asynchronous and safe: an absent seller is paid on their next login (on any server of the network); the purchase is atomic in the database (two simultaneous buyers, even on two servers: only one succeeds, the other is refunded); each delivery (payment, bought item, unsold item) is marked in the database before being given, so never twice.
• Counters follow: the card leaves the seller's counter and enters the buyer's.

Objectives (/tcg objectives, objectives.yml)

Daily objectives (reset at midnight) and weekly ones (on Monday). Each player gets 3 daily and 2 weekly objectives drawn at random from the list (daily_count, weekly_count, 0 = all), the same draw on every server of a network.

Included example: "Nether Expedition" (kill 50 mobs of the Nether collection this week, reward: a Nether Pack). Kills follow the drops exclusions (worlds, game modes, spawner mobs if excluded). Cards given by an admin do not count.

/tcg show

Shows the card (or pack, or booster) held in hand in chat: "Alice shows: Panda", with the card's full tooltip on hover. 30-second cooldown (show.cooldown_seconds, admins are exempt), adjustable range (show.radius, 0 = whole server).

Paying with money (Vault)

With Vault and an economy plugin, the shop also shows money prices: left click = dust, right click = money (two clicks to confirm). Prices in config.yml > shop.money (cards by rarity, packs) and boosters.yml > money_price. Everything is 0 by default (nothing for sale for money): set the prices according to your economy. Without Vault, everything works with dust.