AchievementSystem 2.0

نظام إنجازات معياري ومرن لـ Unreal Engine. نواة نظيفة لإدارة الإنجازات

والتصنيفات، دون فرض أي واجهة مستخدم أو منطق حفظ.

مقدمة

يوفّر AchievementSystem نواة نظيفة لإدارة الإنجازات والتصنيفات. لا يفرض أي واجهة مستخدم أو منطق حفظ، فتبقى لك السيطرة الكاملة. تُحمَّل جميع البيانات من جداول البيانات (Data Tables)، مما يتيح التوطين والتوسّع بكفاءة.

مبني على جداول البياناتالأسماء والأوصاف والأيقونات موجودة في جداول البيانات، وجاهزة للتوطين.

تصنيفات من مستويينتحتوي التصنيفات الرئيسية على تصنيفات، وتحتوي التصنيفات على الإنجازات.

تتبّع التقدّملكل إنجاز تقدّم حالي وحدّ أقصى للتقدّم، مع إكمال تلقائي.

بيانات جاهزة للواجهةدوال للقراءة فقط ببيانات منظّمة، يمكن ربطها مباشرة بعناصر الواجهة (Widgets).

يدعم اللعب الجماعيمراجع نظام خاصة بكل لاعب للألعاب عبر الإنترنت والألعاب متعددة الملفات الشخصية.

ماكروهات إضافيةيتضمن For Each With Delay وGet All Data Table Items.

كيف يعمل النظام

يعتمد النظام على تدفّق بيانات بسيط.

التعريف
تُعرَّف الإنجازات والتصنيفات في جداول البيانات وتُحمَّل مسبقًا أثناء التشغيل.
الحفظ والتحميل
أنت من يتحكم في كيفية حفظ الإنجازات وتحميلها، ثم تُعلِم النظام بالإنجازات التي سبق فتحها.
الاستخدام
بعد التحميل، ينظّم النظام الإنجازات حسب التصنيف ويوفّر بيانات منظّمة يمكنك استخدامها مباشرة في الواجهة أو في منطق اللعب.

البدء

أنشئ Blueprint فرعيًا
افتح BP_AchievementsSystem وأنشئ Child Blueprint Class. سيكون هذا الـ Blueprint الفرعي نسخة نظام الإنجازات الرئيسية لديك.
أنشئ هيكل بيانات (Structure)
أنشئ Structure يحتوي على بيانات الإنجاز. يجب أن يتضمن ID (عدد صحيح) وMax Progress (عدد صحيح).
أنشئ جدول بيانات (Data Table)
أنشئ Data Table واربطه بالـ Structure الذي أنشأته. املأه ببيانات الإنجازات (الأسماء، الأوصاف، الأيقونات، إلخ).
افتح Event Graph
افتح BP_Achievements_Child وانتقل إلى Event Graph.
أضف Preload Achievement Data
أضف الدالة Preload Achievement Data. تتطلب ثلاث قيم (انظر الجدول أدناه).
اربط القيم
اربط جميع القيم المطلوبة لكل إنجاز تريد تحميله مسبقًا.

المُدخَل	الوصف
`ID`	المعرّف الفريد للإنجاز.
`Max Progress`	الحد الأقصى لقيمة التقدّم المطلوبة لإكمال الإنجاز.
`Row Name`	اسم الصف الخاص بالإنجاز في جدول البيانات.

تحتاج إلى مثال؟ راجع النسخة التجريبية AchievementStyle_01.

نظرة عامة على التصنيفات

نظام التصنيفات عبارة عن شجرة بسيطة بمستويين فقط: التصنيفات الرئيسية (Top Level Categories) وتصنيفات الإنجازات (Achievement Categories). هذا يجعل النظام سهل الفهم وفعّالًا.

تصنيف رئيسي 01
├─ تصنيف 01
│   ├─ إنجاز
│   └─ إنجاز
└─ تصنيف 02
    ├─ إنجاز
    └─ إنجاز

تحتوي التصنيفات الرئيسية على تصنيفات أخرى.
تحتوي التصنيفات على الإنجازات.
لا تحتوي الإنجازات على أي عناصر بداخلها.

التحميل المسبق لتصنيفات الإنجازات

لتحديد الإنجازات التي تنتمي إلى تصنيف ما، استخدم Preload Achievement Category. تعمل بالطريقة نفسها المستخدمة في التحميل المسبق للإنجازات.

المُدخَل	الوصف
`Category ID`	معرّف فريد للتصنيف.
`Achievement IDs` (Array)	جميع معرّفات الإنجازات التي تنتمي إلى هذا التصنيف.
`Row Name`	اسم صف التصنيف في جدول بيانات التصنيفات.

التحميل المسبق للتصنيفات الرئيسية

تجمع التصنيفات الرئيسية عدة تصنيفات معًا. استخدم Preload Top Level Category.

