این راهنما عیبیابی پیشرفته مادها را برای سرورهای Project Zomboid میزبانی شده در Legion Hosting پوشش میدهد. اگر هنوز مادها را نصب نکردهاید، ابتدا با راهنمای پایه نصب ماد شروع کنید. این مقاله رایجترین مشکلات مرتبط با مادها که در تیکتهای پشتیبانی Legion Hosting مشاهده شده را بررسی میکند، از جمله خرابی WorldDictionary، خطاهای فرمت ماد، تداخل ترتیب بارگذاری، و عدم تطابق نسخه بین سرور و کلاینت.
مادها مشکل شماره ۱ پشتیبانی هستند. تقریباً ۱۴٪ از کل تیکتهای پشتیبانی Legion Hosting مربوط به مشکلات ماد است. اکثریت این موارد ناشی از فرمت نادرست ماد، خرابی WorldDictionary، یا ترکیبهای ناسازگار مادها هستند. این راهنما راهحل هر یک از این مشکلات را پوشش میدهد.
قبل از شروع
- وارد GPanel شوید و سرور Project Zomboid خود را انتخاب کنید.
- سرور خود را متوقف کنید قبل از هرگونه تغییر در تنظیمات یا فایلها.
- قبل از انجام هرگونه تعمیر، از پوشه ذخیره دنیای خود (
/.cache/saves/multiplayer/) از طریق SFTP یا GPanel نسخه پشتیبان تهیه کنید. اگر با انتقال فایل آشنا نیستید، راهنمای SFTP را ببینید. - مسیر فایل
.iniسرور خود را آماده داشته باشید:/.cache/server/<servername>.ini(مثلاًservertest.ini).
۱. خطاهای فرمت ماد (B42 در مقابل B41)
رایجترین دلیل بارگذاری نشدن مادها، فرمت نادرست در خط Mods= فایل .ini سرور شماست. Build 42 و Build 41 از نحو متفاوتی استفاده میکنند و مخلوط کردن آنها باعث میشود مادهای شما بدون هیچ خطایی بارگذاری نشوند.
فرمت B42 (پیشفرض فعلی)
Build 42 نیاز به پیشوند بکاسلش قبل از هر Mod ID در خط Mods= دارد:
Mods=\ModID1;\ModID2;\ModID3;فرمت DLMP شناسههای Workshop و شناسههای ماد را با جداکننده بکاسلش ترکیب میکند:
Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;خط WorkshopItems= در هر دو بیلد از فرمت یکسان جدا شده با سمیکالن استفاده میکند:
WorkshopItems=2392987841;1550458773;2786383654فرمت B41 (قدیمی)
Build 41 از شناسههای ماد جدا شده با سمیکالن ساده و بدون بکاسلش استفاده میکند:
Mods=ModID1;ModID2;ModID3
فرمتها را مخلوط نکنید. استفاده از فرمت B41 روی سرور B42 (یا بالعکس) شایعترین دلیل تیکتهای «مادها بارگذاری نمیشوند» است. اگر اخیراً از B41 به B42 ارتقا دادهاید، باید کل خط
Mods= خود را برای شامل شدن پیشوند بکاسلش دوباره فرمتبندی کنید.
نحوه رفع
- فایل
/.cache/server/<servername>.iniرا در مدیریت فایل GPanel باز کنید. - خط
Mods=را پیدا کنید و فرمت آن را با مثالهای بالا مقایسه کنید. - اگر فرمت برای نسخه بیلد شما اشتباه است، آن را تصحیح کنید. از سازماندهنده ماد Legion Hosting برای تولید خودکار خطوط با فرمت صحیح استفاده کنید.
- فایل را ذخیره کنید و سرور را راهاندازی کنید.
۲. خرابی WorldDictionary
WorldDictionary یک فایل (WorldDictionary.bin) است که نام آیتمها را به شناسههای عددی داخلی نگاشت میکند. وقتی مادها اضافه یا حذف میشوند، دیکشنری میتواند خراب شود و باعث شود سرور هنگام راهاندازی با خطای WorldDictionaryException کرش کند.
علائم
- کنسول یا
debug.logخطاهایWorldDictionaryExceptionیاWorldDictionaryرا نشان میدهد. - سرور بلافاصله در حین راهاندازی، به طور خاص در حین بارگذاری دنیا، کرش میکند.
- کرش پس از اضافه کردن، حذف کردن، یا بهروزرسانی مادها شروع شده است.
درک خطر
حذف WorldDictionary.bin آخرین راهحل است. WorldDictionary هر آیتم و وسیله نقلیه در دنیای شما را به شناسههای داخلی نگاشت میکند. حذف آن سرور را مجبور به بازسازی نگاشت میکند که میتواند باعث خراب شدن آیتمهای موجود، ناپدید شدن وسایل نقلیه، یا حاوی آیتمهای نادرست بودن موجودیها شود. فقط در صورتی این کار را انجام دهید که سرور به هیچ وجه راهاندازی نمیشود و نسخه پشتیبان از پوشه ذخیره خود دارید.
مراحل بازیابی
- سرور خود را در GPanel متوقف کنید.
- از کل پوشه ذخیره خود از طریق SFTP نسخه پشتیبان تهیه کنید: دایرکتوری کامل
/.cache/saves/multiplayer/<YourWorldName>/را به دستگاه محلی خود دانلود کنید. - ابتدا سعی کنید تغییر مادی که باعث خطا شده را برگردانید. اگر به تازگی مادی اضافه کردهاید، آن را از هر دو خط
Mods=وWorkshopItems=در فایل.iniحذف کنید. اگر به تازگی مادی حذف کردهاید، آن را دوباره اضافه کنید. سرور را راهاندازی کنید و ببینید آیا کرش برطرف شده است. - اگر برگرداندن تغییر ماد جواب نداد، از طریق SFTP متصل شوید و به
/.cache/saves/multiplayer/<YourWorldName>/بروید. WorldDictionary.binرا حذف کنید.- سرور را راهاندازی کنید. Project Zomboid دیکشنری را هنگام راهاندازی بازسازی خواهد کرد.
- به سرور متصل شوید و دنیا را از نظر آیتمهای خراب، وسایل نقلیه گمشده، یا موجودیهای خراب بررسی کنید. اگر دنیا به شدت آسیب دیده است، از نسخه پشتیبانی که در مرحله ۲ ایجاد کردید بازیابی کنید.
پیشگیری: همیشه قبل از اضافه یا حذف کردن مادها از پوشه ذخیره خود نسخه پشتیبان تهیه کنید. مادها را در دستههای کوچک (۳ تا ۵ تا در هر بار) اضافه کنید و بین هر دسته تست کنید. به این ترتیب، اگر خرابی WorldDictionary رخ دهد، دقیقاً میدانید کدام ماد باعث آن شده و میتوانید سریعاً بازیابی کنید.
۳. تداخلهای ماد Authentic Z
Authentic Z یکی از محبوبترین مجموعههای ماد Project Zomboid است، اما منبع مکرری برای تیکتهای پشتیبانی است زیرا حاوی چندین زیرماد است که با یکدیگر تداخل دارند.
قانون
فقط یک زیرماد Authentic Z نصب کنید. اجرای همزمان چندین زیرماد Authentic Z باعث کرش سرور، خرابی جدول لوت، و باگهای تکثیر آیتم میشود. زیرماد توصیه شده برای سرورهای چندنفره
Authentic Z - Current است.
اشتباهات رایج
- اضافه کردن همزمان
Authentic Z - CurrentوAuthentic Z - Litemode. - اضافه کردن زیرمادهای Authentic Z که برای تکنفره طراحی شدهاند در کنار نسخه چندنفره.
- عدم آگاهی از اینکه زیرمادهای مختلف Authentic Z شناسه Workshop یکسانی دارند اما شناسههای ماد متفاوتی دارند، بنابراین دانلود Workshop موفق میشود اما سرور فایلهای ماد متداخل را بارگذاری میکند.
نحوه رفع
- فایل
/.cache/server/<servername>.iniرا در مدیریت فایل GPanel باز کنید. - خط
Mods=را برای هر ورودی حاویAuthenticیاAuthenticZجستجو کنید. - فقط یک زیرماد Authentic Z را نگه دارید (توصیه شده:
Authentic Z - Current). تمام ورودیهای دیگر Authentic Z را از هر دو خطMods=وWorkshopItems=حذف کنید. - فایل را ذخیره کنید و سرور را ریاستارت کنید.
۴. مشکلات حساسیت به حروف بزرگ و کوچک Linux
سرورهای Legion Hosting روی Linux اجرا میشوند، جایی که نام فایلها و پوشهها حساس به حروف بزرگ و کوچک هستند. فایلی با نام MyMod.lua و mymod.lua به عنوان دو فایل کاملاً متفاوت شناخته میشوند. این موضوع وقتی مشکل ایجاد میکند که توسعهدهندگان ماد روی Windows (بدون حساسیت به حروف) توسعه میدهند و مادهای آنها حاوی ارجاعات فایلی ناهمخوان هستند.
علائم
- یک ماد در حالت تکنفره روی کامپیوتر Windows شما کاملاً کار میکند اما روی سرور خطا میدهد.
- کنسول یا
debug.logخطاهایFileNotFoundExceptionیاcan't find fileمرتبط با یک اسکریپت Lua یا بافت درون یک ماد را نشان میدهد. - خطا به فایلی اشاره میکند که در پوشه ماد وجود دارد، اما با حروف متفاوت (مثلاً کد به
Items.txtارجاع میدهد اما نام واقعی فایلitems.txtاست).
نحوه تشخیص
- کنسول یا فایلهای لاگ در
/.cache/Logs/را برای مسیر دقیق فایل ذکر شده در خطا بررسی کنید. - از طریق SFTP متصل شوید و به پوشه ماد در
/steamapps/workshop/content/108600/<WorkshopID>/بروید. - نام فایلها روی دیسک را با نام فایل ارجاع داده شده در پیام خطا مقایسه کنید. به دنبال تفاوتهای حروف بزرگ و کوچک بگردید.
نحوه رفع
- اگر میتوانید فایل را تغییر نام دهید: از طریق SFTP متصل شوید و نام فایل را مطابق با حروف مورد انتظار کد ماد تغییر دهید. توجه داشته باشید که اگر ماد در Steam Workshop بهروزرسانی شود، این تعمیر بازنویسی خواهد شد.
- اگر مشکل در خود ماد است: باگ را به نویسنده ماد در صفحه Steam Workshop گزارش دهید. ذکر کنید که ارجاع فایل عدم تطابق حروف دارد و روی سرورهای Linux خطا میدهد. بسیاری از نویسندگان ماد از حساسیت حروف Linux آگاه نیستند.
- به عنوان راهحل موقت: نظرات صفحه Workshop ماد را بررسی کنید — سایر اپراتورهای سرور Linux ممکن است یک رفع یا فورک سازگار از ماد را منتشر کرده باشند.
این یک مشکل تنظیمات سرور نیست. مشکلات حساسیت حروف باگهایی در خود ماد هستند. هیچ چیزی در تنظیمات سرور خود نمیتوانید تغییر دهید تا مشکل مادی که فایلها را با حروف نادرست ارجاع میدهد برطرف شود. رفع باید از طرف نویسنده ماد یا با تغییر نام دستی فایل انجام شود.
۵. مشکلات ترتیب بارگذاری ماد
Project Zomboid مادها را به ترتیبی که در خط Mods= ظاهر میشوند بارگذاری میکند. برخی مادها نیاز دارند که مادهای دیگر ابتدا بارگذاری شوند. اگر یک وابستگی بعد از مادی که به آن نیاز دارد بارگذاری شود، ماد وابسته ممکن است بیصدا خطا دهد یا باعث خطا شود.
علائم
- ویژگیهای ماد به صورت ناقص کار میکنند — برخی آیتمها یا سیستمهای یک ماد وجود دارند اما بقیه گم هستند.
- کنسول خطاهای
NullPointerExceptionیاattempt to index a nil valueمرتبط با اسکریپتهای Lua یک ماد را نشان میدهد. - خطاها فقط وقتی ظاهر میشوند که ترکیب خاصی از مادها نصب شده باشد، اما هر ماد به تنهایی بدون مشکل کار میکند.
نحوه رفع
- صفحه Steam Workshop هر ماد را برای بخش "Required Mods" یا "Load Order" بررسی کنید. بسیاری از نویسندگان ماد مشخص میکنند کدام مادها باید قبل از ماد آنها بارگذاری شوند.
- فایل
/.cache/server/<servername>.iniرا باز کنید و خطMods=را پیدا کنید. - ورودیها را طوری مرتب کنید که مادهای وابستگی قبل از مادهایی که به آنها نیاز دارند ظاهر شوند. برای مثال، اگر ماد B به ماد A نیاز دارد، خط باید
Mods=\ModA;\ModB;(فرمت B42) باشد. - مادهای فریمورک و کتابخانه (مانند
ModFramework،TsarLib، یاShark's Mod Utils) باید همیشه اول در خطMods=فهرست شوند. - فایل را ذخیره کنید و سرور را ریاستارت کنید.
نکته: سازماندهنده ماد Legion Hosting میتواند به شما در مدیریت و سازماندهی لیست مادها کمک کند. از آن برای تولید خطوط پیکربندی تمیز و با فرمت صحیح استفاده کنید.
۶. کرش سرور پس از اضافه کردن مادها
اگر سرور شما بدون مشکل کار میکرد و پس از اضافه کردن یک یا چند ماد کرش کرد، ماد جدید احتمالاً عامل آن است. این بخش روند جداسازی ماد مشکلدار را توضیح میدهد.
جداسازی مرحله به مرحله
- سرور را در GPanel متوقف کنید.
- فایل
/.cache/server/<servername>.iniرا در مدیریت فایل باز کنید. - تمام مادهایی که به تازگی اضافه کردهاید را یادداشت کنید. همه آنها را از هر دو خط
Mods=وWorkshopItems=حذف کنید. - سرور را راهاندازی کنید. اگر با موفقیت شروع شد، مشکل از یکی از مادهایی است که حذف کردید.
- مادها را یکی یکی دوباره اضافه کنید و پس از هر بار اضافه کردن سرور را ریاستارت کنید. وقتی کرش برگشت، آخرین مادی که اضافه کردید عامل آن است.
- پس از شناسایی، صفحه Workshop ماد را برای موارد زیر بررسی کنید:
- توضیحی درباره سازگاری با B42 — بسیاری از مادهای B41 برای B42 بهروزرسانی نشدهاند.
- تداخلهای شناخته شده با سایر مادهایی که در حال اجرا هستید.
- مادهای وابستگی مورد نیاز که ممکن است نصب نکرده باشید.
خواندن لاگ کرش
قبل از انجام فرآیند جداسازی، لاگ کرش را بررسی کنید — اغلب مستقیماً به ماد مشکلدار اشاره میکند:
- در GPanel، تب Console را باز کنید و به انتهای خروجی بروید.
- به دنبال خطوط
STACK TRACE،Exception، یاERRORبگردید. - خطوط بلافاصله بالای stack trace معمولاً به نام فایل ماد یا Mod ID ارجاع میدهند — این به شما میگوید کدام ماد باعث کرش شده است.
- برای جزئیات بیشتر، فایل لاگ کامل را از طریق SFTP در
/.cache/Logs/باز کنید و آخرین فایلDebugLog-server.txtیاdebug.logرا بررسی کنید.
مادها را در دستههای کوچک اضافه کنید. اضافه کردن ۳ تا ۵ ماد در هر بار و تست بین دستهها، جداسازی کرش را بسیار آسانتر از اضافه کردن بیش از ۲۰ ماد به یکباره و تلاش برای یافتن عامل مشکل میکند.
۷. عدم تطابق نسخه ماد (سرور در مقابل کلاینت)
Project Zomboid نیاز دارد که سرور و تمام کلاینتهای متصل نسخه یکسانی از هر ماد را داشته باشند. اگر مادی در Steam Workshop بهروزرسانی شود و سرور نسخه جدید را دانلود کند اما بازیکنی هنوز نسخه قدیمی را در کش داشته باشد (یا بالعکس)، خطاهای اتصال یا کرش رخ خواهد داد.
علائم
- بازیکنان هنگام تلاش برای اتصال خطای "Mod mismatch" یا "Version mismatch" دریافت میکنند.
- برخی بازیکنان میتوانند متصل شوند اما بقیه نمیتوانند — آنهایی که نمیتوانند متصل شوند نسخه متفاوتی از ماد را به صورت محلی در کش دارند.
- سرور بدون مشکل کار میکرد، سپس مادی در Steam Workshop بهروزرسانی شد و ناگهان برخی بازیکنان نمیتوانند وارد شوند.
- بازیکنان بافتها، آیتمها، یا عناصر رابط کاربری گمشده یا خراب از مادهایی که اخیراً بهروزرسانی شدهاند را مشاهده میکنند.
رفع برای اپراتورهای سرور
- سرور را در GPanel متوقف کنید.
- سرور را دوباره راهاندازی کنید. هنگام راهاندازی، سرور آخرین نسخههای تمام مادهای Workshop را دوباره دانلود میکند. این تضمین میکند سرور جدیدترین نسخه را اجرا میکند.
- اگر سرور همچنان نسخه قدیمی را در کش دارد، از طریق SFTP متصل شوید و پوشه کش Workshop ماد مورد نظر را در
/steamapps/workshop/content/108600/<WorkshopID>/حذف کنید. سرور را ریاستارت کنید تا دانلود تمیز اجباری شود.
رفع برای بازیکنان
بازیکنانی که به دلیل عدم تطابق نسخه ماد نمیتوانند متصل شوند باید:
- Steam را باز کنند و به Library → Project Zomboid بروند.
- روی Project Zomboid کلیک راست کنند، Properties → Local Files → Verify Integrity of Game Files را انتخاب کنند.
- همچنین به پوشه Steam Workshop برای Project Zomboid در دستگاه محلی خود بروند و فایلهای کش ماد را حذف کنند تا دانلود مجدد اجباری شود.
- بازی را اجرا کنند و دوباره به سرور متصل شوند.
در صورت امکان نسخههای ماد را ثابت نگه دارید. اگر مادی حیاتی مکرراً بهروزرسانی میشود و مشکلات عدم تطابق مکرر ایجاد میکند، نسخه خاصی از ماد را به صورت دستی دانلود و در
/.cache/mods/ روی سرور آپلود کنید به جای استفاده از بهروزرسانی خودکار Workshop. شناسه Workshop مربوطه را از خط WorkshopItems= حذف کنید تا از بهروزرسانی خودکار جلوگیری شود. برای دستورالعملهای نصب ماد غیر Workshop، راهنمای نصب ماد را ببینید.
۸. پاکسازی کش Steam Workshop
اگر مشکلات متعدد ماد ادامه دارند و مشکوک هستید که کش دانلود Workshop خراب شده، میتوانید دانلود مجدد کامل تمام مادهای Workshop را اجبار کنید.
این کار تمام فایلهای کش Workshop را حذف میکند. سرور هر آیتم Workshop مشترک شده را در راهاندازی بعدی دوباره دانلود خواهد کرد. برای لیستهای ماد بزرگ، این ممکن است چند دقیقه به زمان راهاندازی اضافه کند.
- سرور را در GPanel متوقف کنید.
- از طریق SFTP متصل شوید و به
/steamapps/workshop/بروید. - کل پوشه
workshop/(یا محتویات آن) را حذف کنید. - سرور را راهاندازی کنید. Steam تمام آیتمهای Workshop را از ابتدا دوباره دانلود خواهد کرد.
- کنسول GPanel را مشاهده کنید تا مطمئن شوید تمام مادها قبل از شروع بارگذاری دنیا توسط سرور دانلود شدهاند.
مرجع سریع تشخیص
| آنچه مشاهده میکنید | محتملترین دلیل | بخش |
|---|---|---|
| مادها بارگذاری نمیشوند، هیچ خطایی در لاگ نیست | فرمت ماد اشتباه (فرمت B41 روی سرور B42 یا بالعکس) | ۱. خطاهای فرمت ماد |
WorldDictionaryException در کنسول |
خرابی WorldDictionary ناشی از اضافه/حذف مادها | ۲. خرابی WorldDictionary |
| کرش سرور با چندین زیرماد Authentic Z | زیرمادهای متداخل Authentic Z که همزمان بارگذاری شدهاند | ۳. تداخلهای Authentic Z |
FileNotFoundException برای فایل مادی که وجود دارد |
عدم تطابق حساسیت حروف Linux | ۴. مشکلات حساسیت حروف |
خطاهای NullPointerException یا nil value از مادها |
ترتیب بارگذاری نادرست ماد یا وابستگی گمشده | ۵. مشکلات ترتیب بارگذاری |
STACK TRACE پس از اضافه کردن مادهای جدید |
ماد ناسازگار یا متداخل | ۶. کرش پس از اضافه کردن مادها |
| "Mod mismatch" یا "Version mismatch" هنگام اتصال | سرور و کلاینت نسخههای متفاوت ماد دارند | ۷. عدم تطابق نسخه |
| مشکلات متعدد ماد، هیچ چیز دیگری جواب نمیدهد | کش Workshop خراب | ۸. کش Workshop |
هنوز مشکل ماد دارید؟
اگر مشکل ماد شما در بالا پوشش داده نشده یا راهحلها آن را برطرف نکردند، یک تیکت پشتیبانی با اطلاعات زیر باز کنید تا تیم پشتیبانی بتواند مشکل را سریعاً تشخیص دهد:
- نسخه بیلد سرور شما (B41 یا B42)، که هنگام راهاندازی در کنسول نشان داده میشود
- خطوط کامل
Mods=وWorkshopItems=از فایل.iniشما - ۵۰ خط آخر خروجی کنسول GPanel در زمان کرش
- محتویات آخرین فایل لاگ در
/.cache/Logs/ - کدام مادها بلافاصله قبل از شروع مشکل اضافه، حذف، یا بهروزرسانی شدهاند
- آیا مشکل هنگام راهاندازی رخ میدهد یا فقط وقتی بازیکنان متصل میشوند
یک تیکت پشتیبانی باز کنید و شناسه سرور خود و جزئیات فهرست شده در بالا را درج کنید.
