Deze gids behandelt geavanceerde mod-probleemoplossing voor Project Zomboid servers gehost bij Legion Hosting. Als je nog geen mods hebt geïnstalleerd, begin dan eerst met de basis mod-installatiegids. Dit artikel behandelt de meest voorkomende mod-gerelateerde problemen die in Legion Hosting supporttickets worden gezien, waaronder WorldDictionary-corruptie, mod-formaatfouten, laadvolgorde-conflicten en versieverschillen tussen server en client.

Voordat je begint

• Log in op GPanel en selecteer je Project Zomboid server.
• Stop je server voordat je configuratie- of bestandswijzigingen aanbrengt.
• Maak een back-up van je wereldopslagmap (/.cache/saves/multiplayer/) via SFTP of GPanel voordat je een oplossing probeert. Zie de SFTP-gids als je niet bekend bent met bestandsoverdracht.
• Houd het pad naar het .ini-bestand van je server bij de hand: /.cache/server/<servername>.ini (bijv. servertest.ini).

1. Mod-formaatfouten (B42 vs B41)

De meest voorkomende reden dat mods niet laden is een incorrect formaat in de Mods=-regel van het .ini-bestand van je server. Build 42 en Build 41 gebruiken een andere syntax, en het door elkaar halen ervan zorgt ervoor dat je mods stilzwijgend niet worden geladen.

B42-formaat (huidige standaard)

Build 42 vereist een backslash-prefix voor elke Mod ID in de Mods=-regel:

Mods=\ModID1;\ModID2;\ModID3;

Het DLMP-formaat combineert Workshop ID's en Mod ID's met een backslash-scheidingsteken:

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

De WorkshopItems=-regel gebruikt hetzelfde puntkomma-gescheiden formaat op beide builds:

WorkshopItems=2392987841;1550458773;2786383654

B41-formaat (verouderd)

Build 41 gebruikt gewone puntkomma-gescheiden Mod ID's zonder backslash:

Mods=ModID1;ModID2;ModID3

Hoe op te lossen

1. Open /.cache/server/<servername>.ini in de GPanel Bestandsbeheerder.
2. Zoek de Mods=-regel en controleer het formaat aan de hand van de bovenstaande voorbeelden.
3. Als het formaat verkeerd is voor je buildversie, corrigeer het dan. Gebruik de Legion Hosting Mod Organizer om automatisch correct geformateerde regels te genereren.
4. Sla het bestand op en start de server.

2. WorldDictionary-corruptie

De WorldDictionary is een bestand (WorldDictionary.bin) dat itemnamen koppelt aan interne numerieke ID's. Wanneer mods worden toegevoegd of verwijderd, kan het woordenboek corrupt raken, waardoor de server crasht bij het opstarten met een WorldDictionaryException.

Symptomen

• Console of debug.log toont WorldDictionaryException of WorldDictionary-fouten.
• Server crasht onmiddellijk tijdens het opstarten, specifiek tijdens het laden van de wereld.
• De crash begon na het toevoegen, verwijderen of updaten van mods.

Het risico begrijpen

Herstelstappen

1. Stop je server in GPanel.
2. Maak een back-up van je volledige opslagmap via SFTP: download de volledige /.cache/saves/multiplayer/<YourWorldName>/-map naar je lokale machine.
3. Probeer eerst simpelweg de modwijziging ongedaan te maken die de fout veroorzaakte. Als je net een mod hebt toegevoegd, verwijder deze dan uit zowel Mods= als WorkshopItems= in het .ini-bestand. Als je net een mod hebt verwijderd, voeg deze dan weer toe. Start de server en kijk of de crash is opgelost.
4. Als het ongedaan maken van de modwijziging niet werkt, maak dan verbinding via SFTP en navigeer naar /.cache/saves/multiplayer/<YourWorldName>/.
5. Verwijder WorldDictionary.bin.
6. Start de server. Project Zomboid zal het woordenboek opnieuw genereren bij het opstarten.
7. Verbind met de server en inspecteer de wereld op corrupte items, ontbrekende voertuigen of kapotte inventarissen. Als de wereld ernstig beschadigd is, herstel dan vanuit de back-up die je in stap 2 hebt gemaakt.

3. Authentic Z Mod-conflicten

Authentic Z is een van de populairste Project Zomboid mod-collecties, maar het is een veelvoorkomende bron van supporttickets omdat het meerdere sub-mods bevat die met elkaar conflicteren.

De regel

Veelgemaakte fouten

