EAM(EventAlertMod)

# EventAlertMod Retail 12.1.5 (Alpha 8.8) 專為《魔獸世界：地心之戰 / 午夜 (Retail 12.1.5 / 12.1 / 12.0+)》量身打造的超輕量、零污染、純事件驅動法術監控、技能冷卻、地面效果、玩家職業資源與角色屬性戰鬥告警插件。 *** ## 🌟 本次更新亮點 (Release Highlights) ### 🚀 1. 魔獸世界 12.1.5 正式服全面適配與原生 C++ 加速庫 (Retail 12.1.5 Compatibility & Native Acceleration) * **TOC 介面升級**：全面適配魔獸世界正式服 12.1.5 版本號（Interface: `120105`），持續無縫向下相容 `120100` 與 `120007` 客戶端。 * **暴雪 12.1.5 原生底層 C++ 加速**：整合暴雪底層數學庫 (`math.clamp`, `math.saturate`, `math.round`, `math.lerp`, `math.normalize`, `math.sign`, `math.remap`, `math.wrap`, `math.isfinite`, `math.isnan`, `math.isinf`)、字串庫 (`string.contains`, `string.ltrim`, `string.rtrim`, `string.startswith`, `string.endswith`) 與表格庫 (`table.isempty`, `table.contains`, `table.indexof`, `table.removeunordered`, `table.removevalue`, `table.keys`, `table.values`)，並具備防禦性向下相容 (Polyfills)。 ### ⏱️ 2. 原生 TimedSignalMap 零分配排程器引擎 (Zero-Alloc TimedSignalMap Scheduler Engine) * **C++ 引擎直通排程**：深度整合 12.1.5 `C_Timer.NewTimedSignalMap` 原生鍵值排程機制，由暴雪 C++ 引擎直接託管倒數計時與定時信號。 * **重複定時零記憶體配置 (Zero-Alloc Key Rescheduling)**：舊版客戶端自動平滑切換至自主維護的精準鍵值排程狀態機，消滅反覆建立 Timer 的暫存 Table 垃圾回收 (GC) 開銷。 * **防禦性 Proxy Table 保護**：針對原生 C++ TimedSignalMap 之唯讀保護結構實裝輕量級安全防禦代理，徹底杜絕 `Attempted to assign to read-only key SignalAt` 報錯。 ### 🦠 3. 12.1.5 原生 Pandemic 結餘窗口精確判斷與動畫支援 (12.1.5 Native Pandemic Carry-Over Precision & Animations) * **精確 DoT 結餘時間計算**：採用 `C_UnitAuras.GetRefreshCarryOverDuration` 精準結餘時間計算，嚴格於結餘小於等於 30% 基礎時長時觸發補 DoT 提示，杜絕提早補 DoT 損失秒數；舊版客戶端自動降級至 `C_UnitAuras.GetRefreshExtendedDuration`。 * **Native Aura 原生動畫 API 支援**：深度適配 12.1.5 原生動畫 API (`AddPandemicActiveAnimation`, `AddPandemicEnterAnimation`, `AddPandemicLeaveAnimation`)，補 DoT 進入與退出動畫更細緻流暢。 * **音效警示頻率限制保護**：於 `C_UnitAuras.AddAuraSound` 註冊時加入 `throttleSeconds` 參數（預設 0.3s），杜絕高頻率觸發或層數暴漲時引發連續音效轟炸。 ### 🌋 4. 地面效果多組時間解析與自選組別 (Ground Effect Multi-Duration Candidate Selection) * **全文多時間智慧解析**：針對技能說明中包含多組秒數（如地面持續時間 vs 減速持續時間 vs 引導時間，例如暴風雪「8 秒內造成傷害…減速 50%，持續 3 秒」）的複雜技能，自動依出現順序解析出所有時間候選。 * **設定視窗候選下拉選單**：在地面效果設定介面新增「時間組別選取」下拉選單，使用者可自由挑選欲使用的時間組別，點選後即時同步帶入「手動設定時間」輸入框。 * **一鍵擷取動態聯動**：點擊「一鍵擷取」時，即時重整並更新下拉選單候選列表，自動選中目標組別秒數並帶入編輯框。 ### 🎨 5. 模組圖示外框色彩自訂與無邊框模式 (Customizable Alert Border Colors & Borderless Mode) * **8 大模組獨立選色**：自身增益、自身減益、目標增益、目標減益、技能冷卻、物品冷卻、地面效果、寵物警示支援獨立調色盤與透明度調節。 * **無邊框極簡模式**：提供「啟用圖示類型外框」全域總開關與各模組獨立勾選開關，方便喜愛無邊框風格的玩家完全關閉外框線條。 * **即時動態熱套用**：修改外框色彩或開關後，畫面當前已顯示之所有圖示即時動態重繪，無須手動重載介面 (/reload)；提供「重設邊框色彩」按鈕一鍵還原經典預設。 ### 🖱️ 6. 玩家職業資源獨立拖曳定位與九宮格依附 (Per-Resource Independent Dragging & 9-Point Attachment) * **每項資源獨立位置與自由拖曳**：於「玩家職業資源 -> 位置與錨點」新增「啟用此項獨立位置」開關與「移動此單項資源」／「移動全部/主錨點」／「歸零偏移 (0, 0)」按鈕，支援個別資源脫離群組堆疊並以滑鼠左鍵直接拖曳定位、右鍵點擊完成並自動同步滑桿數值。 * **常見框架九宮格方向依附**：新增「依附目標框架」選單（支援 EAM 資源主錨點、螢幕中央 UIParent、玩家頭像 PlayerFrame、目標頭像 TargetFrame、焦點頭像 FocusFrame、寵物頭像 PetFrame、個人資源條 PersonalResourceDisplay），搭配中文直覺化九宮格方位自由對齊。 ### ⚡ 7. 玩家職業資源動態格數分割、雙色漸層與條件式警戒系統 (Dynamic Segments, Gradient Colors & Conditional Alerts) * **點數型資源自動對齊上限與自訂分割**：連擊點數 (5/6/7)、真氣 (5/6)、喚能師龍能 (5/6)、聖能 (5)、靈魂裂片 (5)、秘法充能 (4)、符文 (6) 現已自動依據角色實際上限 (`UnitPowerMax`) 即時分割 StatusBar 格線與底部子格，並於「條形與尺寸」新增「自訂分割格數 (0=自動, 1~20)」滑桿。 * **自訂條形單色與雙色漸層**：於「條形與尺寸」新增「條形色彩模式」（預設職業動態色、自訂單色、自訂雙色漸層）及起點／終點調色盤，支援水平與垂直漸層渲染。 * **StatusBar 條件式警戒擴充**：於「顯示與模式」新增「條件判定」（`>=` 高於或等於門檻 / `<=` 低於或等於門檻）、「條件達成時變色」（含警戒顏色調色盤）及「條件達成時播放音效」（邊緣觸發防洗頻提示音）。 ### 📚 8. 第三方素材庫 LibSharedMedia-3.0 升級與五語系術語校準 (LibSharedMedia r156 & Evoker Essence Calibration) * **LibSharedMedia-3.0 r156**：升級第三方素材庫 LibSharedMedia-3.0 至最新 r156 (支援 12.0.1+ / Interface `12000103`)，擴充字型與材質素材庫，提升素材動態載入相容性與記憶體管理效率。 * **喚能師龍能五語系官方術語校準**：全面校準喚能師專用資源於全語系之暴雪官方術語命名（繁體中文「龍能」、簡體中文「精华」、英文「Essence」、韓文「정수」、俄文「Сущность」），確保介面選單、狀態條標籤與提示訊息 100% 精準對齊各語系官方客戶端。 *** ## 🐛 關鍵缺陷修復與戰鬥防禦加固 (Critical Bug Fixes & Combat Hardening) * **戰鬥動作條污染報錯徹底排除 (RightManagedFrameContainer Taint Remediation)**： * 徹底移除對暴雪全域環境庫 (table/math/string) 的外部賦值與偽填充，防禦性收攏至專屬 `Util` 命名空間，徹底杜絕暴雪介面 (如 PetActionBar/EditMode/RightManagedFrameContainer) 遭污染引發之 `ADDON_ACTION_BLOCKED` 錯誤。 * **天賦覆蓋技能冷卻倒數與天賦減 CD 即時動態同步 (Channeled Activation & Live Passive CDR Sync)**： * 重構冷卻施法匹配與法術家族識別 (getSpellCooldownInfo)，依序檢定優先施法 ID、覆蓋 ID、基礎 ID 與原始 ID，終結冰霜射線、彗星風暴等天賦覆蓋技能冷卻時有時無問題。 * 支援引導類型技能於引導起始瞬間 (`UNIT_SPELLCAST_CHANNEL_START`) 即刻激活冷卻倒數與地面效果，在戰鬥中無延遲倒數。 * 實裝 60ms 高頻自適應突發採樣器與 120ms/350ms/700ms 彈道飛行延遲補償，精準同步冰法「白化」、「結冰」等被動減 CD。 * 實裝覆蓋技能冷卻保護屏障：施放無實質冷卻之臨時覆蓋觸發技時，禁止覆寫原技能激活身分，絕不提前截斷未到期冷卻。 * **冷卻飛行記錄器 (Cooldown Flight Trace) 與即時偵錯視窗 (/eam trace)**： * 內建 300 筆高精度環形緩衝區之冷卻飛行記錄器，完整記錄施法成功、引導啟閉、法術覆蓋更新、API 底層參數與狀態機轉移。 * 提供 `/eam trace`（或 `/eam cdtrace`）遊戲內除錯彈出視窗，內建「全選記錄 (Ctrl+C)」一鍵複製、清空記錄與即時刷新功能，並於重載介面或登出時持久化存檔。 * **秘密值 (Secret Values) 安全防護加固與原生接收槽單向綁定**： * 全面加固型別安全性校驗 (`Util.isSafeTableKey` / `Util.isSafePositiveNumber`)，任何含有秘密值或保護屬性的數據嚴格隔離於 Lua 陣列索引與字串運算之外，一律由底層原生元件（Cooldown:SetCooldown、StatusBar:SetValue、DurationObject）進行單向管道綁定，徹底杜絕 Taint 與運算崩潰風險。 * **戰鬥中多圖示重疊堆疊修復與首格 Slot 1 防蒸發**： * 修復戰鬥中非安全警示框架因佈局判定誤觸戰鬥延遲，導致新觸發圖示無法計算二維網格位移座標、全部堆疊重疊在中心座標 (0, 0) 的問題。 * 建立 `GetNumPoints() == 0` 物理計數守衛與幾何坐標回正機制，杜絕圖示第一格消失與移動模式坐標漂移。 *** ## 📦 安裝與使用指引 (Installation & Usage) 1. 下載最新版本解壓縮後，將 `EventAlertMod` 資料夾複製至魔獸世界目錄： * 正式服 Retail: `World of Warcraft\_retail_\Interface\AddOns\` * 測試服 PTR: `World of Warcraft\_ptr_\Interface\AddOns\` 2. 進入遊戲後輸入 `/eam` 開啟主設定面板，或輸入 `/eam opt`、`/eam preview`、`/eam trace`、`/eam metrics`。 3. 遊戲中將滑鼠游標懸停於任意技能、物品或巨集圖示上，按下 `CTRL + ALT` 即可叫出快捷加入面板。