Частые вопросы и устранение неполадок

Ответы, построенные от симптома. Каждая ошибка импорта также несёт собственное предложение где/что/почему/как в отчёте консоли — начните оттуда.

Настройка и первый запуск

«Я импортировал ассет без Addressables — он компилируется? Почему импорт заблокирован?»

Ассет компилируется без Addressables: код, использующий Addressables, защищён версийным define'ом SHEETFORGE_ADDRESSABLES. Загрузка по адресу и тип AssetRef@Group всё равно нуждаются в com.unity.addressables, поэтому весь конвейер (импорт · экспорт · отправка · запись обратно) заблокирован, пока вы его не установите. Каждая точка входа показывает уведомление об установке и останавливается — никакого частичного запуска.

Установите com.unity.addressables через Package Manager. Строка Addressables в окне «Начало работы» содержит кнопку Открыть Package Manager, и это окно работает как обычно, а не блокируется Safe Mode, поскольку редактор компилируется без пакета.

Если после установки ошибки компиляции остаются, они связаны с другим кодом проекта — SheetForge компилируется как с пакетом, так и без него.

«Я обновился до более новой версии, и теперь проект не компилируется.»

Импорт .unitypackage добавляет и обновляет файлы, но никогда их не удаляет. Поэтому файл, который этот продукт вывел из употребления в более поздней версии, может задержаться и ссылаться на API, которого больше не существует.

При загрузке редактора ни от чего не зависящий бутстрап SheetForge.Setup обнаруживает эти известные выведенные из употребления пути и предлагает их удалить, перечисляя все пути прежде, чем что-либо трогать. Подтвердите диалог, и компиляция восстановится. Поскольку он живёт в собственной сборке, он продолжает работать, пока основные сборки не компилируются. Чтобы вообще пропустить этот диалог, удалите папку Assets/SheetForge перед импортом нового пакета.

Чего это не покрывает, так это ваш собственный код, написанный против контракта, который с тех пор был выведен из употребления. Портируйте его вручную, используя таблицу Upgrade notes в CHANGELOG.md в исходном репозитории — пакет релиза этот файл не поставляет — а Начало работы резюмирует, что там написано.

«В Create Sheet есть только встроенные шаблоны — где шаблон демо-навыков? / Как добавить свой собственный?»

Встроенный список Create Sheet поставляется с двумя шаблонами плюс вариантом «с нуля»: Пример предмета (только базовые типы) и Enum definitions, который раскладывает лист @enum.

Доменные шаблоны, которым нужен плагин (например, демо навыков), регистрируются самим этим плагином, поэтому появляются только когда плагин присутствует. Импортируйте пакет Plugin Demo, и его шаблон Skill demo появится. Чтобы поставить свой собственный, реализуйте ISheetForgeTemplatePlugin — см. Создание плагинов §4.6.

«С чего начать? / При открытии редактора постоянно открывается окно.»

Это окно «Начало работы». Оно открывается автоматически при первой загрузке редактора и является рекомендуемой точкой входа: статус Addressables, выбор активного ассета настроек, импорт примера и запуск первого импорта, всё в одном месте.

Отключите автопоказ переключателем «Показывать это окно при запуске редактора» внизу и откройте его заново в любой момент через Tools ▸ SheetForge ▸ Getting Started.

«Я импортировал демо-пакет, но ничего не происходит — нет ассета настроек и нет группы addressable»

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

Затем один раз нажмите ↓ Pull from source в Tools ▸ SheetForge ▸ Data Studio: это автоматически создаст группу addressable и адреса для каждой вкладки. Процесс: импортировать пакет → (настройки активируются автоматически) → Выполнить импорт → Play.

«Демонстрационная сцена вместо демо показывает лишь текстовое сообщение»

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

(Закоммиченные типы демо используют пространство имён по умолчанию SheetForge.Generated, так что никакая настройка generatedNamespace не нужна — повторный импорт перегенерирует их на месте.)

«Первый импорт демо плагина завершается ошибкой `UnknownAssetGroup 'Scripts'`»

В демо плагина есть столбец script типа List<AssetRef@Scripts>, для которого нужна группа Addressables с именем Scripts. Группы Addressables локальны для каждой машины (не коммитятся), поэтому у только что импортированного демо её ещё нет.

Демо автоматически настраивает эту группу при импорте (PluginDemoAddressableSetup, срабатывает при перезагрузке домена и при открытии демо-сцены), так что обычный импорт просто работает. Если ошибка всё же появляется, заново откройте демо-сцену (Tools ▸ SheetForge ▸ Open Plugin Demo Scene), чтобы запустить настройку, затем выполните повторный импорт.

Это касается только демо плагина — свои собственные группы AssetRef@… вы регистрируете сами.

«Какой ассет настроек используется, если у меня их несколько?»

