O que é um ficheiro de tesouros?

Os ficheiros de tesouros definem as tabelas de saque dos baús do BetterStructures. Normalmente são atribuídos a geradores, mas também podem ser definidos na configuração de uma construção individual.

Estas tabelas permitem configurar muitos aspetos do saque, mas exigem alguns conceitos básicos de estatística.

Conceitos de estatística

Leia estes conceitos aqui; o resto da página pressupõe que os compreende!

Probabilidade ponderada

O BetterStructures e o EliteMobs, outro plugin do mesmo autor, usam probabilidade ponderada nos seus sistemas de saque. Isto resolve um problema simples: como definir a probabilidade de escolher um objeto de uma lista que pode crescer indefinidamente?

A probabilidade ponderada atribui um peso a cada objeto. Se tiver 100 objetos com peso 1, todos têm a mesma probabilidade de serem escolhidos: 1%. Se acrescentar outro objeto com peso 1, os 101 objetos continuam a ter probabilidades iguais, agora de aproximadamente 0,99%. Se atribuir peso 2 ao último objeto, o peso total passa a 102. Cada unidade de peso vale 1/102, aproximadamente 0,98%, pelo que esse objeto tem aproximadamente 1,96% de probabilidade de ser escolhido. Se lhe atribuir peso 100, o peso total passa a 200. Como esse objeto representa metade do peso total, a sua probabilidade é de 50%.

Este método é útil para escolher aleatoriamente entre centenas de possibilidades.

Distribuição gaussiana

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

Na geração de saque, o BetterStructures precisa de decidir quanto colocar em cada baú. A quantidade deve manter-se normalmente perto de um determinado número, sem tornar a abertura dos baús demasiado previsível.

Para obter este efeito, a distribuição gaussiana determina aleatoriamente quantos objetos tentar escolher. Depois, a probabilidade ponderada escolhe uma entrada da tabela de raridades, tendo em conta os respetivos pesos.

Como funciona a distribuição gaussiana?

Não é necessário conhecer os cálculos internos. Basta compreender as duas definições que a controlam: a média e o desvio padrão.

Média

mean define o centro do sorteio gaussiano usado para determinar o número de tentativas de saque. A implementação arredonda para cima, limita os resultados negativos a zero e acrescenta uma tentativa. Por isso, uma média de 5 não significa que sejam entregues, em média, exatamente cinco pilhas de objetos.

Desvio padrão

standardDeviation controla a dispersão do sorteio inicial. Antes do arredondamento, cerca de 68% dos valores gaussianos ficam a menos de um desvio padrão da média e cerca de 95% ficam a menos de dois. Com média 5 e desvio padrão 1, aproximadamente 68% dos resultados brutos ficam entre 4 e 6. Aumentar ou reduzir o desvio padrão altera essa dispersão.

Estas são probabilidades, não limites mínimos ou máximos absolutos. O número final de pilhas entregues também depende da validade das entradas de saque e dos espaços disponíveis no inventário.

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

Detalhes da implementação

Compreender o funcionamento interno do sistema ajuda a configurá-lo:

Número mínimo de tentativas de saque

Para uma lista de raridades personalizada não vazia, o número de tentativas é max(ceil(gaussian(mean, standardDeviation)), 0) + 1. A tentativa adicional significa que a média configurada não corresponde à média final de pilhas. É feita pelo menos uma tentativa, mas uma tabela de objetos inválida ou vazia, uma falha na criação dos objetos ou o cancelamento do evento de preenchimento podem deixar o baú vazio.

Colocação em espaços aleatórios

Os objetos são colocados em espaços aleatórios do baú, em vez de o preencherem sequencialmente a partir do primeiro espaço. Cada pilha vai para um espaço vazio escolhido ao acaso, e o conteúdo existente nunca é substituído. Os sorteios param quando o contentor deixa de ter espaços vazios, e um contentor que já esteja cheio não recebe saque, nem personalizado nem normal.

Tratamento de erros

Se o material de um objeto não existir na sua versão do Minecraft, por exemplo devido a uma alteração de nome entre versões, a entrada é ignorada silenciosamente. Os encantamentos que não correspondam a uma chave de encantamento real de minecraft: também são ignorados silenciosamente. No entanto, um bloco procedurallyGeneratedItemSettings cuja chave seja um material inexistente gera um aviso com o nome do ficheiro.

Um amount ausente ou inválido gera um aviso. O mínimo lido é aumentado para pelo menos 1 e o máximo para pelo menos esse mínimo. Um valor ausente torna-se 1, enquanto 5-2 se torna uma quantidade fixa de 5. Intervalos mal formados podem manter um mínimo lido com sucesso. Corrija o ficheiro em vez de depender desta reparação.

