Advanced Modular Leveling system

إضافة وحدوية لنظام الخبرة (XP) والمستويات في Unreal Engine (بدعم C++ وBlueprint) مع مزامنة عبر الشبكة (Replication). تتضمن منحنيات تعتمد على البيانات، وحدودًا قصوى للمستوى عبر نظام الصعود (Ascension)، ومكافآت المراحل، وتحويل الخبرة الفائضة (Overflow XP).

الميزات

مكوّن جاهز للإضافةأضِف AMLSLevelComponent إلى أي Actor: اللاعبون أو الأعداء أو الأسلحة أو المباني.

3 أنواع من منحنيات الخبرة (XP)مصفوفة صريحة، أو صيغة رياضية، أو أصل Float Curve من Unreal.

تقييد التقدّم عبر الصعود (Ascension)حدود قصوى صارمة للمستوى لا يمكن تجاوزها إلا باستدعاء Ascend.

مكافآت المراحلمكافآت قائمة على Gameplay Tag لكل مستوى، إضافةً إلى معالِجات مكافآت مخصّصة بـ Blueprint أو C++.

الخبرة الفائضة (Overflow XP)حوِّل الخبرة المكتسبة عند بلوغ أقصى مستوى إلى عملة باستخدام وسم (Tag) ومُعامِل ضرب.

جاهز للعب الجماعينظام يعتمد على سلطة الخادم، مع مزامنة المستوى والخبرة ومرحلة الصعود عبر الشبكة.

ربط مع نظام الحفظبنية SaveGame لحفظ التقدّم واستعادته.

متوافق مع Blueprintدوال جلب Pure، ودوال استدعاء للسلطة (Authority) فقط، وأحداث قابلة للربط.

البدء السريع

فعِّل الإضافة وتأكّد من أن وحدة GameplayTags متاحة في مشروعك.
أنشئ أصل بيانات (Data Asset): Content Browser → Miscellaneous → Data Asset → AMLSLevelUpConfigDataAsset.
حدِّد Max Level، واختر XP Curve Method، وأضِف مراحل المكافآت اختياريًا.
أضِف AMLS Level Component إلى الـ Actor (شخصيتك) وعيِّن أصل البيانات في الحقل Level Config Data.
على الخادم، استدعِ AddXP كلما اكتسب الـ Actor خبرة.
اربط OnLevelUpDelegate / OnXPChangedDelegate لتشغيل واجهة المستخدم (UI).

// مثال C++

if (UAMLSLevelComponent* Level = Actor->FindComponentByClass<UAMLSLevelComponent>())
{
    Level->OnLevelUpDelegate.AddDynamic(this, &AMyClass::HandleLevelUp);
    Level->AddXP(250); // على الخادم فقط
}

إذا لم يتم تعيين أصل الإعدادات، يتم تسجيل تحذير في السجل وتُستخدم قيم احتياطية (الحد الأقصى للمستوى 50، الخبرة المطلوبة = المستوى × 100).

مكوّن المستوى (`UAMLSLevelComponent`)

تبدأ من المستوى 1، و0 خبرة، ومرحلة الصعود 1. الدوال المُعلَّمة بـ Authority تعمل على الخادم فقط.

