Como usar JSON

This page is a translated version of the page How to JSON and the translation is 100% complete.

Como usar JSON explica as regras que todos os arquivos de dados do DragonMineZ seguem. Você não precisa saber Java para configurar o DragonMineZ, mas seus arquivos precisam ser JSON válido, e o DragonMineZ atualiza seus arquivos entre versões de jeitos que você deve conhecer antes de começar a editar.

Regras básicas

JSON padrão. Sem vírgulas sobrando no final; chaves e textos vão entre aspas duplas. O parser da configuração tolera comentários // e ignora sem aviso as chaves que começam com _, $ ou //, mas o DragonMineZ os descarta sempre que reescreve um arquivo (uma atualização de versão, /dmzconfig ou o editor de configuração do jogo). Deixe anotações longas fora do arquivo.
Codificação UTF-8. A configuração é lida e gravada em UTF-8 (ConfigLoader.java). Não salve arquivos em UTF-16 nem com uma marca de ordem de bytes (BOM) que seu editor pode adicionar sem avisar.
Use um editor de verdade. VS Code, Notepad++ ou IntelliJ detectam colchetes e aspas sem par antes que cheguem ao servidor. O Bloco de Notas funciona, mas não avisa sobre erros de sintaxe.
Valide antes de publicar. Uma única vírgula fora do lugar faz o arquivo inteiro falhar na leitura. Cole o arquivo em qualquer validador de JSON (ou use o linter embutido do seu editor) antes de reiniciar ou recarregar um servidor em funcionamento.

Quando o DragonMineZ não consegue ler seu arquivo

O DragonMineZ nunca sobrescreve um arquivo que não consegue ler. Se um arquivo de configuração tiver um erro de sintaxe:

O DragonMineZ registra <file> has malformed JSON; using defaults this session and leaving your file untouched, com a linha, a coluna e o caminho do erro.
Durante essa sessão, o jogo usa os valores padrão incluídos desse arquivo. Seu arquivo fica exatamente como você deixou.
Corrija a sintaxe e execute /dmzreload (ou reinicie) para aplicar seus valores.

O mesmo vale para os outros arquivos JSON que o DragonMineZ carrega: um arquivo malformado de forma personalizada, incursão, torneio, missão, saga, missão secundária ou desejo é ignorado (não é regenerado) e reportado.

O relatório de carregamento de JSON

Configurado em: Configuração do servidordeveloper.reportJsonProblemsInChat

Todos esses problemas são reunidos em um único relatório. Com developer.reportJsonProblemsInChat ativado em general-server.json (o padrão), cada jogador vê um breve resumo no chat ao entrar: os arquivos que falharam ([!]) e os arquivos padrão que foram atualizados automaticamente ([~]). O relatório também aponta chaves desconhecidas, geralmente um erro de digitação como "tpGainMultipler": a chave é ignorada e o resto do arquivo carrega normalmente. O log do servidor tem todos os detalhes.

Versões de configuração e atualizações automáticas

Todo arquivo de configuração (general-server.json, combat.json, o character.json e o stats.json de uma raça, as formas, entities.json, incursões, torneios etc.) tem um texto configVersion no formato X.Y.Z, por exemplo "2.2.0". Não o edite à mão. O DragonMineZ o compara com a versão de configuração do próprio mod sempre que carrega o arquivo:

Versão atual: o arquivo é carregado como está.
Versão mais antiga ou ausente: o DragonMineZ atualiza o arquivo. Qualquer valor que não esteja no formato X.Y.Z, como o antigo valor numérico 21.0, conta como desatualizado.

Uma atualização segue estes passos:

O arquivo antigo é movido para config/dragonminez/oldBackup/<same relative path> (por exemplo oldBackup/races/saiyan/forms/superforms.json).
Um arquivo novo é gerado a partir dos novos valores padrão.
Seus valores antigos são incorporados de volta com uma mesclagem de três vias contra os valores padrão da versão anterior, que vêm dentro do jar do mod (data/dragonminez/previousConfigs/):
- um valor que você nunca alterou (ainda igual ao padrão da versão anterior) recebe o novo padrão, então as mudanças de balanceamento chegam até você;
- um valor que você alterou é mantido;
- chaves adicionadas na nova versão entram com seu valor padrão, e as entradas que você adicionou a mapas (por exemplo, ids de entidades extras) são mantidas;
- se não houver cópia da versão anterior de um arquivo (raças personalizadas, arquivos adicionados recentemente), todo valor diferente do novo padrão é mantido.
O log mostra Regenerating <file>. Reason: Outdated version (...) e quantos dos seus valores foram preservados.

