Справочник по API — публичная поверхность

Эта страница перечисляет каждый публичный тип в сборках продукта. Всё, что здесь не перечислено, является internal по замыслу — публичная поверхность намеренно узкая.

• Core (SheetForge.Core + SheetForge.Core.Tooling): 137 публичных типов (Core: 131, Core.Tooling: 6). Core.Tooling — это редакторская половина, содержащая сервисы времени импорта, такие как формирование отчётов и планирование отправки, — она не поставляется в билды игрока.
• Editor: 53 публичных типа верхнего уровня плюс их публичные вложенные типы.
• Runtime: 7 типов, плюс сгенерированные результаты.

Это именно та поверхность, против которой компилируются тесты-симуляторы потребителя (без InternalsVisibleTo).

Контракт обнаружения (не тип): сторонний ассет также может обнаружить, что SheetForge установлен, во время компиляции через символ scripting-define SHEETFORGE, который сборка Editor регистрирует самостоятельно. Это define, а не публичный тип, поэтому он не перечислен в таблицах ниже — см. Создание плагинов ▸ Обнаружение SheetForge из другого ассета. (Отдельно от SHEETFORGE_ADDRESSABLES — внутреннего version-define, который лишь отмечает, присутствует ли пакет Addressables.)

Соглашения: сигнатуры сокращены (… = см. XML-документацию в исходном коде); «чистый» означает отсутствие UnityEngine / отсутствие ввода-вывода.

Сборка Core (SheetForge.Core) — чистый C#

Нет UnityEngine, нет ввода-вывода, нет сети, нет знаний о домене. Обеспечивается компилятором: Core ни на что не ссылается.

Контракты регистрации плагинов (SheetForge.Core.Plugins)

Композиция и совместимость (SheetForge.Core.Plugins)

Обнаружение зависит от хоста — TypeCache Unity в редакторе, сканирование загруженной сборки в браузере. Всё, что происходит после (создание экземпляров, порядок, изоляция и шлюз совместимости), — это одна общая функция Core, именно она не даёт двум хостам расходиться слот за слотом.

PluginComposition — два члена:

• IReadOnlyList<Type> ContractTypes — фильтр обнаружения. Его порядок фиксирован, поскольку именно он определяет порядок появления диагностики.
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — сам вызов сборки.

Два вида проблем держатся раздельно. Конфликты регистрации и отказы по совместимости становятся структурированной диагностикой в errors; ошибки реализации — сбой конструирования, бросающий исключение колбэк — становятся строками на английском в failures, а передача туда null их отбрасывает.

Завершающий предикат isProductKey — это то, как правило строкового оверлея «плагин не может перезаписать ключ продукта» обеспечивается без того, чтобы Core вообще видел языковые таблицы: правило живёт здесь, хост поставляет только материал. Опустите предикат, и пропускается только это одно правило.

Реестры (SheetForge.Core.Model / .Validation / .Edges)

EnumRegistry — три члена подробно:

• EnumRegistry(EnumRegistry parent) — дочерний реестр, который читает через родительский и регистрирует только в себе. Родитель хранит зарегистрированные плагином CLR-enum на всю перезагрузку домена, дочерний — определённые в таблице для этого импорта, поэтому импорт никогда не изменяет общий кеш. Регистрация имени, которым уже владеет родитель, бросает исключение, а не затеняет его.
• Contains(name) — сначала свой, затем родительский, Ordinal.
• SetClrTypeName(name, fullTypeName) — заполняет имя CLR после регистрации только по строке. Имя сборки остаётся пустым, поскольку тип ещё не существует.

Шаблоны «Создать лист» (SheetForge.Core.Model)

Пользовательские типы ячеек (SheetForge.Core.Model)

Константы грамматики таблицы (SheetForge.Core.Model)

Пакет, который читает или пишет текст ячейки, работает по той же грамматике, что и импортёр — разбивает ячейку-список, составляет строку @type, проверяет, не занято ли уже имя.

Эти константы — единственный источник истины для этой грамматики, поэтому пакет никогда не переопределяет собственный разделитель заново: скопированный символ разойдётся с оригиналом в тот день, когда грамматика изменится. Списки выдаются только для чтения, поэтому ничто из того, что делает пакет, не может изменить саму грамматику. Нотация, которую они описывают, полностью задокументирована на странице Синтаксис таблиц — это программный доступ к ней.

