Questa guida copre la risoluzione avanzata dei problemi con le mod per i server Project Zomboid ospitati con Legion Hosting. Se non hai ancora installato le mod, inizia prima con la guida base all'installazione delle mod. Questo articolo affronta i problemi più comuni relativi alle mod riscontrati nei ticket di supporto di Legion Hosting, inclusi la corruzione del WorldDictionary, errori di formato delle mod, conflitti di ordine di caricamento e disallineamenti di versione tra server e client.

Prima di Iniziare

• Accedi a GPanel e seleziona il tuo server Project Zomboid.
• Ferma il tuo server prima di apportare qualsiasi modifica alla configurazione o ai file.
• Esegui il backup della cartella di salvataggio del tuo mondo (/.cache/saves/multiplayer/) tramite SFTP o GPanel prima di tentare qualsiasi soluzione. Vedi la guida SFTP se non hai familiarità con i trasferimenti di file.
• Tieni a portata di mano il percorso del file .ini del tuo server: /.cache/server/<servername>.ini (es. servertest.ini).

1. Errori di Formato delle Mod (B42 vs B41)

Il motivo più comune per cui le mod non si caricano è un formato errato nella riga Mods= del file .ini del tuo server. Build 42 e Build 41 utilizzano una sintassi diversa, e confonderli farà fallire silenziosamente il caricamento delle tue mod.

Formato B42 (Predefinito Attuale)

Build 42 richiede un prefisso backslash prima di ogni Mod ID nella riga Mods=:

Mods=\ModID1;\ModID2;\ModID3;

Il formato DLMP combina Workshop ID e Mod ID con un separatore backslash:

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

La riga WorkshopItems= utilizza lo stesso formato separato da punto e virgola su entrambe le build:

WorkshopItems=2392987841;1550458773;2786383654

Formato B41 (Legacy)

Build 41 utilizza Mod ID semplici separati da punto e virgola senza backslash:

Mods=ModID1;ModID2;ModID3

Come Risolvere

1. Apri /.cache/server/<servername>.ini nel File Manager di GPanel.
2. Trova la riga Mods= e controlla il formato rispetto agli esempi sopra.
3. Se il formato è sbagliato per la tua versione di build, correggilo. Usa il Legion Hosting Mod Organizer per generare automaticamente righe formattate correttamente.
4. Salva il file e avvia il server.

2. Corruzione del WorldDictionary

Il WorldDictionary è un file (WorldDictionary.bin) che mappa i nomi degli oggetti agli ID numerici interni. Quando le mod vengono aggiunte o rimosse, il dictionary può corrompersi, causando il crash del server all'avvio con un WorldDictionaryException.

Sintomi

• La console o debug.log mostra errori WorldDictionaryException o WorldDictionary.
• Il server va in crash immediatamente durante l'avvio, specificamente durante il caricamento del mondo.
• Il crash è iniziato dopo aver aggiunto, rimosso o aggiornato delle mod.

Comprendere il Rischio

Passaggi di Recupero

1. Ferma il tuo server in GPanel.
2. Esegui il backup dell'intera cartella di salvataggio tramite SFTP: scarica l'intera directory /.cache/saves/multiplayer/<YourWorldName>/ sulla tua macchina locale.
3. Prima, prova semplicemente a ripristinare la modifica della mod che ha causato l'errore. Se hai appena aggiunto una mod, rimuovila sia da Mods= che da WorkshopItems= nel file .ini. Se hai appena rimosso una mod, riaggiungila. Avvia il server e vedi se il crash è risolto.
4. Se il ripristino della modifica della mod non funziona, connettiti tramite SFTP e naviga in /.cache/saves/multiplayer/<YourWorldName>/.
5. Elimina WorldDictionary.bin.
6. Avvia il server. Project Zomboid rigenererà il dictionary all'avvio.
7. Unisciti al server e ispeziona il mondo per oggetti corrotti, veicoli mancanti o inventari danneggiati. Se il mondo è gravemente danneggiato, ripristina dal backup che hai creato al passaggio 2.

3. Conflitti con la Mod Authentic Z

Authentic Z è una delle raccolte di mod più popolari di Project Zomboid, ma è una frequente fonte di ticket di supporto perché contiene più sotto-mod che vanno in conflitto tra loro.

La Regola

Errori Comuni

