快速上手

需求

• Unity 6（開發與測試版本為 6000.0.79f1，URP 範本）。
• Addressables 套件（com.unity.addressables）——必要套件。 位址載入是執行期的核心路徑，且 AssetRef@Group 型別需要 Addressables。
  • 沒有這個套件，此素材依然可以編譯，因為所有使用 Addressables 的程式碼都藏在一個 SHEETFORGE_ADDRESSABLES 版本定義之後。
  • 但管線——匯入．匯出．推送．編寫寫回——會維持鎖定狀態。每個進入點都會顯示安裝提示，而入門視窗會引導你完成安裝。

安裝 Addressables

• 主要途徑：當你從 Asset Store 匯入此素材時，「套件管理員相依套件」提示視窗會在編譯之前出現——選擇安裝，即可一併安裝 Addressables。
• 安全網：如果你按下了 Skip（或手動匯入），管線會維持鎖定狀態，而入門視窗會透過其 Addressables 狀態列引導你完成安裝。即使沒有 Addressables，該視窗依然會照常執行，因為 Editor 依然能夠編譯。
  • 不具相依性的 SheetForge.Setup 啟動視窗，同樣會在編輯器載入時偵測缺少的套件，並在每個工作階段顯示一次提示。因為它沒有任何相依套件，即使其他編譯錯誤擋住了主要組件，它依然能持續運作。
• 沒有一鍵式的程式化安裝：Asset Store 的上架規則限制了程式化套件安裝，因此改由指引視窗帶你完成安裝。
• 該提示會反映真實的安裝狀態，說明產品本身能正常編譯、但其功能會在套件安裝完成前維持鎖定，並在之後指引你前往入門視窗。你隨時都能從 Tools ▸ SheetForge ▸ Addressables 設定 重新開啟它（即使主要組件因其他原因編譯失敗，這個選單依然可以正常使用）。

從舊版升級

匯入 .unitypackage 時只會新增與更新檔案，絕不會刪除檔案。因此，新版本已淘汰的檔案可能會殘留在 Assets/SheetForge 中，繼續參照一個已不存在的 API——導致編譯失敗，看起來就像是這次升級把你的專案弄壞了。有兩道安全網可以應付這種情況：

• 自動偵測。 編輯器載入時，不具相依性的 SheetForge.Setup 啟動組件會檢查此產品已淘汰的路徑；如果找到任何殘留，就會主動提議刪除——對話框會先列出每一條路徑，在你核准之前不會碰觸任何內容。它之所以位於自己獨立的組件中，正是為了能在自身存在的目的——修正編譯錯誤——本身發生的當下依然存活。
• 從乾淨狀態開始。 若要確保升級完全乾淨，先刪除既有的 Assets/SheetForge 資料夾，匯入新套件，接著執行一次執行匯入，把刪除動作一併帶走的內容重新建出來。設定資源與烘焙後的 SO（Assets/SheetForgeBaked）都位於該資料夾之外，不受影響；產生的程式碼只要落在預設位置 Assets/SheetForgeGenerated，同樣不受影響。若你的專案先前仍在舊有的產品內部位置（Assets/SheetForge/Runtime/Generated）產生程式碼，刪除該資料夾會連同那些程式碼一併清除，重新匯入則會改將程式碼寫入 Assets/SheetForgeGenerated。這正是將既有專案遷移到新位置的官方支援做法。任何重新匯入都無法復原的，只有你自己放進 Assets/SheetForge 裡的內容（例如存放在那裡的設定資源、你自己的外掛指令碼、試算表檔案），因此只需要先把這些移到別處即可。

有一項邊界值得明確說明：自動清理只會刪除 SheetForge 自身已淘汰的檔案，絕不會動到你的檔案。如果你自己的外掛程式碼實作了一個後來被淘汰的合約，就必須手動移植。簡言之：

• 逐分頁的圖形建構器（IGraphShapeBuilder / GraphSpecBuilder）現在變成了記錄畫布的擴增器（IRecordCanvasAugmenter / CanvasAugmentBuilder）——它是在畫布已組裝完成的封閉集合之上進行擴增，而不是自行建構整幅畫面；
• GraphMode 已經消失，因為方向現在改由畫布自行控制；
• StudioGraphContext.ShapeId / ModeId 雖然仍可編譯，但兩者各自都只會回傳一個常數值，因此任何拿它們來比對的 AppliesTo 判斷式都應該直接刪除；
• IAuthorableGraphShape.CreatableTabs 則未受影響。