الدالة	النوع	الوصف
AddXP(Amount)	Authority	تضيف الخبرة وتعالج الارتقاءات المتتالية في المستوى. عند بلوغ أقصى مستوى مطلق، تُحوَّل الخبرة إلى التحويل الفائض.
SetLevel(NewLevel)	Authority	تضيف الخبرة وتعالج الارتقاءات المتتالية في المستوى. عند بلوغ أقصى مستوى مطلق، تُحوَّل الخبرة إلى التحويل الفائض.
AddLevels(LevelsToAdd)	Authority	تمنح عددًا ثابتًا من المستويات مع احترام حدود الصعود القصوى.
Ascend()	Authority	تنتقل إلى مرحلة الصعود التالية إذا كانت `CanAscend()` تساوي true.
ResetProgression()	Authority	تعيد المستوى والخبرة والمرحلة إلى القيم الافتراضية (مفيدة لنظام الـ Prestige).
LoadProgressionSaveData(Data)	Authority	تستعيد التقدّم من بنية الحفظ.
GetProgressionSaveData()	Pure	تُرجِع لقطة من النوع `FAMLSProgressionSaveData`.
GetCurrentLevel /GetCurrentXP	Pure	القيم الحالية.
GetXPRequiredForNextLevel	Pure	الخبرة اللازمة لإتمام المستوى الحالي.
GetRemainingXPToNextLevel	Pure	الخبرة اللازمة لإتمام المستوى الحالي.
GetXPProgressPercentage	Pure	قيمة شريط التقدّم من ⁦0.0 – 1.0⁩.
GetCurrentLevelCap	Pure	قيمة شريط التقدّم من ⁦0.0 – 1.0⁩.
GetCurrentLevelCap	Pure	الحد الأقصى الصارم لمرحلة الصعود الحالية.
IsAtCurrentLevelCap/IsAtAbsoluteMaxLevel	Pure	فحوصات الحد الأقصى.
CanAscend	Pure	تكون true عند بلوغ الحد الحالي مع عدم بلوغ أقصى مستوى مطلق.
GetCurrentAscensionPhase	Pure	المرحلة الحالية (تبدأ من 1).
GetRequiredAscensionPhaseForLevel	Pure	المرحلة المطلوبة لبلوغ مستوى معيّن.
HasReachedLevel(Level)	Pure	تكون true إذا كان المستوى الحالي ≥ المستوى المستهدف.
GetLevelStatus(Level)	Pure	تُرجِع `FAMLSLevelStatusData`: bHasReached, bRequiresAscension, bIsAbsoluteMaxLevel, bIsInvalid. مثالية لواجهات خريطة المستويات.
GetRewardsForLevel(Level)	Pure	عناصر المكافآت المُعدّة لمستوى معيّن.

أصل بيانات الإعدادات (`UAMLSLevelUpConfigDataAsset`)

الخاصية	الافتراضي	الوصف
Max Level	50	أعلى مستوى مطلق (الحد الأدنى 2).
XP Curve Method	Formulaic	Explicit Array أو Formulaic أو Float Curve Asset.
System ID	Player	معرّف يُستخدم لمطابقة معالِجات المكافآت مع هذا الأصل.
Use Ascension System	false	تُفعِّل حدودًا قصوى للمستوى تتطلب استدعاء `Ascend()`.
Ascension Level Caps	فارغ	الحد الأقصى لكل مرحلة، مثال: `[20, 40]`.
Explicit XP Thresholds	فارغ	الفهرس 0 = الخبرة اللازمة لمغادرة المستوى 1. تعود المدخلات المفقودة إلى `Level × FormulaBaseXP`.
Formula Base XP / Multiplier / Exponent	100 / 1.2 / 1.5	راجع الصيغة أدناه.
Visual Curve Asset	لا شيء	منحنى Float: المحور X = المستوى، والمحور Y = الخبرة المطلوبة.
Reward Milestones	فارغ	قوائم لكل مستوى من `(RewardTag, RewardCount)`.
Custom Processor Milestones	فارغ	فئة معالِج المكافآت لكل مستوى.
Convert Overflow XP To Currency	false	تُفعِّل تحويل الفائض عند أقصى مستوى.
Overflow Currency Tag	لا شيء	الوسم (Tag) الذي يُرسَل مع حدث التحويل.
Overflow Conversion Multiplier	10.0	العملة = ⁦max(1, round(XP × multiplier))⁩.

منحنى الصيغة الرياضية (Formulaic)

XP required = round( FormulaBaseXP × Level ^ FormulaExponent × FormulaMultiplier )   (minimum 1)

بالإعدادات الافتراضية، يحتاج المستوى 1 إلى 120 خبرة، ويحتاج المستوى 10 إلى نحو 3,795 خبرة. لا تُطلب أي خبرة عند Max Level أو بعده.

نظام الصعود (Ascension)

يتيح لك الصعود تقييد التقدّم بحدوث إجراء من اللاعب (مواد، مهمة، زعيم). فعِّل Use Ascension System وحدِّد الحدود القصوى:

AscensionLevelCaps = [20, 40, 50]   // الحد في المرحلة 1 هو 20، وفي المرحلة 2 هو 40، وفي المرحلة 3 هو 50

يرتقي اللاعب في المستويات بشكل طبيعي حتى يبلغ الحد الأقصى؛ وتبقى الخبرة الزائدة محفوظة.
تتحقق لعبتك من التكلفة، ثم تستدعي Ascend() على الخادم.
تزداد المرحلة، ويُطلَق OnAscendedDelegate، وتستمر الخبرة المحفوظة في رفع المستوى.

