Shokkoh: Translation sync from dragonminez-wiki repository

2026-10-14T06:46:20Z

Translation sync from dragonminez-wiki repository

New page

'''Cómo usar JSON''' explica las reglas que siguen todos los archivos de datos de DragonMineZ. No necesitas saber Java para configurar DragonMineZ, pero tus archivos tienen que ser JSON válido, y DragonMineZ actualiza sus archivos entre versiones de formas que deberías conocer antes de empezar a editar.


== Reglas básicas ==
* '''JSON estándar.''' Sin comas finales; las claves y los textos van entre comillas dobles. El parser de la configuración tolera los comentarios <code>//</code> y omite sin avisar las claves que empiezan por <code>_</code>, <code>$</code> o <code>//</code>, pero DragonMineZ los elimina cada vez que reescribe un archivo (una actualización de versión, <code>/dmzconfig</code> o el editor de configuración del juego). Deja las notas largas fuera del archivo.
* '''Codificación UTF-8.''' La configuración se lee y se escribe en UTF-8 (<code>ConfigLoader.java</code>). No guardes archivos en UTF-16 ni con una marca de orden de bytes (BOM) que tu editor podría añadir sin avisar.
* '''Usa un editor de verdad.''' VS Code, Notepad++ o IntelliJ detectan corchetes y comillas sin cerrar antes de que lleguen al servidor. El Bloc de notas funciona, pero no te avisará de los errores de sintaxis.
* '''Valida antes de desplegar.''' Una sola coma mal puesta hace que todo el archivo no se pueda analizar. Pega el archivo en cualquier validador de JSON (o usa el linter integrado de tu editor) antes de reiniciar o recargar un servidor en marcha.


== Cuando DragonMineZ no puede leer tu archivo ==
DragonMineZ nunca sobrescribe un archivo que no puede leer. Si un archivo de configuración tiene un error de sintaxis:
* DragonMineZ registra <code><file> has malformed JSON; using defaults this session and leaving your file untouched</code>, con la línea, la columna y la ruta del error.
* Durante esa sesión, el juego usa los valores por defecto incluidos de ese archivo. Tu archivo queda exactamente como lo dejaste.
* Corrige la sintaxis y ejecuta <code>/dmzreload</code> (o reinicia) para aplicar tus valores.
Lo mismo ocurre con los demás archivos JSON que carga DragonMineZ: un archivo de forma personalizada, incursión, torneo, misión, saga, misión secundaria o deseo mal formado se '''omite''' (no se regenera) y se informa.


=== El reporte de carga de JSON ===
{{Config|General Server Config|developer.reportJsonProblemsInChat}}
Todos estos problemas se reúnen en un solo reporte. Con <code>developer.reportJsonProblemsInChat</code> activado en <code>general-server.json</code> (el valor por defecto), cada jugador ve un breve resumen en el chat al entrar: los archivos que fallaron (<code>[!]</code>) y los archivos por defecto que se actualizaron automáticamente (<code>[~]</code>). El reporte también señala las '''claves desconocidas''', normalmente un error de escritura como <code>"tpGainMultipler"</code>: la clave se ignora y el resto del archivo carga igual. El log del servidor tiene todos los detalles.


== Versiones de configuración y actualizaciones automáticas ==
Cada archivo de configuración (<code>general-server.json</code>, <code>combat.json</code>, el <code>character.json</code> y el <code>stats.json</code> de una raza, las formas, <code>entities.json</code>, incursiones, torneos, etc.) lleva un texto <code>configVersion</code> con el formato <code>X.Y.Z</code>, por ejemplo <code>"2.2.0"</code>. '''No lo edites a mano.''' DragonMineZ lo compara con la versión de configuración del propio mod cada vez que carga el archivo:
* '''Versión actual:''' el archivo se carga tal cual.
* '''Versión más antigua o ausente:''' DragonMineZ actualiza el archivo. Cualquier valor que no tenga el formato <code>X.Y.Z</code>, como el antiguo valor numérico <code>21.0</code>, cuenta como desactualizado.
Una actualización sigue estos pasos:
# El archivo antiguo se '''mueve''' a <code>config/dragonminez/oldBackup/<same relative path></code> (por ejemplo <code>oldBackup/races/saiyan/forms/superforms.json</code>).
# Se genera un archivo nuevo a partir de los nuevos valores por defecto.
# Tus valores antiguos se vuelven a incorporar con una '''fusión de tres vías''' contra los valores por defecto de la versión anterior, que vienen dentro del jar del mod (<code>data/dragonminez/previousConfigs/</code>):
#* un valor que nunca cambiaste (sigue igual al valor por defecto de la versión anterior) toma el '''nuevo''' valor por defecto, así que te llegan los cambios de balance;
#* un valor que cambiaste se '''conserva''';
#* las claves añadidas en la nueva versión se añaden con su valor por defecto, y las entradas que añadiste a mapas (por ejemplo, ids de entidades extra) se conservan;
#* si no hay copia de la versión anterior de un archivo (razas personalizadas, archivos añadidos recientemente), se conservan todos los valores que difieran del nuevo valor por defecto.
# El log muestra <code>Regenerating <file>. Reason: Outdated version (...)</code> y cuántos de tus valores se conservaron.
Los valores que la fusión no puede trasladar (por ejemplo, un valor del tipo equivocado, como un texto donde se espera un número) vuelven al valor por defecto. Después de una actualización, compara el archivo nuevo con su copia en <code>oldBackup/</code> si algo no te cuadra.