Use pesos finitos e positivos tanto nas raridades como nos seus objetos. Uma raridade cujo peso esteja em falta, seja zero, negativo ou não seja um número é omitida. Uma entrada de objeto cujo peso esteja em falta, seja negativo ou não seja um número é descartada; os valores não numéricos e negativos geram um aviso com o nome do ficheiro. Um objeto com peso 0 permanece na tabela, mas nunca é escolhido. Se todos os objetos de uma raridade tiverem peso 0, um sorteio que calhe nessa raridade não acrescenta nada. Uma seleção falhada gera apenas um aviso por categoria enquanto o plugin permanece carregado, não um aviso por ficheiro. Não dependa dos avisos para detetar todos os pesos incorretos.

Formato especial

Os ficheiros de tesouros usam o seguinte formato:

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 é um exemplo abreviado. Os ficheiros de tesouros incluídos têm tabelas de objetos e definições de encantamentos maiores. Algumas predefinições usam outras médias e desvios. Por exemplo, a tabela de comida dos barris usa uma média de 1 e um desvio de 0.7.

isEnabled

Chave	Valores	Predefinição
`isEnabled`	Booleano	`true`

Este campo é guardado, mas o carregador de tesouros e o sorteio de saque atuais não o usam para desativar uma tabela. Defini-lo como false não impede, por si só, o saque. Desative a estrutura ou o gerador correspondente, ou use a opção de saque dos barris para os barris.

mean

Chave	Valores	Predefinição
`mean`	Decimal	`4`

Define mean. Consulte a explicação aqui.

standardDeviation

Chave	Valores	Predefinição
`standardDeviation`	Decimal	`3`

Define standardDeviation. Consulte a explicação aqui.

vanillaTreasure

Chave	Valores	Predefinição
`vanillaTreasure`	Texto	nenhuma, exceto nos ficheiros `vanilla_*` incluídos

Define uma tabela de saque opcional do Minecraft para usar além do saque personalizado. Aceita os valores da enumeração LootTables do Bukkit, como BURIED_TREASURE, SHIPWRECK_TREASURE e SIMPLE_DUNGEON, sem distinguir maiúsculas de minúsculas. O sorteio normal decorre depois do saque personalizado e usa os espaços vazios restantes. Sem esta definição, só é usado saque personalizado. Nomes inválidos geram um aviso e desativam a parte normal.

Os ficheiros de tesouros normais incluídos usam por predefinição a tabela correspondente quando a chave está em falta: 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 e vanilla_shipwreck_treasure.yml usa SHIPWRECK_TREASURE. Qualquer outro ficheiro precisa deste campo definido explicitamente; o nome vanilla_*, por si só, não seleciona uma tabela de saque.

items

Esta secção exige mais atenção, porque os administradores podem definir muitas das opções. Vejamos parte do exemplo 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

Dentro da chave items, existe um mapa com common e rare. Estas entradas são as raridades!

Raridades

Os nomes das raridades não são fixos. Pode acrescentá-las, removê-las e personalizá-las, desde que mantenha o mesmo formato.

O que torna uma tabela mais ou menos rara é o seu weight!

Por predefinição:

common tem weight 60.
rare tem weight 30.
epic tem weight 10.

Assim, os objetos comuns têm seis vezes mais probabilidade de sair do que os épicos. Leia mais sobre os pesos aqui.

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

Objetos de uma raridade

Os objetos de uma raridade formam uma lista de mapas com todos os objetos da tabela.

Cada objeto tem as seguintes definições:

Chave	Valores	Predefinição
`amount`	mín.-máx. Inteiro	variável
`material`	Material	variável
`procedurallyGenerateEnchantments`	Booleano	variável
`weight`	Decimal	variável

amount

Define a quantidade a largar. Aceita um intervalo, amount: MIN-MAX, ou um valor fixo, amount: VALUE. Exemplos:

Quantidade variável: amount: 1-5, entre 1 e 5 objetos.
Quantidade fixa: amount: 3, sempre exatamente 3 objetos.

material

Define o material do objeto que pode sair, usando os nomes da API Spigot.

Caso especial: serialized

/bs lootify escreve um mapa serialized através da serialização de objetos do Bukkit, preservando os dados do objeto na mão. Deixe o comando gerá-lo em vez de o construir manualmente. Use apenas uma origem por entrada: material, serialized ou mmoitem. Se também existir um material válido, este tem prioridade sobre o objeto serializado ou do MMOItems. Os encantamentos procedurais aplicam-se apenas a entradas de material.

