Hướng dẫn này sẽ hướng dẫn bạn cài đặt mod Steam Workshop trên máy chủ Project Zomboid của bạn được lưu trữ với Legion Hosting. Nó bao gồm định dạng mod B42 và B41, công cụ Legion Hosting Mod Organizer, các lưu ý về tương thích cho các gói mod lớn, và cách khôi phục từ tình trạng hỏng thế giới (world corruption) phổ biến liên quan đến mod.

Điều Kiện Tiên Quyết

• Một máy chủ Project Zomboid đang hoạt động với Legion Hosting, có thể truy cập tại gpanel.legionhosting.net
• Máy chủ của bạn phải Offline trước khi chỉnh sửa cài đặt mod — dừng nó trong GPanel trước
• (Các) Steam Workshop ID và (các) Mod ID cho mỗi mod bạn muốn cài đặt (được tìm thấy trên trang Steam Workshop của mỗi mod)
• Một bản sao lưu của bản lưu thế giới hiện tại của bạn (đặc biệt khuyến nghị — xem cảnh báo ở trên)

Bước 1 — Tìm Workshop ID và Mod ID Cho Mỗi Mod

Mỗi mod bạn muốn cài đặt yêu cầu hai định danh riêng biệt:

• Workshop ID — ID số trong URL Steam Workshop, ví dụ: https://steamcommunity.com/sharedfiles/filedetails/?id=2392987841
• Mod ID — ID nội bộ được định nghĩa bởi tác giả mod, được tìm thấy trong phần mô tả của mod trên trang Workshop, thường được liệt kê là "Mod ID:" hoặc bên trong tệp mod.info của mod

Ghi lại cả hai ID cho mỗi mod trước khi tiếp tục. Một mục Workshop đơn lẻ đôi khi chứa nhiều sub-mod, mỗi sub-mod có Mod ID riêng.

Bước 2 — Sử Dụng Legion Hosting Mod Organizer (Khuyến Nghị)

Cách dễ nhất để xây dựng danh sách mod của bạn là Legion Hosting Zomboid Mod Organizer. Nó cho phép bạn tìm kiếm Workshop, thêm mod theo URL hoặc ID, và tự động tạo ra các dòng cấu hình được định dạng chính xác mà bạn cần dán vào GPanel.

1. Đi đến legionhosting.net/zomboid-mod-organizer.php.
2. Tìm kiếm mod theo tên hoặc dán URL Steam Workshop vào ô tìm kiếm.
3. Thêm từng mod vào danh sách của bạn bằng nút Add.
4. Khi danh sách của bạn hoàn tất, nhấp Generate Config. Công cụ xuất ra các dòng WorkshopItems và Mods sẵn sàng để sử dụng, được định dạng cho phiên bản build của máy chủ của bạn.
5. Sao chép các dòng được tạo và tiến hành đến Bước 4 để dán chúng vào cài đặt máy chủ của bạn.

Nếu bạn muốn nhập ID theo cách thủ công, hãy tiếp tục với Bước 3 để định dạng chúng chính xác cho phiên bản build của bạn.

Bước 3 — Định Dạng Danh Sách Mod Chính Xác

WorkshopItems (giống nhau cho tất cả các build)

Dòng WorkshopItems sử dụng dấu chấm phẩy để phân tách các Workshop ID. Định dạng này giống nhau cho cả B41 và B42:

Mods — Định Dạng Build 42 (B42)

B42 sử dụng tiền tố dấu gạch chéo ngược (\) trước mỗi Mod ID:

Định Dạng DLMP (B42)

Một số cấu hình sử dụng định dạng DLMP, kết hợp các Workshop ID và Mod ID với dấu gạch chéo ngược trong một trường duy nhất:

Mods — Định Dạng Build 41 (B41)

B41 sử dụng các Mod ID phân tách bằng dấu chấm phẩy đơn thuần mà không có tiền tố dấu gạch chéo ngược:

Bước 4 — Áp Dụng Danh Sách Mod Trong Tệp Cài Đặt Máy Chủ Của Bạn