每個已淘汰合約各自變成了什麼，完整對照表列於原始碼儲存庫中的 CHANGELOG.md（發行套件並不隨附此檔案）的升級注意事項章節。仍可編譯的已淘汰成員會標示為 [Obsolete] 而非直接移除，因此升級時只會顯示為警告，而不會導致建置失敗。

入門視窗（從這裡開始）

安裝好 Addressables 之後，只要**「編輯器啟動時顯示此視窗」這個切換開關維持開啟狀態（預設即為開啟），入門視窗就會每個編輯器工作階段自動開啟一次**——也就是每次 Editor 啟動時都會開啟，但網域重新載入後不會再次出現。

這是建議的進入點。你可以隨時從 Tools ▸ SheetForge ▸ 入門 重新開啟它，並透過底部的這個切換開關關閉自動開啟功能（此選擇會依專案與使用者各別儲存）。

它將整個首次執行流程集中在同一個地方：

1. 狀態儀表板——一個三列式的紅綠燈：Addressables 是否已安裝、是否有使用中的匯入設定資源，以及是否已完成首次匯入。每一列都會顯示 ✓ 或 ✗，任何仍需處理的項目旁邊都會附上一個對應的動作按鈕（新增設定資源，或執行匯入）。
2. 匯入設定——列出每一個 SheetForgeSettings 資源，並提供單選按鈕以選擇使用中的那一個，另附新增設定資源按鈕，以及可定位各資源所在位置的顯示按鈕。
3. 範例——一鍵匯入外掛示範或核心示範套件。
4. 從範本開始——挑選兩個內建範本之一，選擇「從零開始」自行定義欄位，或使用外掛註冊的範本。按下「使用」即可開啟 Data Studio 的建立面板，並預先填入該範本內容。此功能需要一個具有可寫入來源的使用中設定資源；若你尚未建立，此需求會被明確顯示出來。
   • 兩個內建範本分別是僅使用核心型別的物品範例，以及會排出一份 @enum 試算表的 Enum definitions。
   • 技能示範分頁僅在有範本外掛存在時才會出現，例如外掛示範。
5. 執行——執行匯入（使用目前的使用中設定）以及開啟 Data Studio。
6. 開啟完整指南——連結到本說明網站。

以下各節會詳細說明每個步驟；你可以完全透過此視窗完成所有操作，也可以依照本文所述，透過選單與 Project 視窗來進行。

更快速的做法——拖放。 如果你已經有一個存放試算表檔案的資料夾，請開啟 Data Studio，然後將該資料夾——或單一 .tsv／.csv／.xlsx 檔案——拖放到其上。它會主動提議建立一個讀取該資料夾的匯入設定資源，並將其設為使用中，完全不需要手動設定。

在沒有使用中設定的狀態下開啟時，Studio 會顯示一個**「開始使用」**面板，提供與入門視窗相同的建立／匯入示範／前往入門等按鈕，取代原本的空白表格。

健康檢查。 你隨時都可以開啟 Data Studio，並從工具列中選擇 ⋯ ▸ 健康檢查，進行一次快速、無需連網的診斷。它會回報 ✓／✗——每一項都附上建議的修正方式——內容涵蓋：

• 使用中設定
• 來源是否可存取（本機資料夾是否存在，或 Google id ＋ 金鑰路徑）
• 是否已有匯入 baseline
• 產生的程式碼、烘焙後的 SO 與 Addressables 是否為最新

UI 語言。 第一次開啟專案時，SheetForge 會依你編輯器的系統語言設定其 UI 語言（九種語言可直接對應；其餘一律維持英文）。它絕不會覆寫你已選擇過的語言；你可以隨時在 Preferences ▸ SheetForge 中變更（請參閱在地化）。

1. 選擇匯入設定資源

你可以透過入門視窗的新增設定資源按鈕來建立一個，或是在 Project 視窗中按右鍵 → Create ▸ SheetForge ▸ 匯入設定（選單標籤會依你的語言設定而異——請參閱在地化）。