المُدخَل	الوصف
`Category ID`	معرّف فريد للتصنيف الرئيسي.
`Category IDs` (Array)	جميع معرّفات التصنيفات التي تنتمي إلى هذا التصنيف الرئيسي.
`Row Name`	اسم صف التصنيف الرئيسي في جدول البيانات.

مثال بسيط

التقدّم (تصنيف رئيسي 01)
├─ القصة (تصنيف 01)
│   ├─ الخطوة الأولى
│   └─ بداية جديدة
└─ الاستكشاف (تصنيف 02)
    ├─ أول اكتشاف
    └─ خبير الاستكشاف

المهارات (تصنيف رئيسي 02)
├─ مهارات عامة (تصنيف 01)
│   └─ تنفيذ مثالي
└─ الدقّة (تصنيف 02)
    ├─ ضربة واحدة مذهلة
    └─ ثبات اليد

مرجع الدوال

ملاحظة: هذه الدوال للقراءة فقط ولا تعدّل أي بيانات (باستثناء Achievement Trigger).

الإنجازات المكتملة (Complete Achievements)

تُرجع الدوال الثلاث أدناه البنية (struct) نفسها:

Number of Completed Achievements: إجمالي عدد الإنجازات المكتملة.
Max Completed Achievements: الحد الأقصى الممكن للإنجازات.
Achievements Array: مصفوفة بجميع الإنجازات مع بياناتها (المعرّف، التقدّم، حالة الإكمال، إلخ).

الدالة	المُدخَل	الوصف
`Get All Completed Achievements`	لا يوجد	التقدّم الكلي لجميع الإنجازات في النظام. استخدمها للإحصاءات أو الواجهة أو ملاحظات اللاعب.
`Get All Completed Achievements By Category`	Category ID	التقدّم داخل تصنيف محدد. استخدمها لعرض تقدّم التصنيف في الواجهة أو للتحقق مما إذا كان التصنيف مكتملًا بالكامل.
`Get Completed Achievements In Top Level Category`	Category ID (تصنيف رئيسي)	التقدّم داخل تصنيف رئيسي، بما في ذلك جميع تصنيفاته الفرعية. استخدمها لعرض تقدّم مجموعة من التصنيفات.

التحميل (Load)

تُرجع دوال تحميل الإنجازات مصفوفة من البنى (structs) تحتوي على: Row Name، Complete Date (String)، Progress (Int)، Max Progress (Int) وIs Completed (Bool).

الدالة	المُدخَل	المُخرَج / الاستخدام
`Load Achievements By Category`	Category ID	جميع الإنجازات في تصنيف ما. استخدمها لملء الواجهة بإنجازات تصنيف واحد.
`Load All Achievements`	لا يوجد	كل الإنجازات دفعة واحدة. استخدمها للإحصاءات العامة أو ملخصات نهاية اللعبة.
`Load All Categories`	لا يوجد	مصفوفة من البنى (structs) تحتوي على `ID` و`Row`. استخدمها لملء قوائم التصنيفات أو لتنفيذ عمليات على مستوى التصنيف.
`Load Child Categories`	Category ID (التصنيف الأب / الرئيسي)	`ID` و`Row` لكل تصنيف فرعي. استخدمها لعرض التصنيفات الفرعية داخل تصنيف رئيسي.
`Load Top Level Categories`	لا يوجد	مصفوفة من البنى (structs) تحتوي على `Row` و`Category ID` و`Category IDs` (مصفوفة التصنيفات الفرعية). استخدمها لعرض جميع التصنيفات الرئيسية مع تصنيفاتها الفرعية.

الحالات (States)

الدوال الثلاث كلها دوال نقية (Pure Functions).

الدالة	المُدخَل	المُخرَج	حالة الاستخدام
`Get Progress`	Achievement ID (Int)	`Progress` (Int)، `Max Progress` (Int)	عرض أو فحص تقدّم إنجاز واحد.
`Get Row Name`	Achievement ID (Int)	`Row Name` (Name)	استرجاع البيانات المترجمة (الاسم، الوصف، الأيقونة) الخاصة بإنجاز ما.
`Is Completed ?`	Achievement ID (Int)	`Return Value` (Bool)	التحقق من حالة إكمال الإنجاز لمنطق اللعب أو لتحديث الواجهة.

Achievement Trigger

تُفعّل تقدّم إنجاز محدد وتحدّثه للاعب معيّن.

المُدخَل	الوصف
`Achievement ID` (Int)	معرّف الإنجاز المراد تفعيله.
`Player Ref` (Actor)	مرجع إلى اللاعب الذي فعّل الإنجاز.

تزيد تقدّم الإنجاز المحدد أو تحدّثه.
تضع علامة الإكمال على الإنجاز تلقائيًا عند بلوغ الحد الأقصى للتقدّم.
تخزّن حالة الإكمال ووقت الإكمال عند الانتهاء.

حالة الاستخدام: استدعِها كلما نفّذ اللاعب إجراءً مرتبطًا بإنجاز (قتل، جمع، استكشاف، تفاعل، إلخ).

