Qu'est-ce qu'un fichier de trésor ?

Les fichiers de trésor déterminent les tables de butin des coffres de BetterStructures. Ils sont généralement assignés aux générateurs, mais peuvent aussi être définis au niveau d'une configuration de construction individuelle.

Ces tables de butin offrent de nombreuses possibilités, mais nécessitent quelques notions de statistiques pour bien les comprendre.

Notions de statistiques

Découvrez ces notions ici : la suite de la page suppose que vous les comprenez !

Probabilité pondérée

BetterStructures et EliteMobs (un autre plugin du même auteur) utilisent tous deux la probabilité pondérée dans leurs systèmes de butin. Elle résout un problème simple : comment définir la probabilité de choisir un objet dans une liste potentiellement infinie ?

La probabilité pondérée attribue un poids à chaque objet. Avec 100 objets ayant chacun un poids de 1, tous ont la même probabilité d'être choisis : 1 %. Si vous ajoutez un objet de poids 1, le total passe à 101 objets et chacun conserve une probabilité identique d'environ 0,99 %. Si ce dernier objet a un poids de 2, le poids total devient 102 : comme 1/102 vaut environ 0,98 %, sa probabilité atteint 0,98 % + 0,98 % = 1,96 %. Si son poids passe à 100, le poids total devient 200. Ce nouvel objet représente alors la moitié du poids total et a donc 50 % de chances d'être choisi.

Cette méthode convient bien aux tirages aléatoires parmi des centaines d'éléments.

Distribution gaussienne

Une distribution gaussienne est une fonction mathématique en forme de cloche.

Quel rapport avec le butin ? BetterStructures doit déterminer la quantité de butin à placer dans chaque coffre. Cette quantité doit rester proche d'une valeur donnée tout en variant suffisamment pour que l'ouverture des coffres reste intéressante.

Pour obtenir cet effet partiellement aléatoire, la distribution gaussienne détermine combien d'objets sont choisis. La probabilité pondérée choisit ensuite un élément de la table de rareté au hasard, en tenant compte des poids.

Alors comment fonctionne la distribution gaussienne ?

Vous n'avez pas besoin de maîtriser les calculs : il suffit de comprendre les deux paramètres qui la modifient, la moyenne et l'écart-type.

Moyenne

mean définit le centre du tirage gaussien utilisé pour choisir le nombre de tentatives de butin. L'implémentation arrondit vers le haut, ramène les résultats négatifs à zéro, puis ajoute une tentative. Une moyenne de 5 ne correspond donc pas à une moyenne exacte de cinq piles d'objets effectivement distribuées.

Écart-type

standardDeviation contrôle la dispersion de ce tirage initial. Avant l'arrondi, environ 68 % des valeurs gaussiennes se trouvent à moins d'un écart-type de la moyenne, et environ 95 % à moins de deux. Avec une moyenne de 5 et un écart-type de 1, environ 68 % des tirages bruts se situent donc entre 4 et 6 ; augmenter ou réduire ce paramètre modifie cette dispersion.

Il s'agit de probabilités, pas de limites minimales ou maximales strictes. Le nombre final de piles distribuées dépend également de la validité des entrées de butin et des emplacements libres de l'inventaire.

La moyenne par défaut est 4 et l'écart-type par défaut est 3.

Détails d'implémentation

Comprendre le fonctionnement interne du système de trésor vous aide à mieux le configurer :

Nombre minimum de tentatives de butin

Pour une liste de raretés personnalisées non vide, le nombre de tentatives de butin est max(ceil(gaussian(mean, standardDeviation)), 0) + 1. Cette tentative supplémentaire signifie que la moyenne configurée n'est pas le nombre moyen final de piles. Au moins une tentative a lieu, mais une table d'objets invalide ou vide, un échec de création d'objet ou l'annulation de l'événement de remplissage peuvent laisser le coffre vide.

Placement dans des emplacements aléatoires

Les objets sont placés dans des emplacements aléatoires du coffre plutôt que successivement à partir du premier. Chaque pile va dans un emplacement vide choisi au hasard, et le contenu existant n'est jamais écrasé. Les tirages s'arrêtent dès que le conteneur n'a plus d'emplacement vide, et un conteneur déjà plein ne reçoit aucun butin, ni personnalisé ni vanilla.

Gestion des erreurs