mmoitem

Define um objeto personalizado do plugin MMOItems. É uma alternativa ao campo material para usar objetos personalizados em vez dos materiais normais do Minecraft.

O formato é mmoitem: TYPE@ITEMNAME.

Exemplo:

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

Exige MMOItems. mmoitems também é aceite como nome alternativo do campo. Uma pesquisa de objeto inválida normalmente gera um aviso e ignora a entrada, mas a ausência de MMOItems não está protegida de forma segura. Classes em falta podem impedir o carregamento do conteúdo. Instale a dependência ou remova estas entradas antes de carregar o ficheiro.

info

Campo opcional para notas ou comentários sobre um objeto. O plugin ignora-o completamente; serve apenas para documentação administrativa. Use-o para recordar o motivo de determinadas configurações.

Exemplo:

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

weight

Define o peso usado na seleção ponderada. Leia mais aqui.

procedurallyGenerateEnchantments

Define se o objeto deve ser gerado proceduralmente com base em procedurallyGeneratedItemSettings. Consoante as definições, o objeto pode ainda assim ser gerado sem encantamentos.

procedurallyGeneratedItemSettings

Vejamos novamente o exemplo:

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

O ficheiro lista os tipos de material, seguidos dos encantamentos e, para cada encantamento, os níveis mínimo e máximo e uma probabilidade.

Esta secção aceita materiais Bukkit e encantamentos registados no espaço de nomes minecraft:. Os outros espaços de nomes são ignorados. Use uma entrada de objeto serializado para preservar um objeto fornecido por outro plugin.

Se um ficheiro de tesouro não tiver a secção procedurallyGeneratedItemSettings, o BetterStructures escreve nele a sua tabela de encantamentos predefinida. Um ficheiro que já tenha a secção usa apenas as entradas que lista.

Definições dos encantamentos:

Chave	Valores	Predefinição
`minlevel`	Inteiro	variável
`maxlevel`	Inteiro	variável
`chance`	Probabilidade	variável

minlevel

Define o nível mínimo do encantamento. Deve ser pelo menos 1 e não pode ultrapassar maxlevel.

maxlevel

Define o nível máximo do encantamento, incluído no sorteio. O plugin não o limita ao máximo normal do Minecraft. Adiciona os encantamentos ignorando as restrições de nível do Bukkit. Valores numéricos inválidos ou intervalos invertidos podem impedir o carregamento ou a criação do objeto.

chance

Define a probabilidade de aplicar o encantamento, como um decimal entre 0.0, nunca, e 1.0, sempre. Por exemplo, 0.2 corresponde a 20%. Usa uma verificação de probabilidade simples, distinta da seleção ponderada dos objetos.

Resolução de problemas

Os objetos não aparecem nos baús

Confirme que a estrutura e o gerador estão ativos e referenciam um ficheiro de tesouros válido. Uma substituição no schematic continua a exigir uma tabela de tesouros válida no gerador.
Procure avisos sobre materiais ou objetos inválidos na consola.
Confirme que o MMOItems está instalado se usar os seus objetos personalizados.
Os materiais têm de usar os nomes exatos da API Spigot.

Os encantamentos não são aplicados

Defina procedurallyGenerateEnchantments: true no objeto.
Confirme que os nomes dos encantamentos correspondem às chaves com espaço de nomes do Minecraft.
Verifique se os níveis mínimo e máximo são válidos para o encantamento.
Os valores de chance são probabilidades, não garantias: 0.2 significa 20%.

Os encantamentos de outros plugins não funcionam

Apenas são lidos os encantamentos registados no espaço de nomes normal minecraft:. Tudo o resto num bloco procedurallyGeneratedItemSettings é ignorado sem aviso. Por isso, um encantamento personalizado que não produz efeito é o comportamento esperado. Consulte o autor do plugin de encantamentos sobre a compatibilidade.

Aparecem baús vazios

O mínimo aplica-se às tentativas de saque, não aos objetos efetivamente colocados. Se encontrar baús vazios, verifique:

Se o baú está a ser preenchido pelo BetterStructures e não por outro plugin.
Se todos os objetos do ficheiro de tesouros são válidos, consultando os avisos da consola.
Se o ficheiro de tesouros está realmente a ser carregado, consultando os registos de arranque.

Conceitos de estatística​

Detalhes da implementação

Formato especial

isEnabled

mean

standardDeviation

vanillaTreasure

items

Raridades​

Objetos de uma raridade​

amount​

material​

Caso especial: serialized​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​