• Aggiungere sia Authentic Z - Current che Authentic Z - Litemode contemporaneamente.
• Aggiungere sotto-mod Authentic Z progettate per il single player insieme alla versione multiplayer.
• Non rendersi conto che diverse sotto-mod Authentic Z condividono lo stesso Workshop ID ma hanno Mod ID diversi, quindi il download dal Workshop ha successo ma il server carica file mod in conflitto.

Come Risolvere

1. Apri /.cache/server/<servername>.ini nel File Manager di GPanel.
2. Cerca nella riga Mods= ogni voce contenente Authentic o AuthenticZ.
3. Mantieni solo una sotto-mod Authentic Z (consigliata: Authentic Z - Current). Rimuovi tutte le altre voci Authentic Z sia dalla riga Mods= che da WorkshopItems=.
4. Salva il file e riavvia il server.

4. Problemi di Sensibilità alle Maiuscole/Minuscole su Linux

I server Legion Hosting girano su Linux, dove i nomi di file e cartelle sono sensibili a maiuscole/minuscole. Un file chiamato MyMod.lua e mymod.lua sono trattati come due file completamente diversi. Questo causa problemi quando gli autori delle mod sviluppano su Windows (insensibile alle maiuscole/minuscole) e le loro mod contengono riferimenti a file non corrispondenti.

Sintomi

• Una mod funziona perfettamente in single player sul tuo PC Windows ma fallisce sul server.
• La console o debug.log mostra errori FileNotFoundException o can't find file che fanno riferimento a uno script Lua o a una texture all'interno di una mod.
• L'errore punta a un file che esiste nella cartella della mod, ma con una capitalizzazione diversa (ad esempio, il codice fa riferimento a Items.txt ma il file effettivo si chiama items.txt).

Come Diagnosticare

1. Controlla la console o i file di log in /.cache/Logs/ per il percorso esatto del file menzionato nell'errore.
2. Connettiti tramite SFTP e naviga nella cartella della mod in /steamapps/workshop/content/108600/<WorkshopID>/.
3. Confronta i nomi dei file su disco con il nome del file riferito nel messaggio di errore. Cerca differenze di capitalizzazione.

Come Risolvere

• Se puoi rinominare il file: Connettiti tramite SFTP e rinomina il file per corrispondere alla capitalizzazione attesa dal codice della mod. Nota che questa correzione sarà sovrascritta se la mod si aggiorna sullo Steam Workshop.
• Se il problema è nella mod stessa: Segnala il bug all'autore della mod nella pagina dello Steam Workshop. Menziona che il riferimento al file ha un disallineamento di maiuscole/minuscole e che fallisce sui server Linux. Molti autori di mod non sono consapevoli della sensibilità alle maiuscole/minuscole di Linux.
• Come soluzione alternativa: Controlla i commenti della pagina Workshop della mod -- altri operatori di server Linux potrebbero aver pubblicato una soluzione o un fork compatibile della mod.

5. Problemi di Ordine di Caricamento delle Mod

Project Zomboid carica le mod nell'ordine in cui appaiono nella riga Mods=. Alcune mod dipendono da altre mod che devono essere caricate per prime. Se una dipendenza viene caricata dopo la mod che la richiede, la mod dipendente potrebbe fallire silenziosamente o causare errori.

Sintomi

• Le funzionalità delle mod funzionano parzialmente -- alcuni oggetti o sistemi di una mod sono presenti ma altri mancano.
• La console mostra errori NullPointerException o attempt to index a nil value che fanno riferimento agli script Lua di una mod.
• Gli errori appaiono solo quando è installata una combinazione specifica di mod, ma ogni mod funziona bene individualmente.

Come Risolvere