1. Đăng nhập vào GPanel và chọn máy chủ Project Zomboid của bạn.
2. Đảm bảo máy chủ Offline. Dừng nó nếu cần.
3. Mở File Manager và điều hướng đến /.cache/server/.
4. Mở tệp cài đặt máy chủ của bạn — nó được đặt tên là <servername>.ini (ví dụ: servertest.ini).
5. Tìm các dòng WorkshopItems= và Mods= trong tệp. Dán các giá trị bạn đã tạo ở Bước 2 hoặc định dạng ở Bước 3.
6. Lưu tệp.
7. Khởi động máy chủ. Việc tải xuống Steam Workshop sẽ bắt đầu tự động khi khởi động.

Bước 5 — Thêm Mod Từ Từ và Kiểm Tra

Đừng thêm toàn bộ danh sách mod mong muốn của bạn cùng một lúc, đặc biệt trên một máy chủ đang hoạt động hoặc khi làm việc với một bộ sưu tập lớn. Thay vào đó:

1. Thêm không quá 3–5 mod mỗi lần.
2. Khởi động máy chủ và xác nhận nó đạt trạng thái Running và rằng bạn có thể kết nối và chơi.
3. Kiểm tra GPanel Console để tìm bất kỳ thông báo lỗi hoặc stack trace nào trước khi thêm lô tiếp theo.
4. Lặp lại cho đến khi tất cả mod được tải và ổn định.

Cách tiếp cận này giúp dễ dàng hơn nhiều trong việc xác định mod nào gây ra vấn đề nếu có điều gì đó sai sót.

Cài Đặt Mod Không Phải Workshop

Nếu bạn có một mod không có trên Steam Workshop (được tải xuống dưới dạng thư mục hoặc tệp ZIP), hãy tải nó lên qua SFTP đến đường dẫn sau trên máy chủ của bạn:

Đặt thư mục của mod (phải chứa tệp mod.info) trực tiếp bên trong /.cache/mods/. Bạn có thể truy cập thư mục này bằng thông tin đăng nhập SFTP được hiển thị trong GPanel dưới tab SFTP. Sau khi tải lên, hãy thêm Mod ID (từ tệp mod.info của mod) vào dòng Mods= trong cấu hình máy chủ của bạn như được mô tả ở Bước 4. Không cần Workshop ID cho các mod không phải Workshop.

Lưu Ý Về Tương Thích Authentic Z

Authentic Z là một trong những gói mod Project Zomboid phổ biến nhất, nhưng nó bao gồm nhiều sub-mod. Chỉ cài đặt một sub-mod tại một thời điểm, và sub-mod được khuyến nghị cho các máy chủ nhiều người chơi là:

Đừng bật nhiều sub-mod Authentic Z đồng thời trên cùng một máy chủ. Chạy nhiều hơn một sub-mod từ bộ sưu tập này gây ra xung đột có thể làm crash máy chủ hoặc làm hỏng các bảng loot. Nếu bạn không chắc chắn sub-mod nào đang hoạt động, hãy kiểm tra dòng Mods= trong cấu hình của bạn và đảm bảo chỉ có Authentic Z - Current (hoặc sub-mod duy nhất bạn đã chọn) được liệt kê.

Xác Minh

Sau khi khởi động máy chủ với các mod mới của bạn, hãy xác nhận chúng đã tải thành công:

1. Trong GPanel, mở tab Console và theo dõi nhật ký khởi động. Tìm các dòng tham chiếu đến từng mod đang được tải — bạn sẽ thấy thứ gì đó như [ModLoader] Loading mod: ModID cho mỗi mod được cài đặt.
2. Kết nối với máy chủ trong game và mở menu Mods từ menu chính (Esc → Mods). Các mod đã cài đặt sẽ xuất hiện trong danh sách.
3. Tìm kiếm trong nhật ký Console cụm từ STACK TRACE. Nếu không có cụm từ nào xuất hiện, máy chủ đã khởi động sạch sẽ. Nếu bạn thấy một cụm từ, hãy ghi lại mod được đề cập gần đầu của trace — mod đó là nguyên nhân có khả năng gây ra vấn đề.
4. Đi xung quanh trong game và xác nhận nội dung do mod thêm vào (vật phẩm, tòa nhà, zombie) xuất hiện như mong đợi.

Khắc Phục Sự Cố

Mod không tải / máy chủ khởi động nhưng mod dường như không hoạt động

