Communitygithub.com

UI 預覽

在遊戲專案中,先建立一個可調校的 HTML 預覽(HUD 元素、選單、提示、轉場或畫面效果),再於引擎中實作,並將調校後的數值轉換為建置規格。

UI 預覽 是什麼?

此技能提供一套嚴謹的工作流程,用於在遊戲引擎外部設計、預覽和調校 UI 元素或視覺效果。開發者或設計師可以創建一個精確的 HTML 預覽,該預覽使用真實的遊戲截圖作為背景,並包含一個調校面板(提供滑桿、顏色選擇器、變體和狀態切換)。調校過程中,所有變更會即時儲存到磁碟上的草稿檔案,當使用者按下「儲存」按鈕後,會產生一份經過批准的 `values.json` 檔案,作為最終的建置規格。此技能支援 Godot、Unity 和 Unreal 引擎,並提供專用腳本和主題檔案,能將批准的數值自動套用到引擎的屬性或主題系統中。其主要優點在於避免在程式碼中出現「魔術數字」,確保所有 UI 參數都可透過編輯器進行調整,並為每次設計決策建立完整的審查軌跡。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

UI 預覽 是做什麼的?

在人員調校 HTML 預覽並按下「儲存」之前,任何改變遊戲 UI 外觀的工作都不應開始建置。儲存的 values.json 即為規格:其中的每個數字都將成為編輯器可公開的屬性或主題條目,絕不會是程式碼中的魔術數字。看不到的變更不需要預覽。

工作順序: 確定要預覽的內容 → 取得該位置的截圖 → 建立預覽頁面 → 產生審閱表 → 人員調校並按下儲存 → 從 values.json 建置 → 產生建置對比預覽表。

1. 設定(每個專案一次)

  • 將 assets/kit/ 複製到 docs/mockups/kit/(可以使用其他資料夾:將 --mockups 傳遞給腳本即可)。引擎專用檔案在不使用時可以省略:godot_theme.js + apply_godot.py(Godot)、unity_theme.js + apply_uss.py(Unity)、unreal_theme.js + apply_unreal.py(Unreal)。Godot:同時將 assets/godot/project.js 複製到 kit/ 並填入內容(字型、按鍵圖示);Godot 頁面會從該位置載入它。
  • project.css 是唯一需要編輯的套件檔案:遊戲的字型(@font-face)和面板色板,包括 --display。kit.js 會在繪製前載入所有宣告的字型。
  • 將預覽排除在引擎的匯入之外(Godot:在 docs/mockups/ 中建立一個空的 .gdignore 檔案),並將 docs/mockups/*/values.draft.json 和 docs/mockups/*/shots/ 加入 .gitignore。
  • 提供專案根目錄的服務:python docs/mockups/kit/serve.py(僅使用標準函式庫),然後開啟 http://127.0.0.1:8765/docs/mockups/<feature>/。頁面會透過相對路徑載入遊戲的美術資源,並將調校結果儲存到磁碟(§5)。
  • 將專案自身的樣式讀入面板:Godot 使用 GodotTheme(主題 .tres)、Unity 使用 UnityTheme(.uss、ScriptableObject .asset)、Unreal 使用 UnrealTheme(來自標頭檔和 Default*.ini 的 C++ 類別預設值、匯出為 JSON/CSV 的 DataTable)。請參閱 references/engines.md;每個引擎在 assets/<engine>/ 中都有一個可運作的範例頁面。

2. 詢問,然後取得真實背景

  • 詢問是哪個畫面、元素或效果,以及在哪種情境下,除非這已經很清楚。
  • 以遊戲的視口尺寸(專案的解析度設定;也是 manifest 的 stage)截取該位置的螢幕截圖,隱藏 UI,再截一張顯示今天 UI 的截圖作為基準線。使用引擎執行的小型腳本(Godot 範本:assets/godot/game_shots.gd;其他引擎:references/engines.md),並將其放在預覽旁邊,用於建置檢查。
  • 僅當無法透過腳本到達該位置時,才要求人員提供螢幕截圖。對於尚無任何可拍攝內容的新事物,或當引擎無法在此執行時,使用純色或偽造的背景,並在狀態的標題中註明。

3. 編寫頁面