1. Controlla la pagina dello Steam Workshop di ogni mod per una sezione "Required Mods" o "Load Order". Molti autori di mod specificano quali mod devono essere caricate prima delle loro.
2. Apri /.cache/server/<servername>.ini e trova la riga Mods=.
3. Riordina le voci in modo che le mod di dipendenza appaiano prima delle mod che le richiedono. Ad esempio, se la Mod B richiede la Mod A, la riga dovrebbe essere Mods=\ModA;\ModB; (formato B42).
4. Le mod framework e libreria (come ModFramework, TsarLib o Shark's Mod Utils) dovrebbero sempre essere elencate per prime nella riga Mods=.
5. Salva il file e riavvia il server.

6. Crash del Server Dopo l'Aggiunta di Mod

Se il tuo server funzionava bene e va in crash dopo aver aggiunto una o più mod, la nuova mod è probabilmente la causa. Questa sezione spiega come isolare la mod problematica.

Isolamento Passo per Passo

1. Ferma il server in GPanel.
2. Apri /.cache/server/<servername>.ini nel File Manager.
3. Nota tutte le mod che hai appena aggiunto. Rimuovile tutte sia dalla riga Mods= che da WorkshopItems=.
4. Avvia il server. Se si avvia con successo, il problema è in una delle mod che hai rimosso.
5. Aggiungi nuovamente le mod una alla volta, riavviando il server dopo ogni aggiunta. Quando il crash torna, l'ultima mod aggiunta è la causa.
6. Una volta identificata, controlla la pagina Workshop della mod per:
   • Una nota sulla compatibilità B42 -- molte mod B41 non sono state aggiornate per B42.
   • Conflitti noti con altre mod che stai eseguendo.
   • Mod di dipendenza richieste che potresti non aver installato.

Leggere il Log dei Crash

Prima di eseguire il processo di isolamento, controlla il log dei crash -- spesso punta direttamente alla mod problematica:

1. In GPanel, apri la scheda Console e scorri fino alla fine dell'output.
2. Cerca righe STACK TRACE, Exception o ERROR.
3. Le righe immediatamente sopra lo stack trace tipicamente fanno riferimento a un nome di file mod o Mod ID -- questo ti dice quale mod ha causato il crash.
4. Per maggiori dettagli, apri il file di log completo tramite SFTP in /.cache/Logs/ e controlla il file DebugLog-server.txt o debug.log più recente.

7. Disallineamenti di Versione delle Mod (Server vs Client)

Project Zomboid richiede che il server e tutti i client connessi abbiano la stessa versione di ogni mod. Se una mod si aggiorna sullo Steam Workshop e il server scarica la nuova versione ma un giocatore ha ancora la vecchia versione in cache (o viceversa), si verificheranno fallimenti di connessione o crash.

Sintomi

• I giocatori ricevono un errore "Mod mismatch" o "Version mismatch" quando cercano di connettersi.
• Alcuni giocatori possono connettersi ma altri no -- quelli che non possono connettersi hanno una versione mod diversa in cache localmente.
• Il server funzionava bene, poi una mod si è aggiornata sullo Steam Workshop e improvvisamente alcuni giocatori non possono unirsi.
• I giocatori vedono texture mancanti, oggetti o elementi UI rotti da mod che sono state recentemente aggiornate.

Soluzione per gli Operatori del Server

1. Ferma il server in GPanel.
2. Avvia di nuovo il server. All'avvio, il server riscarica le ultime versioni di tutte le mod Workshop. Questo garantisce che il server stia eseguendo la versione più recente.
3. Se il server ha ancora una vecchia versione in cache, connettiti tramite SFTP ed elimina la cartella di cache Workshop della mod specifica in /steamapps/workshop/content/108600/<WorkshopID>/. Riavvia il server per forzare un download pulito.

Soluzione per i Giocatori

I giocatori che non possono connettersi a causa di disallineamenti di versione delle mod dovrebbero:

1. Aprire Steam e navigare in Library → Project Zomboid.
2. Fare clic con il tasto destro su Project Zomboid, selezionare Properties → Local Files → Verify Integrity of Game Files.
3. Inoltre, navigare nella cartella Steam Workshop per Project Zomboid sulla loro macchina locale ed eliminare i file mod in cache per forzare un nuovo download.
4. Avviare il gioco e connettersi di nuovo al server.

8. Cancellazione della Cache dello Steam Workshop

Se persistono più problemi con le mod e sospetti che la cache di download Workshop sia corrotta, puoi forzare un nuovo download completo di tutte le mod Workshop.

1. Ferma il server in GPanel.
2. Connettiti tramite SFTP e naviga in /steamapps/workshop/.
3. Elimina l'intera cartella workshop/ (o il suo contenuto).
4. Avvia il server. Steam riscaricherà tutti gli elementi Workshop da zero.
5. Osserva la Console di GPanel per confermare che tutte le mod finiscano di scaricarsi prima che il server inizi il caricamento del mondo.

Riferimento Diagnostico Rapido

Hai Ancora Problemi con le Mod?