Esta guía cubre la solución avanzada de problemas de mods para servidores de Project Zomboid alojados en Legion Hosting. Si aún no has instalado mods, comienza primero con la guía básica de instalación de mods. Este artículo aborda los problemas más comunes relacionados con mods vistos en los tickets de soporte de Legion Hosting, incluyendo corrupción del WorldDictionary, errores de formato de mods, conflictos de orden de carga y desajustes de versión entre servidor y cliente.

Antes de Comenzar

• Inicia sesión en GPanel y selecciona tu servidor de Project Zomboid.
• Detén tu servidor antes de realizar cualquier cambio de configuración o archivos.
• Haz una copia de seguridad de tu carpeta de guardado del mundo (/.cache/saves/multiplayer/) mediante SFTP o GPanel antes de intentar cualquier corrección. Consulta la guía de SFTP si no estás familiarizado con la transferencia de archivos.
• Ten lista la ruta del archivo .ini de tu servidor: /.cache/server/<servername>.ini (por ejemplo, servertest.ini).

1. Errores de Formato de Mods (B42 vs B41)

La razón más común por la que los mods no se cargan es un formato incorrecto en la línea Mods= del archivo .ini de tu servidor. Build 42 y Build 41 usan diferente sintaxis, y mezclarlos hará que tus mods no se carguen silenciosamente.

Formato B42 (Predeterminado Actual)

Build 42 requiere un prefijo de barra invertida antes de cada Mod ID en la línea Mods=:

Mods=\ModID1;\ModID2;\ModID3;

El formato DLMP combina Workshop IDs y Mod IDs con un separador de barra invertida:

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

La línea WorkshopItems= usa el mismo formato separado por punto y coma en ambas versiones:

WorkshopItems=2392987841;1550458773;2786383654

Formato B41 (Legado)

Build 41 usa Mod IDs separados por punto y coma sin barra invertida:

Mods=ModID1;ModID2;ModID3

Cómo Solucionarlo

1. Abre /.cache/server/<servername>.ini en el File Manager de GPanel.
2. Encuentra la línea Mods= y verifica el formato comparándolo con los ejemplos anteriores.
3. Si el formato es incorrecto para tu versión de build, corrígelo. Usa el Organizador de Mods de Legion Hosting para generar líneas correctamente formateadas automáticamente.
4. Guarda el archivo e inicia el servidor.

2. Corrupción del WorldDictionary

El WorldDictionary es un archivo (WorldDictionary.bin) que mapea nombres de objetos a IDs numéricos internos. Cuando se añaden o eliminan mods, el diccionario puede corromperse, causando que el servidor se bloquee al iniciar con una WorldDictionaryException.

Síntomas

• La consola o debug.log muestra errores de WorldDictionaryException o WorldDictionary.
• El servidor se bloquea inmediatamente durante el inicio, específicamente durante la carga del mundo.
• El bloqueo comenzó después de añadir, eliminar o actualizar mods.

Entendiendo el Riesgo

Pasos de Recuperación

1. Detén tu servidor en GPanel.
2. Haz una copia de seguridad de toda tu carpeta de guardado mediante SFTP: descarga el directorio completo /.cache/saves/multiplayer/<YourWorldName>/ a tu máquina local.
3. Primero, intenta simplemente revertir el cambio de mod que causó el error. Si acabas de añadir un mod, elimínalo tanto de Mods= como de WorkshopItems= en el archivo .ini. Si acabas de eliminar un mod, vuelve a añadirlo. Inicia el servidor y comprueba si el bloqueo se resuelve.
4. Si revertir el cambio de mod no funciona, conéctate mediante SFTP y navega a /.cache/saves/multiplayer/<YourWorldName>/.
5. Elimina WorldDictionary.bin.
6. Inicia el servidor. Project Zomboid regenerará el diccionario al iniciar.
7. Únete al servidor e inspecciona el mundo en busca de objetos corruptos, vehículos desaparecidos o inventarios rotos. Si el mundo está severamente dañado, restaura desde la copia de seguridad que creaste en el paso 2.

3. Conflictos del Mod Authentic Z

Authentic Z es una de las colecciones de mods más populares de Project Zomboid, pero es una fuente frecuente de tickets de soporte porque contiene múltiples sub-mods que entran en conflicto entre sí.

La Regla

Errores Comunes

