Aquesta guia cobreix la resolució avançada de problemes de mods per a servidors de Project Zomboid allotjats amb Legion Hosting. Si encara no heu instal·lat mods, comenceu amb la guia bàsica d'instal·lació de mods primer. Aquest article aborda els problemes més comuns relacionats amb mods vistos als tiquets de suport de Legion Hosting, incloent-hi la corrupció del WorldDictionary, errors de format de mods, conflictes d'ordre de càrrega i discrepàncies de versions entre servidor i client.

Abans de començar

• Inicieu sessió a GPanel i seleccioneu el vostre servidor de Project Zomboid.
• Atureu el servidor abans de fer qualsevol canvi de configuració o fitxers.
• Feu una còpia de seguretat de la carpeta de la partida desada (/.cache/saves/multiplayer/) via SFTP o GPanel abans d'intentar qualsevol solució. Consulteu la guia de SFTP si no esteu familiaritzat amb les transferències de fitxers.
• Tingueu a mà la ruta del fitxer .ini del vostre servidor: /.cache/server/<servername>.ini (per exemple, servertest.ini).

1. Errors de format de mods (B42 vs B41)

La raó més comuna per la qual els mods no es carreguen és un format incorrecte a la línia Mods= del fitxer .ini del vostre servidor. Build 42 i Build 41 utilitzen una sintaxi diferent, i barrejar-les farà que els mods no es carreguin de manera silenciosa.

Format B42 (per defecte actual)

Build 42 requereix un prefix de barra inversa abans de cada Mod ID a la línia Mods=:

Mods=\ModID1;\ModID2;\ModID3;

El format DLMP combina els Workshop IDs i els Mod IDs amb un separador de barra inversa:

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

La línia WorkshopItems= utilitza el mateix format separat per punt i coma en ambdues versions:

WorkshopItems=2392987841;1550458773;2786383654

Format B41 (llegat)

Build 41 utilitza Mod IDs separats per punt i coma sense barra inversa:

Mods=ModID1;ModID2;ModID3

Com solucionar-ho

1. Obriu /.cache/server/<servername>.ini al gestor de fitxers de GPanel.
2. Trobeu la línia Mods= i comproveu el format comparant-lo amb els exemples anteriors.
3. Si el format és incorrecte per a la vostra versió de build, corregiu-lo. Utilitzeu l'Organitzador de Mods de Legion Hosting per generar línies amb el format correcte automàticament.
4. Deseu el fitxer i inicieu el servidor.

2. Corrupció del WorldDictionary

El WorldDictionary és un fitxer (WorldDictionary.bin) que mapeja els noms d'objectes a IDs numèrics interns. Quan s'afegeixen o s'eliminen mods, el diccionari es pot corrompre, causant que el servidor es bloquegi a l'inici amb un WorldDictionaryException.

Símptomes

• La consola o el debug.log mostra WorldDictionaryException o errors de WorldDictionary.
• El servidor es bloqueja immediatament durant l'inici, específicament durant la càrrega del món.
• El bloqueig va començar després d'afegir, eliminar o actualitzar mods.

Comprendre el risc

Passos de recuperació

1. Atureu el servidor a GPanel.
2. Feu una còpia de seguretat de tota la carpeta de la partida desada via SFTP: descarregueu el directori complet /.cache/saves/multiplayer/<YourWorldName>/ al vostre ordinador local.
3. Primer, proveu simplement de revertir el canvi de mod que va causar l'error. Si acabeu d'afegir un mod, elimineu-lo tant de Mods= com de WorkshopItems= al fitxer .ini. Si acabeu d'eliminar un mod, torneu-lo a afegir. Inicieu el servidor i comproveu si el bloqueig s'ha resolt.
4. Si revertir el canvi de mod no funciona, connecteu-vos via SFTP i navegueu a /.cache/saves/multiplayer/<YourWorldName>/.
5. Elimineu WorldDictionary.bin.
6. Inicieu el servidor. Project Zomboid regenerarà el diccionari a l'inici.
7. Uniu-vos al servidor i inspeccioneu el món per trobar objectes corruptes, vehicles desapareguts o inventaris trencats. Si el món està greument danyat, restaureu des de la còpia de seguretat que heu creat al pas 2.

3. Conflictes del mod Authentic Z

Authentic Z és una de les col·leccions de mods de Project Zomboid més populars, però és una font freqüent de tiquets de suport perquè conté múltiples sub-mods que entren en conflicte entre ells.

La regla

Errors comuns