Активный. Меню, окна авторинга и импорты — все используют активный ассет настроек. Выберите его в окне «Начало работы» или в выпадающем списке на панели инструментов Data Studio (показывается только когда их несколько).

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

«У меня уже есть папка с таблицами — как быстрее всего указать на неё SheetForge?»

Откройте окно Workbench и перетащите папку на него, или один файл .tsv/.csv/.xlsx. У Workbench нет собственного пункта меню, поэтому используйте кнопку «Use» в галерее шаблонов окна «Начало работы», чтобы открыть его.

Оно предложит создать ассет настроек импорта, который читает из этой папки, и сделать его активным — без ручного заполнения полей. Если у вас уже есть активные настройки, диалог сообщает об этом и предлагает переключиться. (Обработчик перетаскивания есть только у Workbench; Data Studio перетаскивание не принимает.)

«Как проверить, что мой проект настроен правильно / почему импорт не запускается?»

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

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

Результаты выводятся в консоль и в итоговый диалог.

«Меню и интерфейс открылись на языке, который я не выбирал»

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

(Смена языка вызывает одну короткую перекомпиляцию, потому что подписи меню перегенерируются.)

«Я склонировал репозиторий, и мои ссылки на запечённые SO в сцене стали Missing»

Ожидаемо: запечённые SO — это кеши, локальные для каждой машины, с локальными для каждой машины GUID. Никогда не ссылайтесь на них напрямую из сцен — загружайте по адресу (SheetForgeDatabases.LoadAsync("Tab")). Выполните импорт один раз, чтобы перестроить свой локальный кеш.

«Моя сборка была прервана с сообщением от SheetForge»

Это pre-build хук проверки актуальности защищает вас от отправки в сборку пустого/устаревшего кеша. Сделайте то, что написано в предложении, — нажмите ↓ Pull from source в Tools ▸ SheetForge ▸ Data Studio — и соберите проект снова.

Импорт и проверка

«Импорт выполнился, нашёл ошибки и не создал вообще ничего»

Так и задумано: одна ошибка ⇒ никакого результата (частичная сборка невозможна). Отчёт перечисляет каждую проблему с координатами и предлагаемыми исправлениями — исправьте их за один проход и выполните повторный импорт. Из-за этого вы никогда не теряете работу; таблица остаётся нетронутой.

«Могу ли я сразу перейти к ячейке, о которой сообщает ошибка?»

Да. У каждой ошибки в понятном человеку отчёте консоли есть кликабельная ссылка «Open in Data Studio». Клик по ней открывает Data Studio, переключается на эту вкладку и выделяет эту ячейку (для ошибок на уровне файла/вкладки — просто переключает вкладку). Машиночитаемая строка координат не меняется, так что скрапинг CI/логов не затрагивается.

«Импорт записал код, перекомпилировался… он завершился?»

Да. Когда схема новая/изменилась, импорт внутренне состоит из двух этапов (генерация кода → компиляция/перезагрузка → запекание), и запекание автоматически возобновляется после перезагрузки. Следите за консолью для финального отчёта.

Если код вашей игры больше не компилируется (например, после переименования столбца), цепочка безопасно прерывается с предложением конкретных действий; исправьте свой код и импортируйте снова.

«Ошибка пустой ячейки, а я хотел, чтобы ячейка была необязательной»

Непомеченные типы обязательны (защита от молчаливого загрязнения данных). Чтобы сделать ячейку необязательной:

объявите float? — значение по умолчанию для типа;
объявите int=1 — явное значение по умолчанию;
либо используйте List<T>, где пустая ячейка — это пустой список.

См. Синтаксис таблиц.

«`1.5` импортируется нормально, а `1,5` выдаёт ошибку»

Это намеренно: числа не зависят от локали — десятичный разделитель всегда .. Десятичные с запятой, NaN и Infinity блокируются на входе.

«Импорт внезапно стал очень медленным»

Время импорта линейно зависит от размера ваших данных: 50k строк × 20 столбцов ≈ 628 ms в редакторе. Оно остаётся линейным даже когда одновременно ломается множество ссылок, потому что поиск ближайшего совпадения ограничен бюджетом на каждое поле и отфильтрован по длине (≈ 45 ms при 4,000 сломанных ссылках, headless).

Если импорт вдруг стал занимать намного больше времени, чем это, смотреть нужно на размер таблицы, а не на количество ошибок.

«Ошибка неизвестного маркера / неизвестного типа с подсказкой "вы имели в виду"»

Опечатки в именах @marker, именах типов или членах enum являются ошибками с предложениями ближайшего совпадения — примените предложение. Неизвестный @ у незарегистрированного имени типа — тоже ошибка (защита от опечаток для ссылок вида RecordId@Tab).

Google Таблицы

«Импорт из Google завершается ошибкой `PERMISSION_DENIED` (403)»

