Това ръководство обхваща напреднало отстраняване на проблеми с модове за Project Zomboid сървъри, хоствани в Legion Hosting. Ако още не сте инсталирали модове, започнете първо с основното ръководство за инсталиране на модове. Тази статия разглежда най-често срещаните проблеми, свързани с модове, наблюдавани в тикетите за поддръжка на Legion Hosting, включително WorldDictionary корупция, грешки във формата на модовете, конфликти в реда на зареждане и несъответствия във версиите между сървъра и клиента.

Преди да започнете

• Влезте в GPanel и изберете вашия Project Zomboid сървър.
• Спрете сървъра си, преди да правите каквито и да е промени в конфигурацията или файловете.
• Направете резервно копие на папката със световете си (/.cache/saves/multiplayer/) чрез SFTP или GPanel, преди да опитате каквото и да е поправяне. Вижте ръководството за SFTP, ако не сте запознати с прехвърлянето на файлове.
• Имайте готов пътя към .ini файла на сървъра си: /.cache/server/<servername>.ini (напр. servertest.ini).

1. Грешки във формата на модовете (B42 срещу B41)

Най-честата причина модовете да не се зареждат е неправилен формат в реда Mods= на .ini файла на вашия сървър. Build 42 и Build 41 използват различен синтаксис и смесването им ще доведе до тихо неуспешно зареждане на модовете ви.

B42 формат (текущ по подразбиране)

Build 42 изисква префикс с обратна наклонена черта преди всеки Mod ID в реда Mods=:

Mods=\ModID1;\ModID2;\ModID3;

DLMP форматът комбинира Workshop ID-та и Mod ID-та с разделител обратна наклонена черта:

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

Редът WorkshopItems= използва същия формат, разделен с точка и запетая в двата build-а:

WorkshopItems=2392987841;1550458773;2786383654

B41 формат (наследен)

Build 41 използва обикновени Mod ID-та, разделени с точка и запетая без обратна наклонена черта:

Mods=ModID1;ModID2;ModID3

Как да поправите

1. Отворете /.cache/server/<servername>.ini в GPanel File Manager.
2. Намерете реда Mods= и проверете формата спрямо примерите по-горе.
3. Ако форматът е грешен за вашата версия на build, поправете го. Използвайте Legion Hosting Mod Organizer, за да генерирате правилно форматирани редове автоматично.
4. Запазете файла и стартирайте сървъра.

2. WorldDictionary корупция

WorldDictionary е файл (WorldDictionary.bin), който картографира имената на предметите към вътрешни числови ID-та. Когато се добавят или премахват модове, речникът може да се повреди, причинявайки срив на сървъра при стартиране с WorldDictionaryException.

Симптоми

• Конзолата или debug.log показва WorldDictionaryException или WorldDictionary грешки.
• Сървърът се срива незабавно при стартиране, специфично по време на зареждането на света.
• Сривът започна след добавяне, премахване или актуализиране на модове.

Разбиране на риска

Стъпки за възстановяване

1. Спрете сървъра си в GPanel.
2. Направете резервно копие на цялата си папка със световете чрез SFTP: изтеглете цялата директория /.cache/saves/multiplayer/<YourWorldName>/ на локалната си машина.
3. Първо, опитайте просто да върнете промяната на мода, която причини грешката. Ако току-що сте добавили мод, премахнете го от Mods= и WorkshopItems= във .ini файла. Ако току-що сте премахнали мод, добавете го обратно. Стартирайте сървъра и вижте дали сривът е разрешен.
4. Ако връщането на промяната на мода не работи, свържете се чрез SFTP и навигирайте до /.cache/saves/multiplayer/<YourWorldName>/.
5. Изтрийте WorldDictionary.bin.
6. Стартирайте сървъра. Project Zomboid ще регенерира речника при стартиране.
7. Присъединете се към сървъра и проверете света за повредени предмети, липсващи превозни средства или счупени инвентари. Ако светът е сериозно повреден, възстановете от резервното копие, което сте създали в стъпка 2.

3. Конфликти с мода Authentic Z

Authentic Z е една от най-популярните мод колекции за Project Zomboid, но е чест източник на тикети за поддръжка, защото съдържа множество под-модове, които конфликтват помежду си.

