Ten przewodnik obejmuje zaawansowane rozwiązywanie problemów z modami dla serwerów Project Zomboid hostowanych w Legion Hosting. Jeśli nie zainstalowałeś jeszcze modów, zacznij najpierw od podstawowego przewodnika instalacji modów. Ten artykuł porusza najczęstsze problemy związane z modami spotykane w zgłoszeniach do pomocy technicznej Legion Hosting, w tym uszkodzenie WorldDictionary, błędy formatu modów, konflikty kolejności ładowania oraz niezgodności wersji między serwerem a klientem.

Zanim zaczniesz

• Zaloguj się do GPanel i wybierz swój serwer Project Zomboid.
• Zatrzymaj serwer przed wprowadzeniem jakichkolwiek zmian w konfiguracji lub plikach.
• Wykonaj kopię zapasową folderu zapisu świata (/.cache/saves/multiplayer/) przez SFTP lub GPanel przed podjęciem jakiejkolwiek naprawy. Zobacz przewodnik SFTP, jeśli nie znasz transferu plików.
• Przygotuj ścieżkę do pliku .ini serwera: /.cache/server/<servername>.ini (np. servertest.ini).

1. Błędy formatu modów (B42 vs B41)

Najczęstszym powodem, dla którego mody nie ładują się, jest nieprawidłowy format w linii Mods= pliku .ini serwera. Build 42 i Build 41 używają różnej składni, a ich pomylenie spowoduje ciche nieładowanie modów.

Format B42 (obecny domyślny)

Build 42 wymaga prefiksu z ukośnikiem wstecznym przed każdym identyfikatorem moda w linii Mods=:

Mods=\ModID1;\ModID2;\ModID3;

Format DLMP łączy identyfikatory Workshop oraz identyfikatory modów za pomocą separatora w postaci ukośnika wstecznego:

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

Linia WorkshopItems= używa tego samego formatu rozdzielanego średnikami w obu buildach:

WorkshopItems=2392987841;1550458773;2786383654

Format B41 (starszy)

Build 41 używa zwykłych identyfikatorów modów rozdzielanych średnikami, bez ukośnika wstecznego:

Mods=ModID1;ModID2;ModID3

Jak naprawić

1. Otwórz /.cache/server/<servername>.ini w Menedżerze plików GPanel.
2. Znajdź linię Mods= i sprawdź format względem powyższych przykładów.
3. Jeśli format jest nieprawidłowy dla Twojej wersji buildu, popraw go. Użyj Legion Hosting Mod Organizer, aby automatycznie wygenerować poprawnie sformatowane linie.
4. Zapisz plik i uruchom serwer.

2. Uszkodzenie WorldDictionary

WorldDictionary to plik (WorldDictionary.bin), który mapuje nazwy przedmiotów na wewnętrzne identyfikatory numeryczne. Gdy mody są dodawane lub usuwane, słownik może ulec uszkodzeniu, powodując awarię serwera podczas uruchamiania z błędem WorldDictionaryException.

Objawy

• Konsola lub debug.log pokazuje błędy WorldDictionaryException lub WorldDictionary.
• Serwer ulega awarii natychmiast podczas uruchamiania, konkretnie podczas ładowania świata.
• Awaria rozpoczęła się po dodaniu, usunięciu lub zaktualizowaniu modów.

Zrozumienie ryzyka

Kroki odzyskiwania

1. Zatrzymaj serwer w GPanel.
2. Wykonaj kopię zapasową całego folderu zapisu przez SFTP: pobierz pełny katalog /.cache/saves/multiplayer/<YourWorldName>/ na swój komputer lokalny.
3. Najpierw spróbuj po prostu cofnąć zmianę moda, która spowodowała błąd. Jeśli właśnie dodałeś moda, usuń go zarówno z Mods=, jak i WorkshopItems= w pliku .ini. Jeśli właśnie usunąłeś moda, dodaj go z powrotem. Uruchom serwer i sprawdź, czy awaria została rozwiązana.
4. Jeśli cofnięcie zmiany moda nie zadziała, połącz się przez SFTP i przejdź do /.cache/saves/multiplayer/<YourWorldName>/.
5. Usuń WorldDictionary.bin.
6. Uruchom serwer. Project Zomboid ponownie wygeneruje słownik podczas uruchamiania.
7. Dołącz do serwera i sprawdź świat pod kątem uszkodzonych przedmiotów, brakujących pojazdów lub uszkodzonych ekwipunków. Jeśli świat jest poważnie uszkodzony, przywróć go z kopii zapasowej utworzonej w kroku 2.

3. Konflikty modów Authentic Z

Authentic Z to jedna z najpopularniejszych kolekcji modów do Project Zomboid, ale jest częstym źródłem zgłoszeń do pomocy technicznej, ponieważ zawiera wiele submodów, które konfliktują ze sobą.

Zasada

Częste błędy