• Zowel Authentic Z - Current als Authentic Z - Litemode tegelijkertijd toevoegen.
• Authentic Z sub-mods toevoegen die ontworpen zijn voor singleplayer naast de multiplayer-versie.
• Niet beseffen dat verschillende Authentic Z sub-mods dezelfde Workshop ID delen maar verschillende Mod ID's hebben, waardoor de Workshop-download slaagt maar de server conflicterende modbestanden laadt.

Hoe op te lossen

1. Open /.cache/server/<servername>.ini in de GPanel Bestandsbeheerder.
2. Doorzoek de Mods=-regel op elke vermelding met Authentic of AuthenticZ.
3. Houd slechts één Authentic Z sub-mod aan (aanbevolen: Authentic Z - Current). Verwijder alle andere Authentic Z-vermeldingen uit zowel de Mods=- als de WorkshopItems=-regels.
4. Sla het bestand op en herstart de server.

4. Linux hoofdlettergevoeligheidsproblemen

Legion Hosting servers draaien op Linux, waar bestands- en mapnamen hoofdlettergevoelig zijn. Een bestand genaamd MyMod.lua en mymod.lua worden behandeld als twee compleet verschillende bestanden. Dit veroorzaakt problemen wanneer mod-auteurs op Windows ontwikkelen (niet hoofdlettergevoelig) en hun mods niet-overeenkomende bestandsverwijzingen bevatten.

Symptomen

• Een mod werkt perfect in singleplayer op je Windows-pc, maar faalt op de server.
• Console of debug.log toont FileNotFoundException of can't find file-fouten die verwijzen naar een Lua-script of textuur binnen een mod.
• De fout verwijst naar een bestand dat wel bestaat in de modmap, maar met een andere hoofdlettergebruik (bijv. de code verwijst naar Items.txt maar het daadwerkelijke bestand heet items.txt).

Hoe te diagnosticeren

1. Controleer de console of /.cache/Logs/ logbestanden op het exacte bestandspad dat in de fout wordt vermeld.
2. Maak verbinding via SFTP en navigeer naar de modmap op /steamapps/workshop/content/108600/<WorkshopID>/.
3. Vergelijk de bestandsnamen op schijf met de bestandsnaam die in de foutmelding wordt vermeld. Let op verschillen in hoofdlettergebruik.

Hoe op te lossen

• Als je het bestand kunt hernoemen: Maak verbinding via SFTP en hernoem het bestand zodat het overeenkomt met het hoofdlettergebruik dat door de code van de mod wordt verwacht. Let op dat deze oplossing wordt overschreven als de mod wordt bijgewerkt op Steam Workshop.
• Als het probleem in de mod zelf zit: Meld de bug bij de mod-auteur op de Steam Workshop-pagina. Vermeld dat de bestandsverwijzing een hoofdletterverschil heeft en dat het faalt op Linux-servers. Veel mod-auteurs zijn niet op de hoogte van Linux-hoofdlettergevoeligheid.
• Als tijdelijke oplossing: Controleer de reacties op de Workshop-pagina van de mod — andere Linux-serveroperators hebben mogelijk een oplossing of een compatibele fork van de mod geplaatst.

5. Problemen met mod-laadvolgorde

Project Zomboid laadt mods in de volgorde waarin ze verschijnen in de Mods=-regel. Sommige mods zijn afhankelijk van andere mods die eerst geladen moeten worden. Als een afhankelijkheid wordt geladen na de mod die deze vereist, kan de afhankelijke mod stilzwijgend falen of fouten veroorzaken.

Symptomen

• Modfuncties werken gedeeltelijk — sommige items of systemen van een mod zijn aanwezig, maar andere ontbreken.
• Console toont NullPointerException of attempt to index a nil value-fouten die verwijzen naar Lua-scripts van een mod.
• Fouten verschijnen alleen wanneer een specifieke combinatie van mods is geïnstalleerd, maar elke mod werkt afzonderlijk prima.

Hoe op te lossen

