SheetForge — Sheet-Driven Data Pipeline for Unity

SheetForge turns a spreadsheet (Google Sheets or local TSV/CSV/xlsx) into strongly-typed C# classes and baked ScriptableObjects your game loads by stable address.

Every cell is validated at import. A bad value is caught when you import, not when the row is first hit at runtime. It is reported as a sentence with its tab, row, column, and a suggested fix. The pipeline works like a compiler: it collects all errors in one pass and assembles the immutable Definitions only from a fully clean sheet.

The sheet is always the single source of truth; the baked SO is only a lookup cache. Around that:

• Round-trip. Import has a reverse path: Export/Push writes values back into the sheet while preserving its structure.
• In-editor authoring. An in-editor authoring window — the Data Studio — edits the sheet with Ctrl+Z undo.
• Localized UI. The product UI ships in 10 languages.
• Extension by plugin. Plugins add cell types, validation rules, graph edges, and import sources without editing Core. The boundary is enforced by the C# compiler.

The public API is an authoring kernel: a second authoring surface, such as a node-graph canvas, can be built on it with zero Core or Editor changes — see Authoring Kernel.

Requirements: Unity 6 and the Addressables package (com.unity.addressables) — runtime loading is address-based. The asset compiles without the package, but the pipeline stays locked until it is installed. Getting Started covers the guided install.

How it works (at a glance)

              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)          │
  └───────────────────────────┘   └──────────────────┘   └───────────────────────────────┘

Every entrance produces the same validated IR, and every exit is derived from it. One error anywhere means no output at all — no partial assembly.

Every error tells you:

• where — tab · row · column letter and field name
• what — the offending value
• why — the violated rule
• how — an actionable suggestion

This replaces what a team otherwise writes per table: the parser, the validator, the code generator, and the loading path.

Key numbers

• 50,000 rows × 20 columns import ≈ 628 ms in the live editor (Mono); 50 tabs × 2,000 rows with 180k reference cells ≈ 294 ms.
• Structured error codes — a complete validation reference.
• 10 languages for the whole product UI (menus, the authoring window, dialogs, reports, tooltips).
• Test suite: a dual harness of headless .NET tests plus Unity EditMode tests, 0 failures — the exact counts are in Capabilities & Limits ▸ Verified state.

Documentation map

SheetForge Web (companion)

A companion web app at web.sheetforge.workers.dev brings authoring, validation and sheet-reflection to the browser.

It compiles the same C# core to WebAssembly — not a re-implementation — so the parser and validator can never drift from the Unity asset, and a Unity-built plugin DLL loads unmodified. Codegen and baking stay a Unity-only responsibility; the web output is the reflected sheet.

The three web pages above cover the app, its plugin market, and its Google Sheets access. Every sheet-syntax rule on this site — including IntId@Tab reference parity — holds identically in the browser.

Design principles

1. The sheet is canonical. Direct SO editing is not a workflow. Everything goes through the sheet and re-import validation. (A "test edit" toggle exists for temporary runtime experiments — it is never written back and disappears on re-import.)
2. Collect everything, assemble nothing broken. Validation never stops at the first error, and one error means no output. You fix a complete list once, instead of a fix-one-reimport loop.
3. WYSIWYG authoring. In the Data Studio, everything you stage is immediately visible exactly as it will land: added columns appear and deleted rows vanish before you ever write to the sheet.
4. Fully automatic. After an authoring action, codegen → recompile → bake completes without you re-triggering anything, across the domain reload.
5. Open-closed extension. New cell types, validation rules, graph edges, and import sources join by registration; the pipeline itself is never modified.
6. Documented limits. What the product cannot do is documented as precisely as what it can. See Capabilities & Limits.
7. Open data. The truth is a plain TSV/CSV/xlsx file or a Google sheet, readable by any tool. Removing SheetForge removes the pipeline, not your data.

Related pages

• Start here: Getting Started
• Understand the model: Core Concepts