Shokkoh: Translation sync from dragonminez-wiki repository

2026-10-14T06:47:52Z

Translation sync from dragonminez-wiki repository

New page

'''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 <code>//</code> e ignora sem aviso as chaves que começam com <code>_</code>, <code>$</code> ou <code>//</code>, mas o DragonMineZ os descarta sempre que reescreve um arquivo (uma atualização de versão, <code>/dmzconfig</code> 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 (<code>ConfigLoader.java</code>). 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 <code><file> has malformed JSON; using defaults this session and leaving your file untouched</code>, 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 <code>/dmzreload</code> (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 ===
{{Config|General Server Config|developer.reportJsonProblemsInChat}}
Todos esses problemas são reunidos em um único relatório. Com <code>developer.reportJsonProblemsInChat</code> ativado em <code>general-server.json</code> (o padrão), cada jogador vê um breve resumo no chat ao entrar: os arquivos que falharam (<code>[!]</code>) e os arquivos padrão que foram atualizados automaticamente (<code>[~]</code>). O relatório também aponta '''chaves desconhecidas''', geralmente um erro de digitação como <code>"tpGainMultipler"</code>: 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 (<code>general-server.json</code>, <code>combat.json</code>, o <code>character.json</code> e o <code>stats.json</code> de uma raça, as formas, <code>entities.json</code>, incursões, torneios etc.) tem um texto <code>configVersion</code> no formato <code>X.Y.Z</code>, por exemplo <code>"2.2.0"</code>. '''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 <code>X.Y.Z</code>, como o antigo valor numérico <code>21.0</code>, conta como desatualizado.
Uma atualização segue estes passos:
# O arquivo antigo é '''movido''' para <code>config/dragonminez/oldBackup/<same relative path></code> (por exemplo <code>oldBackup/races/saiyan/forms/superforms.json</code>).
# 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 (<code>data/dragonminez/previousConfigs/</code>):
#* 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 <code>Regenerating <file>. Reason: Outdated version (...)</code> 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 <code>oldBackup/</code> se algo parecer estranho.

{{Note|type=warning|title=Não mexa no configVersion|text=Alterar o <code>configVersion</code> à 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 <code>config/dragonminez/races/</code> que não seja uma raça padrão): passam pela mesma verificação de versão; seu <code>character.json</code> e seu <code>stats.json</code> 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 <code>races/<race>/forms/</code> ou <code>forms/</code>): mantêm seu conteúdo; quando a versão está desatualizada, uma cópia é movida para <code>oldBackup/</code> 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 <code>old_</code> 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 ==
{{Config|General Server Config|gameplay.autoUpdateQuests}}
Os arquivos padrão de missões, sagas e missões secundárias em <code><world>/dragonminez/</code> têm um campo <code>"defaultsVersion"</code> em vez de <code>configVersion</code>. Quando uma nova versão do DragonMineZ traz padrões alterados e <code>autoUpdateQuests</code> está ativado, o DragonMineZ aplica neles uma mesclagem de três vias parecida (contra <code>data/dragonminez/previousQuests/</code> no jar). Se você e a nova versão alteraram o mesmo campo, '''seu valor é mantido''' e o conflito é listado em <code><world>/dragonminez/quest_update_report.txt</code>. Antes de alterar um arquivo, o DragonMineZ o copia para <code><world>/dragonminez/oldBackup/</code>.
Veja [[Special:MyLanguage/Custom Quests#Default file upgrades|Missões personalizadas]] para saber como a mesclagem trata cada campo, e [[Special:MyLanguage/Reloading and Updating Changes|Recarregar e atualizar mudanças]] para saber como as atualizações são reportadas.


== Erros comuns ==
* Não renomear <code>raceName</code>, <code>groupName</code> 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 [[Special:MyLanguage/Reloading and Updating Changes|Recarregar e atualizar mudanças]] para saber o que precisa de recarga e o que precisa de reinicialização.
* Editar a cópia em <code>oldBackup/</code> 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 <code>RaceCharacterConfig.java</code>, <code>FormConfig.java</code> ou <code>GeneralServerConfig.java</code> em <code>com.dragonminez.common.config</code>). 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.

{{Navbox Modding}}

How to JSON/pt - Revision history

Shokkoh: Translation sync from dragonminez-wiki repository