هل يتم تنظيف الـ weak maps تلقائياً في Verse عند مغادرة اللاعب في UEFN؟

إذا كنت تثق بمساعد البرمجة الذكي (AI coding assistant) الخاص بك عندما يخبرك بأن لغة Verse تقوم تلقائياً بتطهير بيانات اللاعب من الـ weak_map في الجزء من الثانية الذي يقطعون فيه الاتصال بجزيرة Fortnite الخاصة بك، فأنت تهيئ نفسك لحدوث runtime crash خطير. تبدو هذه الادعاءات منطقية: نظرًا لأنها عبارة عن weak reference، يجب على المحرك (engine) تنظيف المفتاح (key) بمجرد خضوع كائن اللاعب لعملية Garbage Collection. ولكن في Unreal Editor for Fortnite (UEFN)، فإن الواقع أكثر تعقيداً بكثير، ويؤدي سوء فهم كيفية معالجة مدير الذاكرة (memory manager) في Verse لدورات حياة اللاعبين (player lifecycles) إلى حدوث leaks خفية في الحالة (state) و exceptions تؤدي إلى تعطل اللعبة.

عندما يغادر لاعب ما، فإن الإشارة إلى كائنهم التالف (stale object) في الخريطة (map) يمكن أن تؤدي إلى إطلاق الخطأ المخيف ErrRuntime_WeakMapInvalidKey أو التسبب في انهيارات على مستوى الجزيرة بأكملها، مما يتطلب منك تطبيق UEFN server crash fix protocol صارم للحفاظ على استقرار الخوادم (servers) الخاصة بك. لتجنب ذلك، يجب على المطورين فهم كيفية تعامل Verse مع الذاكرة داخلياً وكيفية تنفيذ إجراءات تنظيف (cleanup routines) حاسمة.

الاعتقاد الخاطئ: نصائح الذكاء الاصطناعي مقابل واقع Verse

