SheetForge — 以試算表驅動的 Unity 資料管線
SheetForge 會將一份試算表（Google 試算表或本機 TSV/CSV/xlsx）轉換為強型別的 C# 類別，以及供遊戲以穩定位址載入的烘焙後 ScriptableObject。
每個儲存格都會在匯入時被驗證。錯誤的值會在你匯入的當下就被攔截，而不是等到執行期第一次讀到該列才發現。並以一句話回報其分頁、列、欄，以及建議的修正方式。這條管線的運作方式就像編譯器：它會在單一輪次中蒐集所有錯誤，並只從一份完全乾淨的試算表組裝出不可變的定義。
試算表永遠是唯一真實來源；烘焙後的 SO 僅是查詢用的快取。圍繞這一點：
- 往返回寫。 匯入有一條反向路徑：匯出／推送會將數值寫回試算表，同時保留其結構。
- 編輯器內編寫。 編輯器內建的一個編寫視窗——Data Studio——可直接編輯試算表，並具備 Ctrl+Z 復原功能。
- 在地化 UI。 產品 UI 支援 10 種語言。
- 透過外掛擴充。 外掛可以在不修改 Core 的前提下新增儲存格型別、驗證規則、圖形邊，以及匯入來源。這道邊界由 C# 編譯器強制把關。
公開 API 本身就是一個編寫核心：第二個編寫介面（例如節點圖畫布）可以完全建構於其上，且無需變更 Core 或 Editor——請參閱編寫核心。
需求：Unity 6 以及 Addressables 套件（com.unity.addressables）——執行期載入是以位址為基礎。此素材在沒有該套件的情況下仍可編譯，但管線會維持鎖定狀態直到套件安裝完成；引導安裝流程請參閱快速上手。
運作方式（概覽）
ENTRANCES TRUTH EXITS
┌───────────────────────────┐ ┌──────────────────┐ ┌───────────────────────────────┐
│ Google Sheets (SheetsApi/ │ │ │ │ Strongly-typed C# classes │
│ ExportUrl) │──▶│ Immutable IR │──▶│ (codegen, last stage) │
│ Local TSV / CSV / xlsx │ │ (Definitions) │ │ Per-tab Database SO (bake) │
│ Data Studio (in-editor │ │ │ │ → Addressables address │
│ authoring, WYSIWYG) │ │ built ONLY if │ │ "SheetForge/{tab}" │
│ Custom source providers │ │ validation is │ │ Export / Push back to the │
│ (plugin, e.g. DB/REST) │ │ 100% clean │ │ sheet (round-trip) │
└───────────────────────────┘ └──────────────────┘ └───────────────────────────────┘每個入口都會產生相同、經過驗證的 IR；每個出口皆由此衍生而來。任何地方只要出現一個錯誤，就完全不會有輸出——不會有部分組裝的結果。
每個錯誤都會告訴你：
- 在哪裡 — 分頁．列．欄字母及欄位名稱
- 是什麼 — 有問題的值
- 為什麼 — 違反的規則
- 怎麼修 — 可執行的建議
這取代了一個團隊原本得為每張表各自撰寫的東西：剖析器、驗證器、程式碼產生器，以及載入路徑。
關鍵數據
- 50,000 列 × 20 欄的匯入作業，在實際運作的編輯器（Mono）中約 628 ms；50 個分頁 × 2,000 列、180k 個參照儲存格約 294 ms。
- 結構化錯誤代碼——一份完整的驗證參考。
- 整個產品 UI（選單、編寫視窗、對話框、報告、工具提示）皆支援 10 種語言。
- 測試套件：由無頭 .NET 測試與 Unity EditMode 測試組成的雙軌測試機制，0 個失敗——確切數量請見功能與限制 ▸ 已驗證狀態。
檔案導覽地圖
| 頁面 | 內容涵蓋範圍 |
|---|---|
| 快速上手 | 需求（Unity 6、Addressables）、安裝、設定、第一次匯入、示範場景 |
| 核心概念 | 試算表 = 唯一真實來源、IR、管線各階段、烘焙後的 SO 作為快取、baseline、自動匯入鏈 |
| 試算表語法 | 標記（@name／@type／@desc／@overlap／@style／@enum/@loc）、完整型別系統、enum 定義試算表、語法規則 |
| Data Studio | 編寫介面——查詢、搜尋、儲存格編輯、結構編輯、記錄畫布、Ctrl+Z、預檢驗證 |
| 來源、匯出與推送 | 本機與 Google 來源、提供者設定、匯出往返流程、推送安全防護、寫入試算表的下拉選單 |
| Google 試算表設定 | 建立服務帳戶與 JSON 金鑰、分享試算表、讓 SheetForge 指向該金鑰 |
| 在地化 | 10 種語言 UI、依使用者設定語言、選單重新產生、新增翻譯 |
| 在地化試算表 | 你遊戲的文字化為一份試算表——@loc 語言欄、LocRef 參照、鍵值常數、Unity Localization StringTable 橋接，以及翻譯工作流程 |
| 外掛開發 | 16 種外掛合約（儲存格型別、驗證器、邊、標記、範本、畫布覆寫、程式碼註冊表、主題、宣告式編寫介面、UI 字串、管線觀察者、來源、Studio 小工具／動作／儲存格編輯器／面板）+ 選用能力，包括讓自訂記法擁有完整參照對等性——以零 Core 修改新增一個領域 |
| 編寫核心 | 在公開引擎 API 之上建構第二個編寫介面（例如圖形畫布） |
| API 參考 | 完整的公開 API 介面——依組件列出每個公開型別 |
| 功能與限制 | 完整列出哪些功能可行、哪些不行，以及原因 |
| 常見問題與疑難排解 | 首次執行與整合過程中的問題，並附上解法 |
| SheetForge Web | 瀏覽器版隨附應用——編譯自相同核心的 WebAssembly，具備編寫／驗證／反射對等性，適用時機 |
| Web 外掛市集 | 從登錄庫安裝外掛（一鍵、雜湊固定）、相容性關卡、以 GitHub URL 側載未經審查的外掛、Unity 內建的市集視窗 |
| Web Google 試算表存取 | 透過你自己的 OAuth，從已部署的網站讀寫 Google 試算表，以及服務帳戶金鑰僅限本機的規則 |
SheetForge Web（隨附應用）
位於 web.sheetforge.workers.dev 的隨附網頁應用，將編寫、驗證與試算表反射能力帶進瀏覽器。
它會將相同的 C# 核心編譯為 WebAssembly——而非重新實作——因此剖析器與驗證器永遠不會偏離 Unity 素材，且以 Unity 建置的外掛 DLL 可原封不動載入。程式碼產生與烘焙仍僅由 Unity 端負責；網頁端的輸出則是反射後的試算表。
上方三個 Web 頁面依序涵蓋這個應用程式、它的外掛市集，以及它的 Google 試算表存取功能。本站的每一條試算表語法規則——包括 IntId@Tab 參照對等性——在瀏覽器中同樣完全成立。
設計原則
- 試算表才是唯一依據。 直接編輯 SO 並不是一種工作流程；所有變更都必須透過試算表並重新匯入驗證。（有一個「測試編輯」切換開關可供暫時性的執行期實驗使用——此類變更絕不會被寫回，且會在重新匯入時消失。）
- 蒐集所有問題，絕不組裝任何有瑕疵的結果。 驗證絕不會在第一個錯誤處就停止，而只要有一個錯誤，就完全不會有輸出——你只需一次修正完整的錯誤清單，而不必陷入「修一個、重新匯入一次」的迴圈。
- 所見即所得的編寫方式。 在 Data Studio 中，你所暫存的每一項變更都會立即以最終呈現的樣貌顯示——新增的欄會出現、刪除的列會消失，而這一切都發生在寫回試算表之前。
- 全自動化。 完成一項編寫操作後，程式碼產生 → 重新編譯 → 烘焙會自動完成，橫跨網域重新載入的過程中，你都不需要再手動觸發任何動作。
- 開放封閉式擴充。 新的儲存格型別、驗證規則、圖形邊與匯入來源，皆透過註冊的方式加入——管線本身永遠不會被修改。
- 已記錄的限制。 產品做不到的事情，會和它能做到的事情一樣被精確記錄下來。請參閱功能與限制。
- 開放資料。 真實資料就是一份純粹的 TSV/CSV/xlsx 檔案，或一份 Google 試算表，任何工具都能讀取。移除 SheetForge 只會移除管線，不會移除你的資料。