Правилото

Чести грешки

• Добавяне както на Authentic Z - Current, така и на Authentic Z - Litemode едновременно.
• Добавяне на Authentic Z под-модове, проектирани за сингълплейър, заедно с мултиплейър версията.
• Неосъзнаване, че различните Authentic Z под-модове споделят един и същи Workshop ID, но имат различни Mod ID-та, така че Workshop изтеглянето успява, но сървърът зарежда конфликтуващи мод файлове.

Как да поправите

1. Отворете /.cache/server/<servername>.ini в GPanel File Manager.
2. Потърсете в реда Mods= всеки запис, съдържащ Authentic или AuthenticZ.
3. Запазете само един Authentic Z под-мод (препоръчително: Authentic Z - Current). Премахнете всички останали Authentic Z записи както от реда Mods=, така и от WorkshopItems=.
4. Запазете файла и рестартирайте сървъра.

4. Проблеми с чувствителност към регистъра в Linux

Legion Hosting сървърите работят на Linux, където имената на файловете и папките са чувствителни към регистъра. Файл с име MyMod.lua и mymod.lua се третират като два напълно различни файла. Това причинява проблеми, когато авторите на модове разработват на Windows (нечувствителен към регистъра) и техните модове съдържат несъответстващи файлови референции.

Симптоми

• Мод работи перфектно в сингълплейър на вашия Windows PC, но се проваля на сървъра.
• Конзолата или debug.log показва FileNotFoundException или can't find file грешки, отнасящи се до Lua скрипт или текстура вътре в мод.
• Грешката сочи към файл, който наистина съществува в папката на мода, но с различна капитализация (напр. кодът се отнася до Items.txt, но действителният файл е именуван items.txt).

Как да диагностицирате

1. Проверете конзолата или лог файловете в /.cache/Logs/ за точния файлов път, споменат в грешката.
2. Свържете се чрез SFTP и навигирайте до папката на мода в /steamapps/workshop/content/108600/<WorkshopID>/.
3. Сравнете имената на файловете на диска с името на файла, посочено в съобщението за грешка. Потърсете разлики в капитализацията.

Как да поправите

• Ако можете да преименувате файла: Свържете се чрез SFTP и преименувайте файла, за да съответства на капитализацията, очаквана от кода на мода. Имайте предвид, че тази поправка ще бъде презаписана, ако модът се актуализира в Steam Workshop.
• Ако проблемът е в самия мод: Докладвайте бъга на автора на мода на страницата в Steam Workshop. Споменете, че файловата референция има несъответствие в регистъра и че се проваля на Linux сървъри. Много автори на модове не са запознати с чувствителността към регистъра в Linux.
• Като заобикалящо решение: Проверете коментарите на Workshop страницата на мода — други оператори на Linux сървъри може да са публикували поправка или съвместим форк на мода.

5. Проблеми с реда на зареждане на модове

Project Zomboid зарежда модовете в реда, в който се появяват в реда Mods=. Някои модове зависят от това други модове да бъдат заредени първи. Ако зависимост е заредена след мода, който я изисква, зависимият мод може да се провали тихо или да причини грешки.

Симптоми

• Функциите на мода работят частично — някои предмети или системи от мод присъстват, но други липсват.
• Конзолата показва NullPointerException или attempt to index a nil value грешки, отнасящи се до Lua скриптовете на мода.
• Грешките се появяват само когато е инсталирана конкретна комбинация от модове, но всеки мод работи добре поотделно.

Как да поправите