你可以同時保留多個設定資源（例如每個資料來源各建立一個），並選擇其中哪一個是使用中的。選單、Data Studio 與匯入作業全都會使用目前的使用中設定。此選擇會依專案與使用者各別儲存（一個 EditorPrefs 指標——不會造成 VCS 異動，每位隊友各自獨立），若使用中的資源被刪除，此指標會自動修復。

只有單一設定資源時，你的第一次匯入會自動選定它——不需要明確選擇。當存在多個設定資源時，可在入門視窗或 Data Studio 工具列出現的下拉選單中選擇使用中的那一個。

接著設定 SheetForgeSettings 資源：

設定檢閱器只會顯示與目前來源模式相關的欄位——本機模式會隱藏 Google 相關輸入欄；gidMap 僅會在 Google ExportUrl 模式下出現。

2. 服務帳戶金鑰安全性（Google 來源）

如果你使用的是 LocalFile 來源？可以略過本節。

在 SheetsApi 模式下使用 Google 試算表，需要一組服務帳戶 JSON 金鑰。如果你從未建立過，Google 試算表設定會逐步說明整個流程。請將此金鑰放在 Assets/ 之外，也放在你的儲存庫之外——絕對不要提交它。

• 建議做法：將環境變數 SHEETFORGE_SHEETS_KEY 設定為你金鑰檔案的絕對路徑。此設定的優先權高於設定資源中的金鑰路徑欄位，因此每位開發者都能注入自己的本機金鑰，而不會在儲存庫中留下任何路徑。
• 如果你必須在設定欄位中填入路徑，請指向儲存庫之外的位置（例如 C:/keys/service-account.json）。放在 Assets/ 底下的金鑰檔案會外洩進建置產物與提交紀錄中。

3. 執行你的第一次匯入

Tools ▸ SheetForge ▸ Data Studio，接著在工具列中按下 ↓ Pull from source。

• 此管線會依序執行：擷取 → 驗證 →（成功後）產生程式碼 → 烘焙。診斷資訊會以你所設定語言的易讀報告形式顯示於 Console。
• 第一次匯入會自動分成兩個內部階段完成：當結構描述是新的或有變動時，匯入會先寫入產生的程式碼，進而觸發編譯／網域重新載入——重新載入完成後便會自動接續完成烘焙。使用者只需執行一次動作，無需手動再次觸發。若編譯失敗，自動接續程序會安全中止（重試上限為 3 次），並在 Console 留下一句可據以行動的說明。
• 驗證會在匯入時蒐集所有診斷資訊（絕不會在第一個錯誤處就停止）。只要存在一個錯誤，就不會產生任何輸出（不會有部分組裝的結果）。
• 匯入會自動將每個分頁的 Database SO 註冊到 Addressables 群組 SheetForge 中，位址為 "SheetForge/{tab}"——你的遊戲即可透過這個穩定位址載入（請參閱核心概念）。

4. 在你的遊戲中載入資料

using SheetForge.Runtime;
using UnityEngine.ResourceManagement.AsyncOperations;
 
AsyncOperationHandle<DefinitionDatabase> handle = SheetForgeDatabases.LoadAsync("Items");
await handle.Task;   // or coroutine yield / handle.WaitForCompletion()
if (handle.Status == AsyncOperationStatus.Succeeded)
{
    DefinitionDatabase db = handle.Result;
    // For strong typing: SheetForgeDatabases.LoadAsync<ItemsDatabase>("Items")
}
SheetForgeDatabases.Release(handle);   // Addressables is ref-counted — release what you load

SheetForge.Runtime 組件為 autoReferenced，因此遊戲程式碼無需 asmdef 參照即可使用它。

絕對不要讓場景直接參照烘焙後的 SO。 烘焙後的 SO 屬於未提交、依機器而異的快取——它們的 GUID 會因機器與每次重新烘焙而不同，因此直接的場景參照會在隊友的機器上變成 Missing（遺失）。透過位址載入即可從設計上避免此問題。

5. 試用示範場景

有兩個範例以可選擇匯入的套件形式提供：外掛範例 SheetForge.PluginDemo（自訂型別、enum、驗證器、邊）與不含外掛的 SheetForge.CoreDemo（僅使用核心內建型別），兩者都各自附有一個「開啟即可 Play」的示範場景。

示範匯入只存在於一個地方——入門視窗的範例區塊——因此不再有對應的選單項目。

