Fonctionnement

Drop des paquets

Quand un joueur tue un mob listé dans une collection, le plugin tire « 1 chance sur X » (package_drop_chance dans groups.yml). En cas de succès, le paquet arrive dans l'inventaire du joueur (le surplus tombe au sol).

Pas de paquet si le mob meurt de chute, de feu, de lave, d'un autre mob, d'une commande ou d'un plugin. Par défaut (require_direct_player_damage: true), le coup fatal doit venir du joueur (mêlée ou projectile). Un même évènement de mort ne peut pas donner deux paquets.

Un mob présent dans plusieurs collections (ex. Enderman dans Monstres et End) fait un tirage par collection. Le champ environments restreint une collection à certaines dimensions : les paquets End ne tombent que dans l'End, les paquets Monstres que dans l'Overworld et le Nether.

Ouverture d'un paquet (clic droit)

1. Tirage de la rareté selon les chances de config.yml.
2. Tirage d'une carte au hasard parmi les cartes de cette rareté dans la collection du paquet.
3. Si la collection n'a aucune carte de la rareté tirée (draw.fallback) :
   • RENORMALIZE (défaut) : seules les raretés présentes sont tirées, en gardant leurs proportions. C'est équivalent à « relancer jusqu'à tomber sur une rareté présente », sans boucle.
   • NEAREST : on prend la rareté présente la plus proche, d'abord vers le plus commun puis vers le plus rare.
4. Le paquet est consommé, la carte est enregistrée dans la collection puis donnée au joueur. Tout se fait dans le même tick, dans cet ordre.
5. Animation d'ouverture plein écran (avec ItemsAdder : le paquet tremble, s'illumine, se déchire, puis chaque carte apparaît de dos, brille de la couleur de sa rareté et se retourne ; s'accroupir pour passer), puis le récapitulatif. Sans ItemsAdder ou si une image manque, l'animation texte plus simple prend le relais (les raretés défilent puis la carte est révélée). L'animation est purement visuelle : la carte est déjà dans l'inventaire, donc se déconnecter ou subir un crash pendant l'animation ne fait rien perdre et ne duplique rien.

Doublons

Une carte peut être obtenue plusieurs fois. Les exemplaires sont de vrais items qui s'empilent dans l'inventaire. Le classeur affiche « Possédée : x3 » : le nombre d'exemplaires obtenus (paquets, boosters, boutique, échanges reçus, /tcg givecard) moins ceux donnés en échange (/tcg trade) ou recyclés (/tcg recycle).

• Une carte découverte le reste pour toujours : l'échanger ou la recycler ne la retire pas du classeur ni de la progression (elle affiche alors « x0 »).
• Un exemplaire jeté, posé dans un coffre ou donné de la main à la main n'est pas suivi (il n'existe pas de façon fiable de suivre un item à travers coffres et morts). Pour donner une carte, utilisez /tcg trade : le compteur suit.
• Les versions brillantes ont leur propre compteur (« Brillantes : x1 »).

Classeur

• /tcg : menu principal, une icône par collection avec possédées / total, le pourcentage et une barre de progression.
• Clic sur une collection (ou /tcg collection nature) : grille des cartes triées par numéro. Une carte possédée s'affiche comme la vraie carte avec son nombre d'exemplaires. Une carte jamais obtenue n'affiche jamais l'image de la carte : elle utilise l'item placeholder. Au choix (gui.collection.undiscovered_display) :
  • HIDDEN (défaut) : ???, nom et infos masqués (unknown_show_rarity: true laisse voir la rareté) ;
  • INFO : nom, rareté, numéro, collection et description visibles, avec la mention « Pas encore découverte ».