يسأل العديد من المطورين مساعدي الذكاء الاصطناعي الخاصين بهم عن كيفية التعامل مع بيانات الخريطة (map data) الخاصة باللاعب عند مغادرته للمباراة. النصيحة الشائعة التي ينشئها الذكاء الاصطناعي هي أن المحرك يعامل مفتاح اللاعب (player key) كـ "weak reference" ويقوم تلقائياً بحذف مدخلات اللاعب (player's entry) من الخريطة بمجرد المغادرة. هذا غير صحيح تماماً.

على الرغم من أن الـ weak_map(player, t) في Verse تستخدم weak references كمفاتيح (keys) خلف الكواليس لمنع حدوث reference cycles قوية قد تعوق عمل الـ Garbage Collector، إلا أنها لا تقوم بعملية تنظيف تلقائية وفورية للمدخلات نفسها داخل الـ map. يظل المدخل (entry) - الذي يحتوي على كل من مكان المفتاح (key slot) والبيانات المرتبطة به - محجوزاً في حاوية الـ map.

إذا حاول الكود الخاص بك الوصول إلى هذا المفتاح، أو تقييمه، أو تعديله بعد مغادرة اللاعب، فسيحاول Verse runtime استرجاع القيمة (dereference) من كائن لاعب فارغ (null) أو غير صالح. وبدلاً من إنهاء العملية بشكل سلس (failing gracefully)، يقوم الـ runtime بإحداث crash أو يطلق uncatchable exception. يتوقع النظام منك معالجة انتقالات دورة الحياة (lifecycle transitions) بشكل صريح بدلاً من الاعتماد على التنظيف التلقائي.

لماذا لا تقوم Weak Maps بتنظيف مدخلات اللاعبين تلقائياً

لفهم سبب حدوث ذلك، يجب أن ننظر إلى الغرض من الـ weak_map في UEFN. على عكس بيئات البرمجة القياسية حيث تكون الـ weak maps عبارة عن transient memory caches، تستخدم Verse الـ weak_map(player, t) بشكل أساسي كحارس لبوابة بيانات اللاعبين المستمرة (persistent player data).

الاستمرارية عبر جلسات اللعب (Play Sessions)

عندما تستخدم weak_map(player, t) معلنة على مستوى الـ module scope، يقوم المحرك بربط القيم بقاعدة البيانات السحابية المستمرة (persistent cloud database) الخاصة بـ Epic. فإذا غادر اللاعب المباراة وعاد بعد ثلاثة أيام، يطابق المحرك معرف اللاعب (player ID) الخاص به مع مفتاح الخريطة المستمر (persistent map key) لاستعادة تقدمه.

إذا قام المحرك بمسح مدخلات اللاعب تلقائياً من الخريطة بمجرد مغادرته اللعبة، فستفقد الخريطة جميع البيانات المستمرة (persistent data). وبالتالي، ستتم إعادة تعيين المستويات (levels)، والعملات المخصصة (custom currencies)، والعناصر المفتوحة (unlocked items) إلى الصفر في كل مرة يقطع فيها اللاعب الاتصال أو يواجه انقطاعاً في الشبكة (network timeout). لذلك، تم تصميم قاعدة البيانات للحفاظ على هذه المدخلات سليمة وتحديداً لأنها تهدف إلى البقاء حتى بعد انقطاع الاتصال.

نطاق دورة حياة كائنات اللاعب (Scoped Lifetime of Player Objects)

عندما يغادر لاعب المباراة، يتم تدمير كائن الجلسة النشط (active session object) الخاص به في الـ playspace. ويصبح مرجع الـ player الفعلي الذي يحتفظ به كود Verse الخاص بك عبارة عن dead handle.

ونظراً لأن المفتاح داخل الخريطة يشير الآن إلى كائن غير صالح وغير نشط، فإن الاستعلام عن الخريطة باستخدام هذا المرجع الميت (dead reference) سيفشل. لا يقوم المحرك بفحص وإزالة المفاتيح الميتة (dead keys) بشكل نشط من الخريطة في الوقت الفعلي. بدلاً من ذلك، يتركها خاملة، ولهذا السبب تكون الإدارة اليدوية إلزامية لمنع تراكم المراجع التالفة (stale references).

العواقب: تسريبات الذاكرة (Memory Leaks)، البيانات التالفة، وانهيارات الخادم (Server Crashes)

يؤدي الفشل في تنظيف مدخلات اللاعبين إلى ثلاث مشكلات رئيسية تؤدي إلى تدهور أداء اللعبة واستقرار الخادم (server stability) خلال المباريات الطويلة.

• تسريب البيانات التالفة (Stale Data Leakage): إذا غادر لاعب وانضم لاعب آخر، فقد يرث اللاعب الجديد بيانات جلسة اللاعب القديم إذا قام المحرك بإعادة استخدام خانات اللاعبين الداخلية (internal player slots). يؤدي هذا إلى حدوث bugs في الحالة (state bugs)، مثل رصد ظهور اللاعبين الجدد مع حقائب مخزون كاملة (full inventory bags) أو إحصائيات مباراة غير صحيحة.
• تراكم الذاكرة (Memory Accumulation): في حين أن قيمة boolean أو integer واحدة تأخذ مساحة لا تذكر، فإن تخزين هياكل معقدة (complex structures) لما يصل إلى 50 لاعباً في ردهة (lobby) عالية السعة يمكن أن يزيد من استهلاك الذاكرة. وعلى مدار جلسة خادم (server session) مدتها 4 ساعات، يمكن أن يؤدي هذا التراكم إلى إضعاف الـ server tick rates.
• فشل الاستعلام (Look-up Failures): محاولة الاستعلام عن حالة لاعب غير نشط أو استدعاء دوال (functions) على مرجع لاعب ميت (dead player reference) تؤدي إلى حدوث runtime crashes فورية.

الوصول إلى حدود حفظ السحابة لـ Epic (Epic Cloud Save Limits)

يفرض UEFN قيوداً صارمة على البيانات المستمرة (persistent data). فأنت مقيد بحد أقصى 4 من الـ persistent weak_maps لكل جزيرة، ولا يمكن أن يتجاوز حجم السجل الفردي لكل لاعب 256 KB من البيانات.

إذا كنت تستخدم weak_map مستمرة لتخزين حالات الجلسة المؤقتة (temporary session states)، فإنك تضيع هذه المساحة القيمة من قاعدة البيانات. وتكتب كل عملية تحديث في قاعدة بيانات Epic، مما يعرضك لخطر عقوبة خنق الكتابة (write-throttling penalty) أو تجاوز حد الـ 256 KB، وهو ما يطلق خطأ runtime error عند محاولة كتابة المزيد من البيانات.

دليل خطوة بخطوة: إدارة حالات جلسة اللاعب بأمان

لإدارة حالات اللاعبين دون المخاطرة بحدوث تسريبات للذاكرة (memory leaks) أو تضخم قاعدة البيانات، يجب عليك فصل بيانات جلستك المؤقتة (transient session data) عن بياناتك السحابية المستمرة (persistent cloud data). يجب تخزين البيانات المؤقتة في خرائط (maps) قياسية غير مستمرة، والتي يجب عليك تنظيفها يدوياً عند انقطاع اتصال اللاعب.

الخطوة 1: تعريف هيكل حالة الجلسة (Session State Struct)

ابدأ بتعريف struct غير قابل للاستمرار (non-persistable) يحتوي على جميع المتغيرات التي يحتاجها لاعبك خلال جولة أو مباراة واحدة. لا تحدد هذا الكلاس أو الـ struct بـ <persistable>.

# Define the transient data structure for active gameplay tracking
player_session_state := struct:
    IsMoneyBagFull : logic = false
    CurrentGold : int = 0
    SpawnTime : float = 0.0

الخطوة 2: إنشاء جهاز المدير (Manager Device)

قم بإنشاء creative device يعمل كمنسق (coordinator). سيحتفظ هذا الجهاز بـ map قابلة للتعديل (mutable) وغير مستمرة (non-persistent) للاعبين النشطين. وبما أن الـ maps القياسية في Verse غير قابلة للتغيير (immutable)، فإننا نعلن عن متغير الخريطة كـ var حتى نتمكن من الكتابة فوقه عندما ينضم اللاعبون أو يغادرون.

using { /Fortnite.com/Devices }
using { /Fortnite.com/Playspaces }
using { /Verse.org/Simulation }

# Device handling player lifecycle events and session state mapping
state_manager_device := class(creative_device):

    # Non-persistent map for tracking active player sessions
    var SessionStates : [player]player_session_state = map{}

الخطوة 3: الاشتراك في أحداث الـ Playspace

في دالة OnBegin، اشترك في أحداث الاتصال الخاصة بالـ playspace. يضمن this تشغيل كود التهيئة (initialization code) عند انضمام لاعب، وكود التنظيف (cleanup code) عند مغادرته.

    OnBegin<override>()<suspends>:void=
        GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerAdded)
        GetPlayspace().PlayerRemovedEvent().Subscribe(OnPlayerRemoved)
        
        # Initialize any players already in the session (useful for UEFN hot-reloading)
        for (Player : GetPlayspace().GetPlayers()):
            OnPlayerAdded(Player)

