Panduan ini membahas pemecahan masalah mod tingkat lanjut untuk server Project Zomboid yang dihosting dengan Legion Hosting. Jika Anda belum menginstal mod, mulailah dengan panduan instalasi mod dasar terlebih dahulu. Artikel ini membahas masalah terkait mod yang paling umum terlihat di seluruh tiket dukungan Legion Hosting, termasuk korupsi WorldDictionary, kesalahan format mod, konflik urutan pemuatan, dan ketidakcocokan versi antara server dan klien.

Sebelum Anda Mulai

• Masuk ke GPanel dan pilih server Project Zomboid Anda.
• Hentikan server Anda sebelum membuat perubahan konfigurasi atau file apa pun.
• Cadangkan folder world save Anda (/.cache/saves/multiplayer/) melalui SFTP atau GPanel sebelum mencoba perbaikan apa pun. Lihat panduan SFTP jika Anda belum familier dengan transfer file.
• Siapkan path file .ini server Anda: /.cache/server/<servername>.ini (mis., servertest.ini).

1. Kesalahan Format Mod (B42 vs B41)

Alasan paling umum mod gagal dimuat adalah format yang salah di baris Mods= pada file .ini server Anda. Build 42 dan Build 41 menggunakan sintaks yang berbeda, dan mencampuradukkannya akan menyebabkan mod Anda gagal dimuat tanpa peringatan.

Format B42 (Default Saat Ini)

Build 42 memerlukan awalan backslash sebelum setiap Mod ID di baris Mods=:

Mods=\ModID1;\ModID2;\ModID3;

Format DLMP menggabungkan Workshop ID dan Mod ID dengan pemisah backslash:

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

Baris WorkshopItems= menggunakan format yang sama yang dipisahkan titik koma pada kedua build:

WorkshopItems=2392987841;1550458773;2786383654

Format B41 (Legacy)

Build 41 menggunakan Mod ID polos yang dipisahkan titik koma tanpa backslash:

Mods=ModID1;ModID2;ModID3

Cara Memperbaiki

1. Buka /.cache/server/<servername>.ini di GPanel File Manager.
2. Temukan baris Mods= dan periksa formatnya terhadap contoh-contoh di atas.
3. Jika format salah untuk versi build Anda, perbaiki. Gunakan Legion Hosting Mod Organizer untuk menghasilkan baris yang diformat dengan benar secara otomatis.
4. Simpan file dan jalankan server.

2. Korupsi WorldDictionary

WorldDictionary adalah file (WorldDictionary.bin) yang memetakan nama item ke ID numerik internal. Ketika mod ditambahkan atau dihapus, dictionary dapat menjadi rusak, menyebabkan server crash saat startup dengan WorldDictionaryException.

Gejala

• Konsol atau debug.log menunjukkan kesalahan WorldDictionaryException atau WorldDictionary.
• Server crash segera saat startup, khususnya selama pemuatan world.
• Crash dimulai setelah menambahkan, menghapus, atau memperbarui mod.

Memahami Risiko

Langkah Pemulihan

1. Hentikan server Anda di GPanel.
2. Cadangkan seluruh folder save Anda melalui SFTP: unduh seluruh direktori /.cache/saves/multiplayer/<YourWorldName>/ ke mesin lokal Anda.
3. Pertama, coba sekadar mengembalikan perubahan mod yang menyebabkan kesalahan. Jika Anda baru saja menambahkan mod, hapus dari kedua baris Mods= dan WorkshopItems= di file .ini. Jika Anda baru saja menghapus mod, tambahkan kembali. Jalankan server dan lihat apakah crash teratasi.
4. Jika mengembalikan perubahan mod tidak berhasil, hubungkan melalui SFTP dan navigasikan ke /.cache/saves/multiplayer/<YourWorldName>/.
5. Hapus WorldDictionary.bin.
6. Jalankan server. Project Zomboid akan membuat ulang dictionary saat startup.
7. Bergabunglah ke server dan periksa world untuk item yang rusak, kendaraan yang hilang, atau inventaris yang rusak. Jika world rusak parah, pulihkan dari cadangan yang Anda buat di langkah 2.

3. Konflik Mod Authentic Z

Authentic Z adalah salah satu koleksi mod Project Zomboid paling populer, tetapi sering menjadi sumber tiket dukungan karena berisi beberapa sub-mod yang saling berkonflik.

Aturannya

Kesalahan Umum

