اگر پلاگینی روی Paper بدون مشکل اجرا میشود، اما پس از انتقال سرور به Folia بارگذاری نمیشود یا هنگام اجرای دستورات خطای Thread میدهد، احتمالاً با مشکل Folia Plugin Compatibility روبهرو هستید. این ناسازگاری همیشه در زمان روشنشدن سرور مشخص نمیشود؛ گاهی پلاگین فعال است اما هنگام Teleport بازیکن، تغییر Block، اجرای Task زمانبندیشده یا فعالیت همزمان چند بازیکن خطا ایجاد میکند.
دلیل اصلی این تفاوت، معماری Folia است. برخلاف مدل معمول Paper که بخش اصلی Tick جهان را در یک چرخه مرکزی مدیریت میکند، Folia از Regionized Multithreading استفاده میکند؛ یعنی چند Region مستقل میتوانند همزمان روی Threadهای متفاوت Tick شوند.
به همین دلیل، پلاگینی که فرض میکند همیشه یک Main Thread برای دسترسی به تمام Entityها و Chunkها وجود دارد، ممکن است در Folia با خطای Thread Ownership، Race Condition یا دسترسی نامعتبر به دادههای World مواجه شود.
در این آموزش ایرانیکاسرور یاد میگیرید چگونه وضعیت folia-supported را بررسی کنید، Stack Trace را بخوانید، چهار Scheduler اصلی Folia را بشناسید و تفاوت اجرای عملیات Async با دسترسی ایمن به دادههای بازی را درک کنید. همچنین روش عملی تشخیص و اصلاح یک پلاگین ناسازگار را مرحلهبهمرحله بررسی میکنیم.
چرا پلاگین Paper روی Folia کار نمیکند؟
Paper و Folia هر دو در اکوسیستم PaperMC قرار دارند، اما مدل اجرای آنها یکسان نیست.
در Paper معمولی، بسیاری از پلاگینها فرض میکنند عملیات مرتبط با World و Entity روی یک Thread اصلی انجام میشود. به همین دلیل، توسعهدهندگان معمولاً کارهایی مانند تغییر Block، Teleport یا مدیریت موجودات را در Taskهای همگام زمانبندی میکنند.
در Folia، یک Main Thread واحد برای تمام Regionهای جهان وجود ندارد. هر Region مستقل در زمان Tick شدن، مالک دادههای مربوط به خودش است.
برای مثال، بازیکنی در یک منطقه Survival و بازیکن دیگری در منطقهای دورتر ممکن است در دو Region مستقل پردازش شوند. پلاگینی که از Thread منطقه اول مستقیماً Entity متعلق به منطقه دوم را تغییر دهد، میتواند قانون مالکیت Thread را نقض کند.
این مسئله فقط یک تفاوت عملکردی نیست؛ Folia برای محافظت از دادههای بازی، بسیاری از دسترسیهای نامعتبر را بررسی میکند و در بعضی شرایط بهجای ادامه اجرای ناامن، خطا ایجاد میکند.
در مستندات رسمی معماری Folia نیز بر مالکیت دادهها و لزوم هماهنگی عملیات میان Regionها تأکید شده است.
مرحله اول: آیا پلاگین اصلاً از Folia پشتیبانی میکند؟
پیش از بررسی Threadها باید مشخص شود پلاگین بهطور رسمی از Folia پشتیبانی میکند یا خیر.
بهترین منبع، صفحه رسمی توسعهدهنده، مستندات نسخه و فهرست نرمافزارهای پشتیبانیشده است.
اگر فقط نام Paper یا Spigot در صفحه پلاگین نوشته شده، نباید سازگاری با Folia را فرض کنید.
بررسی گزینه folia-supported
در پلاگینهای سازگار با Folia، فایل plugin.yml یا paper-plugin.yml میتواند شامل گزینه زیر باشد:
folia-supported: true
این گزینه اعلام میکند که توسعهدهنده، پلاگین را برای Folia آماده کرده است.
اما وجود این خط بهتنهایی هیچ تضمینی درباره Thread Safety، عملکرد Schedulerها یا سازگاری تمام قابلیتهای پلاگین ارائه نمیدهد.
هشدار: هرگز صرفاً برای بارگذاری پلاگین، فایل JAR را دستکاری نکنید تا folia-supported: true به آن اضافه شود. این کار کد پلاگین را اصلاح نمیکند و ممکن است باعث ایجاد خطاهای خطرناکتر شود.
بررسی محتوای plugin.yml بدون اجرای پلاگین
اگر دسترسی SSH دارید، میتوانید فایل متادیتای داخل JAR را بررسی کنید.
ابتدا در پوشه plugins نام فایل را پیدا کنید:
ls -lh plugins/*.jar
سپس محتویات متادیتای پلاگین را، در صورتی که فایل plugin.yml داشته باشد، مشاهده کنید:
unzip -p plugins/ExamplePlugin.jar plugin.yml
برای پلاگینهایی که از paper-plugin.yml استفاده میکنند:
unzip -p plugins/ExamplePlugin.jar paper-plugin.yml
نام ExamplePlugin.jar فقط نمونه است و باید با فایل واقعی جایگزین شود. ابزار unzip نیز باید در سیستم نصب شده باشد.
اگر گزینه folia-supported وجود ندارد، ابتدا نسخه سازگار منتشرشده توسط توسعهدهنده را بررسی کنید؛ نه اینکه خودتان مقدار را به فایل اضافه کنید.
مرحله دوم: تفاوت خطای بارگذاری با خطای Thread Ownership
دو حالت اصلی ناسازگاری وجود دارد که باید از یکدیگر جدا شوند.
| وضعیت | علت احتمالی | مسیر بررسی |
|---|---|---|
| پلاگین اصلاً Load نمیشود | نبود اعلام پشتیبانی، نسخه ناسازگار یا وابستگی ناقص | Startup Log و متادیتای پلاگین |
| پلاگین Load میشود اما هنگام استفاده خطا میدهد | دسترسی به Region یا Entity از Thread اشتباه | Stack Trace و Schedulerها |
| پلاگین بدون Exception رفتار اشتباه دارد | Race Condition یا مدیریت ناامن دادههای مشترک | آزمایش همزمانی و بررسی کد |
| فقط یک قابلیت پلاگین خراب است | استفاده از API ناسازگار یا Scheduler نامناسب در همان قابلیت | بررسی مسیر اجرایی قابلیت |
اگر پلاگین حتی بارگذاری نمیشود، ابتدا نسخه، متادیتا و Dependencyها را بررسی کنید. اما اگر هنگام فعالیت بازیکنان خطای IllegalStateException یا پیام مربوط به Thread Check ظاهر میشود، احتمالاً مشکل به مدل Region Threading مربوط است.
مرحله سوم: پیدا کردن خطای پلاگین در latest.log
در اکثر نصبهای Minecraft Java، گزارش اجرای فعلی در فایل logs/latest.log ذخیره میشود.
اگر سرور را با پنلهایی مانند Pterodactyl اجرا میکنید، ممکن است لاگ از طریق کنسول پنل نیز در دسترس باشد.
جستوجوی عبارتهای مرتبط با خطای Thread
در پوشه اصلی سرور:
grep -nEi \
'failed main thread check|threadedregion|region scheduler|asynchronous|IllegalStateException|not supported|could not load|exception' \
logs/latest.log
این دستور فقط خطوط مرتبط را پیدا میکند. برای بررسی علت، باید چند خط قبل و بعد از نتیجه و کل زنجیره Stack Trace را نیز بخوانید.
اگر عبارت مشخصی مانند failed main thread check پیدا کردید، شماره خط را یادداشت کنید و بخش مربوط به آن را با دستور زیر مشاهده کنید:
sed -n '120,180p' logs/latest.log
محدوده ۱۲۰ تا ۱۸۰ صرفاً مثال است و باید با شماره خطوط واقعی جایگزین شود.
نمونه خطای Thread Ownership
ممکن است در گزارش Folia پیامهایی مشابه نمونه آموزشی زیر دیده شود:
java.lang.IllegalStateException:
Thread failed main thread check:
Cannot access entity from another region
at com.example.myplugin.PlayerTask.run(PlayerTask.java:87)
در این مثال فرضی، کلاس PlayerTask از پلاگین ExamplePlugin هنگام دسترسی به داده یک Entity در وضعیت Thread نامناسب قرار گرفته است.
عدد ۸۷ شماره خط کد منبع را نشان میدهد و برای توسعهدهنده اهمیت دارد.
البته در خطای واقعی ممکن است متن دقیق پیام و کلاسهای موجود در Stack Trace متفاوت باشند.
مرحله چهارم: چگونه Stack Trace را درست بخوانیم؟
هنگام مشاهده خطای Java، فقط به آخرین عبارت Exception توجه نکنید.
یک Stack Trace معمولاً اطلاعاتی درباره نوع خطا، مسیر فراخوانی متدها و کلاسی که عملیات نامعتبر را انجام داده ارائه میکند.
برای بررسی مؤثر، این ترتیب را رعایت کنید:
- نوع Exception را مشخص کنید؛ برای مثال IllegalStateException یا UnsupportedOperationException.
- متن خطای اصلی را بخوانید؛ مانند failed main thread check.
- در Stack Trace به دنبال نام پکیج پلاگین بگردید.
- کلاس و شماره خطی را که از API سرور استفاده کرده شناسایی کنید.
- بررسی کنید آن متد از چه Task، Event یا Command فراخوانی شده است.
- مشخص کنید داده موردنظر متعلق به کدام Entity یا Region بوده است.
اگر چند پلاگین در Stack Trace وجود دارند، اولین پلاگین قابل مشاهده الزاماً عامل اصلی نیست. ممکن است پلاگین دیگری از طریق API یا Event باعث فراخوانی آن مسیر شده باشد.
برای تشخیص نهایی باید زنجیره فراخوانی و شرایط ایجاد خطا بررسی شوند.
یک نمونه گزارش Thread Check نیز در بخش Issues مخزن Folia ثبت شده است.
مرحله پنجم: شناخت چهار Scheduler اصلی در Folia
مهمترین بخش توسعه پلاگین سازگار با Folia، اجرای عملیات در Context صحیح است.
PaperMC چهار Scheduler اصلی را معرفی میکند:
| Scheduler | کاربرد | مثال |
|---|---|---|
| RegionScheduler | عملیات وابسته به یک Location یا Region | تغییر Block در مختصات مشخص |
| EntityScheduler | عملیات روی Entity یا Player | تغییر وضعیت بازیکن |
| GlobalRegionScheduler | وظایف متعلق به Global Region | عملیات سراسری مجاز در آن Context |
| AsyncScheduler | کارهای مستقل از Tick جهان | بخش مناسب از عملیات I/O یا پردازش پسزمینه |
انتخاب Scheduler باید براساس مالکیت داده و نوع عملیات انجام شود؛ نه فقط اینکه توسعهدهنده قصد دارد کد را «همگام» یا «غیرهمگام» اجرا کند.
مرحله ششم: استفاده صحیح از RegionScheduler
RegionScheduler برای انجام عملیات مرتبط با یک موقعیت مشخص در جهان استفاده میشود.
برای مثال، اگر میخواهید در Location معینی یک Block قرار دهید، باید عملیات تغییر جهان در Region مالک آن موقعیت اجرا شود.
نمونه کد Java برای تغییر Block
Location location = targetLocation.clone();
server.getRegionScheduler().execute(
plugin,
location,
() -> {
location.getBlock().setType(Material.STONE);
}
);
در این مثال، server، plugin و targetLocation باید از Context واقعی پلاگین تأمین شده باشند و Chunk موردنظر طبق قرارداد API قابل استفاده باشد.
Scheduler براساس Location مشخص میکند عملیات روی Region مربوط اجرا شود.
نکته مهم: RegionScheduler برای دنبالکردن Entity متحرک مناسب نیست؛ زیرا Entity ممکن است بین Regionها جابهجا شود.
برای عملیات روی Player یا Entity باید از EntityScheduler استفاده کنید.
مرحله هفتم: استفاده صحیح از EntityScheduler
EntityScheduler به Entity مرتبط است و هنگام تغییر Region، Context اجرای مناسب آن را دنبال میکند.
اگر پلاگین باید روی یک بازیکن عملیات انجام دهد، بهتر است از Scheduler خود همان بازیکن استفاده کند.
نمونه کد Java
player.getScheduler().execute(
plugin,
() -> {
player.sendMessage("Task executed safely");
},
null,
1L
);
در این مثال، Task با زمانبندی مناسب برای Entity اجرا میشود. پارامتر null به معنی نداشتن Callback جداگانه برای وضعیت بازنشستگی Entity در این نمونه است؛ در کد واقعی باید وضعیت حذف یا غیرفعالشدن Entity نیز در نظر گرفته شود.
برای کارهایی مانند Teleport، جابهجایی میان Regionها و تغییر وضعیت Entity، APIهای مخصوص باید رعایت شوند.
استفاده از RegionScheduler با Location فعلی Player و سپس فرض ثابتماندن آن Location میتواند در صورت حرکت بازیکن باعث خطای منطقی شود.
مرحله هشتم: GlobalRegionScheduler برای چه کاری است؟
GlobalRegionScheduler برای Taskهایی طراحی شده که به Global Region تعلق دارند و نباید بهصورت مستقیم روی Region یک بازیکن یا Chunk مشخص اجرا شوند.
نمونه دریافت Scheduler:
GlobalRegionScheduler scheduler =
server.getGlobalRegionScheduler();
scheduler.execute(plugin, () -> {
plugin.getLogger().info("Global task executed");
});
این مثال فقط اجرای یک عملیات عمومی مجاز را نشان میدهد.
Global Region به معنی دسترسی آزاد به داده تمام Regionهای دیگر نیست. برای تغییر Entity یا Block باید مالکیت همان داده رعایت شود.
انتقال تمام Taskهای قدیمی Main Thread به GlobalRegionScheduler راهکار صحیحی برای سازگاری پلاگین با Folia نیست.
مرحله نهم: AsyncScheduler و مشکل Thread Safety
AsyncScheduler برای عملیات مستقل از Tick جهان استفاده میشود.
برای مثال، بخشی از پردازش داده، ارتباط با سرویس خارجی یا عملیات I/O میتواند خارج از Threadهای Tick انجام شود.
اما این موضوع به معنی مجازبودن دسترسی مستقیم Async به World یا Entity نیست.
نمونه الگوی صحیح تفکیک کار Async و Entity
server.getAsyncScheduler().runNow(plugin, task -> {
String result = loadDataFromStorage(playerId);
player.getScheduler().execute(
plugin,
() -> {
player.sendMessage(result);
},
null,
1L
);
});
متد loadDataFromStorage در این مثال فرضی است و باید بهصورت Thread-safe پیادهسازی شود.
همچنین بهتر است دادههایی مانند playerId قبل از ورود به Task Async جمعآوری شده باشند و در زمان اجرای Callback، فعالبودن پلاگین، معتبر بودن Entity و وضعیت کار بررسی شود.
الگوی کلی چنین است:
Async Task:
Read data from storage
Perform independent computation
Entity Scheduler:
Apply result to the target player
این جداسازی کمک میکند عملیات پرهزینه بیرون از مسیر Tick انجام شود و تغییر دادههای بازی به Context مالک آن بازگردد.
مرحله دهم: تفاوت Async Safety و Thread Safety چیست؟
بعضی توسعهدهندگان تصور میکنند اگر یک عملیات در Thread جداگانه اجرا شود، حتماً ایمنتر یا سریعتر است.
اما Async بودن فقط نشان میدهد عملیات خارج از مسیر معمول Tick اجرا میشود. این ویژگی تضمین نمیکند دسترسی به دادهها Thread-safe باشد.
برای مثال، یک ساختار HashMap معمولی اگر همزمان توسط چند Region نوشته شود ممکن است رفتار نامعتبر ایجاد کند.
اما حتی استفاده از ConcurrentHashMap نیز همه مشکلات را حل نمیکند؛ زیرا ممکن است مجموعهای از عملیات چندمرحلهای نیازمند هماهنگی منطقی باشد.
نمونه مشکل Race Condition
فرض کنید دو بازیکن در دو Region جداگانه همزمان یک اعتبار مشترک را مصرف میکنند.
اگر پلاگین ابتدا موجودی را بخواند و سپس بدون هماهنگی کافی از آن کم کند، ممکن است هر دو عملیات براساس موجودی قدیمی انجام شوند.
در این حالت حتی اگر هیچ خطای Thread Check ثبت نشود، داده مالی یا امتیاز بازیکنان میتواند نادرست شود.
برای رفع چنین مشکلاتی باید از روش مناسب همزمانی، تراکنشهای دیتابیس یا طراحی داده ایمن استفاده شود.
قاعده مهم این است که ایمنی دسترسی به دادههای World و ایمنی دادههای داخلی پلاگین دو مسئله جداگانه هستند.
مرحله یازدهم: چرا کدهای Bukkit Scheduler قدیمی مشکل ایجاد میکنند؟
در بسیاری از پلاگینهای Paper، استفاده از Bukkit Scheduler رایج است.
برای مثال:
Bukkit.getScheduler().runTask(plugin, () -> {
player.sendMessage("Hello");
});
در مدل کلاسیک Paper، این کد یک Task را روی Thread اصلی سرور زمانبندی میکند.
اما در Folia، یک Main Thread واحد برای تمام Regionها وجود ندارد. بنابراین همین فرض طراحی برای عملیات وابسته به Entity میتواند نامعتبر باشد.
برای پشتیبانی صحیح از Folia باید با توجه به نوع عملیات، Scheduler مناسب انتخاب شود.
بهعنوان مثال، برای عملیات مرتبط با Player استفاده از EntityScheduler مناسبتر است و برای تغییر Block در Location مشخص باید RegionScheduler بررسی شود.
البته هر استفاده از Bukkit Scheduler الزاماً به یک خطای Thread Ownership یکسان منجر نمیشود؛ رفتار به نسخه و مسیر اجرایی مربوط بستگی دارد. اما نباید API قدیمی را بدون آزمایش با معماری Folia سازگار فرض کرد.
مرحله دوازدهم: تشخیص پلاگین مشکلدار از روی Event و Command
بعضی خطاها هنگام اجرای یک دستور خاص رخ میدهند و بعضی دیگر در Eventهایی مانند PlayerMoveEvent یا BlockBreakEvent ظاهر میشوند.
در Folia، Eventهای مربوط به یک Entity یا Region ممکن است از Context همان Region فراخوانی شوند.
بنابراین پلاگینی که هنگام وقوع Event یک بازیکن، اطلاعات Entity دیگری در Region دورتر را تغییر میدهد، ممکن است خطای مالکیت Thread ایجاد کند.
مثال سناریوی ناسازگار
فرض کنید پلاگین پس از شکستن یک Block توسط بازیکن اول، بدون استفاده از Scheduler مناسب تلاش میکند وضعیت بازیکن دیگری در منطقه دور را تغییر دهد.
در Paper معمولی، توسعهدهنده ممکن است تصور کند همه این عملیات روی Main Thread اجرا میشوند.
اما در Folia دو بازیکن میتوانند تحت مالکیت Regionهای مستقل قرار داشته باشند.
راهکار این است که عملیات مربوط به بازیکن دوم از طریق EntityScheduler همان بازیکن انجام شود، نه مستقیماً از Event منطقه اول.
همچنین دادههایی که میان Eventها به اشتراک گذاشته میشوند باید با روش مناسب Thread-safe مدیریت شوند.
مرحله سیزدهم: آیا مشکل با افزایش تعداد Threadها برطرف میشود؟
خیر. اگر پلاگین با خطای Thread Ownership یا Race Condition مواجه است، افزایش تعداد Threadهای Folia راهکار نیست.
حتی ممکن است با افزایش موازیسازی، بعضی مشکلات همزمانی بیشتر ظاهر شوند.
تعداد Tick Threadها برای مدیریت ظرفیت پردازش Regionهای مستقل اهمیت دارد؛ اما ناسازگاری کد باید در سطح API و طراحی پلاگین اصلاح شود.
از طرف دیگر، کاهش تعداد Threadها برای پنهانکردن خطا نیز جایگزین اصلاح کد نیست. ممکن است خطا در برخی آزمایشها کمتر دیده شود، اما تضمینی برای سلامت دادهها ایجاد نمیکند.
مرحله چهاردهم: آزمایش سازگاری پلاگین در محیط جداگانه
اگر پلاگین روی Folia مشکوک به ناسازگاری است، بهتر است آزمایش را روی کپی جداگانه انجام دهید.
اجرای آزمایش روی World اصلی ممکن است به دادههای بازیکنان یا تنظیمات پلاگین آسیب بزند.
روش پیشنهادی آزمایش
- از World، تنظیمات پلاگین و دیتابیس مربوطه نسخه پشتیبان تهیه کنید.
- نسخه دقیق Folia، Java و پلاگین را ثبت کنید.
- یک سرور آزمایشی با World مستقل اجرا کنید.
- در ابتدا فقط پلاگین موردنظر و وابستگیهای ضروری را نصب کنید.
- خطای Startup را بررسی کنید.
- تمام دستورات، Eventها و Taskهای زمانبندیشده پلاگین را آزمایش کنید.
- چند بازیکن آزمایشی را در Regionهای مستقل قرار دهید.
- عملیات همزمان روی دادههای مشترک را آزمایش کنید.
- نتایج را با همان پلاگین روی Paper مقایسه کنید.
اگر پلاگین در یک سرور خالی و با یک بازیکن بدون مشکل کار میکند، این نتیجه برای تأیید کامل سازگاری با Folia کافی نیست.
بعضی Race Conditionها فقط زمانی رخ میدهند که چند Region بهصورت همزمان فعالیت کنند.
مرحله پانزدهم: چگونه بفهمیم خود پلاگین مشکل دارد یا Folia؟
مشاهده یک Exception داخل Folia الزاماً به معنی وجود باگ در Folia نیست. در بسیاری از موارد، Folia دسترسی نامعتبر پلاگین را شناسایی و متوقف میکند.
برای تشخیص بهتر:
- بررسی کنید خطا با حذف پلاگین در محیط آزمایشی تکرار میشود یا خیر.
- آزمایش را با Build پشتیبانیشده و بهروز Folia انجام دهید.
- نسخه دقیق پلاگین و Dependencyها را ثبت کنید.
- Stack Trace را با مستندات API تطبیق دهید.
- اگر احتمال باگ خود Folia وجود دارد، سناریوی حداقلی قابلبازتولید تهیه کنید.
اگر خطا از کلاسهای پلاگین شروع میشود و به دسترسی نامعتبر به Entity یا Region میرسد، توسعهدهنده باید آن مسیر را بررسی کند.
اگر مشکل بدون پلاگینهای جانبی و در شرایط حداقلی نیز تکرار میشود، ثبت گزارش فنی در مخزن رسمی Folia میتواند مناسب باشد.
مرحله شانزدهم: اگر توسعهدهنده پلاگین نیستیم چه کنیم؟
اگر فقط مدیر سرور هستید و به سورسکد پلاگین دسترسی ندارید، معمولاً نمیتوانید مشکل Thread Safety را صرفاً با تغییر تنظیمات سرور برطرف کنید.
در این شرایط چند اقدام منطقی وجود دارد:
- نسخه رسمی دارای پشتیبانی Folia را پیدا کنید.
- مستندات توسعهدهنده و Issueهای پروژه را بررسی کنید.
- Stack Trace کامل و نسخه نرمافزارها را برای توسعهدهنده ارسال کنید.
- در صورت وجود، جایگزین واقعاً سازگار را آزمایش کنید.
- اگر پلاگین حیاتی است و جایگزین مطمئن ندارد، بازگشت به Paper را بررسی کنید.
برای پلاگینهای اختصاصی نیز لازم است توسعهدهنده با استفاده از Schedulerهای مناسب و قواعد همزمانی، کد را بازبینی کند.
نباید با غیرفعالکردن کنترلهای Thread یا دستکاری فایل JAR تلاش کرد ناسازگاری را پنهان کرد.
جدول تشخیص سریع ناسازگاری پلاگین با Folia
| نشانه | علت احتمالی | اقدام مناسب |
|---|---|---|
| Plugin not supported by Folia | اعلامنشدن سازگاری | دریافت نسخه رسمی سازگار |
| failed main thread check | Context یا مالکیت Thread نامعتبر | بررسی Stack Trace و Scheduler |
| خطا هنگام تغییر Block | دسترسی به Region اشتباه | RegionScheduler |
| خطا هنگام تغییر Player | دسترسی به Entity خارج از Context مالک | EntityScheduler |
| خطا در Task پسزمینه | استفاده ناامن از API بازی در Async | تفکیک Async و عملیات روی Region |
| رفتار اشتباه بدون Exception | Race Condition در دادههای مشترک | بازبینی همزمانی و تراکنشها |
| فقط با چند بازیکن خطا ایجاد میشود | همزمانی چند Region | آزمایش موازی و تحلیل کد |
| پلاگین روی Paper سالم است | احتمال وابستگی به Main Thread واحد | بررسی پشتیبانی واقعی Folia |
اشتباهات رایج هنگام رفع خطای پلاگین Folia
- افزودن دستی folia-supported: true: فقط کنترل اعلام پشتیبانی را دور میزند.
- استفاده از GlobalRegionScheduler برای تمام Taskها: مالکیت دادههای Regionهای دیگر را تغییر نمیدهد.
- استفاده از RegionScheduler برای Entity متحرک: Entity ممکن است به Region دیگری منتقل شود.
- اجرای API بازی داخل AsyncScheduler: Async بودن به معنی Thread-safe بودن نیست.
- استفاده بیهدف از ConcurrentHashMap: مشکلات عملیات چندمرحلهای را الزاماً حل نمیکند.
- افزایش Tick Threadها برای رفع Exception: مشکل طراحی کد را اصلاح نمیکند.
- آزمایش با یک بازیکن: بعضی Race Conditionها فقط در فعالیت همزمان آشکار میشوند.
- نادیدهگرفتن Stack Trace: بدون کلاس و شماره خط، پیدا کردن مسیر نامعتبر دشوار است.
- مهاجرت مستقیم سرور اصلی: بدون بکاپ و محیط تست، ریسک خرابی دادهها افزایش مییابد.
چکلیست نهایی Folia Plugin Compatibility
- نسخه دقیق Folia و پلاگین را مشخص کنید.
- پشتیبانی رسمی توسعهدهنده از Folia را بررسی کنید.
- فایل plugin.yml یا paper-plugin.yml را کنترل کنید.
- لاگ بارگذاری و خطاهای Thread را بررسی کنید.
- کلاس و شماره خط مشکلدار را از Stack Trace پیدا کنید.
- تشخیص دهید عملیات به Region، Entity، Global Region یا Async تعلق دارد.
- از Scheduler مناسب استفاده کنید.
- دادههای داخلی مشترک پلاگین را از نظر Race Condition بررسی کنید.
- تست چندبازیکنه در Regionهای مستقل انجام دهید.
- فقط پس از تأیید سازگاری واقعی، پلاگین را روی سرور اصلی فعال کنید.
سؤالات متداول درباره سازگاری پلاگینها با Folia
چرا پلاگین Paper روی Folia Load نمیشود؟
ممکن است پلاگین پشتیبانی از Folia را اعلام نکرده باشد، نسخه آن ناسازگار باشد یا Dependency موردنیاز وجود نداشته باشد. ابتدا Startup Log و مستندات توسعهدهنده را بررسی کنید.
آیا اضافهکردن folia-supported: true مشکل را حل میکند؟
خیر. این گزینه فقط اعلام سازگاری است و Thread Safety یا استفاده صحیح از Schedulerها را تضمین نمیکند. افزودن دستی آن به پلاگین ناسازگار توصیه نمیشود.
خطای failed main thread check در Folia یعنی چه؟
معمولاً نشان میدهد بخشی از کد در Context اجرایی نامناسب به داده یا عملیاتی دسترسی پیدا کرده است. باید Stack Trace و مالکیت Region یا Entity بررسی شود.
تفاوت RegionScheduler و EntityScheduler چیست؟
RegionScheduler برای عملیات وابسته به Location است؛ EntityScheduler به Entity وابسته است و هنگام جابهجایی آن بین Regionها، Context اجرا را دنبال میکند.
آیا میتوان از Bukkit Scheduler در Folia استفاده کرد؟
نباید فرض کنید مدل قدیمی Bukkit Scheduler برای عملیات وابسته به جهان با Folia سازگار است. توسعهدهنده باید براساس نوع عملیات از Schedulerهای پشتیبانیشده استفاده کند.
آیا ConcurrentHashMap تمام مشکلات Thread را حل میکند؟
خیر. این ساختار میتواند بعضی دسترسیهای همزمان به Map را مدیریت کند، اما مجموعه عملیات چندمرحلهای یا دسترسی به Entity و World را بهطور خودکار ایمن نمیکند.
آیا AsyncScheduler اجازه تغییر Block را میدهد؟
خیر. تغییر Block باید طبق قواعد مالکیت World و Region انجام شود. برای عملیات وابسته به Location از Scheduler مناسب استفاده کنید.
آیا Folia از تمام پلاگینهای Paper پشتیبانی میکند؟
خیر. Folia به دلیل معماری Regionized Multithreading به سازگاری مخصوص نیاز دارد و نمیتوان صرف پشتیبانی از Paper را کافی دانست.
اگر پلاگین حیاتی با Folia سازگار نیست، چه کنیم؟
ابتدا نسخه رسمی سازگار یا جایگزین قابلاعتماد را بررسی کنید. اگر هیچ راهکار پایداری وجود ندارد، استفاده از Paper میتواند انتخاب مناسبتری باشد.
جمعبندی: چگونه مشکل پلاگین ناسازگار با Folia را برطرف کنیم؟
ناسازگاری پلاگین با Folia اغلب از تفاوت معماری Threading آن با Paper ناشی میشود. در Folia، هر Region مستقل مالک دادههای خود است و دسترسی به Entityها، Chunkها و وضعیت جهان باید در Context صحیح انجام شود.
برای تشخیص مشکل، ابتدا پشتیبانی رسمی پلاگین را بررسی کنید. سپس گزارشهای Startup و Stack Trace را بخوانید و مشخص کنید عملیات نامعتبر در کدام کلاس و Scheduler رخ داده است.
اگر توسعهدهنده هستید، استفاده صحیح از RegionScheduler، EntityScheduler، GlobalRegionScheduler و AsyncScheduler در کنار مدیریت ایمن دادههای مشترک اهمیت زیادی دارد.
اما اگر فقط مدیر سرور هستید، نباید با اضافهکردن folia-supported: true یا غیرفعالکردن کنترلهای Thread تلاش کنید پلاگین ناسازگار را به اجبار اجرا کنید.
بهترین روش، استفاده از نسخه رسمی سازگار، آزمایش روی محیط مستقل و بررسی عملکرد چندبازیکنه است. در شرایطی که پلاگینهای ضروری از Folia پشتیبانی نمیکنند، باقیماندن روی Paper معمولاً تصمیم منطقیتری خواهد بود.






دیدگاهها (۰)