Таблица не расшарена на адрес client_email сервисного аккаунта — один лишь ключ не даёт никаких прав. Откройте JSON-ключ, скопируйте client_email и предоставьте доступ к таблице этому адресу (Viewer для импорта, Editor для отправки). Полное пошаговое руководство — в разделе Настройка Google Таблиц.

«Отправка сообщает, что требует SheetsApi»

Вы находитесь в режиме ExportUrl, который доступен только для чтения (без аутентификации). Любая запись обратно требует режима SheetsApi с ключом сервисного аккаунта. См. Источники, экспорт и отправка. Создание сервисного аккаунта и ключа описано в разделе Настройка Google Таблиц.

«Импорт ExportUrl завершается неудачей, требуя карту gid»

Это обязательно: URL экспорта без gid молча возвращает только первую вкладку, поэтому карта (имя вкладки → #gid=) обязательна. Либо переключитесь на режим SheetsApi, для которого карта не нужна.

«Отправка сообщила о пропущенных ячейках»

Повторное получение живых данных перед отправкой обнаружило конфликты (коллега отредактировал ячейку, строка переместилась/исчезла, дублирующийся ключ). Пропущенные ячейки — это защита, а не неудача — отчёт показывает количество применённых/пропущенных. Выполните повторный импорт для согласования, затем отправьте снова.

«Я удалил строки локально, но они всё ещё в Google Таблице после отправки»

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

Авторинг

«Ctrl+Z не отменяет мою подготовленную правку»

Две границы:

сфокусированное текстовое поле первым перехватывает Ctrl+Z — щёлкните в другом месте, затем отмените;
после успешного «Отразить в таблице» история подготовленных изменений очищается, так что undo работает только в пределах сессии до отражения.

После отражения редактируйте таблицу (она канонична).

«Некоторые мои подготовленные правки показывают значок "изолирована" и не были отражены»

Таблица изменилась извне между подготовкой и отражением так, что это сломало логический адрес этих правок (ключ строки переименован снаружи / строка удалена / конфликт ключа). Они исключаются — не теряются молча, не блокируют остальное. Отмените их по отдельности и подготовьте заново относительно нового baseline.

«Я переименовал столбец/вкладку, и теперь код моей игры не компилируется»

Ожидаемо и раскрыто в диалоге подтверждения: переименования меняют имя сгенерированного поля/класса. Обновите код своей игры; после этого цепочка импорта завершится при следующем запуске. Значения данных столбца были полностью сохранены.

«Могу ли я обменять имена двух вкладок (A↔B) или переименовать вкладки по циклу в одном пакете?»

Да. Взаимные обмены и циклы (A→B→C→A) подготавливаются и отражаются в одном пакете, а интерфейс отклоняет только настоящий конфликт: два переименования, нацеленные на одно и то же имя. Ссылки следуют за данными и переписываются атомарно.

В Google остаётся один пограничный случай: две обменивающиеся вкладки, ссылающиеся друг на друга, не перенаправляются (локально это работает полностью корректно). Направьте взаимную ссылку через третью вкладку, либо отразите через промежуточное имя. См. Data Studio и Возможности и ограничения.

«Моё переименование ключа не обновило ссылку, которую я набрал в том же пакете»

Распространение переписывает только ячейки baseline — никогда текст, который вы только что набрали (никакой молчаливой перезаписи свежего ввода). Предварительная проверка помечает повисшую ссылку; исправьте её самостоятельно.

«Отражение отклонено из-за вкладки xlsx»

Два известных случая:

вкладки, происходящие из xlsx, нельзя переименовывать (защита книги);
распространение переименования ключа, которое затронуло бы вкладку xlsx, блокирует весь пакет целиком (частичное отражение не допускается).

Отредактируйте книгу напрямую, затем выполните повторный импорт.

«Я отредактировал запечённый SO в инспекторе, и повторный импорт стёр это»

Так и задумано — таблица является единственным источником истины, а SO — это кеш. Переключатель «тестовая правка» в инспекторе явно временный. Вносите настоящие изменения через таблицу или Data Studio.

Экспорт и разное

«Экспорт завершается неудачей из-за несовпадения схемы»

Ваше запекание устарело относительно изменения схемы (ExportSchemaMismatch — проверка отпечатка). Выполните импорт, чтобы завершить генерацию кода + запекание, затем экспорт/отправку.

«Мой экспортированный float показывает `1`, хотя в таблице было `1.0`»

Семантический round-trip: значения сохраняются точно; нотация нормализуется до кратчайшей round-trip-формы. Структура (маркеры, порядок столбцов, комментарии, ваш текст) сохраняется на 100%.

«Импорт xlsx отклонил некоторые ячейки»

Встроенный читатель OOXML намеренно минимален. Три вещи не поддерживаются:

ячейки с формулами без закешированных значений;
ячейки с ошибками;
табуляции/переносы строк внутри ячейки.

Материализуйте формулы в значения; используйте ; для списков.