Advanced Modular Leveling system

適用於 Unreal Engine 的模組化、支援網路複製的 XP 與等級外掛程式（支援 C++ 與藍圖）。支援資料驅動的曲線、升階（Ascension）等級上限、里程碑獎勵，以及溢出經驗轉換。

功能特色

即插即用的元件將 AMLSLevelComponent 加入任意 Actor：玩家、敵人、武器、建築物等。

3 種 XP 曲線類型明確陣列、數學公式或 Unreal Float Curve 資產。

升階限制必須透過呼叫 Ascend 才能突破的硬性等級上限。

里程碑獎勵依等級發放的 Gameplay Tag 獎勵，並支援自訂藍圖或 C++ 獎勵處理器。

溢出經驗將達到最高等級後獲得的 XP，透過標籤與倍率轉換為貨幣。

支援多人連線以伺服器為權威，並複製等級、XP 與升階階段。

存檔系統介面提供用於儲存與還原進度的 SaveGame 結構。

對藍圖友善提供 Pure 取得函式、僅限 Authority 呼叫的函式，以及可綁定的事件。

快速入門

啟用外掛程式，並確保專案中可使用 GameplayTags 模組。
建立資料資產：Content Browser → Miscellaneous → Data Asset → AMLSLevelUpConfigDataAsset。
設定 Max Level，選擇 XP Curve Method，並可選擇性新增獎勵里程碑。
將 AMLS Level Component 加入你的 Actor（你的角色），並將資料資產指定給 Level Config Data。
在伺服器上，每當 Actor 獲得經驗時，呼叫 AddXP。
綁定 OnLevelUpDelegate / OnXPChangedDelegate 以驅動你的 UI。

// C++ 範例

if (UAMLSLevelComponent* Level = Actor->FindComponentByClass<UAMLSLevelComponent>())
{
    Level->OnLevelUpDelegate.AddDynamic(this, &AMyClass::HandleLevelUp);
    Level->AddXP(250); // 僅限伺服器
}

如果未指定設定資產，將記錄警告，並使用備援值（等級上限為 50，所需 XP = 等級 × 100）。

等級元件（`UAMLSLevelComponent`）

初始為 1 級、0 XP、升階階段 1。標示為 Authority 的函式僅在伺服器上執行。

函式	類型	說明
AddXP(Amount)	Authority	增加 XP 並處理連續升級。達到絕對最高等級後，XP 將轉入溢出轉換。
SetLevel(NewLevel)	Authority	增加 XP 並處理連續升級。達到絕對最高等級後，XP 將轉入溢出轉換。
AddLevels(LevelsToAdd)	Authority	直接給予固定數量的等級，並遵守升階等級上限。
Ascend()	Authority	如果 `CanAscend()` 為 true，則進入下一個升階階段。
ResetProgression()	Authority	將等級、XP 與階段重設為預設值（適用於 Prestige 聲望機制）。
LoadProgressionSaveData(Data)	Authority	從存檔結構還原進度。
GetProgressionSaveData()	Pure	回傳一個 `FAMLSProgressionSaveData` 快照。
GetCurrentLevel /GetCurrentXP	Pure	目前的值。
GetXPRequiredForNextLevel	Pure	完成目前等級所需的 XP。
GetRemainingXPToNextLevel	Pure	完成目前等級所需的 XP。
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。非常適合等級地圖 UI。
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 級所需的 XP。缺少的項目將回退為 `Level × FormulaBaseXP`。
Formula Base XP / Multiplier / Exponent	100 / 1.2 / 1.5	請參閱下方公式。
Visual Curve Asset	無	Float 曲線：X = 等級，Y = 所需 XP。
Reward Milestones	空	依等級劃分的 `(RewardTag, RewardCount)` 清單。
Custom Processor Milestones	空	依等級指定的獎勵處理器類別。
Convert Overflow XP To Currency	false	在最高等級時啟用溢出轉換。
Overflow Currency Tag	無	隨轉換事件一併傳送的標籤。
Overflow Conversion Multiplier	10.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。

升階系統

升階可讓你將進度限制在玩家的某項行為之後（材料、任務、Boss 等）。啟用 Use Ascension System 並定義等級上限：

AscensionLevelCaps = [20, 40, 50]   // 階段 1 上限 20，階段 2 上限 40，階段 3 上限 50

玩家正常升級，直到達到上限；多餘的 XP 會被保留。
你的遊戲驗證消耗後，在伺服器上呼叫 Ascend()。
階段提升，OnAscendedDelegate 觸發，已保留的 XP 會繼續用於升級。

使用 CanAscend() 來啟用 Ascend 按鈕，並使用 GetLevelStatus() 在等級地圖上顯示升階鎖定狀態。

獎勵與處理器

獎勵里程碑

向 Reward Milestones 新增項目，指定目標等級與獎勵項目清單（Gameplay Tag + 數量）。達到該等級時，OnRewardsProcessedDelegate 會廣播這些項目，讓你的遊戲發放它們。

自訂獎勵處理器

若需要自訂邏輯，請繼承 UAMLSLevelUpRewardProcessor （使用 C++ 或藍圖），並在 Custom Processor Milestones 中為目標等級註冊它。

覆寫藍圖事件 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`）

在需要接收回呼的 Actor 上實作。可透過藍圖實作。

函式	說明
GetLevelComponent()	回傳該 Actor 的 `UAMLSLevelComponent`。
OnLevelUp(NewLevel)	升級時呼叫：套用屬性、治療、解鎖內容。

事件（委派）

事件	參數	觸發時機
OnLevelUpDelegate	NewLevel, Owner	獲得一個等級時觸發（等級複製到用戶端時，用戶端上也會觸發）。
OnXPChangedDelegate	CurrentXP, XPToNextLevel, Percent	XP 或等級變化時觸發；BeginPlay 時也會觸發。
OnRewardsProcessedDelegate	LevelAchieved, Rewards, Owner	達到設定了獎勵或處理器的等級時觸發。
OnOverflowXPConvertedDelegate	WastedXP, CurrencyEarned, CurrencyTag, Owner	在最高等級獲得 XP 且啟用轉換時觸發。
OnAscendedDelegate	NewAscensionPhase, 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 中。
獎勵與處理器里程碑依精確的等級數字進行配對。