SheetForge — конвейер данных на основе таблиц для Unity

SheetForge превращает таблицу (Google Таблицы или локальные TSV/CSV/xlsx) в строго типизированные классы C# и запечённые объекты ScriptableObject, которые ваша игра загружает по стабильному адресу.

Каждая ячейка проверяется при импорте. Некорректное значение отлавливается в момент импорта, а не когда строка впервые встретится во время выполнения. Оно сообщается как предложение с указанием вкладки, строки, столбца и предлагаемого исправления. Конвейер работает как компилятор: он собирает все ошибки за один проход и собирает неизменяемые определения (Definitions) только из полностью чистой таблицы.

Таблица всегда является единственным источником истины; запечённый SO — лишь кеш для поиска. Вокруг этого:

Round-trip. У импорта есть обратный путь: экспорт/отправка записывают значения обратно в таблицу, сохраняя её структуру.
Авторинг в редакторе. Окно авторинга в редакторе — Data Studio — редактирует таблицу с отменой действий через Ctrl+Z.
Локализованный интерфейс. Интерфейс продукта поставляется на 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 столбцов ≈ 628 ms в живом редакторе (Mono); 50 вкладок × 2,000 строк со 180k ячеек-ссылок ≈ 294 ms.
Структурированные коды ошибок — полный справочник по проверкам.
10 языков для всего пользовательского интерфейса продукта (меню, окно авторинга, диалоги, отчёты, подсказки).
Тестовый набор: двойной комплект из headless-тестов .NET и тестов Unity EditMode, 0 провалов — точные значения приведены в разделе Возможности и ограничения ▸ Проверенное состояние.

Карта документации

Страница	Что описывает
Начало работы	Требования (Unity 6, Addressables), установка, настройки, ваш первый импорт, демонстрационная сцена
Основные концепции	Таблица = единственный источник истины, IR, этапы конвейера, запечённый SO как кеш, baseline, автоматическая цепочка импорта
Синтаксис таблиц	Маркеры (`@name`/`@type`/`@desc`/`@overlap`/`@style`/`@enum`/`@loc`), полная система типов, листы определения enum, правила нотации
Data Studio	Поверхность авторинга — просмотр, поиск, редактирование ячеек, правка структуры, холст записи, Ctrl+Z, предварительная проверка
Источники, экспорт и отправка	Локальные и Google-источники, настройки провайдера, round-trip экспорта, защитные механизмы отправки, выпадающие списки, записываемые в таблицу
Настройка Google Таблиц	Создание сервисного аккаунта и JSON-ключа, предоставление доступа к таблице, указание SheetForge на ключ
Локализация	Интерфейс на 10 языках, язык для каждого пользователя, перегенерация меню, добавление переводов
Таблицы локализации	Текст вашей игры в виде таблицы — столбцы языков `@loc`, ссылки `LocRef`, константы ключей, мост StringTable к Unity Localization, рабочие процессы перевода
Создание плагинов	16 контрактов плагинов (типы ячеек, валидаторы, рёбра, маркеры, шаблоны, переопределения холста, реестры кода, темы, декларативные поверхности авторинга, строки интерфейса, наблюдатели конвейера, источники, виджеты/действия/редакторы ячеек/панели Studio) + опциональные возможности, включая полный паритет ссылок для вашей собственной нотации — добавление домена без единой правки Core
Ядро авторинга	Построение второй поверхности авторинга (например, холста графа) на публичном API движка
Справочник по API	Полная публичная поверхность API — все публичные типы, по сборкам
Возможности и ограничения	Полный список того, что работает, что не работает, и почему
Частые вопросы и устранение неполадок	Проблемы первого запуска и интеграции — с исправлениями
SheetForge Web	Браузерный компаньон — то же ядро, скомпилированное в WebAssembly, паритет авторинга/проверки/отражения, когда его стоит использовать
Веб-магазин плагинов	Установка плагинов из реестра (в один клик, с фиксацией по хешу), шлюз совместимости, сайдлоадинг непроверенных плагинов по URL GitHub, окно магазина внутри Unity
Доступ к Google Таблицам из веба	Чтение и запись Google Таблиц с развёрнутого сайта через собственный OAuth и правило «ключ сервисного аккаунта — только локально»

SheetForge Web (компаньон)

Веб-приложение-компаньон на web.sheetforge.workers.dev приносит авторинг, проверку и отражение таблиц в браузер.

Оно компилирует то же самое ядро на C# в WebAssembly — не переписывает его заново, — поэтому парсер и валидатор никогда не разойдутся с ассетом Unity, а собранная в Unity DLL плагина загружается без изменений. Генерация кода и запекание остаются обязанностью только Unity; веб-вывод — это отражённая таблица.

Три веб-страницы выше описывают само приложение, его магазин плагинов и его доступ к Google Таблицам. Каждое правило синтаксиса таблиц с этого сайта — включая паритет ссылок IntId@Tab — действует в браузере точно так же.

Принципы проектирования