Начало работы

Требования

Unity 6 (разработано и протестировано на версии 6000.0.79f1, шаблон URP).
Пакет Addressables (com.unity.addressables) — обязательная зависимость. Загрузка по адресу — это путь времени выполнения, а типу AssetRef@Group нужен Addressables.
- Без пакета ассет всё равно компилируется, потому что весь код, использующий Addressables, находится за версийным define'ом SHEETFORGE_ADDRESSABLES.
- Но конвейер — импорт · экспорт · отправка · запись авторинга обратно — остаётся заблокированным. Каждая точка входа показывает уведомление об установке, а окно «Начало работы» направляет к установке.

Установка Addressables

Основной путь: когда вы импортируете ассет из Asset Store, диалог «Package Manager dependencies» появляется до компиляции — выберите Install, и Addressables установится вместе с ассетом.
Страховочный механизм: если вы нажали Skip (или импортировали вручную), конвейер остаётся заблокированным, а окно «Начало работы» направляет вас к установке через свою строку статуса Addressables. Это окно запускается даже без Addressables, потому что редактор компилируется.
- Ни от чего не зависящее окно-бутстрап SheetForge.Setup тоже обнаруживает отсутствующий пакет при загрузке редактора и показывает уведомление один раз за сессию. Поскольку у него нет зависимостей, оно продолжает работать, даже если другие ошибки компиляции блокируют основные сборки ассета.
Программной установки в один клик нет: правила публикации в Asset Store ограничивают программную установку пакетов, поэтому вместо этого окно лишь направляет вас.
Уведомление отражает реальное состояние установки. Оно объясняет, что продукт прекрасно компилируется, но его функции остаются заблокированными до установки пакета, и после этого указывает на окно «Начало работы». Вы можете открыть его заново в любой момент через Tools ▸ SheetForge ▸ Addressables Setup (этот пункт меню сохраняется, даже если основные сборки не компилируются по какой-то другой причине).

Обновление с предыдущей версии

Импорт .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 не изменился.

Полная таблица того, во что превратился каждый выведенный из употребления контракт, находится в разделе Upgrade notes файла CHANGELOG.md в исходном репозитории (пакет релиза его не поставляет). Выведенные из употребления члены, которые всё ещё компилируются, помечены [Obsolete], а не удалены, поэтому обновление показывает их как предупреждения, а не ломает сборку.

Окно «Начало работы» (начните отсюда)

После установки Addressables окно «Начало работы» открывается автоматически один раз за сессию редактора — при каждом запуске редактора, но не повторно после перезагрузки домена. Так происходит, пока включён переключатель «Показывать это окно при запуске редактора», который по умолчанию включён.

Это рекомендуемая точка входа. Вы можете открыть его заново в любой момент через Tools ▸ SheetForge ▸ Getting Started, а отключить автопоказ можно этим же переключателем внизу (выбор сохраняется для каждого проекта и каждого пользователя).

Оно собирает весь процесс первого запуска в одном месте:

Панель статуса — светофор из трёх строк: установлен ли Addressables, есть ли активный ассет настроек импорта, и выполнен ли первый импорт. Каждая строка показывает ✓ или ✗, и рядом с тем, что ещё требует внимания, стоит кнопка действия (New settings asset либо Выполнить импорт).
Import settings — перечисляет каждый ассет SheetForgeSettings с радиокнопкой для выбора активного, плюс кнопка New settings asset и кнопка Reveal, чтобы найти каждый ассет.
Examples — один клик импортирует пакет Plugin Demo или Core Demo.
Start from a template — выберите один из двух встроенных шаблонов, «from scratch», чтобы определить поля самостоятельно, либо шаблон, зарегистрированный плагином. «Use» открывает панель создания Data Studio, уже заполненную этим шаблоном. Для этого нужен активный ассет настроек с источником, доступным для записи; если у вас его ещё нет, требование показывается явно.
- Встроенные шаблоны — это Пример предмета, который использует только базовые типы, и Enum definitions, который раскладывает лист @enum.
- Вкладки демо-навыка появляются здесь только когда установлен плагин-шаблон, например Plugin Demo.
Run — Выполнить импорт (использует активные настройки) и Открыть Data Studio.
Open Full Guide — ссылка на этот сайт документации.

Разделы ниже подробно объясняют каждый шаг; вы можете делать всё прямо из окна либо через меню и окно Project, как описано.

Ещё быстрее — перетаскивание. Если у вас уже есть папка с файлами таблиц, откройте Data Studio и перетащите эту папку на него — или один файл .tsv/.csv/.xlsx. Оно предложит создать ассет настроек импорта, который читает из этой папки, и сделать его активным — без ручной настройки.

Когда у Studio ещё нет активных настроек, вместо пустой таблицы он показывает панель «Get started» с теми же кнопками создания / импорта демо / «Начала работы».

Проверка состояния. В любой момент откройте Data Studio и выберите ⋯ ▸ Проверка состояния на панели инструментов для быстрой диагностики без обращения к сети. Она сообщает ✓/✗ — каждый пункт с предлагаемым исправлением — для:

