Cómo usar JSON
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
//y omite sin avisar las claves que empiezan por_,$o//, pero DragonMineZ los elimina cada vez que reescribe un archivo (una actualización de versión,/dmzconfigo 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 (
ConfigLoader.java). 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
<file> has malformed JSON; using defaults this session and leaving your file untouched, 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
/dmzreload(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
developer.reportJsonProblemsInChatTodos estos problemas se reúnen en un solo reporte. Con developer.reportJsonProblemsInChat activado en general-server.json (el valor por defecto), cada jugador ve un breve resumen en el chat al entrar: los archivos que fallaron ([!]) y los archivos por defecto que se actualizaron automáticamente ([~]). El reporte también señala las claves desconocidas, normalmente un error de escritura como "tpGainMultipler": 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 (general-server.json, combat.json, el character.json y el stats.json de una raza, las formas, entities.json, incursiones, torneos, etc.) lleva un texto configVersion con el formato X.Y.Z, por ejemplo "2.2.0". 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
X.Y.Z, como el antiguo valor numérico21.0, cuenta como desactualizado.
Una actualización sigue estos pasos:
- El archivo antiguo se mueve a
config/dragonminez/oldBackup/<same relative path>(por ejemplooldBackup/races/saiyan/forms/superforms.json). - 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 (
data/dragonminez/previousConfigs/):- 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
Regenerating <file>. Reason: Outdated version (...)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 oldBackup/ si algo no te cuadra.
configVersion 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
config/dragonminez/races/que no sea una raza por defecto): pasan por la misma comprobación de versión; sucharacter.jsony sustats.jsonse 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
races/<race>/forms/oforms/): conservan su contenido; cuando su versión está desactualizada, se mueve una copia aoldBackup/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
old_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
gameplay.autoUpdateQuestsLos archivos por defecto de misiones, sagas y misiones secundarias en <world>/dragonminez/ llevan un campo "defaultsVersion" en lugar de configVersion. Cuando una nueva versión de DragonMineZ trae valores por defecto cambiados y autoUpdateQuests está activado, DragonMineZ les aplica una fusión de tres vías similar (contra data/dragonminez/previousQuests/ 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 <world>/dragonminez/quest_update_report.txt. Antes de cambiar un archivo, DragonMineZ lo copia a <world>/dragonminez/oldBackup/.
Consulta Misiones personalizadas para ver cómo trata la fusión cada campo, y Recargar y actualizar cambios para ver cómo se informan las actualizaciones.
Errores comunes
- No renombrar
raceName,groupNameu 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 Recargar y actualizar cambios para saber qué necesita una recarga y qué necesita un reinicio.
- Editar la copia de
oldBackup/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 RaceCharacterConfig.java, FormConfig.java o GeneralServerConfig.java en com.dragonminez.common.config). 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.