• Menambahkan Authentic Z - Current dan Authentic Z - Litemode secara bersamaan.
• Menambahkan sub-mod Authentic Z yang dirancang untuk singleplayer bersama dengan versi multiplayer.
• Tidak menyadari bahwa sub-mod Authentic Z yang berbeda berbagi Workshop ID yang sama tetapi memiliki Mod ID yang berbeda, sehingga unduhan Workshop berhasil tetapi server memuat file mod yang berkonflik.

Cara Memperbaiki

1. Buka /.cache/server/<servername>.ini di GPanel File Manager.
2. Cari di baris Mods= untuk setiap entri yang mengandung Authentic atau AuthenticZ.
3. Pertahankan hanya satu sub-mod Authentic Z (direkomendasikan: Authentic Z - Current). Hapus semua entri Authentic Z lainnya dari kedua baris Mods= dan WorkshopItems=.
4. Simpan file dan restart server.

4. Masalah Sensitivitas Huruf Besar/Kecil di Linux

Server Legion Hosting berjalan di Linux, di mana nama file dan folder bersifat case-sensitive. File bernama MyMod.lua dan mymod.lua diperlakukan sebagai dua file yang benar-benar berbeda. Ini menyebabkan masalah ketika pembuat mod mengembangkan di Windows (case-insensitive) dan mod mereka berisi referensi file yang tidak cocok.

Gejala

• Sebuah mod bekerja dengan sempurna dalam singleplayer di PC Windows Anda tetapi gagal di server.
• Konsol atau debug.log menunjukkan kesalahan FileNotFoundException atau can't find file yang mengacu pada skrip Lua atau tekstur di dalam mod.
• Kesalahan menunjuk ke file yang memang ada di folder mod, tetapi dengan kapitalisasi berbeda (mis., kode mengacu pada Items.txt tetapi file sebenarnya bernama items.txt).

Cara Mendiagnosis

1. Periksa file log konsol atau /.cache/Logs/ untuk path file persis yang disebutkan dalam kesalahan.
2. Hubungkan melalui SFTP dan navigasikan ke folder mod di /steamapps/workshop/content/108600/<WorkshopID>/.
3. Bandingkan nama file di disk dengan nama file yang dirujuk dalam pesan kesalahan. Cari perbedaan kapitalisasi.

Cara Memperbaiki

• Jika Anda dapat mengganti nama file: Hubungkan melalui SFTP dan ganti nama file agar sesuai dengan kapitalisasi yang diharapkan oleh kode mod. Perhatikan bahwa perbaikan ini akan ditimpa jika mod diperbarui di Steam Workshop.
• Jika masalahnya ada di mod itu sendiri: Laporkan bug ke pembuat mod di halaman Steam Workshop. Sebutkan bahwa referensi file memiliki ketidakcocokan huruf besar/kecil dan bahwa itu gagal di server Linux. Banyak pembuat mod tidak menyadari sensitivitas huruf besar/kecil di Linux.
• Sebagai solusi sementara: Periksa komentar halaman Workshop mod — operator server Linux lainnya mungkin telah memposting perbaikan atau fork mod yang kompatibel.

5. Masalah Urutan Pemuatan Mod

Project Zomboid memuat mod dalam urutan kemunculannya di baris Mods=. Beberapa mod bergantung pada mod lain yang dimuat terlebih dahulu. Jika dependensi dimuat setelah mod yang memerlukannya, mod dependen dapat gagal tanpa peringatan atau menyebabkan kesalahan.

Gejala

• Fitur mod sebagian berfungsi — beberapa item atau sistem dari mod hadir tetapi yang lain hilang.
• Konsol menunjukkan kesalahan NullPointerException atau attempt to index a nil value yang mengacu pada skrip Lua mod.
• Kesalahan hanya muncul ketika kombinasi mod tertentu diinstal, tetapi setiap mod bekerja dengan baik secara individual.

Cara Memperbaiki