• Afegir tant Authentic Z - Current com Authentic Z - Litemode alhora.
• Afegir sub-mods d'Authentic Z dissenyats per a un sol jugador juntament amb la versió multijugador.
• No adonar-se que diferents sub-mods d'Authentic Z comparteixen el mateix Workshop ID però tenen Mod IDs diferents, de manera que la descàrrega del Workshop té èxit però el servidor carrega fitxers de mod en conflicte.

Com solucionar-ho

1. Obriu /.cache/server/<servername>.ini al gestor de fitxers de GPanel.
2. Cerqueu a la línia Mods= totes les entrades que continguin Authentic o AuthenticZ.
3. Mantingueu només un sub-mod d'Authentic Z (recomanat: Authentic Z - Current). Elimineu totes les altres entrades d'Authentic Z tant de les línies Mods= com de WorkshopItems=.
4. Deseu el fitxer i reinicieu el servidor.

4. Problemes de distinció entre majúscules i minúscules de Linux

Els servidors de Legion Hosting funcionen amb Linux, on els noms de fitxers i carpetes distingeixen entre majúscules i minúscules. Un fitxer anomenat MyMod.lua i mymod.lua es tracten com dos fitxers completament diferents. Això causa problemes quan els autors de mods desenvolupen a Windows (que no distingeix entre majúscules i minúscules) i els seus mods contenen referències de fitxers que no coincideixen.

Símptomes

• Un mod funciona perfectament en un sol jugador al vostre PC amb Windows però falla al servidor.
• La consola o el debug.log mostra errors de FileNotFoundException o can't find file que fan referència a un script Lua o textura dins d'un mod.
• L'error apunta a un fitxer que existeix a la carpeta del mod, però amb una capitalització diferent (per exemple, el codi fa referència a Items.txt però el fitxer real es diu items.txt).

Com diagnosticar-ho

1. Comproveu la consola o els fitxers de registre a /.cache/Logs/ per trobar la ruta exacta del fitxer mencionada a l'error.
2. Connecteu-vos via SFTP i navegueu a la carpeta del mod a /steamapps/workshop/content/108600/<WorkshopID>/.
3. Compareu els noms dels fitxers al disc amb el nom del fitxer referenciat al missatge d'error. Busqueu diferències de capitalització.

Com solucionar-ho

• Si podeu reanomenar el fitxer: Connecteu-vos via SFTP i reanomeneu el fitxer perquè coincideixi amb la capitalització esperada pel codi del mod. Tingueu en compte que aquesta solució se sobreescriurà si el mod s'actualitza al Steam Workshop.
• Si el problema és del mod en si: Informeu de l'error a l'autor del mod a la pàgina del Steam Workshop. Mencioneu que la referència al fitxer té una discrepància de majúscules/minúscules i que falla als servidors Linux. Molts autors de mods no són conscients de la distinció entre majúscules i minúscules de Linux.
• Com a solució temporal: Consulteu els comentaris de la pàgina del Workshop del mod — altres operadors de servidors Linux poden haver publicat una solució o una bifurcació compatible del mod.

5. Problemes d'ordre de càrrega de mods

Project Zomboid carrega els mods en l'ordre en què apareixen a la línia Mods=. Alguns mods depenen que altres mods es carreguin primer. Si una dependència es carrega després del mod que la requereix, el mod dependent pot fallar de manera silenciosa o causar errors.

Símptomes

• Les funcionalitats del mod funcionen parcialment — alguns objectes o sistemes d'un mod estan presents però d'altres falten.
• La consola mostra errors de NullPointerException o attempt to index a nil value que fan referència als scripts Lua d'un mod.
• Els errors només apareixen quan s'instal·la una combinació específica de mods, però cada mod funciona bé individualment.

Com solucionar-ho