Valores que a mesclagem não consegue transferir (por exemplo, um valor do tipo errado, como um texto onde se espera um número) voltam ao padrão. Depois de uma atualização, compare o arquivo novo com a cópia em oldBackup/ se algo parecer estranho.

Não mexa no configVersion Alterar o configVersion à mão ou força uma atualização indesejada ou faz o DragonMineZ tratar um arquivo desatualizado como atual, e aí as chaves novas e os ajustes de balanceamento não são incorporados.

Arquivos personalizados e definidos pelo usuário

Raças personalizadas (qualquer pasta em config/dragonminez/races/ que não seja uma raça padrão): passam pela mesma verificação de versão; seu character.json e seu stats.json são atualizados com a mesclagem acima, mantendo todos os valores que você definiu. O DragonMineZ nunca gera formas padrão para elas.
Arquivos de formas personalizadas (grupos de formas que não são padrão do DragonMineZ, em races/<race>/forms/ ou forms/): mantêm seu conteúdo; quando a versão está desatualizada, uma cópia é movida para oldBackup/ e o arquivo é salvo de novo com a versão atual.
Arquivos extras de incursões e torneios que você adicionar: são carregados como estão.
Missões, sagas e missões secundárias personalizadas que você criar no save do mundo: nunca são modificadas. Só os arquivos padrão gerados pelo DragonMineZ são atualizados (veja abaixo).
Arquivos cujo nome começa com old_ nas pastas de formas, incursões e torneios são ignorados, então você pode deixar um arquivo guardado ali sem que ele seja carregado.

Arquivos de missões e defaultsVersion

Configurado em: Configuração do servidorgameplay.autoUpdateQuests

Os arquivos padrão de missões, sagas e missões secundárias em <world>/dragonminez/ têm um campo "defaultsVersion" em vez de configVersion. Quando uma nova versão do DragonMineZ traz padrões alterados e autoUpdateQuests está ativado, o DragonMineZ aplica neles uma mesclagem de três vias parecida (contra data/dragonminez/previousQuests/ no jar). Se você e a nova versão alteraram o mesmo campo, seu valor é mantido e o conflito é listado em <world>/dragonminez/quest_update_report.txt. Antes de alterar um arquivo, o DragonMineZ o copia para <world>/dragonminez/oldBackup/. Veja Missões personalizadas para saber como a mesclagem trata cada campo, e Recarregar e atualizar mudanças para saber como as atualizações são reportadas.

Erros comuns

Não renomear raceName, groupName ou outros campos do tipo id de forma consistente entre o nome da pasta e o conteúdo JSON. O DragonMineZ usa os dois em muitas buscas.
Copiar um arquivo de forma ou de raça e esquecer de mudar seus identificadores internos, fazendo uma entrada sobrescrever outra sem aviso.
Editar um arquivo com o servidor rodando e esperar que a mudança valha na hora. Veja Recarregar e atualizar mudanças para saber o que precisa de recarga e o que precisa de reinicialização.
Editar a cópia em oldBackup/ achando que ela ainda está ativa. Não está: o DragonMineZ nunca a lê de volta.
Erros de digitação nos nomes das chaves. A chave é ignorada (e reportada), então seu valor nunca é aplicado.

Conferir um campo no código

As páginas de modding desta wiki indicam a classe Java por trás de cada arquivo (por exemplo RaceCharacterConfig.java, FormConfig.java ou GeneralServerConfig.java em com.dragonminez.common.config). Na dúvida sobre o nome ou o tipo de um campo, essa classe é a fonte da verdade: a wiki a descreve, mas o código a define. A referência mais fácil é um arquivo recém-gerado: inicie uma instância de teste e copie o arquivo que o DragonMineZ grava.