• Trois dispositions au choix (gui.collection.mode) :
  • GRID (défaut) : grille pleine, 45 cartes par page ;
  • BINDER : une grande carte au centre, qui occupe 3x3 emplacements ; flèche à droite pour la carte suivante, à gauche pour la précédente. Avec ItemsAdder, l'image de la carte est dessinée en grand (44x60 px, 1:1) dans le fond du menu et la zone est couverte d'un item invisible qui affiche l'infobulle (nom, rareté, exemplaires) ; une carte non découverte montre un dos de carte à la couleur de sa rareté (gris, bleu, violet, or ; big_card_back_by_rarity, vide = dos unique qui ne révèle rien). Sans ItemsAdder, l'item normal est posé au centre de la zone. Réglages dans gui.collection.binder (card_width, card_height, card_slots = coin de chaque carte) ; les options d'affichage absentes de cette section sont reprises du mode GRID.
  • DOUBLE : deux grandes cartes 3x3 côte à côte (colonnes 1-3 et 5-7, la colonne du milieu reste libre), une flèche de chaque côté (colonnes 0 et 8). Même fonctionnement que BINDER, réglages dans gui.collection.double.
• Pagination automatique si la collection dépasse le nombre d'emplacements (card_slots), avec un son de page tournée.
• Les menus sont verrouillés : clic, shift-clic, double-clic, touches numériques et drag sont tous annulés. Les items affichés portent une marque tcg:display : même extraits d'un menu par un client modifié, ils ne valent rien et sont supprimés.

Première découverte et récompenses

La première obtention d'une carte affiche « ✨ NOUVELLE CARTE ! » avec un titre et un son dédiés.

Deux récompenses, chacune donnée une seule fois par joueur (table tcg_completions), même si des cartes sont ajoutées ensuite :

# groups.yml
  nature:
    completion:
      broadcast: true                                  # annonce serveur
      message: ["<gray>Récompense : <gold>5 diamants"]  # lignes envoyées au joueur
      commands:                                        # commandes console (%player%, %uuid%, %group%)
        - "give %player% diamond 5"
        - "tcg givepack %player% nature_pack 3"

# config.yml
binder_completion:
  enabled: true
  retroactive: true    # à la connexion : récompense un joueur qui avait déjà tout terminé avant
  broadcast: true
  message: ["<gold>Titre Collectionneur débloqué !"]
  commands:
    - "give %player% nether_star 1"
    - "lp user %player% permission set tag.collectionneur true"

Les récompenses passent par des commandes console : objets, argent (eco give), permissions, grades, paquets TCG, tout ce qu'un plugin permet. Les messages standard (« COLLECTION TERMINÉE », « CLASSEUR TERMINÉ ») sont dans messages.yml (collection.completed, binder.completed).

Cartes secrètes

secret: true sur une carte : elle est invisible dans le classeur et absente du total tant qu'elle n'est pas obtenue, puis apparaît comme bonus. Elle se tire normalement dans les paquets, selon sa rareté.

Échanges (/tcg trade <joueur>)

1. /tcg trade Bob envoie une demande ; Bob reçoit un message cliquable [ACCEPTER] [REFUSER] (ou /tcg trade accept Alice). Si Bob vous avait déjà envoyé une demande, l'échange s'ouvre directement.
2. Un menu à deux colonnes s'ouvre chez les deux joueurs : votre offre à gauche, celle de l'autre à droite.
3. Clic sur une carte de votre inventaire : elle est proposée (clic gauche : la pile, clic droit : un exemplaire de plus). Clic sur une carte de votre offre : elle est retirée. Paquets et boosters sont aussi échangeables (trade.allow_packs).
4. Chacun clique sur Valider. Quand les deux ont validé, un compte à rebours de 3 s démarre (trade.countdown_seconds), puis l'échange a lieu.

Sécurité :