1. Comproveu la pàgina del Steam Workshop de cada mod per trobar una secció de "Required Mods" o "Load Order". Molts autors de mods especifiquen quins mods s'han de carregar abans del seu.
2. Obriu /.cache/server/<servername>.ini i trobeu la línia Mods=.
3. Reordeneu les entrades perquè els mods de dependència apareguin abans dels mods que els requereixen. Per exemple, si el Mod B requereix el Mod A, la línia hauria de ser Mods=\ModA;\ModB; (format B42).
4. Els mods de framework i biblioteca (com ara ModFramework, TsarLib o Shark's Mod Utils) haurien d'aparèixer sempre primers a la línia Mods=.
5. Deseu el fitxer i reinicieu el servidor.

6. El servidor es bloqueja després d'afegir mods

Si el vostre servidor funcionava bé i es bloqueja després d'afegir un o més mods, el nou mod probablement n'és la causa. Aquesta secció explica com aïllar el mod problemàtic.

Aïllament pas a pas

1. Atureu el servidor a GPanel.
2. Obriu /.cache/server/<servername>.ini al gestor de fitxers.
3. Anoteu tots els mods que acabeu d'afegir. Elimineu-los tots tant de les línies Mods= com de WorkshopItems=.
4. Inicieu el servidor. Si s'inicia correctament, el problema està en un dels mods que heu eliminat.
5. Torneu a afegir els mods un per un, reiniciant el servidor després de cada addició. Quan el bloqueig torni, l'últim mod que heu afegit n'és la causa.
6. Un cop identificat, comproveu la pàgina del Workshop del mod per:
   • Una nota sobre la compatibilitat amb B42 — molts mods de B41 no s'han actualitzat per a B42.
   • Conflictes coneguts amb altres mods que esteu executant.
   • Mods de dependència requerits que potser no heu instal·lat.

Llegir el registre de bloqueig

Abans de realitzar el procés d'aïllament, comproveu el registre de bloqueig — sovint apunta directament al mod problemàtic:

1. A GPanel, obriu la pestanya Console i desplaceu-vos fins al final de la sortida.
2. Busqueu línies de STACK TRACE, Exception o ERROR.
3. Les línies immediatament per sobre del stack trace normalment fan referència a un nom de fitxer de mod o Mod ID — això us indica quin mod ha provocat el bloqueig.
4. Per a més detalls, obriu el fitxer de registre complet via SFTP a /.cache/Logs/ i comproveu el fitxer DebugLog-server.txt o debug.log més recent.

7. Discrepàncies de versions de mods (servidor vs client)

Project Zomboid requereix que el servidor i tots els clients connectats tinguin la mateixa versió de cada mod. Si un mod s'actualitza al Steam Workshop i el servidor descarrega la nova versió però un jugador encara té la versió antiga en memòria cau (o viceversa), es produiran errors de connexió o bloquejos.

Símptomes

• Els jugadors reben un error de "Mod mismatch" o "Version mismatch" en intentar connectar-se.
• Alguns jugadors es poden connectar però d'altres no — els que no es poden connectar tenen una versió diferent del mod emmagatzemada localment.
• El servidor funcionava bé, un mod es va actualitzar al Steam Workshop i de sobte alguns jugadors no poden unir-s'hi.
• Els jugadors veuen textures, objectes o elements d'interfície trencats de mods que s'han actualitzat recentment.

Solució per a operadors de servidors

1. Atureu el servidor a GPanel.
2. Torneu a iniciar el servidor. A l'inici, el servidor torna a descarregar les últimes versions de tots els mods del Workshop. Això assegura que el servidor executa la versió més nova.
3. Si el servidor encara té una versió antiga en memòria cau, connecteu-vos via SFTP i elimineu la carpeta de memòria cau del Workshop del mod específic a /steamapps/workshop/content/108600/<WorkshopID>/. Reinicieu el servidor per forçar una descàrrega neta.

Solució per a jugadors

Els jugadors que no es poden connectar per discrepàncies de versions de mods haurien de:

1. Obrir Steam i navegar a Library → Project Zomboid.
2. Fer clic dret a Project Zomboid, seleccionar Properties → Local Files → Verify Integrity of Game Files.
3. També navegar a la carpeta del Steam Workshop de Project Zomboid al seu ordinador local i eliminar els fitxers de mod en memòria cau per forçar una nova descàrrega.
4. Iniciar el joc i connectar-se al servidor de nou.

8. Buidar la memòria cau del Steam Workshop

Si múltiples problemes de mods persisteixen i sospiteu que la memòria cau de descàrregues del Workshop està corrompuda, podeu forçar una nova descàrrega completa de tots els mods del Workshop.

1. Atureu el servidor a GPanel.
2. Connecteu-vos via SFTP i navegueu a /steamapps/workshop/.
3. Elimineu tota la carpeta workshop/ (o el seu contingut).
4. Inicieu el servidor. Steam tornarà a descarregar tots els elements del Workshop des de zero.
5. Observeu la consola de GPanel per confirmar que tots els mods acaben de descarregar-se abans que el servidor comenci la càrrega del món.

Referència ràpida de diagnòstic

Encara teniu problemes amb mods?