貢獻指南

感謝你願意幫忙維護 rd2-wiki（Random Dice 2 骰子樹非官方玩家攻略站）！

這份文件同時是 repo 的貢獻指南，也是網站 /about 頁面的內容來源 ——正本只有這一份，不會有第二份「網站上寫的」版本跟這裡不一致。

如果你不確定用詞，全站與所有資料一律使用「渾沌」這個寫法（遊戲原始資料的正式用字就是如此），不要用發音相近但不同的另一種寫法。

1. 資料正本在哪裡

你能改、也只需要改這兩個地方：

data/dice-tree.svg——整棵骰子樹的節點與連線，共 239 個節點。每個節點是一個 <g class="node">，節點資訊（類型、名稱、解鎖成本、效果說明⋯）都寫在該節點的 data-* 屬性與 <title> 裡。
data/icons/——202 張骰子／符文／被動／支援的圖示 PNG，檔名是內容的 sha256 前 12 碼。

其他東西（src/generated/tree.json、public/assets/）都是 npm run build:data 從上面兩處自動產生出來的建置產物，不要手動編輯、也不會被提交進 repo（在 .gitignore 裡）。你改了 data/dice-tree.svg 之後，本機跑 npm run build:data 或 npm run dev 就會重新產生。

2. 可以用 Inkscape 等 GUI 工具編輯，但送 PR 前一定要先跑一次正規化

data/dice-tree.svg 用 Inkscape、Illustrator 之類的 GUI 向量編輯器直接開來改是可以的，改節點位置、連線、文字都沒問題。

但這類工具在存檔時，習慣會把檔案「重寫」成它們自己偏好的形式，包括：

把單純的位移 translate(x,y) 改寫成更泛用的 matrix(...)
把連線的絕對座標指令（M x y L x y）改成相對座標指令（m dx dy l dx dy）
在節點外面多包一層看不出差異、但結構上多一層的 <g> 圖層群組

這些改變肉眼看起來畫面完全一樣，但會讓 CI 判讀失敗（見下一節規則 0），因為我們的解析器只認「絕對座標、單一位移、沒有多餘巢狀圖層」這種乾淨形式。

所以編輯完、送出 PR 之前，一定要在專案根目錄執行：

npm run normalize

這支腳本會把 GUI 工具重寫出來的形式，攤平回乾淨的正規形式（matrix 還原成 translate、相對座標指令還原成絕對座標、多餘的巢狀圖層拿掉、座標統一取到小數點後兩位）。跑完後再用 git diff 檢查一下改動是否符合預期，才進行提交。

3. 新增圖示：用 `npm run add-icon <path>`，不要自己命名檔案

data/icons/ 裡每張圖的檔名，規則是「內容 sha256 雜湊值的前 12 碼 + .png」，例如 a1b2c3d4e5f6.png。這是為了：同一張圖不管被幾個節點共用都只存一份、換圖時檔名一定會跟著變（不會有「內容換了但檔名沒換，瀏覽器快取吃到舊圖」的問題）。

因此新增或替換圖示時，不要自己手動存檔命名，改用：

npm run add-icon <你的圖片路徑>

它會自動計算雜湊、用正確檔名複製進 data/icons/，並印出這個檔名，你只要把 data/dice-tree.svg 對應節點的 <image href="icons/..."> 指到這個檔名即可。圖片必須是有效 PNG，且最長邊至少 96px（太小會被 CI 擋下，見規則 7）。

4. 送 PR 前建議自己先跑一遍

npm run normalize   # 把 GUI 工具的重寫攤平回正規形式
npm run validate     # 檢查資料本身正確不正確（規則 0–9，見下一節）
npm run build         # 或 npm run build:data；順便檢查組裝後的體積有沒有超出效能預算（規則 11）
npm run test          # 純函式與解析器的單元測試

npm run validate 和 npm run build 檢查的不是同一件事：validate 只讀 data/dice-tree.svg 本身，檢查資料正確不正確；build（或單獨跑 build:data）會先把資料組裝成正式產出的 tree.json，再檢查組裝後的檔案體積有沒有超標。兩個都要跑—— 只跑 validate 不會抓到體積超標的問題，等 CI 才發現就白跑一趟。

如果你動到的是 src/ 底下的前端程式碼（畫布渲染、互動邏輯、版面⋯），而不只是 data/dice-tree.svg 或 data/icons/，送 PR 前也建議跑一次 npm run build && npm run e2e （第一次跑 E2E 前要先執行一次 npx playwright install --with-deps chromium 裝瀏覽器）—— CI 會用獨立的 job 跑同一套 E2E 測試，本機先跑過能提早抓到問題。

