Advanced Modular Leveling system

Unreal Engine 向けのモジュール式・レプリケーション対応 XP／レベリングプラグイン（C++ および Blueprint 対応）。データ駆動のカーブ、アセンションによるレベル上限、マイルストーン報酬、オーバーフロー XP の変換に対応しています。

機能 

すぐに使えるコンポーネント任意の Actor（プレイヤー、敵、武器、建物など）に AMLSLevelComponent を追加できます。
3 種類の XP カーブ明示的な配列、数式、または Unreal の Float Curve アセットから選べます。
アセンションによる進行制限固定のレベル上限は、Ascend を呼び出すことでのみ突破できます。
マイルストーン報酬レベルごとの Gameplay Tag 報酬に加え、Blueprint または C++ によるカスタム報酬プロセッサに対応します。
オーバーフロー XP最大レベル到達後に獲得した XP を、タグと倍率を使って通貨に変換します。
マルチプレイヤー対応サーバー権威型で、レベル・XP・アセンションフェーズをレプリケートします。
セーブシステム連携進行状況の保存と復元に使える SaveGame 構造体を用意しています。
Blueprint フレンドリーPure なゲッター、Authority 専用の呼び出し可能関数、バインド可能なイベントを備えています。

クイックスタート

  1. プラグインを有効にし、プロジェクトで GameplayTags モジュールが利用可能であることを確認します。
  2. データアセットを作成します：Content Browser → Miscellaneous → Data Asset → AMLSLevelUpConfigDataAsset。
  3. Max Level を設定し、XP Curve Method を選択します。必要に応じて報酬マイルストーンを追加します。
  4. AMLS Level Component を Actor（お使いのキャラクター）に追加し、データアセットを Level Config Data に割り当てます。
  5. サーバー上で、Actor が経験値を獲得するたびに AddXP を呼び出します。
  6. UI を動かすには、OnLevelUpDelegate / OnXPChangedDelegate にバインドします。

// C++ の例

if (UAMLSLevelComponent* Level = Actor->FindComponentByClass<UAMLSLevelComponent>())
{
    Level->OnLevelUpDelegate.AddDynamic(this, &AMyClass::HandleLevelUp);
    Level->AddXP(250); // サーバーのみ
}
設定アセットが割り当てられていない場合は、警告がログに出力され、フォールバック値が使用されます（レベル上限 50、必要 XP = レベル × 100）。


レベルコンポーネント（UAMLSLevelComponent）

レベル 1、XP 0、アセンションフェーズ 1 から開始します。Authority と記載された関数は、サーバー上でのみ実行されます。

関数種類説明
AddXP(Amount)AuthorityXP を加算し、連続するレベルアップを処理します。絶対最大レベルでは、XP はオーバーフロー変換に回されます。
SetLevel(NewLevel)AuthorityXP を加算し、連続するレベルアップを処理します。絶対最大レベルでは、XP はオーバーフロー変換に回されます。
AddLevels(LevelsToAdd)Authority固定数のレベルを付与します。アセンションの上限が考慮されます。
Ascend()AuthorityCanAscend() が true の場合、次のアセンションフェーズへ移行します。
ResetProgression()Authorityレベル、XP、フェーズを初期値にリセットします（プレステージ用途に便利です）。
LoadProgressionSaveData(Data)Authorityセーブ用構造体から進行状況を復元します。
GetProgressionSaveData()PureFAMLSProgressionSaveData のスナップショットを返します。
GetCurrentLevel /GetCurrentXPPure現在の値。
GetXPRequiredForNextLevelPure現在のレベルを完了するために必要な XP。
GetRemainingXPToNextLevelPure現在のレベルを完了するために必要な XP。
GetXPProgressPercentagePure0.0～1.0 のプログレスバー値。
GetCurrentLevelCapPure0.0～1.0 のプログレスバー値。
GetCurrentLevelCapPure現在のアセンションフェーズにおける固定上限。
IsAtCurrentLevelCap/IsAtAbsoluteMaxLevelPure上限の判定。
CanAscendPure現在の上限に達していて、かつ絶対最大レベルではない場合に true。
GetCurrentAscensionPhasePure現在のフェーズ（1 から開始）。
GetRequiredAscensionPhaseForLevelPure指定したレベルに到達するために必要なフェーズ。
HasReachedLevel(Level)Pure現在のレベルが目標以上の場合に true。
GetLevelStatus(Level)PureFAMLSLevelStatusData を返します：bHasReached, bRequiresAscension, bIsAbsoluteMaxLevel, bIsInvalid。レベルマップ UI に最適です。
GetRewardsForLevel(Level)Pureレベルに設定された報酬アイテム。

設定データアセット（UAMLSLevelUpConfigDataAsset）