• Xác minh dòng Mods sử dụng định dạng chính xác cho build của bạn — tiền tố dấu gạch chéo ngược (\ModID) cho B42, Mod ID đơn thuần cho B41. Định dạng WorkshopItems giống nhau cho cả hai build.
• Xác nhận Mod ID trong dòng Mods= khớp chính xác với ID được hiển thị trong phần mô tả Workshop của mod hoặc tệp mod.info. Mod ID phân biệt chữ hoa chữ thường.
• Kiểm tra rằng cả trường WorkshopItems và Mods đều được lưu — điều hướng đi nơi khác và quay lại trong GPanel để xác nhận các giá trị đã được lưu lại.

Tải xuống Steam Workshop thất bại / mod không tải xuống khi khởi động

Nếu máy chủ khởi động nhưng các mod Workshop dường như không tải xuống, thư mục cache Steam có thể bị hỏng. Để khắc phục điều này:

1. Dừng máy chủ trong GPanel.
2. Kết nối qua SFTP và điều hướng đến /steamapps/workshop/.
3. Xóa toàn bộ thư mục workshop/ (hoặc nội dung của nó).
4. Khởi động lại máy chủ. Steam sẽ tải xuống lại tất cả các mục Workshop từ đầu.

WorldDictionaryException / hỏng từ điển thế giới

Nếu nhật ký Console hiển thị lỗi WorldDictionaryException, từ điển thế giới đã bị hỏng — điều này có thể xảy ra khi thêm hoặc gỡ bỏ các mod giới thiệu các vật phẩm hoặc ô (tile) mới.

Nếu bạn phải thử khôi phục:

1. Dừng máy chủ trong GPanel.
2. Sao lưu toàn bộ thư mục lưu của bạn qua SFTP hoặc GPanel Backups.
3. Kết nối qua SFTP và điều hướng đến /.cache/saves/multiplayer/<YourWorldName>/.
4. Xóa WorldDictionary.bin.
5. Khởi động máy chủ. Project Zomboid sẽ tạo lại từ điển khi khởi động.
6. Kiểm tra trong game để tìm các vật phẩm hoặc phương tiện bị hỏng. Nếu thế giới bị hỏng nghiêm trọng, hãy khôi phục từ bản sao lưu bạn đã tạo ở bước 2.

Máy chủ crash khi khởi động với STACK TRACE trong nhật ký console

Một stack trace ngay sau khi khởi động thường cho thấy xung đột mod hoặc một mod không tương thích với phiên bản build hiện tại của bạn. Để chẩn đoán:

1. Trong GPanel, mở nhật ký Console và tìm kiếm STACK TRACE.
2. Đọc các dòng phía trên trace để tìm tên tệp mod hoặc Mod ID được đề cập — đây thường là mod gây ra vấn đề.
3. Gỡ bỏ mod đó khỏi cả hai dòng WorkshopItems và Mods, lưu lại, và khởi động lại máy chủ.
4. Nếu máy chủ khởi động sạch sẽ sau khi gỡ bỏ, hãy kiểm tra trang Workshop của mod để tìm bản cập nhật tương thích B42 hoặc một ghi chú xung đột đã biết trong phần bình luận.

Bạn cũng có thể mở tệp debug.log đầy đủ qua SFTP tại /.cache/Logs/<date>_DebugLog-server.txt để biết chi tiết hơn so với những gì console GPanel hiển thị.

Máy chủ crash khi người chơi có mod cụ thể kết nối

Nếu máy chủ chạy sạch sẽ nhưng crash khi một người chơi tham gia, người chơi đó có thể có các mod phía client xung đột với máy chủ. Yêu cầu người chơi tắt tất cả các mod Project Zomboid cục bộ của họ từ menu Mods trong game và thử kết nối lại. Nếu crash dừng lại, người chơi nên bật lại từng mod một để tìm mod gây xung đột.

Mod đã được gỡ bỏ nhưng máy chủ vẫn cố tải nó

Nếu bạn đã gỡ bỏ ID của một mod khỏi cấu hình nhưng máy chủ vẫn tham chiếu đến nó khi khởi động, mục Workshop có thể vẫn còn trong cache. Xóa thư mục mục Workshop cụ thể khỏi /steamapps/workshop/content/108600/<workshopID>/ qua SFTP, sau đó khởi động lại máy chủ.