1. Controleer de Steam Workshop-pagina van elke mod op een "Required Mods" of "Load Order" sectie. Veel mod-auteurs specificeren welke mods voor de hunne geladen moeten worden.
2. Open /.cache/server/<servername>.ini en zoek de Mods=-regel.
3. Herorden de vermeldingen zodat afhankelijkheidsmods vóór de mods verschijnen die ze vereisen. Als Mod B bijvoorbeeld Mod A vereist, moet de regel luiden Mods=\ModA;\ModB; (B42-formaat).
4. Framework- en bibliotheekmods (zoals ModFramework, TsarLib of Shark's Mod Utils) moeten altijd als eerste in de Mods=-regel worden vermeld.
5. Sla het bestand op en herstart de server.

6. Server crasht na het toevoegen van mods

Als je server prima draaide en crasht na het toevoegen van een of meer mods, is de nieuwe mod waarschijnlijk de oorzaak. Deze sectie leidt je door het isoleren van de problematische mod.

Stapsgewijze isolatie

1. Stop de server in GPanel.
2. Open /.cache/server/<servername>.ini in de Bestandsbeheerder.
3. Noteer alle mods die je zojuist hebt toegevoegd. Verwijder ze allemaal uit zowel de Mods=- als de WorkshopItems=-regels.
4. Start de server. Als deze succesvol start, zit het probleem in een van de mods die je hebt verwijderd.
5. Voeg de mods één voor één weer toe, en herstart de server na elke toevoeging. Wanneer de crash terugkeert, is de laatst toegevoegde mod de oorzaak.
6. Eenmaal geïdentificeerd, controleer de Workshop-pagina van de mod op:
   • Een opmerking over B42-compatibiliteit — veel B41-mods zijn niet bijgewerkt voor B42.
   • Bekende conflicten met andere mods die je draait.
   • Vereiste afhankelijkheidsmods die je mogelijk niet hebt geïnstalleerd.

Het crashlogboek lezen

Controleer voordat je het isolatieproces uitvoert het crashlogboek — het wijst vaak direct naar de problematische mod:

1. Open in GPanel het tabblad Console en scroll naar het einde van de uitvoer.
2. Zoek naar STACK TRACE, Exception of ERROR-regels.
3. De regels direct boven de stack trace verwijzen meestal naar een modbestandsnaam of Mod ID — dit vertelt je welke mod de crash heeft veroorzaakt.
4. Voor meer detail, open het volledige logbestand via SFTP op /.cache/Logs/ en controleer het meest recente DebugLog-server.txt of debug.log-bestand.

7. Mod-versieverschillen (server vs client)

Project Zomboid vereist dat de server en alle verbonden clients dezelfde versie van elke mod hebben. Als een mod wordt bijgewerkt op de Steam Workshop en de server de nieuwe versie downloadt maar een speler nog de oude versie in de cache heeft (of andersom), zullen verbindingsproblemen of crashes optreden.

Symptomen

• Spelers krijgen een "Mod mismatch" of "Version mismatch"-fout bij het verbinden.
• Sommige spelers kunnen verbinden maar anderen niet — degenen die niet kunnen verbinden hebben een andere modversie lokaal in de cache.
• De server werkte prima, toen werd een mod bijgewerkt op Steam Workshop en plotseling kunnen sommige spelers niet meer verbinden.
• Spelers zien ontbrekende textures, items of kapotte UI-elementen van mods die onlangs zijn bijgewerkt.

Oplossing voor serverbeheerders

1. Stop de server in GPanel.
2. Start de server opnieuw. Bij het opstarten downloadt de server de nieuwste versies van alle Workshop-mods opnieuw. Dit zorgt ervoor dat de server de nieuwste versie draait.
3. Als de server nog steeds een oude versie in de cache heeft, maak dan verbinding via SFTP en verwijder de specifieke Workshop-cachemap van de mod op /steamapps/workshop/content/108600/<WorkshopID>/. Herstart de server om een schone download af te dwingen.

Oplossing voor spelers

Spelers die niet kunnen verbinden vanwege mod-versieverschillen moeten:

1. Steam openen en navigeren naar Library → Project Zomboid.
2. Rechts klikken op Project Zomboid, selecteer Properties → Local Files → Verify Integrity of Game Files.
3. Navigeer ook naar de Steam Workshop-map voor Project Zomboid op hun lokale machine en verwijder gecachte modbestanden om een herdownload af te dwingen.
4. Start het spel en verbind opnieuw met de server.

8. De Steam Workshop-cache wissen

Als meerdere modproblemen aanhouden en je vermoedt dat de Workshop-downloadcache corrupt is, kun je een volledige herdownload van alle Workshop-mods forceren.

1. Stop de server in GPanel.
2. Maak verbinding via SFTP en navigeer naar /steamapps/workshop/.
3. Verwijder de volledige workshop/-map (of de inhoud ervan).
4. Start de server. Steam zal alle Workshop-items opnieuw downloaden.
5. Bekijk de GPanel Console om te bevestigen dat alle mods klaar zijn met downloaden voordat de server begint met het laden van de wereld.

Snelle diagnostische referentie

Nog steeds modproblemen?