O que é um arquivo de tesouro?

Os arquivos de tesouro determinam as tabelas de saque para os baús do BetterStructures. Geralmente são atribuídos a geradores mas também podem ser definidos ao nível de uma configuração de construção individual.

Estas tabelas de saque são bastante poderosas, mas também requerem conhecimento de alguns conceitos estatísticos básicos para serem compreendidas.

Leia sobre esses conceitos aqui, o resto da página assume que você os entende!

Probabilidade ponderada

BetterStructures e EliteMobs (outro plugin do mesmo autor) usam o conceito de probabilidade ponderada nos seus sistemas de saque. Isso resolve um problema simples: como definir a chance de escolher um item de uma lista de itens potencialmente infinitos?

A probabilidade ponderada resolve este problema atribuindo um peso a cada item. Se você tem 100 itens e cada um tem peso 1, todos têm a mesma chance - 1% - de serem escolhidos. Se adicionar mais um item, totalizando 101 itens, e der a esse último item um peso de 1, todos os itens ainda terão a mesma chance - ~0.99% - de serem escolhidos. Se der ao último item um peso de 2, a chance dele ser escolhido aumenta - o novo peso total é 102, o último elemento tem peso 2 e 100/102 = ~0.98% então 0.98%+0.98% = 1.96% de chance de ser escolhido. Se der ao último item um peso de 100, o novo peso é 200, e como metade desse peso é do seu novo item, o novo item tem 50% de chance de ser escolhido.

Como pode ver, isso é bom para quando você pode ter listas de centenas de coisas para aleatorizar.

Distribuição gaussiana

Uma distribuição gaussiana é uma função matemática em forma de sino.

Você deve estar se perguntando como isso é relevante para o sistema de saque. Uma coisa que o BetterStructures precisa decidir ao definir o saque dos baús é a quantidade de saque que aparece nesses baús. A quantidade deve ser consistentemente próxima de um número específico, mas idealmente não tão previsível que abrir um baú possa se tornar menos emocionante.

Para alcançar este efeito semi-aleatório, a distribuição gaussiana é usada para aleatorizar quantos itens são escolhidos. Uma vez que esta quantidade é escolhida, a probabilidade ponderada seleciona um elemento da tabela de raridade aleatoriamente, levando os pesos em conta.

Então como funciona a distribuição gaussiana?

Felizmente, você não precisa se preocupar com a matemática por trás, e pode focar nas duas configurações que a modificam: média e desvio padrão.

Média

Simplificando, mean define o meio da curva gaussiana, o que significa que define a quantidade mais provável de itens que aparecerão em um baú. Essencialmente, se quiser que seus baús geralmente tenham 5 itens, defina a média como 5.

Desvio padrão

Imagine que o número médio de itens em um baú é 5. O standard deviation ajuda a decidir o quanto esse número pode variar de um baú para outro.

Standard Deviation pequeno (ex: 1): A maioria dos baús terá itens muito próximos da média, como 4, 5 ou 6 itens. É uma experiência mais previsível. Por exemplo, se um baú tem desvio padrão de 1, você pode esperar que quase todos os baús tenham entre 4 a 6 itens.

Standard Deviation médio (ex: 2): Aqui há mais variedade. Baús podem ter de 3 a 7 itens. Embora 5 itens ainda sejam comuns, não é incomum encontrar baús com um pouco mais ou menos. Então, com desvio padrão de 2, você pode ocasionalmente encontrar um baú com apenas 3 itens, ou se tiver sorte, um com 7 itens.

Standard Deviation grande (ex: 3 ou mais): Agora as coisas ficam realmente surpreendentes! Baús podem ter tão poucos quanto 2 itens ou tantos quanto 8 ou mais. Significa que você pode encontrar um baú com apenas alguns itens, mas também há a chance de encontrar um baú cheio de coisas boas. Por exemplo, com desvio padrão de 3, um baú pode ter de 2 a 8 itens, tornando cada abertura de baú uma aposta emocionante.

