骨架結構導覽
本節概述了 LightScript 整合的基礎結構，涵蓋關鍵技術需求、實際案例、命名慣例和效率提示。它詳細介紹了 update 迴圈、儀錶行為、特效觸發邏輯，並重點說明常見的陷阱。無論您是在除錯、從頭開始建構，還是維護他人的程式碼，本指南都強調清晰性、穩定性和效能是高品質整合的核心標準。
本節提供了從維護角度設置 LightScript 的快速概覽，重點在於問題通常出現在哪裡以及如何發現和修復錯誤。我們將從理想 LightScript 結構的簡短導覽開始，讓您熟悉程式碼，然後介紹疑難排解，最後以常見問題解答結尾。
基本骨架需要 <head>、<body> 和 <script>。所有儀錶和使用者控制項宣告都放在 <head> 內。所有 canvas 宣告屬於 <body>。其他所有內容應放在 <script> 區段中。
<head>
Section titled “<head>”<head> 是任何 LightScript 中最關鍵和複雜的部分之一。此處有問題的使用者控制項或儀錶可能導致當機迴圈，或停用自身及其後宣告的任何儀錶。
建立儀錶時，您需要確保：
- 完整的語法（避免當機和損壞的儀錶）
- 無重複的儀錶名稱（重複項目會被覆寫）
- 無儀錶超出螢幕邊界（導致當機和錯誤）
- 儀錶中無缺少或多餘的選項（導致當機）
- 所有儀錶包含解析度調整（確保一致的行為）
關於解析度，最常見的長寬比是：
- 16:9（3840x2160、2560x1440、1920x1080、1600x900、1366x768、1360x768、1280x720）
- 16:10（2560x1600、1920x1200、1680x1050、1440x900、1280x800）
- 21:9（5120x2160、3440x1440）
預設情況下，我們使用 2560x1440 解析度。
所有 LightScript 必須支援 16:9、16:10 和 21:9 長寬比。雖然 4:3 不代表我們使用者群體的很大一部分，但仍應考慮未來的相容性。
以下是具有多個解析度設定的儀錶結構範例：
您的儀錶的預設位置和大小適用於相同長寬比內的所有其他解析度。例如，如果您最初調整儀錶以適用於 1600x900，該儀錶應在所有其他 16:9 解析度下正常運作。但是，也有例外。Fortnite 即使在相同長寬比內也有多個不同的儀錶位置，一些長寬比本身可能具有誤導性。例如，1366x768 是全球常見的解析度，通常列為 16:9，但實際上並非真正的 16:9 比例，這並不罕見。同樣，像 21:9 這樣的超寬比例也很少符合其標稱尺寸。根據我作為整合開發者的經驗，儘管它們被標記為 21:9，我從未遇到過完全精確的 21:9 解析度。因此，每個超寬解析度都必須單獨建立、測試和設定。
所有調整必須放置在開頭 <meta> 和結尾 </meta> 標籤之間；否則它們將不起作用。如果您的預設儀錶基於 16:9 並在這些解析度間表現一致，您不需要為其他 16:9 解析度添加調整。但是，您必須為其他長寬比（如 16:10 和 21:9）中的每個解析度添加條目，即使該比例是一致的。
最後，除了 OCR 儀錶之外的每個儀錶都需要一個 HSL 範圍才能觸發。這些範圍可能因以下因素而變得複雜：
- 透明的 UI 元素
- 顏色區域中的漸層
- 螢幕扭曲效果
- 遊戲內選單開啟
- 每個解析度的 UI 調整
- 控制器與鍵盤的使用
- 影片錄製，可能引入與壓縮相關的像素錯誤
關於 HSL 和正規化座標的基本說明已在我們的開發者文件中介紹，這裡不再重複。測試這些儀錶將在「識別問題」章節中討論，但有一點很重要：驗證所有儀錶完全正常所需的測試量計算為（儀錶數量）×（解析度調整數量）×（遊戲模式數量）×（可玩角色數量）×（平均遊戲時長）。這可以輕易累積到每個遊戲數小時的驗證，尤其是如果練習模式或其他解決方法不可用的情況下。
保持您的儀錶高效，我們的標準是完美。
<body>
Section titled “<body>”<body> 標籤是實際 canvas 元素宣告的地方。它應該始終與以下範例大致相似。實際的 canvas id 可以更改，但請確保您在腳本中正確取得它。
<script>
Section titled “<script>”在每個整合中，此標籤內必須發生四件事：
- 取得 canvas 並用於建立我們的 2D 上下文。
- 初始 update 迴圈設定儀錶值，然後無限期地重新呼叫自身以維護它們。
- update 迴圈保持使用者控制項變數更新。
- 儀錶在穩定時執行其回呼函式。
我們已經設置了基本的程式碼骨架。下一步是詳細介紹從頭到尾觸發特效的執行迴圈。
- 電子遊戲 UI 以彩色條、按鈕、文字框等形式顯示資訊。SignalRGB 每秒多次擷取這些資料，但實際擷取率在很大程度上取決於您程式碼的效率。需要明確的是，單一迴圈或未宣告的變數都可能破壞您的整個腳本，甚至導致 SignalRGB 當機。更糟糕的是，很容易寫出技術上可以執行但效率太低以至於只能以 1-2 FPS 擷取資訊的程式碼。
- 在 <head> 中宣告的每個儀錶必須盡可能小且高效以減少開銷。儘早且頻繁地進行計算；佔據螢幕 25% 的儀錶永遠不會有效率。對於 OCR 儀錶，擷取單個字母而不是整個單詞。對於血條和魔法條，只監控必要的段落。保持您的儀錶盡可能小。
- 儀錶擷取每次迴圈都刷新的資訊。
- 之前，我們介紹了 Meter 類別定義，它儲存儀錶資料並在資訊陣列穩定時觸發回呼。在腳本頂部，在一個區塊中宣告所有 Meter。您可以組織或按字母排序；只是不要將它們分散在數千行程式碼中。您最終需要調整穩定性值，而試圖記住它們放在哪裡是浪費時間。
- 在 update 函式內，這些儀錶每次迴圈都會從螢幕讀取邏輯接收值。它們的內部邏輯評估穩定性，並在穩定時觸發其關聯的回呼函式。
- 這些回呼函式應在您的腳本中宣告，但在 update 函式之外。在其中，檢查您的 Meter 值（value、decreased、increased、diff）的狀態，並使用這些來確定是否播放特效動畫。以這種方式組織您的程式碼，而不是將所有內容直接放在 update 迴圈內，使我們能夠建立可擴展的整合。
現在您有了大致的概念，我將快速介紹一個實際案例迴圈。
- 我正在玩遊戲英雄聯盟，它用明亮的黃色高亮顯示可用技能。
- 每次迴圈，特定技能儀錶將此顏色讀取為 “1” 的值，因為它完全通過儀錶的 HSL 範圍。
- 這個 “1” 被傳遞給附加到螢幕讀取儀錶的 Meter 實例，並插入該 Meter 的資訊陣列。
- 如果陣列中的每個值都是 “1”，則認為是穩定的，並將啟動附加的特效回呼函式。如果每個值都是 “0” 或 “.1”，此回呼函式也會被啟動；Meter 只關心穩定性。需要注意的是，如果 Meter 在相同值下持續穩定，回呼函式將不會被持續啟動——只有具有新值的穩定性才會啟動回呼。
- 一旦回呼函式被執行，我們到達一些條件檢查——在這種情況下，我們所要做的就是檢查 Meter.value 是否為 “0”，表示技能已被使用。
- 由於 Meter value 是 “1”，我們未通過此檢查，不會播放技能特效。
- 幾秒後，我啟動了技能，按鈕周圍的黃色高亮消失了。
- 新的儀錶值為 0，被傳遞給其 Meter 類別。
- 一旦達到穩定性，回呼啟動，我們的條件通過，播放技能特效。延遲完全取決於 Meter 陣列的長度，您在宣告時設定此值。更長的陣列意味著更多延遲和更少的誤觸發，因此請確保測試直到找到良好的平衡。
螢幕讀取儀錶應具有簡單、清晰和描述性的名稱，始終以小寫字母開頭。將血條儀錶命名為 “healthBar” 非常好。當兩個儀錶在相同區域追蹤不同顏色時，將它們命名為 “healthBarRed” 和 “healthBarGreen” 也很好。但是，將只在某個英雄的終極技能期間出現的小儀錶命名為 “hrO21_yes” 之類的名稱，只會給任何試圖修復您程式碼的人帶來痛苦。如果運氣不好，弄清楚一個命名不佳的小儀錶在追蹤什麼可能需要盯著單個像素看一個小時，所以不要這樣做。
Meter 類別實例應大寫並以 Meter 結尾。像 “Q_Meter”、“TookDamageMeter” 和 “TowerDestroyedMeter” 這樣的範例都完全可以。這些應與在 <head> 區段中宣告的儀錶清楚區分。
特效函式也應盡可能簡單且具描述性地命名。有些遊戲有數百個這樣的函式；其他遊戲可能少於十個。如果多個英雄有獨特的技能，將英雄的名字作為前綴，如 “SonaQ”、“ChamberE” 或 “AshUlt”。例如，在英雄聯盟中，有像 “DragonEffect”、“TowerEffect” 和 “Q_Effects” 這樣的函式，它們包含多個條件並被多個儀錶使用。因此，這種命名方式也有助於為規模優化。
不要拼錯單詞。如果您不確定如何拼寫某個詞，請查閱。名稱必須清晰易讀，無論是誰在處理程式碼，也無論已過了多少時間。按字母順序組織名稱有助於快速查找，特別是如果您經常編輯該區段。雖然這種組織程度不是程式碼執行所必需的，但對於我們的維護開發者來說確實大有不同。