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存在之前不得進行建置;絕不從草稿建置。 - 如果套件缺少預覽所需的內容,請將其加入套件,而不是加入單一頁面。