• Dodawanie zarówno Authentic Z - Current, jak i Authentic Z - Litemode jednocześnie.
• Dodawanie submodów Authentic Z przeznaczonych dla trybu jednoosobowego obok wersji wieloosobowej.
• Nieświadomość, że różne submody Authentic Z dzielą ten sam identyfikator Workshop, ale mają różne identyfikatory modów, więc pobieranie z Workshop kończy się powodzeniem, ale serwer ładuje konfliktujące pliki modów.

Jak naprawić

1. Otwórz /.cache/server/<servername>.ini w Menedżerze plików GPanel.
2. Przeszukaj linię Mods= pod kątem każdego wpisu zawierającego Authentic lub AuthenticZ.
3. Zachowaj tylko jeden submod Authentic Z (zalecany: Authentic Z - Current). Usuń wszystkie pozostałe wpisy Authentic Z zarówno z linii Mods=, jak i WorkshopItems=.
4. Zapisz plik i zrestartuj serwer.

4. Problemy z rozróżnianiem wielkości liter w systemie Linux

Serwery Legion Hosting działają w systemie Linux, gdzie nazwy plików i folderów rozróżniają wielkość liter. Plik o nazwie MyMod.lua i mymod.lua są traktowane jako dwa zupełnie różne pliki. Powoduje to problemy, gdy autorzy modów tworzą je w systemie Windows (nierozróżniającym wielkości liter), a ich mody zawierają niedopasowane odwołania do plików.

Objawy

• Mod działa idealnie w trybie jednoosobowym na Twoim komputerze z Windows, ale zawodzi na serwerze.
• Konsola lub debug.log pokazuje błędy FileNotFoundException lub can't find file odnoszące się do skryptu Lua lub tekstury wewnątrz moda.
• Błąd wskazuje na plik, który istnieje w folderze moda, ale z inną wielkością liter (np. kod odwołuje się do Items.txt, ale rzeczywisty plik nazywa się items.txt).

Jak zdiagnozować

1. Sprawdź konsolę lub pliki logów w /.cache/Logs/ pod kątem dokładnej ścieżki pliku wymienionej w błędzie.
2. Połącz się przez SFTP i przejdź do folderu moda w /steamapps/workshop/content/108600/<WorkshopID>/.
3. Porównaj nazwy plików na dysku z nazwą pliku wymienioną w komunikacie o błędzie. Szukaj różnic w wielkości liter.

Jak naprawić

• Jeśli możesz zmienić nazwę pliku: Połącz się przez SFTP i zmień nazwę pliku, aby pasowała do wielkości liter oczekiwanej przez kod moda. Pamiętaj, że ta poprawka zostanie nadpisana, jeśli mod zaktualizuje się w Steam Workshop.
• Jeśli problem leży w samym modzie: Zgłoś błąd autorowi moda na stronie Steam Workshop. Wspomnij, że odwołanie do pliku ma niezgodność wielkości liter i że zawodzi na serwerach Linux. Wielu autorów modów nie jest świadomych rozróżniania wielkości liter w systemie Linux.
• Jako obejście: Sprawdź komentarze na stronie Workshop moda — inni operatorzy serwerów Linux mogli opublikować poprawkę lub kompatybilny fork moda.

5. Problemy z kolejnością ładowania modów

Project Zomboid ładuje mody w kolejności, w jakiej pojawiają się w linii Mods=. Niektóre mody zależą od tego, by inne mody były załadowane jako pierwsze. Jeśli zależność zostanie załadowana po modzie, który jej wymaga, zależny mod może po cichu zawieść lub powodować błędy.

Objawy

• Funkcje moda działają częściowo — niektóre przedmioty lub systemy z moda są obecne, ale inne brakują.
• Konsola pokazuje błędy NullPointerException lub attempt to index a nil value odnoszące się do skryptów Lua moda.
• Błędy pojawiają się tylko wtedy, gdy zainstalowana jest konkretna kombinacja modów, ale każdy mod działa dobrze osobno.

Jak naprawić