الخطوة 4: تنفيذ منطق التسجيل والتنظيف

عندما ينضم لاعب، قم بملء الـ map بحالة جلسته الافتراضية. وعندما يغادر، يجب عليك تطهير مدخلاته من الـ map. ولأن لغة Verse لا تحتوي على دالة Map.Remove() مدمجة، يجب عليك إعادة بناء الـ map مع تصفية اللاعب المغادر. هذا يمنع بقاء المراجع التالفة (stale references) عالقة في الذاكرة.

    # Triggered when a player connects to the server
    OnPlayerAdded(Player: player):void=
        if (not SessionStates[Player]):
            InitialState := player_session_state{IsMoneyBagFull := false, CurrentGold := 0, SpawnTime := GetEngineTime()}
            if (set SessionStates[Player] = InitialState):
                Print("Initialized gameplay state for joining player.")

    # Triggered when a player disconnects or leaves the game
    OnPlayerRemoved(Player: player):void=
        Print("Player disconnected. Initiating map cleanup.")
        RemovePlayerSession(Player)

    # Purges the player's entry by reconstructing the map
    RemovePlayerSession(PlayerToRemove: player):void=
        var CleanedStates : [player]player_session_state = map{}
        for (ActivePlayer -> State : SessionStates):
            # Copy all players except the one who left
            if (ActivePlayer <> PlayerToRemove):
                if (set CleanedStates[ActivePlayer] = State):
                    # Entry successfully migrated to the cleaned map
        
        set SessionStates = CleanedStates
        Print("Successfully removed player session entry from memory.")

