¿Qué es un archivo de tesoro?

Los archivos de tesoro son los que determinan las tablas de botín para los cofres de BetterStructures. Usualmente se asignan a generadores pero también pueden configurarse a nivel de una configuración de construcción individual.

Estas tablas de botín son bastante poderosas, pero también requieren conocimiento de algunos conceptos básicos de estadística para entenderlas.

Conceptos de estadística

Lee sobre esos conceptos aquí, ¡el resto de la página asume que los entiendes!

Probabilidad ponderada

BetterStructures y EliteMobs (otro plugin del mismo autor) usan el concepto de probabilidad ponderada en sus sistemas de botín. Esto resuelve un problema simple: ¿cómo puedes establecer la probabilidad de elegir un item de una lista potencialmente infinita de items?

La probabilidad ponderada resuelve este problema asignando un peso a cada objeto. Si tienes 100 objetos con un peso de 1 cada uno, todos tienen la misma probabilidad de ser elegidos: 1%. Si añades otro objeto con peso 1, el total pasa a 101 y todos siguen teniendo la misma probabilidad: aproximadamente 0.99%. Si asignas un peso de 2 al último objeto, aumenta su probabilidad: el peso total es 102, ese objeto tiene peso 2 y 1/102 = ~0.98%, por lo que 0.98% + 0.98% = 1.96%. Si asignas al último objeto un peso de 100, el peso total pasa a 200 y, como ese objeto representa la mitad, su probabilidad de ser elegido es del 50%.

Como puedes ver, esto es bueno para usar cuando podrías tener listas de cientos de cosas para aleatorizar.

Distribución gaussiana

Una distribución gaussiana es una función matemática con forma de campana.

Quizás te preguntes cómo es relevante esto para el sistema de botín. Una cosa que BetterStructures debe decidir al configurar el botín en cofres es cuánto botín aparece en esos cofres. La cantidad debería estar consistentemente alrededor de un número específico, pero idealmente no tan predecible que abrir un cofre se vuelva menos emocionante.

Para lograr este efecto semi-aleatorio, se usa la distribución gaussiana para aleatorizar cuántos items se eligen. Una vez que se elige esta cantidad, la probabilidad ponderada selecciona un elemento de la tabla de rareza al azar teniendo en cuenta los pesos.

¿Entonces cómo funciona la distribución gaussiana?

Afortunadamente, no tienes que preocuparte por cómo funcionan las matemáticas detrás, y puedes enfocarte en las dos configuraciones que la modifican: media y desviación estándar.

Media

mean establece el centro de la tirada gaussiana usada para elegir el número de intentos de botín. La implementación redondea hacia arriba, limita los resultados negativos a cero y añade un intento, por lo que una media de 5 no equivale a un promedio de exactamente cinco pilas entregadas.

Desviación estándar

standardDeviation controla la dispersión de esa tirada inicial. Antes de redondear, aproximadamente el 68% de los valores gaussianos quedan a una desviación estándar de la media y el 95% a dos. Una media de 5 y una desviación estándar de 1 sitúan aproximadamente el 68% de las tiradas sin procesar entre 4 y 6; valores mayores o menores cambian esa dispersión.

Son probabilidades, no mínimos ni máximos estrictos. El número final de pilas entregadas también depende de que las entradas de botín sean válidas y haya ranuras de inventario disponibles.

La media predeterminada es 4 y la desviación estándar predeterminada es 3.

Detalles de implementación

Comprender cómo funciona internamente el sistema de tesoros puede ayudarte a configurarlo más efectivamente:

Intentos mínimos de botín

Para una lista de rarezas personalizada no vacía, el número de intentos de botín es max(ceil(gaussian(mean, standardDeviation)), 0) + 1. El intento adicional significa que la media configurada no es el promedio final de pilas. Se realiza al menos un intento, pero una tabla de objetos inválida o vacía, un fallo al crear el objeto o un evento de llenado de cofre cancelado pueden dejar el cofre vacío.

Colocación aleatoria en ranuras

Los objetos se colocan en ranuras aleatorias del cofre en lugar de llenarlo en orden desde la primera ranura. Cada pila va a una ranura vacía elegida al azar, y el contenido existente nunca se sobrescribe. Las tiradas se detienen cuando el contenedor ya no tiene ranuras vacías, y un contenedor que ya está lleno no recibe botín, ni personalizado ni vanilla.

Manejo de errores

Si un material de item no existe en tu versión de Minecraft (por ejemplo, usando una configuración antigua en una versión más nueva donde los items fueron renombrados), ese item será omitido silenciosamente en lugar de causar errores. Las entradas de encantamiento que no se correspondan con una clave de encantamiento minecraft: real también se omiten en silencio, mientras que un bloque procedurallyGeneratedItemSettings indexado por un material que no existe registra una advertencia nombrando el archivo.