Get Achievement Data

تبحث عن نسخة نظام الإنجازات الافتراضية وتُرجع مرجعها.

المُدخَل: لا يوجد
المُخرَج: Return Value (مرجع BP_AchievementSystem)، Is Valid (Bool). تكون قيمة Is Valid خاطئة (false) إذا لم يكن النظام موجودًا.
حالة الاستخدام: الألعاب فردية اللاعب، أو الواجهة، أو نظام إنجازات عام، أو عندما لا تحتاج إلى مرجع لاعب محدد.

Get Achievement Data By Reference

تُرجع نظام الإنجازات المرتبط بلاعب محدد، بحيث يكون لكل لاعب بيانات إنجازات خاصة به.

المُدخَل: Player Ref (مرجع Actor)
المُخرَج: Return Value (مرجع BP_AchievementSystem)، Is Valid (Bool)
حالة الاستخدام: الألعاب الجماعية، وملفات اللاعبين المتعددة، وتتبّع الإنجازات الخاص بكل لاعب.

ملاحظة معمارية مهمة

جميع الدوال في هذا النظام باستثناء Achievement Trigger مبنية داخليًا فوق Get Achievement Data. وهذا يعني أنها:

تستخدم تلقائيًا مرجع نظام الإنجازات الافتراضي.
آمنة ومُوصى بها للاستخدام في الواجهة.
مصمّمة بشكل أساسي للواجهة.

تنبيه للألعاب الجماعية / عبر الإنترنت

إذا كنت تعمل على لعبة عبر الإنترنت أو متعددة اللاعبين، فـلا تعتمد على هذه الدوال في منطق اللعب. استخدمها في الواجهة فقط لعرض التقدّم والإنجازات المكتملة والتصنيفات.

لاستخدام مرجع نظام إنجازات خاص بلاعب محدد:

انتقل إلى BP_AchievementFunctions.
ابحث عن الدالة التي تريد استخدامها.
كرّر الدالة (Duplicate).
عدّل الدالة الجديدة لتستخدم Get Achievement Data By Reference.
أضف مُدخَل Player Reference إلى الدالة.

يمنحك هذا تحكمًا كاملًا في بيانات الإنجازات الخاصة بكل لاعب، ومنطقًا آمنًا للعب الجماعي.

لماذا يختلف Achievement Trigger؟

Achievement Trigger لا تعتمد على Get Achievement Data. فهي تتطلب معرّف الإنجاز (Achievement ID) ومرجع اللاعب (Player Reference)، مما يجعلها آمنة لمنطق اللعب، وجاهزة للعب الجماعي، ويتحكم بها المطوّر بالكامل.

ملاحظة للخرائط التي لا تحتوي على لاعب

في أي مستوى لا يحتوي على لاعب (Player) أو شخصية (Character)، لن يعمل نظام الإنجازات افتراضيًا. لحل ذلك، أضف BP_AchievementsWorld إلى مستواك واضبط خصائصه:

الخاصية	الوصف
`Achievement Class`	اختر مكوّن الإنجازات الذي تريد استخدامه (مثل `BP_AchievementStyle_01`).
`EAchievement Date Format`	تنسيق التاريخ لتواريخ الإكمال (مثل USA، MM/DD/YYYY).
`Use Category Optimized Loading`	تفعيل التحميل المُحسَّن حسب التصنيف.
`Auto Load Category`	تفعيل التحميل التلقائي للتصنيفات.

يتيح هذا للنظام العمل بشكل صحيح في القائمة الرئيسية وشاشة تسجيل الدخول وغيرها من الخرائط التي لا تحتوي على لاعب.

أدوات إضافية

For Each With Delay (Macro)

تعمل مثل حلقة For Each Loop العادية، لكنها تضيف تأخيرًا بين كل تكرار وآخر.

الطرف (Pin)	الوصف
`Array`	المصفوفة المراد التكرار عليها.
`Duration` (Float)	الفاصل الزمني بين معالجة كل عنصر (القيمة الافتراضية 0.05).
`Loop Body`، `Array Element`، `Array Index`، `Completed`	السلوك نفسه كما في حلقة For Each Loop القياسية.

مفيدة لتحميل عناصر الواجهة أو الإنجازات أو أي بيانات مصفوفة بشكل متسلسل دون تجميد اللعبة.

Get All Data Table Items (Macro)

تسترجع جميع الصفوف من Data Table دون الحاجة إلى كتابة عدة عُقد (Nodes).

الطرف (Pin)	الوصف
`Table` (input)	جدول البيانات (Data Table) الذي تريد قراءته.
`Loop Body`	يعمل لكل صف. `Array Element` / `Out Row` هو بنية الصف (row struct) للعنصر الحالي.
`Row Not Found`	يُفعَّل إذا لم يكن الصف موجودًا.
`Completed`	يُفعَّل بعد معالجة جميع الصفوف.

مفيدة للتكرار السريع على جداول البيانات بطريقة نظيفة وفعّالة.