API Reference — The Public Surface

This page lists every public type in the product assemblies. Anything not listed here is internal by design; the public surface is deliberately narrow.

• Core (SheetForge.Core + SheetForge.Core.Tooling): 137 public types (Core: 131, Core.Tooling: 6). Core.Tooling is the editor-only half holding import-time services such as reporting and push planning — none of it ships in player builds.
• Editor: 53 top-level public types plus their public nested types.
• Runtime: 7 types, plus generated outputs.

This is exactly the surface the consumer-simulation tests (no InternalsVisibleTo) compile against.

Detection contract (not a type): a separate asset can also detect that SheetForge is installed at compile time via the SHEETFORGE scripting-define symbol the Editor assembly self-registers. It is a define, not a public type, so it is not listed in the tables below — see Plugin Authoring ▸ Detecting SheetForge from another asset. (Distinct from SHEETFORGE_ADDRESSABLES, an internal version-define that only marks whether the Addressables package is present.)

Conventions: signatures are abbreviated (… = see source XML docs); "pure" means no UnityEngine / no IO.

Core assembly (SheetForge.Core) — pure C#

No UnityEngine, no IO, no network, no domain knowledge. Compiler-enforced: Core references nothing.

Plugin registration contracts (SheetForge.Core.Plugins)

Composition and compatibility (SheetForge.Core.Plugins)

Discovery is per host — Unity's TypeCache in the editor, the browser's uploaded-assembly scan on the web. Everything after it (instantiation, ordering, isolation and the compatibility gate) is one shared Core function, which is what keeps the two hosts from drifting slot by slot.

PluginComposition — the two members:

• IReadOnlyList<Type> ContractTypes — the discovery filter. Its order is fixed, because it decides the order diagnostics appear in.
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — the assembly call itself.

Two kinds of trouble are kept apart. Registration conflicts and compatibility refusals become structured diagnostics in errors; implementation bugs — construction failure, a throwing callback — become English lines in failures, and passing null there discards them.

The trailing isProductKey predicate is how the string overlay's "a plugin may not overwrite a product key" rule is enforced without Core ever seeing the language tables: the rule lives here, the host supplies only the material. Omit the predicate and only that one rule is skipped.

Registries (SheetForge.Core.Model / .Validation / .Edges)

EnumRegistry — the three members in detail:

• EnumRegistry(EnumRegistry parent) — a child that reads through to a parent and registers only on itself. The parent holds plugin-registered CLR enums for the whole domain reload, the child this import's sheet-defined ones, so an import never mutates the shared cache. Registering a name the parent already owns throws rather than shadowing it.
• Contains(name) — own then parent, Ordinal.
• SetClrTypeName(name, fullTypeName) — fill in a CLR name after a string-only registration. The assembly name stays empty because the type does not exist yet.

"Create sheet" templates (SheetForge.Core.Model)

Custom cell types (SheetForge.Core.Model)

Sheet grammar constants (SheetForge.Core.Model)

A pack that reads or writes cell text works in the same grammar the importer does — splitting a list cell, composing an @type string, checking whether a name is already taken.

These constants are that grammar's single source of truth, so a pack never restates a separator of its own: a copied character drifts the day the grammar moves. The lists are handed out read-only, so nothing a pack does can change the grammar itself. The notation they spell out is documented in full on the Sheet Syntax page — this is the programmatic handle on it.

Markers