Маркеры

• CommentPrefix (#) · MarkerPrefix (@).
• По одной константе на каждую встроенную строку-маркер: NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker.
• RequiredMarkers — три, которые обязана нести каждая таблица.
• ReservedMarkers — все встроенные имена. Сверьтесь с ним, прежде чем называть собственный маркер: конфликт отклоняется при регистрации.

Разделители

• ListSeparator (;) — между элементами списка.
• EntrySeparator (,), FieldSeparator (:), SectionSeparator (|), KeyTimeSeparator (@) — слои внутри одного значения, из-за чего ; никогда не встречается в собственном тексте значения.
• StyleKeyValueSeparator (=) — внутри ячейки @style.

Нотация @type

• OptionalSuffix (?) · DefaultSeparator (=) · TargetSeparator (@, как в RecordId@Tab).
• ListTypeName · ListOpen (List<) · ListClose (>).

Имена типов

• По одной константе на каждое встроенное имя: IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName.
• BuiltinScalarTypes и IsBuiltinScalarTypeName(name) — отвечают на вопрос «это имя уже встроенное?» ещё до того, как под этим именем зарегистрируют парсер.
• StyleKeyNames (title, color) · LocReservedColumns (smart, comment).

Значения

• TrueCanonical / FalseCanonical — канонический текст bool.
• NumberCellStyles — NumberStyles, с которым читается каждая числовая ячейка. Разделители тысяч исключены, а культура всегда инвариантна, поэтому локальная десятичная запятая громко завершается ошибкой вместо того, чтобы незаметно изменить число.

Доменная проверка (SheetForge.Core.Validation)

Стык рёбер (SheetForge.Core.Validation / .Edges)

ReferenceScanner — два предиката ссылок:

• GetReferencedTab(TypeToken) — единственный предикат, который спрашивает каждый потребитель: «это ссылка, и куда». Он отвечает для RecordId@Tab, для IntId@Tab (целочисленное пространство ключей), для внутренностей wrapper'а и для пользовательского типа с пометкой IsCustomReference. Именно поэтому одна опция — а для IntId@Tab одно расширение этого предиката — включает их все разом.
• GetReferenceKind(TypeToken) → RefKeyKind — сравнивается ли ссылка со строковым или целочисленным пространством ключей, так что распространение переименования, выпадающий список и пикер ветвятся правильно.
• GetReferenceKind(TypeToken, tables) — перегрузка, осведомлённая о таблицах.

Базовая ссылка сама заявляет своё пространство (RecordId / IntId). У ссылающегося пользовательского типа нет нотации, чтобы это заявить — MyType@Tab единственно возможное написание, — поэтому его пространство выводится из идентичности целевой вкладки: собственный ключ RecordId означает строковое пространство, один лишь IntId означает целочисленное, а неизвестная вкладка или null-таблицы откатываются к строковому пространству — тот же ответ, что даёт перегрузка только с токеном. Именно этот вывод позволяет существующей реализации IReferencingCellType нацелиться на вкладку с ключом IntId без единой изменённой строки.

Индекс графа ссылок (SheetForge.Core.Edges)

Неизменяемый снимок, который объединяет отсканированные ядром ссылки и рёбра от поставщиков в одну модель, индексированную в обе стороны. Материал отображения — он никогда не производит диагностику (Diagnostics проекции остаётся единственным источником истины о проблемах).

Холст записи Data Studio (SheetForge.Core.Graphing)

Холст сам решает, что рисовать: он проходит по индексу ссылок наружу от открытой вами записи (терминуса) и раскладывает результат детерминированно. Плагин не заменяет эту картину — он добавляет к ней. Всюду чистые данные: столбцы — это ячейки сетки, а не пиксели, а цвета — это свободная строка Category, которую окно сопоставляет с палитрой.

CanvasAugmentBuilder — поверхность записи. Всего четыре вещи:

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — виртуальный узел для идентичности, не являющейся записью таблицы (ключ события, атом кода); вкладка может быть пустой.
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — дополнительное ребро, которое сканер ядра не видит. Указание fieldName говорит, в какой ячейке записана связь, fieldOnTarget говорит, что эта ячейка находится на стороне прибытия, а не отправления, а пара параметров цикла помечает петлю для отображения с примечанием, которое известно только домену.
• SetLayer(tab, recordId, layer) — абсолютная подсказка слоя (0 = крайний слева, отрицательное = ещё левее, всё остальное сдвигается вправо для компенсации). SetLayerRelative(tab, recordId, offset) — то же самое, но отсчитываемое от терминуса (−1 = столбец сразу слева от него), разрешаемое относительно столбца терминуса до того, как его сдвинула любая подсказка.
• SetSubtitle(tab, recordId, subtitle) — подсказка отображения, единственная вещь, которая применяется к уже существующим записям и к записям, не показанным на экране (их читает пикер подключения).

Элементы с пустым ключом игнорируются, а то, что было собрано, — internal, поскольку правила слияния живут в одном месте. Каждое расширение — это добавленный в конец аргумент, поэтому переопределение, написанное против более ранней поверхности, всё ещё компилируется.

IAuthorableGraphShape — два значения по умолчанию без неё:

• Список создаваемых вкладок, который заменяет эта возможность, — та же ось, что также решает, откроется ли холст вообще и как далеко достанет проход по строкам в ожидании, — охватывает каждую вкладку, достижимую из вкладки фокуса, следуя по схеме транзитивно.
• Каскад связывания, который пользователь видит на самом деле, начинается с вкладок, на которые нацелены нарисованные в данный момент порты.

Оба отбрасывают вкладки-реестры кода и вкладки без ключевого столбца. Вкладка, которую вернул этот метод, но которую не принимает ни один нарисованный порт, остаётся в каскаде связывания с прикреплённой причиной, а собственные ограничения окна по-прежнему применяются поверх.

Цветовые пресеты (SheetForge.Core.Theming)

Пресет переопределяет только те слоты, которые он называет; каждый остальной слот сохраняет значение продукта по умолчанию, поэтому пресет остаётся валидным по мере добавления новых слотов. Регистрация никогда не применяет пресет — пользователь выбирает его в Preferences ▸ SheetForge ▸ Theme.

Декларативные поверхности авторинга (SheetForge.Core.Studio)

Плагин описывает, что показать — оболочку как данные, предикат и эффект как делегаты, — а каждый хост рисует это собственными виджетами: UIToolkit в редакторе, React в браузере. Нигде не встречаются числа раскладки. Что сказать — дело плагина, как разместить — дело рендерера.

Каждый enum здесь только для добавления, поэтому регистрация сохраняет смысл по мере роста словаря.

StudioUiNode — фабрики, чтение и правило URL:

• Фабрики: Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link, плюс WithTooltip(text), который возвращает новый узел, а не изменяет этот.
• Чтение: Kind · Text · Tooltip · ThemeColorSlot? Tone (никогда не жёстко заданный цвет, поэтому он следует за темой) · ActionId · Detail · Ratio · Url · Children.
• статический bool IsAllowedUrl(url) — только http/https. Один предикат, который спрашивают оба хоста, поэтому они не могут разойтись в том, что безопасно открывать.

Строки интерфейса плагинов (SheetForge.Core.Model)

StringOverlayRegistry — сопоставление и отказы. language — это код IETF ("en", "ko", "zh-Hans", "pt-BR", …), сопоставляется без учёта регистра. Поиск откатывается запрошенный язык → английский → промах, и этот откат живёт здесь, чтобы оба хоста отвечали одинаково.

Четыре регистрации отклоняются, каждая с записью причины, понятной разработчику, а не молчаливым провалом:

• встроенный ключ продукта — оверлей может добавлять ключи, но никогда не перезаписывать собственные предложения или пути меню продукта;
• пара ключ+язык, уже зарегистрированная другим пакетом — побеждает найденная первой, иначе порядок установки решал бы, что на экране;
• пустой ключ или значение;
• код языка, которого продукт не знает, — он никогда не сворачивается в английский.

Наблюдение за конвейером (SheetForge.Core.Plugins / .Model)

Реестры кода (SheetForge.Core.Graphing)

Цели ссылок, которые живут в коде, предоставленные поверхности авторинга как заблокированные виртуальные вкладки. Потребляются Data Studio (боковая панель / граф / инспектор), а не валидатором импорта.

Модель чтения IR (SheetForge.Core.Model)

Типизированные ссылки на ассеты (SheetForge.Core.Model)

<Type> в AssetRef@Group<Type> разрешает хост — Core не знает ни движка, ни сборок проекта, — а Core лишь оценивает результат. Всё здесь — чистые данные.

Генерация кода читает разрешённый словарь, который производит конвейер, и генерирует AssetReferenceT<global::FullName> для разрешённого имени; имя, которое не находится в этом словаре, никогда не генерируется дословно — поле откатывается к AssetReference, и собирается предупреждение AssetTypeUnresolvedFallback. Разрешённое полное имя также учитывается в отпечатке схемы.

Визуальные типы значений (SheetForge.Core.Model)

Независимые от движка модели значений для трёх встроенных визуальных типов. Каждая из них неизменяема, реализует IEquatable и владеет собственной текстовой формой (TryParse / Render) — той же нотацией, которую описывает страница «Синтаксис таблиц», — поэтому тип плагина, хранящий цвет, кривую или градиент, может переиспользовать их вместо изобретения второй нотации. Editor запекает их в UnityEngine.Color / AnimationCurve / Gradient и считывает их обратно; браузер получает их значения через evaluator'ы ниже, а не реализует математику заново.

Ошибки и результаты (SheetForge.Core.Model / .Reporting)

ImportErrorCode — семейства, которые он охватывает:

• маркеры, схема, типы, ячейки, ключи/ссылки и ключи ассетов;
• источники/файлы, csv/xlsx, идентификаторы генерации кода, addressables, baseline/экспорт, Google/аутентификация/отправка и шаблоны;
• плагины — PluginRegistrationConflict, а также PluginIncompatible, когда декларация совместимости сборки выходит за рамки того, что читает этот хост;
• IntId — DuplicateIntId, а для ссылок IntId@Tab — UnresolvedIntId · TargetTabHasNoIntId;
• @overlap и DomainRuleViolation;
• листы определений enum — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue;
• DropdownNotSupportedByFormat, что является предупреждением, а не ошибкой;
• типизированные ссылки на ассеты — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable (один раз на столбец, в строке @type), AssetTypeMismatch на каждую ячейку, и предупреждение генерации кода AssetTypeUnresolvedFallback.

Индексы и утилиты (SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

План отправки (SheetForge.Core.Unparse)

Публичны, потому что IPushApprover.Approve(PushPlan) их предоставляет; чистые данные.

Сборка Editor (SheetForge.Editor)

Настройки, локализация, композиция (SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — комплект и изоляция слотов. Вложенный PluginBundle предоставляет собранный PluginSet Set — единую истину из двенадцати слотов, благодаря которой новый слот можно прочитать, не расширяя комплект, — плюс девять удобных окон в него: Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes. Более ранние конструкторы с шестью и восемью аргументами сохранены как перегрузки, которые по умолчанию делают более поздние реестры пустыми, что ведёт себя идентично версиям до появления этих контрактов.

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

SheetForgeActions — семантика завершения. RunImport/RunPush являются fire-and-forget. Их тела async void, поскольку главный поток редактора не может блокироваться на сетевом вводе-выводе, так что возврат не означает завершения — подпишитесь на ImportEvents.ImportCompleted для этого. RunExport/RunHealthCheck/RunLocalizationSync завершаются синхронно — RunLocalizationSync проходит путь таблица → StringTable, который проходит завершение импорта, а без пакета Unity Localization показывает уведомление об установке и ничего не меняет.

Стык провайдера источника (SheetForge.Editor.Sources)

Точки расширения Data Studio (SheetForge.Editor.Studio)

На стороне редактора, поскольку они затрагивают UIElements / состояние окна — та же обоснованная асимметрия, что и у ISheetSourceProvider. Все четыре контракта обнаруживаются через TypeCache (конструктор без параметров; без вызова регистрации), и все вызываются внутри try/catch. Само окно (DataStudioWindow) — internal.

Что-либо, выразимое как данные, принадлежит словарю Core ISheetForgeStudioPlugin — он тоже отрисовывается в браузере. Эти же контракты — лазейки без потолка для того, что описание сказать не может.

Последние четыре записи — это не контракты, а инструменты, которые может использовать смонтированный виджет:

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

StudioInspectorContext — два делегата подготовки:

• StageCell принимает вкладку, recordId, поле и канонический сырой текст. Окно регистрирует шаг Undo, увеличивает поколение проекции и подготавливает логический адрес.
• StageCells делает то же самое для нескольких ячеек, которые должны измениться вместе: один нативный шаг Undo, всё или ничего. Если хотя бы одну нельзя подготовить, сессия вообще не затрагивается.

Неудача в любом случае молчалива на экране, и объясняет себя только сам шлюз. Источник только для чтения, уже выполняющийся конвейер или вкладка из книги xlsx записывают причину в консоль. Пустой список, запись без вкладки или поля и ключ записи, не разрешающийся ни в одну строку, ничего не делают и ничего не говорят.

StudioPalette — члены:

• 33 цветовых слота: Canvas · Panel · Band · Chrome · Surface · Chip · Selection · PendingCell · Line · LineSoft · GridLine · LineHover · Text · TextMuted · TextFaint · RefText · OnAccent · Accent · AccentDim · Warning · Danger · Ok · SheetTone · CodeTone · EditedCell · NewRowCell · NewRowLine · DangerChip · DangerPanel · Scrim · Wire · WireDot · GridDot.
• IsDark.
• Отступы: SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth.
• Размеры типографики: HeadingFontSize · SectionFontSize · CaptionFontSize.
• FromRgb(uint) · ToHex(uint).

Подтверждение отправки (SheetForge.Editor.Push)

Движок авторинга (SheetForge.Editor.Structure / .Pipeline / .Export)

Типы значений подготовки (SheetForge.Editor.Structure; StagedCellEdit/StagedNewRow находятся в SheetForge.Editor.Windows)

Вспомогательные средства авторинга (SheetForge.Editor.Windows / .Structure)

Сборка Runtime (SheetForge.Runtime)

autoReferenced — можно использовать из кода игры без ссылки на asmdef.

Сгенерированные типы (паттерн — для каждого проекта, не поставляемый API)

Для каждой вкладки Foo генерация кода создаёт в вашем generatedNamespace:

public sealed partial class FooDefinition    // one strongly-typed field per column; @desc → doc/tooltip
public sealed partial class FooDatabase : DefinitionDatabase
{
    // TabName, Count, SchemaFingerprint, Records, RecordsUntyped override,
    // lazy _byId/_byIntId lookups, InvalidateIndex override
}

Загружайте через SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").

Оба класса генерируются как partial, поэтому вы можете добавлять производные члены — вычисляемое свойство, реализацию интерфейса, оператор — в собственном файле рядом со сгенерированным, и повторный импорт его не перезапишет. Одна граница: не добавляйте сериализуемые поля в своей части. Запечённый ScriptableObject перестраивается из таблицы при каждом импорте, поэтому всё, что сериализует только ваша часть, возвращается к значению по умолчанию — если значение принадлежит данным, ему место в столбце. (Ключевое слово partial не затрагивает SchemaFingerprint, который вычисляется только из схемы, поэтому превращение классов в partial не сделало недействительным ни одно существующее запекание.)

Прочие сборки

• SheetForge.Setup — ни от чего не зависящий бутстрап для случая отсутствия Addressables. Нет публичного API (всё internal; существует, чтобы показать окно с рекомендациями).

• SheetForge.PluginDemo (один объединённый asmdef + asmdef Demo.Editor; пространство имён содержимого остаётся SheetForge.Skills) — эталонный пакет примера, не API продукта. Он содержит:

  • SkillsPlugin (семь интерфейсов плагина — базовый, валидатор, ребро, шаблон, граф, реестр кода, тема);
  • Modifier + ModifierCellParser (пользовательский тип ячейки), ModifierStatEdgeContributor (поставщик рёбер);
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter (переопределения холста), ExampleCodeAtoms (реестр кода _Refs);
  • ExampleStudioUi (декларативные действия, панель, значок столбца и подсказка редактора ячейки), ExampleImportObserver (наблюдатель конвейера);
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel (точки расширения редактора Data Studio, отрисованные из публичной палитры), ExampleLocStrings (регистрирует эти метки на двух языках — в основной сборке, так что браузер тоже их показывает);
  • декларация SheetForgePluginCompat на уровне сборки;
  • SkillRunner (потребление во время выполнения), сгенерированные типы Example* в пространстве имён по умолчанию SheetForge.Generated (изоляция обеспечивается префиксом Example*, а не отдельным пространством имён).

  Не требующий плагина пример SheetForge.CoreDemo поставляется без единого asmdef (компилируется в Assembly-CSharp).

Похожие страницы

• Создание плагинов — используемые контракты с полными примерами
• Ядро авторинга — типы движка в контексте
• Возможности и ограничения — границы поведения этих API