03. Guia de Configuração de Trocas (JSON) — Wiki Oficial

Esta página detalha a estrutura dos arquivos JSON de trocas do Visiting Villagers, explicando a sintaxe de itens fixos, famílias dinâmicas (family), listas aleatórias (one_of), tipos especiais e o sistema de recarga sem reiniciar o jogo.

Os catálogos de trocas dos visitantes ficam armazenados na pasta: config/visitingvillagers/trades/

• 23 Arquivos Padrão: Na primeira inicialização, o mod copia 23 arquivos .json padrão (um para cada variante de visitante adulto e andarilho) para essa pasta.
• Preservação de Edições: O mod nunca sobrescreve um arquivo existente na pasta config/. Para restaurar o padrão de uma variante, basta excluir seu arquivo .json correspondente e reiniciar o jogo.

O nome do arquivo (sem .json) deve corresponder a uma das 23 chaves conhecidas pelo mod. Arquivos com nomes fora dessa lista são descartados no carregamento (o mod cai no fallback sem aplicar o catálogo):

Cada arquivo .json representa uma variante e é dividido em dois pools independentes: buys (compras do NPC) e sells (vendas do NPC).

{
  "variant": "miner",
  "buys": {
    "select": 3,
    "trades": [
      {
        "cost": { "id": "minecraft:dandelion", "count": 12 },
        "result": { "id": "minecraft:emerald", "count": 1 },
        "max_uses": 8,
        "xp": 2,
        "price_multiplier": 0.05
      }
    ]
  },
  "sells": {
    "select": 3,
    "trades": [
      {
        "cost": { "id": "minecraft:emerald", "count": 10 },
        "result": { "id": "minecraft:diamond", "count": 1 }
      }
    ]
  }
}

*Nota: Nos tipos especiais (type), o campo type substitui o result.

Define um item específico com quantidade exata (de 1 a 99) e suporte a Data Components nativos da versão 1.21.1:

{
  "id": "minecraft:diamond_sword",
  "count": 1,
  "components": {
    "minecraft:custom_name": "Relíquia Antiga",
    "minecraft:damage": 120
  }
}

• Custos com Componentes: Em ofertas de compra (cost), o jogador precisa entregar exatamente o item com os componentes especificados (mesmo nome, encantamento ou dano).

Em vez de listar dezenas de itens individualmente, o seletor de famílias sorteia um item concreto da família por oferta a cada reabastecimento:

{ "family": "log", "count": 16 }
{ "family": "wool", "colors": ["white", "black"], "count": 16 }
{ "family": "sapling", "variant": "cherry", "count": 1 }

• Sem Filtro: O mod utiliza a lista padrão automática (ex: as 16 cores para wool/dye/stained_glass, madeiras registradas para log/planks, 7 espécies para sapling, ou faz um scan do registro para pottery_sherd e armor_trim_smithing_template).
• Com Filtro: Permite restringir o sorteio usando color / colors (famílias de cores) ou variant / variants (famílias de madeiras/espécies).

Não existe uma lista fixa de nomes de família — a validação é dinâmica contra o registro de itens do jogo pelo padrão de nomenclatura minecraft:<prefixo>_<family>:

• Famílias de cor: a família é válida se existir minecraft:<cor>_<family> para todas as 16 cores de tinta (ex: wool, carpet, bed, banner, terracotta, stained_glass, candle, shulker_box, dye, concrete_powder etc.).
• Famílias de madeira/espécie: válida se existir minecraft:<tipo>_<family> para os tipos pedidos — os 11 conjuntos de madeira vanilla (oak, spruce, birch, jungle, acacia, dark_oak, mangrove, cherry, bamboo, crimson, warped) ou as 7 espécies de sapling (oak, spruce, birch, jungle, acacia, dark_oak, cherry).
• Demais grupos (pottery_sherd, armor_trim_smithing_template): resolvidos por scan de todos os itens registrados que terminam com _<family>.

💡 Dica: se o nome de família não seguir o padrão de nomenclatura, use o seletor one_of com os IDs completos — é o escape recomendado. Um item faltante na família (missingColor/missingVariant) causa erro de validação no log.

Para grupos de itens que não compartilham um sufixo de nome comum (como alimentos, flores ou sementes), defina uma lista de IDs completos:

{
  "cost": {
    "one_of": [
      "minecraft:dandelion",
      "minecraft:poppy",
      "minecraft:blue_orchid",
      "minecraft:lily_of_the_valley"
    ],
    "count": 12
  },
  "result": { "id": "minecraft:emerald", "count": 1 }
}

• Sorteia um único item da lista por oferta gerada e suporta itens de outros mods registrados no runtime.

Quatro tipos originais realizam o sorteio do item resultante no momento exato da transação. Nesses tipos, o campo type substitui o result e o custo deve ser em esmeraldas:

{
  "type": "random_enchanted_book",
  "cost": { "id": "minecraft:emerald", "count": 5 },
  "max_uses": 12,
  "xp": 15
}

Para aplicar alterações nos arquivos JSON sem reiniciar o servidor ou o jogo:

1. Edite ou crie os arquivos .json na pasta config/visitingvillagers/trades/.
2. No chat do jogo, execute o comando de administrador (nível de permissão 2):

   /visitors reloadtrades
   

• Efeito: O mod recarrega os arquivos, valida a sintaxe e limpa o cache de ofertas dos visitantes carregados que não estejam em negociação aberta. As novas ofertas serão geradas na próxima interação com o NPC.

Toda a validação dos arquivos JSON é realizada durante o carregamento do servidor (ServerStartingEvent):

• Checagem Rigorosa: O carregador (TradeJsonLoader) valida se os IDs existem no registro do jogo, se a quantidade (count) está no intervalo permitido (1–99), se os filtros de cores/variantes são válidos e bloqueia conflitos de propriedades (ex: definir id e family no mesmo objeto).
• Proteção contra Crashes (Fallback): Caso algum arquivo JSON contenha um erro de sintaxe ou ID inválido, o mod exibe um aviso claro no log (WARNING) indicando o erro e faz a reversão automática (fallback) para o arquivo original embutido no .jar, garantindo que o servidor continue rodando com segurança.