A média padrão é 4, e o desvio padrão é 3.

Detalhes de Implementação

Entender como o sistema de tesouro funciona internamente pode ajudá-lo a configurá-lo de forma mais eficaz:

Itens Mínimos Garantidos

O sistema garante que pelo menos um item sempre aparecerá em um baú, mesmo que o cálculo de distribuição gaussiana resulte em zero itens. Isso impede que os jogadores encontrem baús completamente vazios.

Posicionamento Aleatório nos Slots

Os itens são colocados em slots aleatórios dentro do baú em vez de preencher sequencialmente a partir do primeiro slot. Isso cria uma distribuição de saque de aparência mais natural que parece menos artificial.

Tratamento de Erros

Se o material de um item não existir na sua versão do Minecraft (por exemplo, usando uma configuração antiga em uma versão mais nova onde itens foram renomeados), esse item será silenciosamente ignorado em vez de causar erros. Encantamentos inválidos mostrarão um aviso uma vez no console, depois serão suprimidos nas ocorrências seguintes para evitar spam nos logs.

Formato especial

Os arquivos de tesouro têm um formato especial como este:

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 é uma versão bastante resumida. A configuração de tesouro padrão completa, quando exportada para YAML, tem aproximadamente 2599 linhas, pois cobre tabelas de saque extensas e todas as combinações de encantamento possíveis.

isEnabled

Chave	Valores	Padrão
`isEnabled`	Boolean	`true`

mean

Chave	Valores	Padrão
`mean`	Double	`4`

Define a mean. Leia os detalhes sobre isso aqui.

standardDeviation

Chave	Valores	Padrão
`standardDeviation`	Double	`3`

Define o standardDeviation. Leia os detalhes sobre isso aqui.

vanillaTreasure

Chave	Valores	Padrão
`vanillaTreasure`	String	nenhum

Define uma tabela de saque vanilla opcional do Minecraft para usar além do saque personalizado. Isso usa os valores do enum LootTables do Bukkit (ex: BURIED_TREASURE, SHIPWRECK_TREASURE, SIMPLE_DUNGEON). Quando definido, a tabela de saque vanilla será rolada junto com quaisquer itens personalizados definidos na seção items. Se não definido, apenas saque personalizado será usado.

items

É aqui que as coisas ficam complicadas, pois muitas das opções podem ser definidas pelos admins. Vamos ampliar o exemplo do arquivo de configuração anterior.

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

Aqui, você pode ver que sob a chave de configuração items temos um mapa com common e rare. Essas são raridades!

rarities

As raridades não têm nome fixo. Você pode adicioná-las ou removê-las e personalizá-las o quanto quiser, desde que use o mesmo formato.

Note que o que torna estas tabelas de raridade mais ou menos raras é o weight da tabela de saque!

Por padrão:

common tem um weight padrão de 60
rare tem um weight padrão de 30
epic tem um weight padrão de 10

Tornando itens comuns 6x mais prováveis de dropar que itens épicos. Você pode ler mais sobre weights aqui!

Além do peso, cada tabela de raridade tem sua própria lista de items.

rarity items

Os itens de raridade são uma lista de mapa que lista todos os itens que a tabela de raridade possui.

Esses itens têm as seguintes configurações:

Chave	Valores	Padrão
`amount`	min-max Integer	variável
`material`	Material	variável
`procedurallyGenerateEnchantments`	Boolean	variável
`weight`	Double	variável

amount

Define a quantidade a dropar. Pode ser expressa como um intervalo amount: MIN-MAX ou como um valor único amount: VALUE para quantidades fixas. Exemplos:

Quantidade variável: amount: 1-5 (dropa entre 1 e 5 itens)
Quantidade fixa: amount: 3 (sempre dropa exatamente 3)

material