استخدم CanAscend() لتفعيل زر Ascend، وGetLevelStatus() لعرض أقفال الصعود على خريطة المستويات.

المكافآت والمعالِجات

مراحل المكافآت

أضِف مدخلات إلى Reward Milestones مع مستوى مستهدف وقائمة بعناصر المكافآت (Gameplay Tag + العدد). عند بلوغ المستوى، يقوم OnRewardsProcessedDelegate ببثّ العناصر حتى تتمكن لعبتك من منحها.

معالِجات المكافآت المخصّصة

للمنطق المخصّص، أنشئ فئة فرعية من UAMLSLevelUpRewardProcessor (في C++ أو Blueprint) وسجِّلها ضمن Custom Processor Milestones للمستوى المطلوب.

تجاوز (Override) حدث Blueprint المسمّى On Process Reward Tags، أو الدالة الافتراضية في C++ المسمّاة NativeProcessTag.
Target System ID في المعالِج يجب أن يطابق System ID الخاص بأصل البيانات (اضبطه على None لقبول الكل).
يجب أن يطبّق الـ Actor المستهدف IAMLSLevelableInterface، وإلا سيتم تخطّي الاستدعاء مع تحذير.
يقوم المكوّن بتخزين مثيلات المعالِج مؤقتًا لكل فئة.

// C++
class UMyRewardProcessor : public UAMLSLevelUpRewardProcessor
{
protected:
    virtual void NativeProcessTag(AActor* Target, const TArray<FAMLSLevelRewardItem>& Items, int32 Level) override;
};

واجهة Levelable (`IAMLSLevelableInterface`)

طبّقها على الـ Actors التي يجب أن تتلقى الاستدعاءات. يمكن تنفيذها عبر Blueprint.

الدالة	الوصف
GetLevelComponent()	تُرجِع المكوّن `UAMLSLevelComponent` الخاص بالـ Actor.
OnLevelUp(NewLevel)	يُستدعى عند رفع المستوى: لتطبيق الإحصاءات أو الشفاء أو فتح المحتوى.

الأحداث (Delegates)

الحدث	المعاملات	متى يُطلَق
OnLevelUpDelegate	NewLevel, Owner	عند اكتساب مستوى (وعلى العملاء أيضًا عند مزامنة المستوى).
OnXPChangedDelegate	CurrentXP, XPToNextLevel, Percent	عند تغيّر الخبرة أو المستوى؛ وكذلك عند BeginPlay.
OnRewardsProcessedDelegate	LevelAchieved, Rewards, Owner	عند بلوغ مستوى له مكافآت أو معالِج.
OnOverflowXPConvertedDelegate	WastedXP, CurrencyEarned, CurrencyTag, Owner	عند اكتساب خبرة في أقصى مستوى مع تفعيل التحويل.
OnAscendedDelegate	NewAscensionPhase, Owner	عند تغيّر مرحلة الصعود.

الحفظ والتحميل

FAMLSProgressionSaveData تحتوي على SavedLevel, SavedXP, SavedAscensionPhase وهي موسومة بـ SaveGame. خزِّنها في كائن SaveGame الخاص بك.

// حفظ
SaveObj->Progression = LevelComp->GetProgressionSaveData();
// تحميل (الخادم)
LevelComp->LoadProgressionSaveData(SaveObj->Progression);

عند التحميل، يتم التحقق من القيم مقابل الحدود الحالية ومعالجة الخبرة المعلّقة.

اللعب الجماعي والمزامنة (Replication)

جميع الدوال التي تغيّر الحالة تعمل على الخادم فقط.
CurrentLevel، CurrentXP وCurrentAscensionPhase تتم مزامنتها إلى العملاء عبر RepNotify، الذي يُعيد إطلاق المفوّضات (Delegates) المطابقة لتحديث واجهة المستخدم.
تتم معالجة المكافآت وتحويل الفائض على الخادم؛ قم بمزامنة العناصر الناتجة عبر أنظمتك الخاصة.

ملاحظات

يضبط المكوّن bCanEverTick = false، لذلك لا توجد أي تكلفة في كل إطار.
يجب أن توجد وسوم المكافآت مثل Reward.Stat في Gameplay Tags الخاصة بمشروعك.
تتم مطابقة مراحل المكافآت والمعالِجات بحسب رقم المستوى المطابق تمامًا.