將 assets/template/(或 assets/<engine>/)複製到 docs/mockups/<feature>/。頁面格式、面板規格、Kit.spec 和 URL 參數都在 references/kit.md 中。

  • manifest.json: 標題、stage([寬, 高])、states(玩家可能看到的每種情境一個:空、滿、聚焦、停用、最長文字、動畫中間;每個狀態都帶有標題和 shotTime)、variants(當有實際選擇時,2-4 個,每個都有名稱和備註)、recommend(建議的變體及其原因,一兩行)。
  • index.html: Kit.start({ feature, images, groups, variants, draw })。為超過大約六個值的群組提供 section,以便面板摺疊它們。每個群組對應這些值在引擎中的存放位置(腳本類別、主題類型、著色器),每個鍵對應建置時將使用的屬性名稱,使用引擎的單位。draw(ctx, values, s) 必須是 s.t 的純函數(使用 t % length 循環動畫)。
  • 使用遊戲自身的外觀,而不是近似值: 使用其字型和尺寸、主題顏色(新顏色是一個提案:說明它會加入哪個色板)、透過相對路徑使用的真實美術資源、真實文字和數字,以及顯示實際綁定按鍵的提示。
  • 像素藝術:使用完整像素,無平滑處理(套件的預設行為)。
  • 動畫以其真實持續時間和緩動函數運行。任何抖動、漂移、閃爍或閃光的內容,都要在 preview: true 群組中加入「減少動畫」/「減少閃爍」切換開關,顯示這些設定會將其轉變為何種效果。
  • 當調校已存在的元素時,變體 a 應完全按照今日的樣子重新繪製它。請對照基準線截圖進行檢查,直到它們匹配,否則每個其他變體的比較都會基於錯誤的基準線。
  • 多個預覽都會繪製的內容,應放在套件中的一個共用檔案中,而不是每個頁面複製一份。

4. 審閱表

  • python docs/mockups/kit/shots.py <feature>(需要 Chrome、Edge 或 Chromium,以及 Pillow ≥ 10.1)會寫入 shots/<variant>_<state>.png 並拼接成 sheet.png。它使用已儲存的 values.json 作為其變體(--defaults 使用頁面的預設值),如果頁面失敗則以非零狀態碼退出,並將錯誤繪製在該張截圖上。
  • 在展示審閱表之前先仔細檢查;以 2 倍放大倍率裁切正在決策的區域:裁剪或重疊的文字、錯誤的字型、超出舞台範圍的任何內容、停滯在無趣時刻的動畫(調整其 shotTime)。
  • 發送審閱表、即時 URL 和需要做出的決策,並附上你的建議。

5. 讀取調校結果

  • 在他們調校期間,每次變更都會寫入 <feature>/values.draft.json。每當他們詢問你的意見時,可以讀取這個檔案;但絕不要從這個草稿進行建置。
  • 儲存(或 Ctrl/Cmd+S)會寫入 <feature>/values.json,即經批准的規格。頁面隨後會基於此規格開啟:有差異的列會被標記,↺ 按鈕可恢復單一數值,Reset 按鈕可恢復所有數值。僅供預覽的數值永遠不會被標記或儲存。
  • 如果沒有 serve.py,調校結果只存在於瀏覽器中:按下儲存會複製 JSON(並將其保留為該瀏覽器的預設值),人員將其貼到對話中,然後你將其儲存為 values.json。
  • 格式:{"feature", "variant", "values": {Group: {Key: value}}};僅供預覽的群組會被省略。

6. 從規格建置

  • Godot: python docs/mockups/kit/apply_godot.py <feature> 會列出規格在主題 .tres 檔案、每個群組命名的腳本中的 [Export] / @export 預設值、<name>.gdshader 群組的 uniform 預設值、尚無匯出的鍵,以及覆蓋這些屬性的場景中所做的變更。--write 會套用變更。
  • Unity: python docs/mockups/kit/apply_uss.py <feature> 對 USS 自訂屬性(uss: 群組)執行相同操作。ScriptableObject 值則手動套用。
  • Unreal: python docs/mockups/kit/apply_unreal.py <feature> 會列出規格在每個群組的 C++ 類別中所做的變更:Config 類別的 Config/Default<Config>.ini 覆寫(--target header 改為重寫宣告中的預設值)、尚無 UPROPERTY 的鍵(附帶要貼上的宣告),以及需要手動設定的預設值。--write 會套用變更。DataTable 值則透過重新匯入編輯後的匯出檔案來套用。
  • 建置尚不存在的內容:在引擎的主題或樣式系統中建立顏色、字型和面板;將尺寸、偏移、持續時間和強度設定為編輯器可公開的屬性,並按 JSON 分組,以批准的數值作為預設值。
  • 在遊戲運行時進行驗證:為預覽中的每個狀態截取螢幕截圖,並建立 <feature>/build_vs_preview.png,將遊戲截圖與預覽截圖並排顯示。修正任何差異。說明未檢查的項目;瀏覽器和引擎的文字抗鋸齒效果不同,因此請判斷位置和大小,而不是邊緣像素。
  • 之後對已批准外觀的任何變更都是一個新的循環:預覽、審閱表、儲存、建置。

規則

  • 預覽保留在儲存庫中:它們記錄了 UI 為何看起來如此的原因。提交 sheet.png 和 values.json;shots/ 和草稿則會重新產生。
  • 在 values.json 存在之前不得進行建置;絕不從草稿建置。
  • 如果套件缺少預覽所需的內容,請將其加入套件,而不是加入單一頁面。

相關技能