• CommentPrefix (#) · MarkerPrefix (@).
• One constant per built-in marker row: NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker.
• RequiredMarkers — the three every sheet must carry.
• ReservedMarkers — every built-in name. Read it before naming a custom marker: a collision is refused at registration.

Separators

• ListSeparator (;) — between list elements.
• EntrySeparator (,), FieldSeparator (:), SectionSeparator (|), KeyTimeSeparator (@) — the layers inside one value, which is why ; never appears in a value's own text.
• StyleKeyValueSeparator (=) — inside a @style cell.

@type notation

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

Type names

• One constant per built-in name: IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName.
• BuiltinScalarTypes and IsBuiltinScalarTypeName(name) — "is this name already a built-in?", answered before a parser is registered under it.
• StyleKeyNames (title, color) · LocReservedColumns (smart, comment).

Values

• TrueCanonical / FalseCanonical — canonical bool text.
• NumberCellStyles — the NumberStyles every numeric cell is read with. Thousands separators are excluded and the culture is always invariant, so a locale decimal comma fails loudly instead of silently changing a number.

Domain validation (SheetForge.Core.Validation)

Edge seam (SheetForge.Core.Validation / .Edges)

ReferenceScanner — the two reference predicates:

• GetReferencedTab(TypeToken) — the one predicate every consumer asks, "is this a reference, and to where". It answers for RecordId@Tab, for IntId@Tab (the integer key space), for the inside of a wrapper, and for a custom type stamped IsCustomReference. That is why one opt-in — and, for IntId@Tab, one widening of this predicate — turns them all on at once.
• GetReferenceKind(TypeToken) → RefKeyKind — whether the reference compares against the string or the integer key space, so rename propagation, the dropdown and the picker branch correctly.
• GetReferenceKind(TypeToken, tables) — the table-aware overload.

A core reference states its own space (RecordId / IntId). A referencing custom type has no notation to say it in — MyType@Tab is the only spelling — so its space is derived from the target tab's identity: a RecordId self key means string space, IntId alone means integer space, and an unknown tab or null tables falls back to string space, which is the same answer the token-only overload gives. That derivation is what lets an existing IReferencingCellType implementation aim at an IntId-keyed tab without a single line changed.

Reference graph index (SheetForge.Core.Edges)

An immutable snapshot that merges core-scanned references and contributor edges into one model, indexed both ways. Display material — it never produces diagnostics (the projection's Diagnostics remain the only source of truth for problems).

Data Studio record canvas (SheetForge.Core.Graphing)

The canvas decides what to draw on its own: it walks the reference index outward from the record you opened (the terminus) and lays the result out deterministically. A plugin does not replace that picture — it adds to it. Pure data throughout: columns are grid cells, not pixels, and colours are a free Category string the window maps to a palette.

CanvasAugmentBuilder — the write surface. Four things only:

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — a virtual node for an identity that is not a sheet record (an event key, a code atom); the tab may be empty.
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — an extra edge the core scanner cannot see. Naming fieldName says which cell the link is written in, fieldOnTarget says that cell sits on the arrival rather than the departure, and the cycle pair marks a loop for display with the note only the domain knows.
• SetLayer(tab, recordId, layer) — an absolute layer hint (0 = leftmost, negative = further left, everything shifts right to compensate). SetLayerRelative(tab, recordId, offset) — the same counted from the terminus (−1 = one column left of it), resolved against the terminus column before any hint moved it.
• SetSubtitle(tab, recordId, subtitle) — a display hint, the one thing that applies to records that already exist and to records that are not on screen (the connect picker reads those).

Items with an empty key are ignored, and what was collected is internal, because the merge rules live in one place. Every widening is trailing, so an override written against an earlier surface still compiles.

IAuthorableGraphShape — the two defaults without it:

• The creatable-tabs list this capability replaces — the axis that also decides whether a canvas opens at all and how far the pending-row sweep reaches — covers every tab reachable from the focus tab by following the schema transitively.
• The linking cascade the user actually sees starts from the tabs the ports currently drawn aim at.

Both drop code-registry tabs and tabs with no key column. A tab this returns that no drawn port accepts stays listed in the linking cascade with its reason attached, and the window's own gates still apply on top.

Colour presets (SheetForge.Core.Theming)

A preset overrides only the slots it names; every other slot keeps the product default, so a preset stays valid as slots are added. Registering never applies a preset — the user picks one in Preferences ▸ SheetForge ▸ Theme.

Declarative authoring surfaces (SheetForge.Core.Studio)

A plugin describes what to show — shell as data, predicate and effect as delegates — and each host draws it with its own widgets: UIToolkit in the editor, React in the browser. No layout numbers appear anywhere. What to say is the plugin's, how to place it is the renderer's.

Every enum here is append-only, so a registration keeps its meaning as the vocabulary grows.

StudioUiNode — factories, reads and the URL rule:

• Factories: Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link, plus WithTooltip(text), which returns a new node rather than changing this one.
• Reads: Kind · Text · Tooltip · ThemeColorSlot? Tone (never a hard-coded colour, so it follows the theme) · ActionId · Detail · Ratio · Url · Children.
• static bool IsAllowedUrl(url) — http/https only. One predicate both hosts ask, so they cannot disagree about what is safe to open.

Plugin UI strings (SheetForge.Core.Model)

StringOverlayRegistry — matching and refusals. language is an IETF code ("en", "ko", "zh-Hans", "pt-BR", …), matched case-insensitively. Lookup falls back requested language → English → miss, and the fallback lives here so both hosts answer identically.

Four registrations are refused, each recording a developer-facing reason rather than failing silently:

• a product built-in key — an overlay may add keys, never overwrite the product's own sentences or menu paths;
• a key+language another pack already registered — first found wins, because otherwise install order would decide the screen;
• an empty key or value;
• a language code the product does not know, which is never folded into English.

Pipeline observation (SheetForge.Core.Plugins / .Model)

Code registries (SheetForge.Core.Graphing)

Reference targets that live in code, exposed to the authoring surface as locked virtual tabs. Consumed by the Data Studio (sidebar / graph / inspector), not by the import validator.

The IR read model (SheetForge.Core.Model)

Typed asset references (SheetForge.Core.Model)

The <Type> in AssetRef@Group<Type> is resolved by the host — the Core knows neither the engine nor the project's assemblies — and the Core only judges the result. Everything here is pure data.

Codegen reads the resolved dictionary the pipeline produces and emits AssetReferenceT<global::FullName> for a resolved name; a name it cannot find in that dictionary is never emitted verbatim — the field falls back to AssetReference and an AssetTypeUnresolvedFallback warning is collected. The resolved full name is also mixed into the schema fingerprint.

Visual value types (SheetForge.Core.Model)

Engine-free value models for the three built-in visual types. Each is immutable, IEquatable, and owns its own text form (TryParse / Render) — the same notation the Sheet Syntax page documents — so a plugin type that stores a colour, a curve or a gradient can reuse them instead of inventing a second notation. The Editor bakes them into UnityEngine.Color / AnimationCurve / Gradient and reads them back; the browser samples them through the evaluators below rather than re-implementing the maths.

Errors and results (SheetForge.Core.Model / .Reporting)

ImportErrorCode — the families it covers:

• markers, schema, types, cells, keys/references and asset keys;
• sources/files, csv/xlsx, codegen identifiers, addressables, baseline/export, Google/auth/Push and templates;
• plugins — PluginRegistrationConflict, plus PluginIncompatible when an assembly's compatibility declaration falls outside what this host reads;
• IntId — DuplicateIntId, and for IntId@Tab references UnresolvedIntId · TargetTabHasNoIntId;
• @overlap and DomainRuleViolation;
• enum definition sheets — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue;
• DropdownNotSupportedByFormat, which is a warning rather than an error;
• typed asset references — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable (once per column, on the @type row), AssetTypeMismatch per cell, and the codegen warning AssetTypeUnresolvedFallback.

Indices and utilities (SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

Push plan (SheetForge.Core.Unparse)

Public because IPushApprover.Approve(PushPlan) exposes them; pure data.

Editor assembly (SheetForge.Editor)

Settings, localization, composition (SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — the bundle and slot isolation. The nested PluginBundle exposes the composed PluginSet Set — the twelve-slot single truth, which is how a newly grown slot is read without widening the bundle — plus nine convenience windows onto it: Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes. The earlier six- and eight-argument constructors remain as overloads that default the later registries to empty, behaving identically to the versions before those contracts existed.

Isolation is Core's, not this type's: a plugin that throws while registering is reported by name and skipped, and every other slot and plugin still registers.

SheetForgeActions — completion semantics. RunImport/RunPush are fire-and-forget. Their bodies are async void because the editor main thread cannot block on network IO, so the return is not completion — subscribe to ImportEvents.ImportCompleted for that. RunExport/RunHealthCheck/RunLocalizationSync complete synchronously — RunLocalizationSync runs the sheet → StringTable path an import completion runs, and without the Unity Localization package it shows the install notice and changes nothing.

Source-provider seam (SheetForge.Editor.Sources)

Data Studio extension points (SheetForge.Editor.Studio)

Editor-side because they hand back UIElements or touch window state — the same justified asymmetry as ISheetSourceProvider. All four contracts are discovered by TypeCache (parameterless constructor; no registration call), and all are called inside try/catch. The window itself (DataStudioWindow) is internal.

Anything expressible as data belongs in the Core ISheetForgeStudioPlugin vocabulary instead, which renders in the browser too. These are the ceiling-free escape hatches for what description cannot say.

The last four entries are not contracts but tools a mounted widget may use:

• the window's own read-only skin values, so it can look like it belongs;
• the key drop-down, so a cell widget picks keys the same way the built-in cell does;
• and the discovery-cache reset, so your own tests can re-discover a probe.

StudioInspectorContext — the two staging delegates:

• StageCell takes tab, recordId, field and canonical raw text. The window registers the Undo step, bumps the projection generation and stages the logical address.
• StageCells does the same for several cells that must change together: one native Undo step, all-or-nothing. If any one cannot be staged the session is not touched at all.

A failure is silent on screen either way, and only the gate explains itself. A read-only source, a pipeline already running, or a workbook-backed tab writes its reason to the console. An empty list, a write missing its tab or field, and a record key that resolves to no row do nothing and say nothing.

StudioPalette — the members:

• 33 colour slots: 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.
• Spacing: SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth.
• Type sizes: HeadingFontSize · SectionFontSize · CaptionFontSize.
• FromRgb(uint) · ToHex(uint).

Push approval (SheetForge.Editor.Push)

Authoring engine (SheetForge.Editor.Structure / .Pipeline / .Export)

Staging value types (SheetForge.Editor.Structure; StagedCellEdit/StagedNewRow are in SheetForge.Editor.Windows)

Authoring helpers (SheetForge.Editor.Windows / .Structure)

Runtime assembly (SheetForge.Runtime)

autoReferenced — usable from game code without an asmdef reference.

Generated types (pattern — per project, not shipped API)

For each tab Foo, codegen emits into your 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
}

Load with SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").

Both classes are emitted partial, so you can add derived members — a computed property, an interface implementation, an operator — in your own file next to the generated one, and a re-import will not overwrite it.

One boundary: add no serialized fields in your part. The baked ScriptableObject is rebuilt from the sheet on every import, so anything only your part serializes comes back at its default. If a value belongs to the data, it belongs in a column.

(The partial keyword does not touch SchemaFingerprint, which is computed from the schema alone, so making the classes partial did not invalidate a single existing bake.)

Other assemblies

• SheetForge.Setup — the dependency-free Addressables-absence bootstrap. No public API (all internal; it exists to show a guidance window).

• SheetForge.PluginDemo (one merged asmdef + a Demo.Editor asmdef; content namespace remains SheetForge.Skills) — the reference sample package, not product API. It holds:

  • SkillsPlugin (seven plugin interfaces — base, validator, edge, template, graph, code registry, theme);
  • Modifier + ModifierCellParser (custom cell type), ModifierStatEdgeContributor (edge contributor);
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter (canvas overrides), ExampleCodeAtoms (the _Refs code registry);
  • ExampleStudioUi (declarative actions, panel, column badge and cell-editor hint), ExampleImportObserver (pipeline observer);
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel (Data Studio Editor extension points, painted from the public palette), ExampleLocStrings (registers those labels in two languages — in the main assembly, so the browser shows them too);
  • an assembly-level SheetForgePluginCompat declaration;
  • SkillRunner (consuming runtime), generated Example* types in the default SheetForge.Generated namespace (isolation is by the Example* prefix, not a separate namespace).

  The plugin-free SheetForge.CoreDemo sample ships with zero asmdefs (compiles into Assembly-CSharp).

Related pages

• Plugin Authoring — the contracts in use, with full examples
• Authoring Kernel — the engine types in context
• Capabilities & Limits — behavioral boundaries of these APIs