1. Проверете страницата в Steam Workshop на всеки мод за секция "Required Mods" или "Load Order". Много автори на модове посочват кои модове трябва да бъдат заредени преди техните.
2. Отворете /.cache/server/<servername>.ini и намерете реда Mods=.
3. Преподредете записите така, че модовете-зависимости да се появяват преди модовете, които ги изискват. Например, ако Мод B изисква Мод A, редът трябва да бъде Mods=\ModA;\ModB; (B42 формат).
4. Framework и библиотечни модове (като ModFramework, TsarLib или Shark's Mod Utils) винаги трябва да са изброени първи в реда Mods=.
5. Запазете файла и рестартирайте сървъра.

6. Срив на сървъра след добавяне на модове

Ако сървърът ви работеше добре и се срине след добавяне на един или повече модове, новият мод вероятно е причината. Тази секция ви превежда през изолиране на проблемния мод.

Стъпка по стъпка изолиране

1. Спрете сървъра в GPanel.
2. Отворете /.cache/server/<servername>.ini във File Manager.
3. Запишете всички модове, които току-що сте добавили. Премахнете всички от тях както от реда Mods=, така и от WorkshopItems=.
4. Стартирайте сървъра. Ако стартира успешно, проблемът е в един от модовете, които сте премахнали.
5. Добавяйте модовете обратно един по един, рестартирайки сървъра след всяко добавяне. Когато сривът се върне, последният мод, който сте добавили, е причината.
6. След като е идентифициран, проверете страницата на мода в Workshop за:
   • Бележка относно B42 съвместимост — много B41 модове не са актуализирани за B42.
   • Известни конфликти с други модове, които използвате.
   • Изисквани мод зависимости, които може да не сте инсталирали.

Четене на лога за срив

Преди да извършите процеса на изолиране, проверете лога за срив — той често сочи директно към проблемния мод:

1. В GPanel отворете раздела Console и превъртете до края на изхода.
2. Потърсете редове STACK TRACE, Exception или ERROR.
3. Редовете непосредствено над stack trace обикновено се отнасят до име на мод файл или Mod ID — това ви казва кой мод е предизвикал срива.
4. За повече детайли отворете пълния лог файл чрез SFTP в /.cache/Logs/ и проверете най-новия файл DebugLog-server.txt или debug.log.

7. Несъответствия във версиите на модовете (Сървър срещу Клиент)

Project Zomboid изисква сървърът и всички свързани клиенти да имат същата версия на всеки мод. Ако мод се актуализира в Steam Workshop и сървърът изтегли новата версия, но играч все още има старата версия кеширана (или обратно), ще възникнат провали при свързване или сривове.

Симптоми

• Играчите получават грешка "Mod mismatch" или "Version mismatch", когато се опитват да се свържат.
• Някои играчи могат да се свържат, но други не могат — тези, които не могат да се свържат, имат различна версия на мода, кеширана локално.
• Сървърът работеше добре, после мод се актуализира в Steam Workshop и внезапно някои играчи не могат да се присъединят.
• Играчите виждат липсващи текстури, предмети или счупени UI елементи от модове, които наскоро са били актуализирани.

Поправка за оператори на сървъри

1. Спрете сървъра в GPanel.
2. Стартирайте сървъра отново. При стартиране сървърът преизтегля най-новите версии на всички Workshop модове. Това гарантира, че сървърът работи с най-новата версия.
3. Ако сървърът все още има стара версия кеширана, свържете се чрез SFTP и изтрийте конкретната Workshop кеш папка на мода в /steamapps/workshop/content/108600/<WorkshopID>/. Рестартирайте сървъра, за да принудите чисто изтегляне.

Поправка за играчи

Играчите, които не могат да се свържат поради несъответствия във версиите на модовете, трябва:

1. Да отворят Steam и да навигират до Library → Project Zomboid.
2. Десен клик върху Project Zomboid, изберете Properties → Local Files → Verify Integrity of Game Files.
3. Също да навигират до Steam Workshop папката за Project Zomboid на тяхната локална машина и да изтрият кешираните мод файлове, за да принудят преизтегляне.
4. Да стартират играта и да се свържат към сървъра отново.

8. Изчистване на Steam Workshop кеша

Ако множество проблеми с модове продължават и подозирате, че Workshop изтеглящият кеш е повреден, можете да принудите пълно преизтегляне на всички Workshop модове.

1. Спрете сървъра в GPanel.
2. Свържете се чрез SFTP и навигирайте до /steamapps/workshop/.
3. Изтрийте цялата папка workshop/ (или нейното съдържание).
4. Стартирайте сървъра. Steam ще преизтегли всички Workshop предмети от нулата.
5. Наблюдавайте GPanel конзолата, за да потвърдите, че всички модове завършват изтеглянето си, преди сървърът да започне зареждането на света.

Бърза диагностична справка

Все още имате проблеми с модовете?