активных настроек;
доступности источника (существует ли локальная папка, либо путь к Google id + ключу);
наличия baseline импорта;
актуальности сгенерированного кода, запечённых SO и addressables.

Язык интерфейса. При первом открытии проекта SheetForge устанавливает язык интерфейса из системного языка вашего редактора (девять языков отображаются напрямую; для всех остальных остаётся английский). Он никогда не переопределяет язык, который вы уже выбрали сами; измените его в любой момент в Preferences ▸ SheetForge (см. Локализация).

1. Выбор ассета настроек импорта

Создайте его кнопкой New settings asset в окне «Начало работы», либо щёлкните правой кнопкой мыши в окне Project → Create ▸ SheetForge ▸ Import Settings (подписи меню зависят от вашей настройки языка — см. Локализация).

Вы можете держать несколько ассетов настроек (например, по одному на источник данных) и выбирать, какой из них активен. Меню, Data Studio и импорты — все используют активный. Выбор хранится для каждого проекта и каждого пользователя отдельно (указатель EditorPrefs — никакого шума в VCS, независимо для каждого участника команды), а если активный ассет удалён, указатель самовосстанавливается.

При единственном ассете настроек ваш первый импорт выбирает его автоматически — явный выбор не нужен. Когда существует несколько, выбирайте активный в окне «Начало работы» или из выпадающего списка на панели инструментов Data Studio.

Настройте ассет SheetForgeSettings:

Поле	Значение
Источник (выпадающий список)	Встроенный `LocalFile` (папка с `.tsv`/`.csv`/`.xlsx`) или `GoogleSheet` — обе реализации равноправны и полностью готовы к работе; локальный источник — не «временная ступень». Здесь же появляются пользовательские источники из плагинов (БД/REST и т. д.), если они зарегистрированы. Сохраняется в `sourceProviderId`; если поле пусто, по умолчанию используется встроенный провайдер `LocalFile`.
`localFolderPath`	Режим LocalFile: папка, содержащая файлы таблиц. Сканируются только непосредственные дочерние элементы папки.
`spreadsheetId`	Режим GoogleSheet: ID целевой таблицы (для режима `SheetsApi` требуется аутентификация через сервисный аккаунт).
`bakeOutputFolder`	Куда попадают запечённые Database SO. По умолчанию `Assets/SheetForgeBaked`.
`generatedCodeFolder`	Куда попадают сгенерированные файлы `.cs`. По умолчанию `Assets/SheetForgeGenerated` — намеренно вне `Assets/SheetForge`, чтобы переустановка или перемещение продукта никогда не удаляли ваш сгенерированный код. Проект, который всё ещё генерирует код в старое расположение внутри продукта (`Assets/SheetForge/Runtime/Generated`), сохраняет это расположение, пока оно не опустеет; о переносе рассказывает раздел Обновление с предыдущей версии. Подходит любая папка. Если сгенерированный код ссылается на типы плагина, которые не видны сборке этой папки, импорт автоматически создаёт там сопутствующий `.asmdef`, чтобы связать ссылки (основная сборка runtime остаётся чистой). Обратите внимание: это местоположение — только для новых вкладок. Вкладка, чей сгенерированный тип уже существует где-то ещё (например, в закоммиченной папке `Generated` пакета плагина), перегенерируется на месте, в своём прежнем расположении, а устаревшие дубликаты автоматически удаляются с записью в консоль.
`generatedNamespace`	Пространство имён для сгенерированных типов. Пусто = `SheetForge.Generated`. Задайте уникальное значение (например, `MyGame.Data`), чтобы изолировать свои сгенерированные типы от других пакетов и от встроенного примера.
`exportFolderPath` / `exportFormat`	Папка назначения и формат экспорта (`Tsv` / `Csv` / `Xlsx` / `MatchSource`).

Инспектор настроек показывает только те поля, что относятся к текущему режиму источника — режим Local скрывает поля Google; gidMap появляется только в режиме Google ExportUrl.

2. Безопасность ключа сервисного аккаунта (источник Google)

Используете источник LocalFile? Пропустите этот раздел.

Использование Google Таблиц в режиме SheetsApi требует JSON-ключа сервисного аккаунта. Если вы никогда раньше его не создавали, раздел Настройка Google Таблиц пошагово проведёт вас через весь процесс. Храните этот ключ вне Assets/ и вне вашего репозитория — никогда не коммитьте его.

Рекомендуется: задайте переменную окружения SHEETFORGE_SHEETS_KEY абсолютным путём к вашему файлу ключа. Она имеет приоритет над полем пути к ключу в ассете настроек, так что каждый разработчик подставляет свой локальный ключ, не оставляя никакого пути в репозитории.
Если вам всё же нужно указать путь в поле настроек, указывайте путь вне репозитория (например, C:/keys/service-account.json). Файл ключа внутри Assets/ попадёт в сборки и коммиты.

3. Выполнение первого импорта

Tools ▸ SheetForge ▸ Data Studio, затем нажмите ↓ Pull from source на панели инструментов.