من خلال إعادة بناء الـ map عند إزالة اللاعب، فإنك تحذف مفتاح المرجع (reference key) بالكامل. وعندئذٍ، يمكن للـ Garbage Collector استعادة موارد اللاعب دون ترك مدخلات تالفة في حلقة اللعبة (game loop).

إذا كنت ترغب في تتبع telemetry مخصصة أثناء انتقالات دورة الحياة هذه، فيجب عليك أيضاً الانتباه لقيود مثل 32-character analytics event name limit in Verse عند إرسال تقارير عن مدة الجلسات أو إحصائيات العملة إلى الـ backends الخارجية.

أفضل الممارسات لإدارة الحالة (State Management) في Verse

لضمان بقاء خوادم UEFN مستقرة وعالية الأداء، اتبع هذه الإرشادات لإدارة بيانات اللاعبين:

1. التمييز بين بيانات الجلسة والبيانات المستمرة: لا تقم أبداً بتخزين متغيرات قصيرة العمر (مثل صحة المباراة الحالية، أو نتيجة الجولة، أو المواقع المؤقتة) في weak_map مستمرة. احتفظ بالحالات المؤقتة (transient states) في map قياسية قابلة للتعديل (mutable map) مغلفة داخل manager class.
2. التحقق من نشاط اللاعب باستخدام IsActive: قبل جلب بيانات اللاعب أو تعديلها في أي map، تحقق مما إذا كان لا يزال متواجداً في الـ playspace باستخدام استعلام IsActive[] الخاص بـ player. فإذا أرجع IsActive[] قيمة خطأ (false)، قم بإلغاء عملية البحث وتشغيل حدث التنظيف (cleanup event).
3. مراقبة أحجام البيانات باستخدام FitsInPlayerMap: عند الكتابة في weak_map مستمرة، استدعِ FitsInPlayerMap() للتأكد من أن التحديث لن يتجاوز حد الـ 256 KB، مما يمنع حدوث runtime exceptions.
4. دمج الـ Maps الخاصة بك: لا تقم بإنشاء maps منفصلة لكل متغير. قم بتعريف class واحدة تحتوي على جميع متغيرات اللاعب وقم بربط اللاعب بتلك الـ class. يقلل هذا من عدد الـ maps لديك ويحترم الحد الأقصى للجزيرة المتمثل في أربع persistent weak maps.

نقل التعقيد إلى Cloud Backend موثوق

قد تصبح إدارة دورات حياة جلسة اللاعب (player session lifecycles)، وحدود قاعدة البيانات، ومنطق التنظيف اليدوي في Verse أمراً معقداً بسرعة. إذا كنت بحاجة إلى بناء تقدم عبر الجلسات (cross-session progression)، أو مخازن متزامنة عالمياً (globally synchronized inventories)، أو matchmaking إقليمي، فإن إدارة هذه الحالات يدوياً تتطلب إعداد webhooks، وتوسيع قواعد البيانات الخارجية، والتعامل مع المزامنة بين الخوادم (server-to-server synchronization).

مع horizOn, يتم التعامل مع تحديات الـ Backend هذه تلقائياً. من خلال دمج horizOn SDK في خادم اللعبة الخاص بك، يمكنك نقل إدارة جلسات اللاعبين إلى قاعدة بيانات سحابية مخصصة. وعندما يقطع لاعب ما الاتصال، تقوم horizOn بتشغيل تنظيف تلقائي للجلسة، وتحديث قواعد البيانات العالمية، ومزامنة سجلات المخزون (inventory records) عبر مثيلات الخادم (server instances) دون الاصطدام بحدود ذاكرة Verse البالغة 256 KB أو المخاطرة بحدوث runtime crashes.

هل أنت مستعد لتوسيع UEFN backend الخاص بك؟ جرب horizOn مجاناً أو اطلع على API docs.

---

المصدر: When using weak maps, does a player's entry in the map automatically get removed on them leaving the game?