5. CI 會擋什麼（白話版）

PR 送出後，CI 會用 npm run validate 檢查 data/dice-tree.svg 本身的正確性（座標與結構一律用瀏覽器同款的 SVG 解析方式判讀，不是用簡單的文字比對，所以看起來「差不多」不代表過得了）。以下任何一條沒過，PR 就會被擋下：

SVG 檔案結構必須是我們認得的乾淨形式：連線只能是「一條直線、絕對座標、附箭頭」；節點只能是「單純位移、沒有多餘圖層」。—— 這條幾乎都是忘記跑 npm run normalize 才會中，錯誤訊息會提醒你。
每個節點的資訊要完整、而且互相對得起來：類型、名稱、解鎖成本、效果說明這些欄位都要填，而且節點上顯示的文字（<title>）跟它的資料屬性（data-*）必須逐字一致，不能一邊寫「造成傷害」另一邊寫「造成損傷」。
每個節點的編號（id）不能重複，而且要符合命名規則（開頭數字代表屬性分支、第二碼代表類型）。
節點外框顏色要跟它的屬性分支對得上：例如粉紫色外框只能用在支援類節點，不能拿去畫骰子。
解鎖成本的寫法要合乎格式：核心與金幣的數字、「最高幾級」之類的字樣，格式必須固定、不能亂寫。
連線兩端要準確接在節點正中央，而且要有箭頭：連線畫歪、沒接到節點中心點，或忘記加箭頭樣式，都會被擋下（座標容許誤差很小，肉眼看起來「差不多對齊」通常不夠）。
整棵樹不能有循環、也不能有孤立節點：不可以出現「A 的前置是 B、B 的前置又繞回 A」這種環，而且除了五個屬性的起手骰之外，每個節點都要能沿著連線往回追到某個起手骰，不能憑空飄在樹外接不到任何東西。
圖示要對得上：節點指到的圖示檔案要存在；圖示檔名（sha256 前 12 碼）要跟檔案實際內容算出來的雜湊一致（也就是前面說的，新增圖示要用 npm run add-icon，不要自己改檔名）；檔案要是合法的 PNG，而且最長邊至少 96px。
效果說明裡的 #關鍵字（例如 #僵硬）必須是白名單裡已經有的詞，白名單在 data/keywords.json。要用新關鍵字，先把詞加進這個檔案。
成長數值的單位前後要一致：像「每級 +2%（最高 +20%）」這種寫法，括號內外的單位要一樣，不能一邊寫 % 一邊寫「秒」。

以上規則 0–9 都是 npm run validate 實際會檢查的內容，本機先跑過一次就能提早抓到，不用等 CI。

規則 11：效能預算（`npm run validate` 不會查，`npm run build` 才會查）

這條不是由 npm run validate 檢查，是 npm run build（或單獨執行 npm run build:data）把資料組裝成正式的 tree.json 與 sprite.webp 之後，順便檢查兩者的體積有沒有超過上限（目前門檻：tree.json 壓縮後不超過 20 KB、sprite.webp 不超過 400 KB）。這個指令執行時會直接印出目前實際用量與距離門檻還剩多少餘裕，例如：

tree.json gzip 17.2 KB / 20 KB，餘裕 2.8 KB
sprite.webp 106.1 KB / 400 KB，餘裕 293.9 KB

這個餘裕平常看起來很寬鬆，但 tree.json 那條其實很緊（目前只剩不到 3 KB，換算大約是再加 40～50 個節點就會超標）——遊戲改版一次加一整個新分支很容易就吃光。所以就算你只是新增幾個節點、沒有動到既有資料，送 PR 前也建議看一眼這行輸出，餘裕快見底了及早跟其他貢獻者提一下，不要等真的超標變成紅燈才發現。

超過門檻的話，npm run build（或 build:data）本身就會印出 ❌ 錯誤訊息並以非 0 狀態結束， CI 的建置步驟也會因此失敗——效果上一樣會擋下 PR，只是踩線的時間點跟 validate 不同。單獨跑 npm run validate 過了，不代表這條也過，送 PR 前記得也跑一次 npm run build（見上一節）。

CI 也會另外跑一次端對端測試（E2E）