• 外掛示範：在入門視窗中按下匯入 Plugin Demo，或雙擊 Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage——兩種方式都會將其還原至 Assets/SheetForge.PluginDemo/… 底下。場景：Demo/PluginDemo.unity（選單 Tools ▸ SheetForge ▸ Open Plugin Demo Scene，由範例本身新增）。此場景會依位址載入範例資料庫，並顯示一個由試算表資料組裝而成的技能（火球術總傷害 = Damage 10 + DamageOverTime 3×3 = 19）。
• 純核心示範：在入門視窗中按下匯入 Core Demo，或雙擊 Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage——會將其還原至 Assets/SheetForge.CoreDemo/… 底下。場景：Demo/CoreDemo.unity（選單 Tools ▸ SheetForge ▸ Open Core Demo Scene）。此場景會顯示僅使用核心內建型別、由物品參照組裝而成的裝備組合。此示範也包含一張本地化表（ExampleStrings），物品透過 LocRef 儲存格參照其中的鍵值——參見本地化表。

（這些示範場景選單的葉節點標籤為英文，因為它們位於核心在地化選單流程之外。）

每個示範套件都內含一個預先設定好的設定資源。 匯入示範套件時，只要你尚未擁有自己的使用中設定，SheetForge 就會自動啟用該內含的設定資源（若你已經有使用中設定，則會改為開啟入門視窗，建議你切換，而不會靜默地覆寫你的選擇）。因此示範流程非常簡單：匯入套件 →（設定資源自動啟用）→ 執行匯入 → Play——完全不需要手動建立設定。

示範必須在你的機器上執行過一次匯入後才能正常運作——它所載入的 Addressables 位址，只有在匯入執行過一次之後才會存在（Addressables 群組資源屬於未提交、可自我修復的快取）。在那之前，示範場景會顯示指引訊息，而不會直接失敗。

若要完成示範設定（在完成上述範例套件匯入之後）：

1. 確認示範內含的設定資源已是使用中狀態（入門視窗會顯示它，或者匯入時已自動啟用它）。它使用來源 = LocalFile，本機資料夾 = 範例的 DemoSheets 資料夾，並使用預設的 SheetForge.Generated 命名空間，因此重新匯入會原地重新產生已提交的型別。
2. 外掛示範的指令碼參照無需任何動作。 ExampleEffects 分頁包含一個 AssetRef@Scripts 範例，而範例本身會自動、冪等地將 DemoScripts/special_effect.lua.txt 註冊到一個 Scripts Addressables 群組中、位址為 special_effect，因此第一次匯入就會通過參照驗證。只有在它記錄了一則「無法完成此動作」的警告時（例如資源遺失），你才需要手動新增該項目——或者，如果你不想要這個 Addressables 範例，也可以直接刪除該列。
3. 在 Tools ▸ SheetForge ▸ Data Studio 中按一次 ↓ Pull from source（或入門視窗中的執行匯入按鈕），接著開啟示範場景並按下 Play。

6. 團隊工作流程摘要

• 烘焙後的 SO（Assets/SheetForgeBaked）是依機器而異的快取。請將它加入 gitignore；複製（clone）儲存庫後，每位隊友只需執行一次執行匯入。
• 產生的程式碼（Assets/SheetForgeGenerated）是你專案自己的原始碼，建議將其提交。如此一來，新複製的儲存庫在任何人執行匯入之前就能編譯，結構描述的變動也會直接顯示在審閱中。它是確定性（deterministic）輸出，因此隊友的匯入會產生完全相同的位元組，不會造成多餘的差異雜訊。改以 gitignore 排除它同樣可行——此時複製後的執行匯入就是用來恢復編譯的手段。
• 一個**建置前新鮮度掛勾（pre-build freshness hook）**會針對每個已提交的產生 Database 型別，檢查：(i) 烘焙後的 SO 是否存在、(ii) 結構描述指紋是否與 baseline 相符、(iii) Addressables 註冊是否存在。只要有任何一項失敗，建置就會中止並提供一句可據以行動的說明，因此複製下來的機器或 CI 機器絕不會在無聲無息中發布一個空的快取。

相關頁面

• 核心概念——為什麼試算表具有權威性，以及管線各階段是什麼
• 試算表語法——如何寫出你的第一份試算表
• 來源、匯出與推送——Google 設定細節
• 常見問題與疑難排解——首次執行時的問題