Saltar al contenido principal

¿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](../Better Structures/creating_generators.md#treasurefilename) pero también pueden configurarse a nivel de una [configuración de construcción individual](../Better Structures/creating_structures.md#treasurefile).

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

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 dando a cada item un peso. Si tienes 100 items y cada uno tiene un peso de 1, entonces todos tienen la misma probabilidad - 1% - de ser elegidos. Si agregas un item más, llevando el total a 101 items, y le das al último item una probabilidad de 1, todos los items siguen teniendo la misma probabilidad - ~0.99% - de ser elegidos. Si le das al último item un peso de 2, la probabilidad de que sea elegido aumenta - el nuevo peso total es 102, el último elemento tiene un peso de 2 y 100/102 = ~0.98% así que 0.98%+0.98% = 1.96% de probabilidad de ser elegido. Si le das al último item un peso de 100, el nuevo peso es 200, y como la mitad de ese peso es tu nuevo item, tu nuevo item tiene un 50% de probabilidad de ser elegido.

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

En pocas palabras, mean establece el centro de la curva gaussiana, lo que significa que establece la cantidad más probable de items que aparecerán en un cofre. Esencialmente, si quieres que tus cofres usualmente tengan 5 items, establece tu media en 5.

Desviación estándar

Imagina que el número promedio de items en un cofre es 5. La standard deviation ayuda a decidir cuánto puede cambiar este número de un cofre a otro.

Standard Deviation pequeña (ej., 1): Esto significa que la mayoría de los cofres tendrán items muy cerca del promedio, como 4, 5 o 6 items. Es una experiencia más predecible. Por ejemplo, si un cofre tiene una desviación estándar de 1, puedes esperar que casi todos los cofres tengan entre 4 y 6 items.

Standard Deviation mediana (ej., 2): Aquí hay más variedad. Los cofres podrían tener de 3 a 7 items. Aunque 5 items siguen siendo comunes, no es inusual encontrar cofres con un poco más o menos. Así, con una desviación estándar de 2, podrías ocasionalmente encontrar un cofre con solo 3 items, o si tienes suerte, uno con 7 items.

Standard Deviation grande (ej., 3 o más): ¡Ahora las cosas se ponen realmente sorprendentes! Los cofres podrían tener tan pocos como 2 items o tantos como 8 o más. Significa que podrías encontrar un cofre con solo un par de items, pero también hay posibilidad de encontrar un cofre cargado de tesoros. Por ejemplo, con una desviación estándar de 3, un cofre podría tener entre 2 y 8 items, haciendo de cada apertura de cofre una apuesta emocionante.

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:

Items mínimos garantizados

El sistema garantiza que siempre aparecerá al menos un item en un cofre, incluso si el cálculo de distribución gaussiana resulta en cero items. Esto previene que los jugadores encuentren cofres completamente vacíos.

Colocación aleatoria en slots

Los items se colocan en slots aleatorios dentro del cofre en lugar de llenar secuencialmente desde el primer slot. Esto crea una distribución de botín más natural que se siente menos artificial.

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. Los encantamientos inválidos mostrarán una advertencia una vez en la consola, luego se suprimirán en ocurrencias subsecuentes para evitar spam en los logs.

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

Nota: esta es una versión muy resumida. La configuración completa de tesoro predeterminada, cuando se exporta a YAML, tiene aproximadamente 2599 líneas ya que cubre tablas de botín extensas y cada combinación posible de encantamientos.

isEnabled

ClaveValoresPredeterminado
isEnabledBooleantrue

mean

ClaveValoresPredeterminado
meanDouble4

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

standardDeviation

ClaveValoresPredeterminado
standardDeviationDouble3

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

vanillaTreasure

ClaveValoresPredeterminado
vanillaTreasureStringninguno

Establece una tabla de botín vanilla de Minecraft opcional para usar además del botín personalizado. Usa los valores enum LootTables de Bukkit (ej., BURIED_TREASURE, SHIPWRECK_TREASURE, SIMPLE_DUNGEON). Cuando se establece, la tabla de botín vanilla se tirará junto con cualquier item personalizado definido en la sección items. Si no se establece, solo se usará botín personalizado.

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)!

rarities​

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.

rarity items​

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:

ClaveValoresPredeterminado
amountmin-max Integervariable
materialMaterialvariable
procedurallyGenerateEnchantmentsBooleanvariable
weightDoublevariable

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​

Al usar el comando lootify, en lugar de un material lootify proporcionará una configuración serialized. Esto es generado automáticamente por el plugin y no debe generarse manualmente. Está en un formato no legible por humanos.

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

Nota: Esto requiere que el plugin MMOItems esté instalado. Si MMOItems no está disponible o el item especificado no existe, la entrada se omitirá con una advertencia en los logs de la consola.

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.

Ten en cuenta que no puedes agregar materiales personalizados de otros plugins en estas configuraciones, y probablemente no puedas agregar encantamientos personalizados de otros plugins a menos que su autor diga explícitamente que han hecho su sistema compatible.

En cuanto a las configuraciones de encantamientos:

ClaveValoresPredeterminado
minlevelIntegervariable
maxlevelIntegervariable
chanceChancevariable

minlevel​

Establece el nivel mínimo de encantamiento.

maxlevel​

Establece el nivel máximo de encantamiento.

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 el archivo de tesoro tenga isEnabled: true
  • 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 los encantamientos personalizados que explícitamente soporten la integración con BetterStructures funcionarán. Consulta con el autor del plugin de encantamientos sobre la compatibilidad. Los encantamientos inválidos mostrarán una advertencia en la consola sugiriendo esta posibilidad.

Cofres vacíos apareciendo

Esto no debería suceder ya que el sistema garantiza al menos un item. Si estás viendo 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)