¿Qué es un archivo de tesoro?

Los archivos de tesoro son los que determinan las tablas de botín para los cofres de BetterStructures. Generalmente se asignan a [generadores](../Better Structures/creating_generators.md#treasurefilename) pero también se pueden establecer a nivel de una [configuración de construcción individual](../Better Structures/creating_structures.md#treasurefile).

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

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

Probabilidad ponderada

BetterStructures y EliteMobs utilizan frecuentemente el concepto de probabilidad ponderada. Esto es para resolver un problema simple: ¿cómo puedes establecer la posibilidad de elegir un objeto de una lista de objetos potencialmente infinitos?

La probabilidad ponderada resuelve este problema dando a cada objeto un peso. Si tienes 100 objetos y cada uno tiene un peso de 1, entonces todos tienen la misma posibilidad - 1% - de ser elegidos. Si agregas un objeto más, llevando el total a 101 objetos, y le das a ese último objeto una posibilidad de 1, todos los objetos aún tienen la misma posibilidad - ~0.99% - de ser elegidos. Si le das al último objeto un peso de 2, la posibilidad de que sea elegido aumenta - el nuevo peso total es 102, el último elemento tiene un peso de 2 y 100/102 = ~0.98% entonces 0.98%+0.98% = 1.96% de posibilidad de ser elegido. Si le das al último objeto un peso de 100, el nuevo peso es 200, y como la mitad de ese peso es tu nuevo objeto, tu nuevo objeto tiene un 50% de posibilidad de ser elegido.

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

Distribución gaussiana

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

Puede que te estés preguntando cómo es esto relevante para el sistema de botín. Una cosa que BetterStructures tiene que decidir al establecer botín en cofres es simplemente cuánto botín aparece en esos cofres. La cantidad debe ser consistentemente alrededor de un número específico, pero idealmente no tan predecible que abrir un cofre pueda volverse menos emocionante.

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

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

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

Media

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

Desviación estándar

Imagina que el número promedio de objetos 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 (por ejemplo, 1): Esto significa que la mayoría de los cofres tendrán objetos muy cercanos al promedio, como 4, 5 o 6 objetos. 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 a 6 objetos.

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

Standard Deviation grande (por ejemplo, 3 o más): ¡Ahora las cosas se ponen realmente sorprendentes! Los cofres podrían tener tan pocos como 2 objetos o tantos como 8 o más. Significa que podrías encontrar un cofre con solo un par de objetos, pero también hay una 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 a 8 objetos, haciendo que cada apertura de cofre sea una apuesta emocionante.

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

Detalles de Implementación

Entender cómo funciona internamente el sistema de tesoros puede ayudarte a configurarlo de manera más efectiva:

Elementos Mínimos Garantizados

El sistema garantiza que al menos un elemento siempre aparecerá en un cofre, incluso si el cálculo de la distribución Gaussiana resultaría en cero elementos. Esto evita que los jugadores encuentren cofres completamente vacíos.

Colocación Aleatoria en Ranuras

Los elementos se colocan en ranuras aleatorias dentro del cofre en lugar de llenarse secuencialmente desde la primera ranura. Esto crea una distribución de botín de aspecto más natural que se siente menos artificial.

Manejo de Errores

Si un material de elemento no existe en tu versión de Minecraft (por ejemplo, usando una configuración antigua en una versión más nueva donde los elementos fueron renombrados), ese elemento se omitirá 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 subsiguientes para evitar spam en los registros.

Formato especial

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

isEnabled: true
mean: 4.0
standardDeviation: 3.0
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 recortada del archivo, el archivo real tiene 2599 líneas ya que cubre mucho más botín y cada posible encantamiento.

isEnabled

Key	Values	Default
`isEnabled`	Boolean	`true`

mean

Key	Values	Default
`mean`	Double	`4`

Establece la mean. Lee los detalles sobre eso aquí.

standardDeviation

Key	Values	Default
`standardDeviation`	Double	`3`

Establece la standardDeviation. Lee los detalles sobre eso aquí.

items

Aquí es donde se pone complicado, ya que muchas de las opciones pueden ser establecidas por los administradores. Hagamos zoom en 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!

rarities

Las rarezas no tienen un nombre fijo. Puedes agregarlas o eliminarlas, y personalizarlas tanto como quieras, siempre y cuando uses el mismo formato.

Ten en cuenta que lo que hace que estas tablas de rareza sean 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 objetos comunes sean 6 veces más probables de caer que los objetos épicos. ¡Puedes leer más sobre los weights aquí!

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

rarity items

Los objetos de rareza son una map list que lista todos los objetos que tiene la tabla de rareza.

Estos objetos tienen las siguientes configuraciones:

Key	Values	Default
`amount`	min-max Integer	variable
`material`	Material	variable
`procedurallyGenerateEnchantments`	Boolean	variable
`weight`	Double	variable

amount

Establece la cantidad a soltar. Esto se expresa como un rango de la siguiente manera amount: MIN-MAX. Como ejemplo, para soltar entre 1 a 5 objetos: amount: 1-5.

material

Establece el material usando los nombres de la API de Spigot del objeto a potencialmente soltar.

Caso especial - serialized

Cuando se usa 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 ser generado manualmente. Está en un formato que no es legible para humanos.

mmoitem

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

El formato es: mmoitem: TYPE@ITEMNAMEEjemplo:yml- amount: 1-1 mmoitem: SWORD@Excalibur weight: 1.0Nota: Esto requiere que el plugin MMOItems esté instalado. Si MMOItems no está disponible o el elemento especificado no existe, la entrada se omitirá con una advertencia en los registros de la consola.

info

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

Ejemplo:yml- amount: 1-1 material: DIAMOND_SWORD weight: 1.0 info: "Botín raro por completar la mazmorra"***

weight

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

procedurallyGenerateItems

Establece si el objeto debe ser generado proceduralmente basándose en las configuraciones de procedurallyGeneratedItemSettings. Ten en cuenta que basándose en las configuraciones esto podría resultar en un objeto generándose sin encantamientos de todos modos.

procedurallyGeneratedItemSettings

Echemos 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 seguidos de niveles mínimos y máximos y una posibilidad.

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 que su sistema sea compatible.

En cuanto a las configuraciones de encantamiento:

Key	Values	Default
`minLevel`	Integer	variable
`maxLevel`	Integer	variable
`chance`	Chance	variable

minLevel

Establece el nivel mínimo de encantamiento.

maxLevel

Establece el nivel máximo de encantamiento.

chance

Establece la posibilidad de que ocurra el encantamiento. Esto no usa probabilidad ponderada, solo un lanzamiento de dados normal.

Solución de Problemas

Los elementos no aparecen en los cofres

Verifica que el archivo de tesoro tenga isEnabled: true
Revisa la consola para advertencias sobre materiales o elementos inválidos
Asegúrate de que MMOItems esté instalado si usas elementos personalizados
Los materiales deben usar nombres exactos de la API de Spigot

Los encantamientos no se aplican

Establece procedurallyGenerateEnchantments: true en el elemento
Verifica que los nombres de encantamientos coincidan con las claves con espacio de nombres de Minecraft
Revisa que los niveles mínimos/máximos estén dentro de rangos válidos para ese encantamiento
Recuerda que los valores de chance son probabilidades (0.2 = 20%), no garantías

Los encantamientos personalizados de plugins no funcionan

Solo los encantamientos personalizados que explícitamente soportan 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.

Aparecen cofres vacíos

Esto no debería suceder ya que el sistema garantiza al menos un elemento. Si estás viendo cofres vacíos, verifica:

Que el cofre esté siendo poblado por BetterStructures (no otro plugin)
Que todos los elementos en tu archivo de tesoro sean válidos (revisa las advertencias de la consola)
Que el archivo de tesoro esté siendo realmente cargado (revisa los registros de inicio)

Detalles de Implementación

Formato especial

isEnabled

mean

standardDeviation

items

rarities​

rarity items​

amount​

material​

Caso especial - serialized​

mmoitem​

info​

weight​

procedurallyGenerateItems​