{{Note|type=warning|title=No toques configVersion|text=Cambiar <code>configVersion</code> a mano o fuerza una actualización no deseada o hace que DragonMineZ trate un archivo desactualizado como actual, de modo que las claves nuevas y los ajustes de balance no se incorporan.}}


== Archivos personalizados y definidos por el usuario ==
* '''Razas personalizadas''' (cualquier carpeta de <code>config/dragonminez/races/</code> que no sea una raza por defecto): pasan por la misma comprobación de versión; su <code>character.json</code> y su <code>stats.json</code> se actualizan con la fusión de arriba y conservan todos los valores que definiste. DragonMineZ nunca les genera formas por defecto.
* '''Archivos de formas personalizadas''' (grupos de formas que no son de DragonMineZ, en <code>races/<race>/forms/</code> o <code>forms/</code>): conservan su contenido; cuando su versión está desactualizada, se mueve una copia a <code>oldBackup/</code> y el archivo se vuelve a guardar con la versión actual.
* '''Archivos extra de incursiones y torneos''' que añadas: se cargan tal cual.
* '''Misiones, sagas y misiones secundarias personalizadas''' que crees en el mundo guardado: nunca se modifican. Solo se actualizan los archivos por defecto que generó DragonMineZ (ver abajo).
* Los archivos cuyo nombre empieza por <code>old_</code> en las carpetas de formas, incursiones y torneos se ignoran, así que puedes dejar ahí un archivo aparcado sin que se cargue.


== Archivos de misiones y defaultsVersion ==
{{Config|General Server Config|gameplay.autoUpdateQuests}}
Los archivos por defecto de misiones, sagas y misiones secundarias en <code><world>/dragonminez/</code> llevan un campo <code>"defaultsVersion"</code> en lugar de <code>configVersion</code>. Cuando una nueva versión de DragonMineZ trae valores por defecto cambiados y <code>autoUpdateQuests</code> está activado, DragonMineZ les aplica una fusión de tres vías similar (contra <code>data/dragonminez/previousQuests/</code> en el jar). Si tanto tú como la nueva versión cambiaron el mismo campo, '''se conserva tu valor''' y el conflicto se lista en <code><world>/dragonminez/quest_update_report.txt</code>. Antes de cambiar un archivo, DragonMineZ lo copia a <code><world>/dragonminez/oldBackup/</code>.
Consulta [[Special:MyLanguage/Custom Quests#Default file upgrades|Misiones personalizadas]] para ver cómo trata la fusión cada campo, y [[Special:MyLanguage/Reloading and Updating Changes|Recargar y actualizar cambios]] para ver cómo se informan las actualizaciones.


== Errores comunes ==
* No renombrar <code>raceName</code>, <code>groupName</code> u otros campos tipo id de forma coherente entre el nombre de la carpeta y el contenido JSON. DragonMineZ usa ambos para muchas búsquedas.
* Copiar un archivo de forma o de raza y olvidarse de cambiar sus identificadores internos, de modo que una entrada sobrescribe a otra sin avisar.
* Editar un archivo con el servidor en marcha y esperar que se aplique en vivo. Consulta [[Special:MyLanguage/Reloading and Updating Changes|Recargar y actualizar cambios]] para saber qué necesita una recarga y qué necesita un reinicio.
* Editar la copia de <code>oldBackup/</code> creyendo que sigue activa. No lo está: DragonMineZ nunca la vuelve a leer.
* Errores de escritura en los nombres de las claves. La clave se ignora (y se informa), así que tu valor nunca se aplica.


== Comprobar un campo con el código ==
Las páginas de modding de esta wiki nombran la clase de Java que hay detrás de cada archivo (por ejemplo <code>RaceCharacterConfig.java</code>, <code>FormConfig.java</code> o <code>GeneralServerConfig.java</code> en <code>com.dragonminez.common.config</code>). Si tienes dudas sobre el nombre o el tipo de un campo, esa clase es la fuente de verdad: la wiki la describe, pero el código la define. La referencia más fácil es un archivo recién generado: inicia una instancia de prueba y copia el archivo que escribe DragonMineZ.

{{Navbox Modding}}

How to JSON/es - Revision history

Shokkoh: Translation sync from dragonminez-wiki repository