1. Sprawdź stronę Steam Workshop każdego moda pod kątem sekcji „Required Mods" lub „Load Order". Wielu autorów modów określa, które mody muszą być załadowane przed ich modem.
2. Otwórz /.cache/server/<servername>.ini i znajdź linię Mods=.
3. Zmień kolejność wpisów tak, aby mody-zależności pojawiały się przed modami, które ich wymagają. Na przykład, jeśli Mod B wymaga Moda A, linia powinna brzmieć Mods=\ModA;\ModB; (format B42).
4. Mody frameworkowe i biblioteczne (takie jak ModFramework, TsarLib lub Shark's Mod Utils) powinny być zawsze wymienione jako pierwsze w linii Mods=.
5. Zapisz plik i zrestartuj serwer.

6. Awarie serwera po dodaniu modów

Jeśli Twój serwer działał poprawnie i ulega awarii po dodaniu jednego lub więcej modów, nowy mod jest prawdopodobnie przyczyną. Ta sekcja przeprowadzi Cię przez izolowanie problematycznego moda.

Izolacja krok po kroku

1. Zatrzymaj serwer w GPanel.
2. Otwórz /.cache/server/<servername>.ini w Menedżerze plików.
3. Zanotuj wszystkie mody, które właśnie dodałeś. Usuń wszystkie z nich zarówno z linii Mods=, jak i WorkshopItems=.
4. Uruchom serwer. Jeśli uruchomi się pomyślnie, problem leży w jednym z usuniętych modów.
5. Dodawaj mody z powrotem pojedynczo, restartując serwer po każdym dodaniu. Gdy awaria powróci, ostatni dodany mod jest przyczyną.
6. Po zidentyfikowaniu sprawdź stronę Workshop moda pod kątem:
   • Informacji o kompatybilności z B42 — wiele modów B41 nie zostało zaktualizowanych do B42.
   • Znanych konfliktów z innymi uruchamianymi modami.
   • Wymaganych modów-zależności, których możesz nie mieć zainstalowanych.

Odczytywanie logu awarii

Przed przeprowadzeniem procesu izolacji sprawdź log awarii — często wskazuje on bezpośrednio na problematyczny mod:

1. W GPanel otwórz zakładkę Console i przewiń do końca danych wyjściowych.
2. Szukaj linii STACK TRACE, Exception lub ERROR.
3. Linie bezpośrednio nad śladem stosu zazwyczaj odnoszą się do nazwy pliku moda lub identyfikatora moda — to mówi Ci, który mod wywołał awarię.
4. Aby uzyskać więcej szczegółów, otwórz pełny plik logu przez SFTP w /.cache/Logs/ i sprawdź najnowszy plik DebugLog-server.txt lub debug.log.

7. Niezgodności wersji modów (serwer vs klient)

Project Zomboid wymaga, aby serwer i wszyscy połączeni klienci mieli tę samą wersję każdego moda. Jeśli mod zaktualizuje się w Steam Workshop, a serwer pobierze nową wersję, ale gracz nadal ma w pamięci podręcznej starą wersję (lub odwrotnie), wystąpią błędy połączenia lub awarie.

Objawy

• Gracze otrzymują błąd „Mod mismatch" lub „Version mismatch" przy próbie połączenia.
• Niektórzy gracze mogą się połączyć, ale inni nie — ci, którzy nie mogą się połączyć, mają lokalnie zapisaną w pamięci podręcznej inną wersję moda.
• Serwer działał poprawnie, następnie mod zaktualizował się w Steam Workshop i nagle niektórzy gracze nie mogą dołączyć.
• Gracze widzą brakujące tekstury, przedmioty lub uszkodzone elementy interfejsu z modów, które zostały niedawno zaktualizowane.

Naprawa dla operatorów serwerów

1. Zatrzymaj serwer w GPanel.
2. Uruchom serwer ponownie. Podczas uruchamiania serwer ponownie pobiera najnowsze wersje wszystkich modów Workshop. Zapewnia to, że serwer działa na najnowszej wersji.
3. Jeśli serwer nadal ma w pamięci podręcznej starą wersję, połącz się przez SFTP i usuń folder pamięci podręcznej Workshop konkretnego moda w /steamapps/workshop/content/108600/<WorkshopID>/. Zrestartuj serwer, aby wymusić czyste pobranie.

Naprawa dla graczy

Gracze, którzy nie mogą się połączyć z powodu niezgodności wersji modów, powinni:

1. Otworzyć Steam i przejść do Library → Project Zomboid.
2. Kliknąć prawym przyciskiem myszy Project Zomboid, wybrać Properties → Local Files → Verify Integrity of Game Files.
3. Przejść również do folderu Steam Workshop dla Project Zomboid na swoim komputerze lokalnym i usunąć pliki modów z pamięci podręcznej, aby wymusić ponowne pobranie.
4. Uruchomić grę i ponownie połączyć się z serwerem.

8. Czyszczenie pamięci podręcznej Steam Workshop

Jeśli liczne problemy z modami nie ustępują i podejrzewasz, że pamięć podręczna pobierania Workshop jest uszkodzona, możesz wymusić całkowite ponowne pobranie wszystkich modów Workshop.

1. Zatrzymaj serwer w GPanel.
2. Połącz się przez SFTP i przejdź do /steamapps/workshop/.
3. Usuń cały folder workshop/ (lub jego zawartość).
4. Uruchom serwer. Steam ponownie pobierze wszystkie elementy Workshop od zera.
5. Obserwuj konsolę GPanel, aby potwierdzić, że wszystkie mody zakończyły pobieranie, zanim serwer rozpocznie ładowanie świata.

Szybkie odniesienie diagnostyczne

Nadal masz problemy z modami?