1. Periksa halaman Steam Workshop setiap mod untuk bagian "Required Mods" atau "Load Order". Banyak pembuat mod menentukan mod mana yang harus dimuat sebelum mod mereka.
2. Buka /.cache/server/<servername>.ini dan temukan baris Mods=.
3. Atur ulang entri sehingga mod dependensi muncul sebelum mod yang memerlukannya. Sebagai contoh, jika Mod B memerlukan Mod A, baris tersebut harus berbunyi Mods=\ModA;\ModB; (format B42).
4. Mod framework dan library (seperti ModFramework, TsarLib, atau Shark's Mod Utils) harus selalu dicantumkan pertama di baris Mods=.
5. Simpan file dan restart server.

6. Server Crash Setelah Menambahkan Mod

Jika server Anda berjalan dengan baik dan crash setelah menambahkan satu atau lebih mod, mod baru kemungkinan adalah penyebabnya. Bagian ini memandu mengisolasi mod yang bermasalah.

Isolasi Langkah demi Langkah

1. Hentikan server di GPanel.
2. Buka /.cache/server/<servername>.ini di File Manager.
3. Catat semua mod yang baru saja Anda tambahkan. Hapus semuanya dari kedua baris Mods= dan WorkshopItems=.
4. Jalankan server. Jika berhasil dijalankan, masalahnya ada di salah satu mod yang Anda hapus.
5. Tambahkan kembali mod satu per satu, me-restart server setelah setiap penambahan. Ketika crash kembali, mod terakhir yang Anda tambahkan adalah penyebabnya.
6. Setelah teridentifikasi, periksa halaman Workshop mod untuk:
   • Catatan tentang kompatibilitas B42 — banyak mod B41 belum diperbarui untuk B42.
   • Konflik yang diketahui dengan mod lain yang Anda jalankan.
   • Mod dependensi yang diperlukan yang mungkin belum Anda instal.

Membaca Log Crash

Sebelum melakukan proses isolasi, periksa log crash — sering kali menunjuk langsung ke mod yang bermasalah:

1. Di GPanel, buka tab Console dan gulir ke akhir output.
2. Cari baris STACK TRACE, Exception, atau ERROR.
3. Baris tepat di atas stack trace biasanya mengacu pada nama file mod atau Mod ID — ini memberi tahu Anda mod mana yang memicu crash.
4. Untuk detail lebih lanjut, buka file log lengkap melalui SFTP di /.cache/Logs/ dan periksa file DebugLog-server.txt atau debug.log terbaru.

7. Ketidakcocokan Versi Mod (Server vs Klien)

Project Zomboid mengharuskan server dan semua klien yang terhubung memiliki versi yang sama dari setiap mod. Jika sebuah mod diperbarui di Steam Workshop dan server mengunduh versi baru tetapi seorang pemain masih memiliki versi lama yang tersimpan dalam cache (atau sebaliknya), kegagalan koneksi atau crash akan terjadi.

Gejala

• Pemain mendapatkan kesalahan "Mod mismatch" atau "Version mismatch" saat mencoba terhubung.
• Beberapa pemain dapat terhubung tetapi yang lain tidak — yang tidak dapat terhubung memiliki versi mod berbeda yang tersimpan secara lokal.
• Server berjalan dengan baik, lalu sebuah mod diperbarui di Steam Workshop dan tiba-tiba beberapa pemain tidak dapat bergabung.
• Pemain melihat tekstur, item, atau elemen UI yang hilang/rusak dari mod yang baru saja diperbarui.

Perbaikan untuk Operator Server

1. Hentikan server di GPanel.
2. Jalankan server lagi. Saat startup, server mengunduh ulang versi terbaru dari semua mod Workshop. Ini memastikan server menjalankan versi terbaru.
3. Jika server masih memiliki versi lama yang tersimpan dalam cache, hubungkan melalui SFTP dan hapus folder cache Workshop mod tertentu di /steamapps/workshop/content/108600/<WorkshopID>/. Restart server untuk memaksa unduhan bersih.

Perbaikan untuk Pemain

Pemain yang tidak dapat terhubung karena ketidakcocokan versi mod harus:

1. Buka Steam dan navigasikan ke Library → Project Zomboid.
2. Klik kanan Project Zomboid, pilih Properties → Local Files → Verify Integrity of Game Files.
3. Navigasikan juga ke folder Steam Workshop untuk Project Zomboid di mesin lokal mereka dan hapus file mod yang tersimpan dalam cache untuk memaksa pengunduhan ulang.
4. Luncurkan game dan hubungkan ke server lagi.

8. Membersihkan Cache Steam Workshop

Jika beberapa masalah mod terus berlanjut dan Anda mencurigai cache unduhan Workshop rusak, Anda dapat memaksa pengunduhan ulang lengkap semua mod Workshop.

1. Hentikan server di GPanel.
2. Hubungkan melalui SFTP dan navigasikan ke /steamapps/workshop/.
3. Hapus seluruh folder workshop/ (atau isinya).
4. Jalankan server. Steam akan mengunduh ulang semua item Workshop dari awal.
5. Perhatikan GPanel Console untuk memastikan semua mod selesai diunduh sebelum server memulai pemuatan world.

Referensi Diagnostik Cepat

Masih Mengalami Masalah Mod?