Конвейер получает данные → проверяет → (при успехе) генерирует код → запекает. Диагностика выводится в консоль в виде понятного человеку отчёта на вашем языке.
Первый импорт автоматически завершается в два внутренних этапа. Когда схема новая или изменилась, импорт записывает сгенерированный код, что вызывает компиляцию/перезагрузку домена. Затем он автоматически продолжает запекание после перезагрузки. Одно действие пользователя; повторный запуск вручную не требуется. Если компиляция завершается неудачно, автовозобновление безопасно прерывается (лимит попыток — 3) и оставляет в консоли предложение с конкретным указанием, что делать.
Проверка собирает всю диагностику во время импорта (она никогда не останавливается на первой ошибке). Если существует хотя бы одна ошибка, результат не создаётся (частичная сборка невозможна).
Импорт автоматически регистрирует 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 (только встроенные типы core) — у каждого есть демо-сцена «открыл и нажал Play».

Импорт демо живёт в одном месте — в разделе Examples окна «Начало работы», — поэтому отдельного пункта меню для них нет.

Демо плагина: нажмите Импортировать Plugin Demo в «Начале работы», либо дважды щёлкните Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage. Оба способа восстановят его в Assets/SheetForge.PluginDemo/…. Сцена: Demo/PluginDemo.unity (меню Tools ▸ SheetForge ▸ Open Plugin Demo Scene, добавляется самим примером). Она загружает примерные базы данных по адресу и показывает навык, собранный из данных таблицы (суммарный урон fireball = Damage 10 + DamageOverTime 3×3 = 19).
Демо только на core: нажмите Импортировать Core Demo в «Начале работы», либо дважды щёлкните Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage. Это восстановит его в Assets/SheetForge.CoreDemo/…. Сцена: Demo/CoreDemo.unity (меню Tools ▸ SheetForge ▸ Open Core Demo Scene). Она показывает комплекты снаряжения, собранные из ссылок на предметы, используя только встроенные типы core. В демо также входит лист локализации (ExampleStrings), на ключи которого предметы ссылаются через ячейки LocRef — см. Листы локализации.

(Конечные подписи этих примерных пунктов меню — на английском, так как они находятся вне основного локализованного конвейера меню.)

Каждый демо-пакет содержит предварительно настроенный ассет настроек. При импорте демо-пакета SheetForge автоматически активирует этот встроенный ассет настроек только если у вас ещё нет собственных активных настроек. Если он у вас уже есть, вместо молчаливой перезаписи вашего выбора открывается окно «Начало работы» с предложением переключиться. Так что весь процесс демо сводится к: импортировать пакет → (настройки активируются автоматически) → Выполнить импорт → Play — без ручного создания настроек.

Демо работает только после выполнения одного импорта на вашей машине — адреса Addressables, которые оно загружает, существуют только после того, как импорт был выполнен хотя бы раз (ассет группы Addressables — это некоммитящийся, самовосстанавливающийся кеш). До этого демо-сцена вместо ошибки показывает сообщение с рекомендациями.

Чтобы завершить демо (после импорта примерного пакета выше):

Убедитесь, что встроенный ассет настроек демо активен (окно «Начало работы» показывает его, либо импорт активировал его автоматически). Он использует source = LocalFile, локальная папка = папка DemoSheets из примера, и пространство имён по умолчанию SheetForge.Generated, так что повторный импорт перегенерирует закоммиченные типы на месте.
Для ссылки на скрипт демо плагина никаких действий не требуется. Вкладка ExampleEffects содержит пример AssetRef@Scripts. Сам пример самостоятельно и идемпотентно регистрирует DemoScripts/special_effect.lua.txt под адресом special_effect в группе Addressables Scripts, так что первый импорт проходит проверку ссылок. Добавлять эту запись вручную нужно, только если он выведет предупреждение о том, что не смог этого сделать (например, из-за отсутствующего ассета), — либо удалите эту строку, если пример с Addressables вам не нужен.
Нажмите ↓ Pull from source в Tools ▸ SheetForge ▸ Data Studio один раз (либо кнопку Выполнить импорт в «Начале работы»), затем откройте демо-сцену и нажмите Play.

6. Командный процесс работы — кратко

Запечённые SO (Assets/SheetForgeBaked) — это локальный для каждой машины кеш. Добавьте их в gitignore; после клонирования каждый участник команды один раз нажимает Выполнить импорт.
Сгенерированный код (Assets/SheetForgeGenerated) — это собственный исходный код вашего проекта, и рекомендуется его коммитить. Тогда свежий клон компилируется ещё до того, как кто-либо выполнит импорт, а изменения схемы видны прямо в ревью. Это детерминированный результат, поэтому импорт у коллеги даёт точно такие же байты и не создаёт лишнего шума. Исключить его через gitignore вместо этого тоже работает — тогда именно Выполнить импорт после клонирования восстанавливает компилируемость.
Хук проверки актуальности перед сборкой для каждого закоммиченного сгенерированного типа Database проверяет: (i) существует ли запечённый SO, (ii) совпадает ли отпечаток схемы с baseline, (iii) существует ли регистрация в Addressables. Если что-то из этого не выполняется, сборка прерывается с предложением конкретных действий, поэтому клонированная машина или CI никогда не смогут молча отправить в сборку пустой кеш.