Un amount ausente o inválido genera una advertencia. El mínimo leído se eleva al menos a 1 y el máximo al menos a ese mínimo: un valor ausente se convierte en 1, mientras que 5-2 se convierte en una cantidad fija de 5. Un rango mal formado puede conservar un mínimo que se haya leído correctamente; corrige el archivo en lugar de depender de esta reparación.

Usa pesos finitos y positivos tanto para las rarezas como para sus objetos. Se omite una rareza cuyo peso falte, sea cero, negativo o no sea un número. Se descarta una entrada de objeto cuyo peso falte, sea negativo o no sea un número; los valores no numéricos y negativos registran una advertencia que nombra el archivo. Un objeto con peso 0 permanece en la tabla, pero nunca se elige. Si todos los objetos de una rareza tienen peso 0, una tirada que caiga en esa rareza no añade nada. Una selección fallida solo genera una advertencia por categoría mientras el plugin siga cargado, no una por archivo. No dependas de una advertencia para detectar todos los pesos incorrectos.

Formato especial

Los archivos de tesoro tienen un formato especial que se ve así:

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

Este es un ejemplo abreviado. Los archivos de tesoro incluidos contienen tablas de objetos y ajustes de encantamientos más extensos, y algunos usan otras medias y desviaciones. Por ejemplo, la tabla de comida para barriles usa una media de 1 y una desviación de 0.7.

isEnabled

Clave	Valores	Predeterminado
`isEnabled`	Boolean	`true`

Este campo se guarda, pero el cargador de tesoros y el sorteo de botín actuales no lo usan para desactivar una tabla. Ponerlo en false por sí solo no detiene el botín. Desactiva la estructura o el generador correspondiente, o usa el interruptor de botín de barriles para estos contenedores.

mean

Clave	Valores	Predeterminado
`mean`	Double	`4`

Establece el mean. Lee los detalles al respecto aquí.

standardDeviation

Clave	Valores	Predeterminado
`standardDeviation`	Double	`3`

Establece la standardDeviation. Lee los detalles al respecto aquí.

vanillaTreasure

Clave	Valores	Predeterminado
`vanillaTreasure`	String	ninguno, salvo en los archivos `vanilla_*` incluidos

Establece una tabla opcional de botín vanilla de Minecraft, además del botín personalizado. Usa valores de la enumeración LootTables de Bukkit (por ejemplo, BURIED_TREASURE, SHIPWRECK_TREASURE, SIMPLE_DUNGEON) sin distinguir mayúsculas. El sorteo vanilla ocurre después del personalizado y usa las ranuras vacías restantes. Si no se establece, solo se usa botín personalizado; los nombres inválidos generan una advertencia y desactivan la parte vanilla.

Los archivos de tesoro vanilla incluidos usan por defecto su tabla correspondiente cuando falta la clave: vanilla_bastion_treasure.yml usa BASTION_TREASURE, vanilla_buried_treasure.yml usa BURIED_TREASURE, vanilla_end_city_treasure.yml usa END_CITY_TREASURE, vanilla_fishing_treasure.yml usa FISHING_TREASURE y vanilla_shipwreck_treasure.yml usa SHIPWRECK_TREASURE. Cualquier otro archivo necesita el campo definido explícitamente; un nombre vanilla_* por sí solo no selecciona una tabla de botín.

items

Aquí es donde se pone complicado, ya que muchas de las opciones pueden ser configuradas por administradores. Veamos de cerca el ejemplo del archivo de configuración de antes.

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

Aquí puedes ver que bajo la clave de configuración items tenemos un mapa con common y rare. ¡Estas son rarities (rarezas)!

Rarezas

Las rarezas no tienen un nombre fijo. Puedes agregar o eliminar y personalizarlas tanto como quieras, siempre que uses el mismo formato.

¡Ten en cuenta que lo que hace estas tablas de rareza más o menos raras es el weight de la tabla de botín!

Por defecto:

common tiene un weight predeterminado de 60
rare tiene un weight predeterminado de 30
epic tiene un weight predeterminado de 10

Haciendo que los items comunes sean 6x más probables de caer que los items épicos. ¡Puedes leer más sobre weights aquí!

Aparte del peso, cada tabla de rareza tiene su propia lista de items.

Objetos de cada rareza

Los items de rareza son una lista de mapas que lista todos los items que tiene la tabla de rareza.

Estos items tienen las siguientes configuraciones:

Clave	Valores	Predeterminado
`amount`	min-max Integer	variable
`material`	Material	variable
`procedurallyGenerateEnchantments`	Boolean	variable
`weight`	Double	variable

amount

Establece la cantidad a soltar. Esto puede expresarse como un rango amount: MIN-MAX o como un valor único amount: VALUE para cantidades fijas. Ejemplos:

Cantidad variable: amount: 1-5 (suelta entre 1 y 5 items)
Cantidad fija: amount: 3 (siempre suelta exactamente 3)

material

Establece el material usando los nombres de la API de Spigot del item que podría soltarse.

Caso especial: serialized