• Añadir tanto Authentic Z - Current como Authentic Z - Litemode al mismo tiempo.
• Añadir sub-mods de Authentic Z diseñados para un solo jugador junto con la versión multijugador.
• No darse cuenta de que diferentes sub-mods de Authentic Z comparten el mismo Workshop ID pero tienen diferentes Mod IDs, por lo que la descarga del Workshop tiene éxito pero el servidor carga archivos de mods en conflicto.

Cómo Solucionarlo

1. Abre /.cache/server/<servername>.ini en el File Manager de GPanel.
2. Busca en la línea Mods= cada entrada que contenga Authentic o AuthenticZ.
3. Mantén solo un sub-mod de Authentic Z (recomendado: Authentic Z - Current). Elimina todas las demás entradas de Authentic Z tanto de las líneas Mods= como de WorkshopItems=.
4. Guarda el archivo y reinicia el servidor.

4. Problemas de Sensibilidad a Mayúsculas en Linux

Los servidores de Legion Hosting funcionan en Linux, donde los nombres de archivos y carpetas son sensibles a mayúsculas y minúsculas. Un archivo llamado MyMod.lua y mymod.lua son tratados como dos archivos completamente diferentes. Esto causa problemas cuando los autores de mods desarrollan en Windows (insensible a mayúsculas) y sus mods contienen referencias de archivos que no coinciden.

Síntomas

• Un mod funciona perfectamente en modo de un solo jugador en tu PC con Windows pero falla en el servidor.
• La consola o debug.log muestra errores de FileNotFoundException o can't find file que hacen referencia a un script Lua o textura dentro de un mod.
• El error apunta a un archivo que sí existe en la carpeta del mod, pero con diferente capitalización (por ejemplo, el código hace referencia a Items.txt pero el archivo real se llama items.txt).

Cómo Diagnosticar

1. Revisa la consola o los archivos de registro en /.cache/Logs/ para la ruta exacta del archivo mencionada en el error.
2. Conéctate mediante SFTP y navega a la carpeta del mod en /steamapps/workshop/content/108600/<WorkshopID>/.
3. Compara los nombres de archivos en disco con el nombre de archivo referenciado en el mensaje de error. Busca diferencias en la capitalización.

Cómo Solucionarlo

• Si puedes renombrar el archivo: Conéctate mediante SFTP y renombra el archivo para que coincida con la capitalización esperada por el código del mod. Ten en cuenta que esta corrección será sobrescrita si el mod se actualiza en Steam Workshop.
• Si el problema está en el mod mismo: Reporta el error al autor del mod en la página de Steam Workshop. Menciona que la referencia del archivo tiene un desajuste de mayúsculas y que falla en servidores Linux. Muchos autores de mods no son conscientes de la sensibilidad a mayúsculas de Linux.
• Como solución temporal: Revisa los comentarios de la página del Workshop del mod — otros operadores de servidores Linux pueden haber publicado una corrección o una versión compatible del mod.

5. Problemas de Orden de Carga de Mods

Project Zomboid carga los mods en el orden en que aparecen en la línea Mods=. Algunos mods dependen de que otros mods se carguen primero. Si una dependencia se carga después del mod que la requiere, el mod dependiente puede fallar silenciosamente o causar errores.

Síntomas

• Las características del mod funcionan parcialmente — algunos objetos o sistemas de un mod están presentes pero otros faltan.
• La consola muestra errores de NullPointerException o attempt to index a nil value que hacen referencia a los scripts Lua de un mod.
• Los errores solo aparecen cuando una combinación específica de mods está instalada, pero cada mod funciona bien individualmente.

Cómo Solucionarlo