• Les items proposés restent dans votre inventaire jusqu'à la dernière seconde : fermer le menu, se déconnecter, recharger le plugin ou un crash du serveur annule l'échange sans rien perdre ni dupliquer.
• Toute modification d'une offre annule les deux validations et le compte à rebours.
• À l'échange, chaque emplacement proposé est revérifié (même item, quantité suffisante). Les items des deux joueurs sont retirés puis donnés dans le même tick ; le surplus tombe aux pieds si l'inventaire est plein.
• Les cartes sont identifiées par leur marque interne (PDC) : une copie d'affichage ou un item renommé ne passe pas.
• Chaque échange est écrit dans la console (Échange Alice -> Bob : 1x nature_pig | Bob -> Alice : 1x end_ender_dragon).
• Les compteurs suivent : la carte quitte le compteur du donneur et entre dans celui du receveur (avec « Nouvelle carte » et les paliers si c'est une découverte).

Recyclage et boutique (/tcg recycle, /tcg shop)

Recyclage : un menu où l'on choisit des cartes de son inventaire (clic gauche : la pile, clic droit : un exemplaire). Le bouton Ajouter tous les doublons sélectionne tout sauf un exemplaire de chaque carte (jamais les brillantes). Recycler confirme : les cartes sont détruites et rapportent de la poussière.

Un exemplaire brillant vaut 10 fois plus de poussière (dust.holo_multiplier) et rend toujours un paquet (dust.holo_pack_chance). Le paquet gagné est le paquet classique (1 carte) de la collection de la carte recyclée : recycler 8 vaches rend en moyenne 2 Paquets Nature. Le bouton Recycler affiche la poussière et le nombre moyen de paquets attendus. Pour ne rendre que des paquets, mettez recycle_value à 0.

Équilibre : un paquet ouvert puis recyclé rend en moyenne environ 0,36 paquet avec ces valeurs. Gardez ce rendement sous 1, sinon recycler en boucle produirait des paquets à l'infini.

Boutique : la poussière achète une carte précise (prix selon la rareté, shop.card_price : 10 / 40 / 200 / 800), un paquet de collection (shop.pack_price, 30 ; par collection groups.yml > shop_price) ou un booster (boosters.yml > price). Un achat se confirme par un second clic sur l'article. shop.allow_undiscovered: false limite la vente aux cartes déjà découvertes ; les cartes secrètes non découvertes ne sont jamais vendues, et les brillantes jamais.

Les admins créditent de la poussière avec /tcg givedust <joueur> <quantité> (récompense de vote, boutique du serveur...).

Boosters (boosters.yml)

Paquets de plusieurs cartes, à vendre dans la boutique ou à donner (/tcg givebooster <joueur> <booster>, ex. en récompense de vote) :

boosters:
  booster_5:
    name: "<light_purple>Booster Premium x5"
    itemsadder: "tcg:booster_5"
    cards: 5                     # 1 à 9 cartes
    collections: []              # [] = toutes, sauf les collections événementielles
    guaranteed_rarity: EPIC      # au moins une Épique OU MIEUX
    price: 250                   # poussière, 0 = pas en vente

• Chaque carte est tirée comme dans un paquet (rareté puis carte), avec sa chance d'être brillante. Si aucune des premières cartes n'atteint la rareté garantie, la dernière est tirée parmi les raretés égales ou supérieures, en gardant leurs proportions.
• rarities donne au booster ses propres chances (somme 100) ; extra_cards ajoute des cartes précises au tirage.
• Saisonniers : sale: { from: "10-15", until: "11-05" } (chaque année, peut passer le 31 décembre) ou des dates complètes AAAA-MM-JJ. Hors période, le booster disparaît de la boutique ; un booster déjà obtenu s'ouvre à tout moment.
• Cartes limitées dans le temps : une collection event: true (ex. Halloween, package_drop_chance: 0, cartes sans entity) n'est tirée que par les boosters qui la citent. Elle reste hors du classeur complet et des boosters « toutes collections ». Un exemple complet est commenté dans groups.yml, cards.yml et boosters.yml.

Cartes brillantes

Chaque carte tirée d'un paquet ou d'un booster a 1 % de chance d'être brillante (holo.chance, précision 0,01 %). Avec ItemsAdder, elle utilise l'item <id de la carte>_holo (cadre irisé, reflets : les 90 sont fournies dans itemsadder-pack/) ; sans lui, la texture normale avec la brillance d'enchantement et un nom irisé. Elle ne s'empile pas avec la version normale, a son propre compteur dans le classeur (« ✦ Brillantes : x1 »), compte comme découverte de la carte, vaut 10 fois plus au recyclage et n'est jamais vendue. Pour un test : /tcg give nature_cow 1 holo.

Paliers et titres

• Paliers (config.yml > milestones) : récompenses à 25, 50 et 75 % de chaque collection (par défaut 1, 2 et 3 paquets de la collection), données une seule fois. groups.yml > <collection>.milestones remplace la liste pour une collection ({} = aucun palier). Commandes console avec %player%, %uuid%, %group%, %pack%. milestones_retroactive: true donne à la connexion les paliers déjà atteints (ex. ajoutés après coup).
• Titres (config.yml > titles) : débloqués par la progression (« Apprenti Nature » à 50 %, « Collectionneur Nature » à 100 %, « Maître du Classeur » pour le classeur complet). /tcg title les liste (cliquables), /tcg title <id> en choisit un, /tcg title off le retire. Le titre s'affiche dans le chat, l'onglet ou un scoreboard via %tcg_title% (PlaceholderAPI).

Classements, statistiques, classeur des autres

• /tcg top [cards|legendaries|holos|packs|firsts] : cartes découvertes, légendaires, brillantes, paquets ouverts, et le premier joueur à avoir terminé chaque collection. Calculés en base hors du thread principal toutes les 5 minutes (leaderboards.refresh_seconds).
• /tcg stats [joueur] : cartes découvertes, collections terminées, paquets et boosters ouverts, meilleure carte (la plus rare, brillante en priorité), légendaires, brillantes, collection préférée (la plus ouverte), poussière, échanges, cartes recyclées et achetées, titre. Fonctionne aussi pour un joueur hors ligne.
• /tcg view <joueur> : son classeur en lecture seule (menu principal puis collections), connecté ou non.

Classeur brillant

Le bouton ✦ du menu principal (gui.main.holo_slot, emplacement 26) bascule vers le classeur brillant : mêmes collections et mêmes menus, mais une carte n'y apparaît que si sa version brillante a été obtenue (image brillante en grand format avec ItemsAdder, compteur des brillantes). Sa progression est à part (« Brillantes : 3/35 »). Quand toutes les brillantes d'une collection sont réunies, config.yml > holo.completion donne une récompense (une fois par collection). Les titres acceptent holo: true (ex. « ✦ Maître du Classeur brillant »).

Hôtel des ventes (/tcg ah)

• /tcg ah sell <prix> [dust|money] met en vente la pile tenue en main (carte, paquet ou booster), en poussière ou en argent (Vault).
• /tcg ah liste les annonces (de la plus récente à la plus ancienne) ; clic puis second clic pour acheter. « Mes annonces » permet de retirer les siennes.
• Le vendeur reçoit le prix moins la taxe (market.tax_percent, 5 %). Une annonce expire après market.duration_hours (48 h) : l'item revient au vendeur.
• Asynchrone et sûr : un vendeur absent est payé à sa prochaine connexion (sur n'importe quel serveur du réseau) ; l'achat est atomique en base (deux acheteurs simultanés, même sur deux serveurs : un seul réussit, l'autre est remboursé) ; chaque livraison (paiement, item acheté, invendu) est marquée en base avant d'être donnée, donc jamais deux fois.
• Les compteurs suivent : la carte quitte le compteur du vendeur et entre dans celui de l'acheteur.

Objectifs (/tcg objectives, objectives.yml)

Objectifs quotidiens (remis à zéro à minuit) et hebdomadaires (le lundi). Chaque joueur en reçoit 3 quotidiens et 2 hebdomadaires tirés au hasard parmi la liste (daily_count, weekly_count, 0 = tous), le même tirage sur tous les serveurs d'un réseau.

Exemple livré : « Expédition dans le Nether » (tuer 50 mobs de la collection Nether cette semaine, récompense : un Paquet Nether). Les kills suivent les exclusions de drops (mondes, modes de jeu, mobs de spawner si exclus). Les cartes données par un admin ne comptent pas.

/tcg show

Montre la carte (ou le paquet, le booster) tenue en main dans le chat : « Alice montre : Panda », avec l'infobulle complète de la carte au survol. Délai de 30 s (show.cooldown_seconds, les admins en sont dispensés), portée réglable (show.radius, 0 = tout le serveur).

Payer en argent (Vault)

Avec Vault et un plugin d'économie, la boutique affiche aussi des prix en argent : clic gauche = poussière, clic droit = argent (deux clics pour confirmer). Prix dans config.yml > shop.money (cartes par rareté, paquets) et boosters.yml > money_price. Tout est à 0 par défaut (rien en vente contre de l'argent) : à vous de fixer les prix selon votre économie. Sans Vault, tout fonctionne en poussière.