Si le matériau d'un objet n'existe pas dans votre version de Minecraft (par exemple avec une ancienne configuration utilisée après un renommage d'objets), cet objet est ignoré silencieusement plutôt que de provoquer une erreur. Les entrées d'enchantement qui ne correspondent à aucune clé d'enchantement minecraft: réelle sont elles aussi ignorées silencieusement, tandis qu'un bloc procedurallyGeneratedItemSettings indexé sur un matériau inexistant enregistre un avertissement nommant le fichier.

Un amount absent ou invalide produit un avertissement. Le minimum lu est porté à au moins 1, puis le maximum à au moins ce minimum : une quantité absente devient 1, tandis que 5-2 devient une quantité fixe de 5. Une plage mal formée peut conserver un minimum correctement lu ; corrigez donc le fichier plutôt que de compter sur cette réparation.

Utilisez des poids finis et positifs pour les raretés et leurs objets. Une rareté dont le poids est absent, nul, négatif ou non numérique est omise. Une entrée d'objet dont le poids est absent, négatif ou non numérique est retirée ; les valeurs non numériques et négatives produisent un avertissement nommant le fichier. Un objet de poids 0 reste dans la table mais n'est jamais choisi. Si tous les objets d'une rareté ont un poids de 0, un tirage qui tombe sur cette rareté n'ajoute rien. Une sélection échouée ne produit qu'un avertissement par catégorie tant que le plugin reste chargé, pas un par fichier. Ne comptez pas sur un avertissement pour détecter chaque poids incorrect.

Format particulier

Les fichiers de trésor utilisent le format suivant :

isEnabled: true
mean: 4.0
standardDeviation: 3.0
vanillaTreasure: BURIED_TREASURE
items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0
  epic:
    weight: 10
    items:
    - amount: 2-10
      material: DIAMOND
      weight: 1.0
    - amount: 1-1
      material: DIAMOND_AXE
      weight: 6.0
procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

Cet exemple est abrégé. Les fichiers fournis contiennent davantage d'objets et de paramètres d'enchantement, et certains modèles utilisent d'autres moyennes et écarts-types. La table de nourriture des tonneaux utilise par exemple une moyenne de 1 et un écart-type de 0.7.

isEnabled

Clé	Valeurs	Par défaut
`isEnabled`	Booléen	`true`

Ce champ est enregistré, mais le chargeur de trésors et le tirage de butin actuels ne l'utilisent pas pour désactiver une table. Le passer à false ne suffit pas à arrêter le butin. Désactivez la structure ou le générateur concerné, ou utilisez l'interrupteur de butin des tonneaux pour ces conteneurs.

mean

Clé	Valeurs	Par défaut
`mean`	Double	`4`

Définit mean. Consultez les explications ici.

standardDeviation

Clé	Valeurs	Par défaut
`standardDeviation`	Double	`3`

Définit standardDeviation. Consultez les explications ici.

vanillaTreasure

Clé	Valeurs	Par défaut
`vanillaTreasure`	Chaîne	aucun, sauf dans les fichiers `vanilla_*` fournis

Définit une table de butin vanilla facultative en complément du butin personnalisé. Elle utilise les valeurs de l'énumération LootTables de Bukkit, comme BURIED_TREASURE, SHIPWRECK_TREASURE et SIMPLE_DUNGEON, sans distinction de casse. Le tirage vanilla suit le butin personnalisé et utilise les emplacements encore vides. Sans ce champ, seul le butin personnalisé est utilisé ; un nom invalide produit un avertissement et désactive la partie vanilla.

Lorsque la clé est absente, les fichiers de trésor vanilla fournis utilisent par défaut la table correspondante : vanilla_bastion_treasure.yml utilise BASTION_TREASURE, vanilla_buried_treasure.yml utilise BURIED_TREASURE, vanilla_end_city_treasure.yml utilise END_CITY_TREASURE, vanilla_fishing_treasure.yml utilise FISHING_TREASURE et vanilla_shipwreck_treasure.yml utilise SHIPWRECK_TREASURE. Tout autre fichier doit définir ce champ explicitement ; un nom en vanilla_* ne sélectionne pas à lui seul une table de butin.

items

Cette partie est plus complexe, car de nombreuses options sont définies par les administrateurs. Examinons l'exemple de configuration précédent.

items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0

Sous la clé items, une table associative contient common et rare. Ce sont les raretés !

Raretés

Les raretés n'ont pas de noms imposés. Vous pouvez en ajouter, en supprimer et les personnaliser autant que vous le souhaitez, à condition de respecter ce format.

Le paramètre weight détermine la fréquence de sélection de chaque table de rareté !

Par défaut :

common a un weight de 60
rare a un weight de 30
epic a un weight de 10

Les objets communs ont donc six fois plus de chances d'être obtenus que les objets épiques. Les poids sont expliqués ici !

Outre son poids, chaque table de rareté possède sa propre liste items.

Objets d'une rareté

Les objets d'une rareté forment une liste de tables associatives contenant tous les objets de cette table de rareté.

Ces objets ont les paramètres suivants :

Clé	Valeurs	Par défaut
`amount`	min-max Entier	variable
`material`	Matériau	variable
`procedurallyGenerateEnchantments`	Booléen	variable
`weight`	Double	variable

amount

Définit la quantité de butin. Utilisez une plage amount: MIN-MAX ou une valeur unique amount: VALUE pour une quantité fixe. Exemples :

Quantité variable : amount: 1-5 (donne entre 1 et 5 objets)
Quantité fixe : amount: 3 (donne toujours exactement 3 objets)

material

Définit le matériau de l'objet susceptible d'être obtenu, avec les noms de l'API Spigot.

Cas particulier : serialized

/bs lootify écrit une table associative serialized avec la sérialisation d'objets de Bukkit, en conservant les données de l'objet tenu. Laissez la commande la générer. Utilisez une seule source par entrée : material, serialized ou mmoitem. Si un material valide est aussi présent, il prend le pas sur l'objet sérialisé ou MMOItems. Les enchantements procéduraux ne s'appliquent qu'aux entrées de matériau.

mmoitem

Définit un objet personnalisé du plugin MMOItems. Ce champ remplace material pour utiliser un objet personnalisé au lieu d'un matériau vanilla de Minecraft.

Le format est : mmoitem: TYPE@ITEMNAME

Exemple :

- amount: 1-1
  mmoitem: SWORD@Excalibur
  weight: 1.0

MMOItems est requis. Le champ accepte aussi l'alias mmoitems. Une recherche d'objet invalide produit normalement un avertissement et ignore l'entrée, mais l'absence de MMOItems n'est pas correctement protégée : des classes manquantes peuvent faire échouer le chargement du contenu. Installez la dépendance ou retirez ces entrées avant de charger le fichier.

info

Champ facultatif permettant d'ajouter des notes aux entrées d'objets. Le plugin l'ignore entièrement : il sert uniquement à documenter la configuration pour les administrateurs. Vous pouvez y expliquer les choix de configuration de certains objets.

Exemple :

- amount: 1-1
  material: DIAMOND_SWORD
  weight: 1.0
  info: "Rare drop for completing the dungeon"

weight

Définit le poids utilisé pour le tirage pondéré. Consultez les explications ici.

procedurallyGenerateEnchantments

Détermine si l'objet doit être généré de façon procédurale selon procedurallyGeneratedItemSettings. Selon ces paramètres, l'objet peut tout de même être généré sans enchantement.

procedurallyGeneratedItemSettings

Reprenons notre exemple de configuration :

procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

Ce fichier indique les types de matériaux, puis leurs enchantements et, pour chacun, les niveaux minimum et maximum ainsi qu'une probabilité.

Cette section accepte les matériaux Bukkit et les enchantements enregistrés dans l'espace de noms minecraft:. Les autres espaces de noms d'enchantement sont ignorés. Utilisez une entrée d'objet sérialisé pour conserver un objet fourni par un autre plugin.

Si un fichier de trésor ne possède pas de section procedurallyGeneratedItemSettings, BetterStructures y écrit sa table d'enchantements par défaut. Un fichier qui possède déjà cette section n'utilise que les entrées qu'elle liste.

Les paramètres d'enchantement sont les suivants :

Clé	Valeurs	Par défaut
`minlevel`	Entier	variable
`maxlevel`	Entier	variable
`chance`	Probabilité	variable

minlevel

Définit le niveau minimum d'enchantement. Il doit être au moins égal à 1 et ne pas dépasser maxlevel.

maxlevel

Définit le niveau maximum d'enchantement, inclus dans le tirage. Le plugin ne le limite pas au plafond vanilla : il ajoute les enchantements en contournant les restrictions de niveau de Bukkit. Des valeurs numériques invalides ou une plage inversée peuvent empêcher le chargement ou la création d'objets.

chance

Définit la probabilité d'application de l'enchantement, avec une valeur décimale entre 0.0 (jamais) et 1.0 (toujours). Par exemple, 0.2 correspond à 20 %. Il s'agit d'un test de probabilité simple, sans la pondération utilisée pour la sélection des objets.

Dépannage

Les objets n'apparaissent pas dans les coffres

Vérifiez que la structure et le générateur sont activés et utilisent un fichier de trésor valide ; une substitution du schematic nécessite toujours une table valide dans le générateur
Consultez les avertissements de la console concernant les matériaux ou objets invalides
Assurez-vous que MMOItems est installé si vous utilisez des objets personnalisés
Les matériaux doivent utiliser les noms exacts de l'API Spigot

Les enchantements ne s'appliquent pas

Définissez procedurallyGenerateEnchantments: true sur l'objet
Vérifiez que les noms d'enchantements correspondent aux clés avec espace de noms de Minecraft
Vérifiez que les niveaux min/max respectent les plages valides de cet enchantement
Rappelez-vous que les valeurs de chance sont des probabilités (0.2 = 20 %), pas des garanties

Les enchantements personnalisés d'autres plugins ne fonctionnent pas

Seuls les enchantements enregistrés sous l'espace de noms vanilla minecraft: sont lus. Tout le reste dans un bloc procedurallyGeneratedItemSettings est ignoré sans avertissement : l'absence d'effet d'un enchantement personnalisé est donc le comportement attendu, et non un bug. Vérifiez la compatibilité auprès de l'auteur du plugin d'enchantement.

Des coffres vides apparaissent

Le minimum s'applique aux tentatives de butin, pas aux objets effectivement distribués. Si vous trouvez des coffres vides, vérifiez :

Que le coffre est rempli par BetterStructures, et non par un autre plugin
Que tous les objets du fichier de trésor sont valides, en consultant les avertissements de la console
Que le fichier de trésor est bien chargé, en consultant les journaux de démarrage

Notions de statistiques​

Détails d'implémentation

Format particulier

isEnabled

mean

standardDeviation

vanillaTreasure

items

Raretés​

Objets d'une rareté​

amount​

material​

Cas particulier : serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​