1. Revisa la página de Steam Workshop de cada mod para una sección de "Required Mods" u "Load Order". Muchos autores de mods especifican qué mods deben cargarse antes que el suyo.
2. Abre /.cache/server/<servername>.ini y encuentra la línea Mods=.
3. Reordena las entradas para que los mods de dependencia aparezcan antes que los mods que los requieren. Por ejemplo, si el Mod B requiere el Mod A, la línea debería ser Mods=\ModA;\ModB; (formato B42).
4. Los mods de framework y bibliotecas (como ModFramework, TsarLib o Shark's Mod Utils) siempre deben listarse primero en la línea Mods=.
5. Guarda el archivo y reinicia el servidor.

6. El Servidor se Bloquea Después de Añadir Mods

Si tu servidor estaba funcionando bien y se bloquea después de añadir uno o más mods, el nuevo mod probablemente sea la causa. Esta sección te guía para aislar el mod problemático.

Aislamiento Paso a Paso

1. Detén el servidor en GPanel.
2. Abre /.cache/server/<servername>.ini en el File Manager.
3. Anota todos los mods que acabas de añadir. Elimina todos ellos de las líneas Mods= y WorkshopItems=.
4. Inicia el servidor. Si inicia correctamente, el problema está en uno de los mods que eliminaste.
5. Vuelve a añadir los mods uno a la vez, reiniciando el servidor después de cada adición. Cuando el bloqueo regrese, el último mod que añadiste es la causa.
6. Una vez identificado, revisa la página del Workshop del mod para:
   • Una nota sobre compatibilidad con B42 — muchos mods de B41 no han sido actualizados para B42.
   • Conflictos conocidos con otros mods que estás ejecutando.
   • Mods de dependencia requeridos que quizás no hayas instalado.

Lectura del Registro de Bloqueo

Antes de realizar el proceso de aislamiento, revisa el registro de bloqueo — a menudo apunta directamente al mod problemático:

1. En GPanel, abre la pestaña Console y desplázate hasta el final de la salida.
2. Busca líneas con STACK TRACE, Exception o ERROR.
3. Las líneas inmediatamente encima del stack trace típicamente hacen referencia a un nombre de archivo de mod o Mod ID — esto te indica qué mod provocó el bloqueo.
4. Para más detalle, abre el archivo de registro completo mediante SFTP en /.cache/Logs/ y revisa el archivo más reciente DebugLog-server.txt o debug.log.

7. Desajustes de Versión de Mods (Servidor vs Cliente)

Project Zomboid requiere que el servidor y todos los clientes conectados tengan la misma versión de cada mod. Si un mod se actualiza en Steam Workshop y el servidor descarga la nueva versión pero un jugador todavía tiene la versión antigua en caché (o viceversa), ocurrirán fallos de conexión o bloqueos.

Síntomas

• Los jugadores reciben un error de "Mod mismatch" o "Version mismatch" al intentar conectarse.
• Algunos jugadores pueden conectarse pero otros no — los que no pueden conectarse tienen una versión diferente del mod en caché localmente.
• El servidor estaba funcionando bien, luego un mod se actualizó en Steam Workshop y de repente algunos jugadores no pueden unirse.
• Los jugadores ven texturas faltantes, objetos o elementos de interfaz rotos de mods que fueron actualizados recientemente.

Solución para Operadores del Servidor

1. Detén el servidor en GPanel.
2. Inicia el servidor de nuevo. Al iniciar, el servidor vuelve a descargar las últimas versiones de todos los mods del Workshop. Esto asegura que el servidor esté ejecutando la versión más reciente.
3. Si el servidor todavía tiene una versión antigua en caché, conéctate mediante SFTP y elimina la carpeta de caché del Workshop del mod específico en /steamapps/workshop/content/108600/<WorkshopID>/. Reinicia el servidor para forzar una descarga limpia.

Solución para Jugadores

Los jugadores que no pueden conectarse debido a desajustes de versión de mods deben:

1. Abrir Steam y navegar a Library → Project Zomboid.
2. Hacer clic derecho en Project Zomboid, seleccionar Properties → Local Files → Verify Integrity of Game Files.
3. También navegar a la carpeta de Steam Workshop de Project Zomboid en su máquina local y eliminar los archivos de mods en caché para forzar una nueva descarga.
4. Iniciar el juego y conectarse al servidor de nuevo.

8. Limpiar la Caché de Steam Workshop

Si persisten múltiples problemas de mods y sospechas que la caché de descarga del Workshop está corrupta, puedes forzar una nueva descarga completa de todos los mods del Workshop.

1. Detén el servidor en GPanel.
2. Conéctate mediante SFTP y navega a /steamapps/workshop/.
3. Elimina toda la carpeta workshop/ (o su contenido).
4. Inicia el servidor. Steam volverá a descargar todos los elementos del Workshop desde cero.
5. Observa la Consola de GPanel para confirmar que todos los mods terminan de descargarse antes de que el servidor comience a cargar el mundo.

Referencia Rápida de Diagnóstico

¿Sigues Teniendo Problemas con Mods?