SheetForge — 面向 Unity 的工作表驱动数据管线

SheetForge 会把一张工作表(Google表格或本地 TSV/CSV/xlsx)转换成强类型的 C# 类,以及供你的游戏按稳定地址加载的烘焙 ScriptableObject。

每个单元格都会在导入时被校验。错误的值会在你导入的那一刻就被发现,而不是等到运行时首次命中该行才暴露。诊断信息会以一句话的形式给出,并标明其所在的标签页、行、列,以及一个建议的修复方法。这套管线的运作方式就像编译器:它会一次性收集所有错误,只有在工作表完全干净的情况下才会组装出不可变的 Definitions。

工作表始终是唯一真实来源;烘焙出的 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，每个出口都由它派生而来。任何地方出现一个错误，都意味着完全没有输出——不会有部分组装的结果。

每个错误都会告诉你:

在哪里——标签页·行·列字母及字段名
是什么——出问题的值
为什么——违反的规则
怎么办——可执行的修复建议

这取代了团队原本需要为每张表分别编写的东西：解析器、验证器、代码生成器，以及加载路径。

关键数据

在实时编辑器中（Mono）导入 50,000 行 × 20 列 ≈ 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`）、完整的类型系统、枚举定义表、书写规则
Data Studio	创作界面——查找、搜索、单元格编辑、结构编辑、记录画布、Ctrl+Z、预检验证
数据源、导出与推送	本地与 Google 来源、提供方设置、导出往返、推送安全防护、写入工作表的下拉列表
Google表格设置	创建服务账号与 JSON 密钥、共享工作表、让 SheetForge 指向该密钥
本地化	10 语言 UI、按用户设置的语言、菜单再生成、添加翻译
本地化表格	把游戏文本当作一张工作表来管理——`@loc` 语言列、`LocRef` 引用、键常量、Unity Localization StringTable 桥接，以及翻译工作流
插件开发	16 种插件契约（单元格类型、验证器、边、标记、模板、画布覆盖、代码注册表、主题、声明式创作界面、UI 字符串、管线观察者、来源、Studio 部件/操作/单元格编辑器/面板）+ 可选启用的 capability，包括为你自己的表示法提供完整的引用对等性——零 Core 改动即可新增一个领域
创作内核	在公共引擎 API 之上构建第二个创作界面（例如图形画布）
API 参考	完整的公共 API 表面——按程序集列出每个公共类型
功能与限制	哪些能做、哪些不能做、以及原因的完整清单
常见问题与故障排查	首次运行问题与集成问题，附带修复方法
SheetForge Web	浏览器配套应用——编译为 WebAssembly 的同一套核心，创作/验证/反射能力对等，以及何时该用它
Web 插件市场	从注册表安装插件（一键安装、哈希锁定）、兼容性门禁、通过 GitHub URL 旁加载未经审核的插件、Unity 内的市场窗口
Web Google表格访问	通过你自己的 OAuth，从已部署的站点读写 Google表格，以及仅限本地的服务账号密钥规则

SheetForge Web（配套应用）

配套的 Web 应用位于 web.sheetforge.workers.dev，把创作、验证与工作表反射带到浏览器中。

它编译的是同一套 C# 核心到 WebAssembly——而不是另一份重新实现——因此解析器与验证器永远不会与 Unity 版资源产生偏差，而且 Unity 构建的插件 DLL 可以原样加载。代码生成与烘焙仍然只属于 Unity 的职责；Web 端的输出是反射后的工作表。

上面这三个 Web 页面分别覆盖该应用本身、它的插件市场，以及它的 Google表格访问。本站的每一条表格语法规则——包括 IntId@Tab 的引用对等性——在浏览器中都同样成立。

设计原则