Define o material usando os nomes da API do Spigot do item a potencialmente dropar.

Caso especial - serialized

Ao usar o comando lootify, em vez de um material, lootify fornecerá uma configuração serialized. Isso é gerado automaticamente pelo plugin e não deve ser gerado manualmente. Está em um formato não legível por humanos.

mmoitem

Define um item personalizado do plugin MMOItems. Esta é uma alternativa ao campo material para usar itens personalizados em vez de materiais vanilla do Minecraft.

O formato é: mmoitem: TYPE@ITEMNAME

Exemplo:

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

Nota: Isso requer que o plugin MMOItems esteja instalado. Se o MMOItems não estiver disponível ou o item especificado não existir, a entrada será ignorada com um aviso nos logs do console.

info

Campo opcional para adicionar notas ou comentários a entradas de itens. Este campo é completamente ignorado pelo plugin e existe apenas para fins de documentação administrativa. Use-o para lembrar-se de por que certos itens estão configurados de maneiras específicas.

Exemplo:

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

weight

Define o peso para a chance ponderada. Mais sobre isso aqui.

procedurallyGenerateEnchantments

Define se o item deve ser gerado proceduralmente com base nas configurações em procedurallyGeneratedItemSettings. Note que, dependendo das configurações, isso pode resultar em um item gerado sem encantamentos.

procedurallyGeneratedItemSettings

Vamos dar outra olhada no nosso exemplo de arquivo de configuração:

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

Como pode ver, este arquivo lista tipos de material, seguidos de encantamentos e depois de níveis mínimo e máximo e uma chance.

Note que você não pode adicionar materiais personalizados de outros plugins nestas configurações, e provavelmente não poderá adicionar encantamentos personalizados de outros plugins a menos que o autor diga explicitamente que tornou o sistema compatível.

Quanto às configurações de encantamento:

Chave	Valores	Padrão
`minlevel`	Integer	variável
`maxlevel`	Integer	variável
`chance`	Chance	variável

minlevel

Define o nível mínimo de encantamento.

maxlevel

Define o nível máximo de encantamento.

chance

Define a probabilidade do encantamento ser aplicado, como um valor decimal entre 0.0 (nunca) e 1.0 (sempre). Por exemplo, um valor de 0.2 significa 20% de chance. Isso usa uma verificação de probabilidade simples, não probabilidade ponderada como o sistema de seleção de itens.

Resolução de Problemas

Itens não aparecem nos baús

Verifique se o arquivo de tesouro tem isEnabled: true
Verifique o console por avisos sobre materiais ou itens inválidos
Garanta que o MMOItems está instalado se usar itens personalizados
Os materiais devem usar nomes exatos da API do Spigot

Encantamentos não sendo aplicados

Defina procedurallyGenerateEnchantments: true no item
Verifique se os nomes dos encantamentos correspondem às chaves do Minecraft
Verifique se os níveis mín/máx estão dentro de intervalos válidos para esse encantamento
Lembre-se de que valores de chance são probabilidades (0.2 = 20%), não garantias

Encantamentos personalizados de plugins não funcionam

Apenas encantamentos personalizados que explicitamente suportam integração com BetterStructures funcionarão. Verifique com o autor do plugin de encantamento sobre compatibilidade. Encantamentos inválidos mostrarão um aviso no console sugerindo essa possibilidade.

Baús vazios aparecendo

Isso não deveria acontecer pois o sistema garante pelo menos um item. Se estiver vendo baús vazios, verifique:

Se o baú está sendo preenchido pelo BetterStructures (não por outro plugin)
Se todos os itens no seu arquivo de tesouro são válidos (verifique os avisos no console)
Se o arquivo de tesouro está realmente sendo carregado (verifique os logs de inicialização)

Detalhes de Implementação

Formato especial

isEnabled

mean

standardDeviation

vanillaTreasure

items

rarities​

rarity items​

amount​

material​

Caso especial - serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​