/bs lootify escribe un mapa serialized mediante la serialización de objetos de Bukkit y conserva los datos del objeto sostenido. Deja que el comando lo genere en vez de construirlo manualmente. Usa una sola fuente por entrada: material, serialized o mmoitem. Si también hay un material válido, tiene prioridad sobre el objeto serializado o de MMOItems. Los encantamientos procedurales solo se aplican a entradas de material.

mmoitem

Establece un item personalizado del plugin MMOItems. Esta es una alternativa al campo material para usar items personalizados en lugar de materiales vanilla de Minecraft.

El formato es: mmoitem: TYPE@ITEMNAME

Ejemplo:

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

Esto requiere MMOItems. También se acepta mmoitems como alias del campo. Las búsquedas de objetos inválidos normalmente generan una advertencia y omiten la entrada, pero la ausencia de MMOItems no está protegida de forma segura: la falta de clases puede hacer fallar la carga de contenido. Instala la dependencia o elimina estas entradas antes de cargar el archivo.

info

Campo opcional para agregar notas o comentarios a las entradas de items. Este campo es completamente ignorado por el plugin y existe únicamente para propósitos de documentación administrativa. Úsalo para recordarte por qué ciertos items están configurados de ciertas maneras.

Ejemplo:

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

weight

Establece el peso para la probabilidad ponderada. Más sobre eso aquí.

procedurallyGenerateEnchantments

Establece si el item debe generarse proceduralmente basándose en las configuraciones en procedurallyGeneratedItemSettings. Ten en cuenta que según las configuraciones esto podría resultar en un item generado sin encantamientos.

procedurallyGeneratedItemSettings

Veamos otro vistazo a nuestro ejemplo de archivo de configuración:

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

Como puedes ver, este archivo lista tipos de materiales, seguidos de encantamientos y luego niveles mínimos y máximos y una probabilidad.

Esta sección acepta materiales de Bukkit y encantamientos registrados bajo el espacio de nombres minecraft:. Los demás espacios de nombres de encantamientos se omiten. Usa una entrada de objeto serializado cuando necesites conservar un objeto proporcionado por otro plugin.

Si un archivo de tesoro no tiene sección procedurallyGeneratedItemSettings, BetterStructures escribe en él su tabla de encantamientos predeterminada. Un archivo que ya tiene la sección usa solo las entradas que enumera.

En cuanto a las configuraciones de encantamientos:

Clave	Valores	Predeterminado
`minlevel`	Integer	variable
`maxlevel`	Integer	variable
`chance`	Chance	variable

minlevel

Establece el nivel mínimo de encantamiento. Debe ser al menos 1 y no superar maxlevel.

maxlevel

Establece el nivel máximo de encantamiento, incluido en el sorteo. El plugin no lo limita al máximo vanilla: añade encantamientos omitiendo las restricciones de nivel de Bukkit. Valores numéricos inválidos o rangos invertidos pueden impedir la carga o la creación del objeto.

chance

Establece la probabilidad de que el encantamiento sea aplicado, como un valor decimal entre 0.0 (nunca) y 1.0 (siempre). Por ejemplo, un valor de 0.2 significa un 20% de probabilidad. Esto usa una verificación de probabilidad simple, no probabilidad ponderada como el sistema de selección de items.

Solución de problemas

Items que no aparecen en cofres

Verifica que la estructura y el generador estén activados y usen un archivo de tesoro válido; una sustitución del schematic sigue necesitando una tabla válida en el generador
Revisa la consola para advertencias sobre materiales o items inválidos
Asegúrate de que MMOItems esté instalado si usas items personalizados
Los materiales deben usar nombres exactos de la API de Spigot

Encantamientos que no se aplican

Establece procedurallyGenerateEnchantments: true en el item
Verifica que los nombres de encantamientos coincidan con las namespaced keys de Minecraft
Comprueba que los niveles min/max estén dentro de los rangos válidos para ese encantamiento
Recuerda que los valores de chance son probabilidades (0.2 = 20%), no garantías

Encantamientos de plugins personalizados que no funcionan

Solo se leen los encantamientos registrados bajo el namespace vanilla minecraft:. Cualquier otra cosa en un bloque procedurallyGeneratedItemSettings se omite sin advertencia, así que un encantamiento personalizado que en silencio no hace nada es el síntoma esperado, no un fallo. Consulta con el autor del plugin de encantamientos sobre la compatibilidad.

Cofres vacíos apareciendo

El mínimo se aplica a los intentos de botín, no a los objetos obtenidos correctamente. Si ves cofres vacíos, verifica:

Que el cofre esté siendo llenado por BetterStructures (no otro plugin)
Que todos los items en tu archivo de tesoro sean válidos (revisa advertencias de consola)
Que el archivo de tesoro esté realmente cargándose (revisa los logs de inicio)

Conceptos de estadística​

Detalles de implementación

Formato especial

isEnabled

mean

standardDeviation

vanillaTreasure

items

Rarezas​

Objetos de cada rareza​

amount​

material​

Caso especial: serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​