除了上面這些資料層級的檢查，CI 還有一個獨立的 job 會把整站建置起來、用真的瀏覽器（Chromium）跑一遍互動流程（點選節點、搜尋篩選、鍵盤操作、手機版面⋯）。這個 job 因為要另外安裝瀏覽器，通常比資料驗證那個 job 慢一些，兩者會平行跑、不互相等待——資料本身有沒有問題，通常很快就能看到結果，不用等瀏覽器裝完。E2E 測試失敗一樣會讓 PR 的 CI 檢查顯示不通過。一般貢獻者如果只是改 data/dice-tree.svg 或 data/icons/，通常不會影響到這個 job；只有動到 src/ 底下前端程式碼時才比較需要留意。

6. 這些情況只會警告、不會擋 PR

以下三種情況，npm run validate 只會印出警告（本機執行時終端機就看得到；CI 上則是在 PR 的 Checks 分頁裡展開「資料驗證」那個步驟的記錄檔才看得到），不會讓 PR 被擋下，也不會另外觸發 PR 留言——只有下一段的規則 10 才會自動貼留言：

節點加了 data-wip="1"（代表「先佔位、之後再接線」），這種節點可以先不接到任何前置節點。
效果說明裡含有 {n} 這種佔位符（代表遊戲原始資料本身還沒填完整數值，不是你的錯，只是提醒）。
新增了圖示、但目前沒有任何節點在用它（可能是準備給下一批節點用的，先警告，不擋）。

另外還有一項提醒不太一樣——它會自動貼在 PR 底下（不只是記錄檔裡才看得到）：

既有節點的 id 若消失或改變：CI 會在 PR 底下自動貼一則「資料差異摘要」留言（規則 10），列出新增／刪除／修改的節點數與全樹解鎖成本的變化，id 若消失還會用 ⚠️ 特別標出來，提醒審核者「分享網址會失效」（骰子樹的分享連結是用 id 組出來的，id 一旦消失，舊的分享連結就打不開了）。這不會擋 PR，只是顯眼地提醒審核者確認這是不是刻意變更；貢獻者若刻意重新編號某個節點，建議在 PR 說明裡順手註明原因，方便審核者判斷。這則留言即使是 fork PR 送出的也一樣會出現，詳見下一節。

7. 關於 fork PR 的重要提醒

如果你是從自己 fork 出來的 repo 送 PR（而不是直接推到這個 repo 的分支），Cloudflare Pages 不會自動幫你的 PR 建立 preview 網址（這是 Cloudflare Pages 對 fork PR 的預設限制），所以你在 PR 底下不會自動看到「這個改動實際長怎樣」的預覽連結。

這種情況下：

npm run validate、單元測試、建置、效能預算、E2E 這些檢查照樣會正常跑在你的 PR 上，不受影響—— GitHub 對 fork PR 只限制「寫入」類的操作（例如自動貼留言），不影響「讀取＋執行檢查」這類操作。
規則 10 的「資料差異摘要」留言也一樣會正常出現：技術上這是靠另一支獨立的 workflow（在本 repo 的情境下執行，而非你 fork 出去那份）讀取檢查結果、貼上留言，繞開了 fork PR 唯讀 token 的限制，所以你不需要做任何額外的事，正常送 PR 即可。
唯一受影響的是 Cloudflare Pages 的視覺預覽：想要看視覺上的預覽，需要請維護者把你的分支拉進本 repo 觸發部署，或是你自己在本機跑 npm run dev 看效果、或截圖貼在 PR 說明裡。

不確定的話，直接在 PR 留言請維護者幫忙看一下即可。

8. 不要上傳遊戲原始資源包本體

data/dice-tree.svg 與 data/icons/ 是我們整理過、拆解出來的必要素材（骰子樹結構、圖示）， 請不要把遊戲客戶端解包出來的完整資源包、聲音檔、模型檔等其他素材放進 PR。這個 repo 只收錄網站呈現骰子樹所需要的最小資料集。

9. 授權說明

這個 repo 的程式碼（Astro 站台、工具腳本、測試等，data/ 目錄以外的所有內容）採 MIT License（repo 根目錄的 LICENSE 檔案）。你送出的程式碼變更、以及對 data/dice-tree.svg／data/icons/ 資料本身的修正貢獻（例如修正錯字、補齊缺漏欄位、更新版本後的數值），都視為對 MIT 授權部分的貢獻，代表你同意以相同條款提供給這個專案使用。
data/ 目錄內的骰子圖示與遊戲效果文字，其著作權屬於原遊戲開發商 111%（111 Percent Inc.），詳見 data/NOTICE.md。這個 repo 只是把官方已公開呈現的遊戲內容，整理成方便查閱的資料結構，不主張這些素材本身的著作權。

再次感謝你願意花時間幫忙維護這份資料，讓其他玩家能更清楚地規劃自己的骰子樹！