プロパティデフォルト説明
Max Level50絶対最大レベル（最小 2）。
XP Curve MethodFormulaicExplicit Array、Formulaic、Float Curve Asset のいずれか。
System IDPlayer報酬プロセッサをこのアセットに対応付けるための識別子。
Use Ascension SystemfalseAscend() の呼び出しが必要なレベル上限を有効にします。
Ascension Level Caps空フェーズごとの上限。例：[20, 40]。
Explicit XP Thresholds空インデックス 0 = レベル 1 を抜けるために必要な XP。不足している項目は Level × FormulaBaseXP にフォールバックします。
Formula Base XP / Multiplier / Exponent100 / 1.2 / 1.5下記の数式を参照してください。
Visual Curve AssetなしFloat カーブ：X = レベル、Y = 必要 XP。
Reward Milestones空レベルごとの (RewardTag, RewardCount) のリスト。
Custom Processor Milestones空レベルごとの報酬プロセッサクラス。
Convert Overflow XP To Currencyfalse最大レベルでのオーバーフロー変換を有効にします。
Overflow Currency Tagなし変換イベントと共に送信されるタグ。
Overflow Conversion Multiplier10.0通貨 = max(1, round(XP × multiplier))。

数式カーブ（Formulaic）

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

デフォルト設定では、レベル 1 に 120 XP、レベル 10 に約 3,795 XP が必要です。Max Level 以上では XP は不要です。


アセンションシステム

アセンションを使うと、プレイヤーの行動（素材、クエスト、ボスなど）を条件に進行を制限できます。Use Ascension System を有効にして、上限を定義します：

AscensionLevelCaps = [20, 40, 50]   // フェーズ 1 の上限は 20、フェーズ 2 は 40、フェーズ 3 は 50
    1. プレイヤーは上限に達するまで通常どおりレベルアップします。余剰の XP は保持されます。
    2. ゲーム側でコストを確認し、サーバー上で Ascend() を呼び出します。
    3. フェーズが上がり、OnAscendedDelegate が発火し、保持されていた XP でレベルアップが続行されます。
    CanAscend() を使って Ascend ボタンを有効化し、GetLevelStatus() を使ってレベルマップにアセンションのロックを表示できます。

    報酬とプロセッサ

    報酬マイルストーン

    Reward Milestones に、対象レベルと報酬アイテム（Gameplay Tag ＋ 個数）のリストを持つエントリを追加します。レベルに到達すると、OnRewardsProcessedDelegate がアイテムをブロードキャストするので、ゲーム側で付与できます。

    カスタム報酬プロセッサ

    カスタムロジックが必要な場合は、UAMLSLevelUpRewardProcessor を（C++ または Blueprint で）サブクラス化し、対象レベルに対して Custom Processor Milestones に登録します。

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

    Levelable インターフェース（IAMLSLevelableInterface）

    コールバックを受け取りたい Actor に実装します。Blueprint から実装できます。

    関数説明
    GetLevelComponent()Actor の UAMLSLevelComponent を返します。
    OnLevelUp(NewLevel)レベルアップ時に呼び出されます。ステータスの適用、回復、コンテンツの解放などに使います。

    イベント（デリゲート）

    イベントパラメータ発火タイミング
    OnLevelUpDelegateNewLevel, Ownerレベルを獲得したとき（レベルがレプリケートされたクライアントでも発火します）。
    OnXPChangedDelegateCurrentXP, XPToNextLevel, PercentXP またはレベルが変化したとき。BeginPlay 時にも発火します。
    OnRewardsProcessedDelegateLevelAchieved, Rewards, Owner報酬またはプロセッサが設定されたレベルに到達したとき。
    OnOverflowXPConvertedDelegateWastedXP, CurrencyEarned, CurrencyTag, Owner変換が有効な状態で、最大レベルで XP を獲得したとき。
    OnAscendedDelegateNewAscensionPhase, Ownerアセンションフェーズが変化したとき。

    セーブとロード

    FAMLSProgressionSaveData には SavedLevel, SavedXP, SavedAscensionPhase が含まれ、SaveGame 指定子が付いています。SaveGame オブジェクトに保存してください。

    // セーブ
SaveObj->Progression = LevelComp->GetProgressionSaveData();
// ロード（サーバー）
LevelComp->LoadProgressionSaveData(SaveObj->Progression);

    ロード時には、値が現在の上限に対して検証され、保留中の XP が処理されます。

    マルチプレイヤーとレプリケーション

    • 状態を変更するすべての関数は、サーバー上でのみ実行されます。
    • CurrentLevel、CurrentXP、CurrentAscensionPhase は RepNotify を使ってクライアントにレプリケートされ、UI 向けに対応するデリゲートが再発火されます。
    • 報酬の処理とオーバーフロー変換はサーバー上で行われます。結果として得られたアイテムは、独自のシステムを通じてレプリケートしてください。

    注意事項

    • コンポーネントは bCanEverTick = false を設定しているため、フレームごとのコストは発生しません。
    • Reward.Stat などの報酬タグは、プロジェクトの Gameplay Tags に存在している必要があります。
    • 報酬マイルストーンとプロセッサマイルストーンは、レベル番号の完全一致で対応付けられます。


    Copyright KhalidBen 2026. 全著作権所有。