Referência da API — A Superfície Pública

Esta página lista todo tipo público nos assemblies do produto. Qualquer coisa não listada aqui é internal por design; a superfície pública é deliberadamente estreita.

• Core (SheetForge.Core + SheetForge.Core.Tooling): 137 tipos públicos (Core: 131, Core.Tooling: 6). O Core.Tooling é a metade exclusiva do editor que hospeda serviços de import-time como relatórios e planejamento de push — nada dele é distribuído em builds de jogador.
• Editor: 53 tipos públicos de nível superior, mais seus tipos aninhados públicos.
• Runtime: 7 tipos, mais as saídas geradas.

Esta é exatamente a superfície contra a qual os testes de simulação de consumidor (sem InternalsVisibleTo) compilam.

Contrato de detecção (não é um tipo): um asset separado também pode detectar que o SheetForge está instalado em tempo de compilação via o símbolo de scripting define SHEETFORGE que o assembly Editor autorregistra. É um define, não um tipo público, então não aparece listado nas tabelas abaixo — veja Autoria de Plugins ▸ Detectando o SheetForge a partir de outro asset. (Diferente de SHEETFORGE_ADDRESSABLES, um version-define interno que apenas indica se o pacote Addressables está presente.)

Convenções: assinaturas são abreviadas (… = veja os documentos XML do código-fonte); "puro" significa sem UnityEngine / sem IO.

Assembly Core (SheetForge.Core) — C# puro

Sem UnityEngine, sem IO, sem rede, sem conhecimento de domínio. Imposto pelo compilador: o Core não referencia nada.

Contratos de registro de plugin (SheetForge.Core.Plugins)

Composição e compatibilidade (SheetForge.Core.Plugins)

A descoberta é por host — o TypeCache da Unity no editor, a varredura de assembly enviado do navegador na web. Tudo depois dela (instanciação, ordenação, isolamento e o portão de compatibilidade) é uma única função Core compartilhada, o que é o que impede os dois hosts de divergirem slot a slot.

PluginComposition — os dois membros:

• IReadOnlyList<Type> ContractTypes — o filtro de descoberta. A sua ordem é fixa, porque ela decide a ordem em que os diagnósticos aparecem.
• PluginSet Compose(IReadOnlyList<Type> candidateTypes, string hostVersion, ErrorCollector errors, ICollection<string> failures, Func<string,bool> isProductKey = null) — a própria chamada de montagem.

Dois tipos de problema são mantidos separados. Conflitos de registro e recusas de compatibilidade viram diagnósticos estruturados em errors; bugs de implementação — falha de construção, um callback que lança exceção — viram linhas em inglês em failures, e passar null ali as descarta.

O predicado final isProductKey é como a regra "um plugin não pode sobrescrever uma chave do produto" da sobreposição de strings é imposta sem o Core jamais ver as tabelas de idioma: a regra vive aqui, o host fornece apenas o material. Omita o predicado e só essa regra é pulada.

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

EnumRegistry — os três membros em detalhe:

• EnumRegistry(EnumRegistry parent) — um filho que lê através de um pai e registra somente em si mesmo. O pai guarda os enums CLR registrados por plugin durante todo o domain reload, o filho guarda os definidos em planilha desta importação, então uma importação nunca modifica o cache compartilhado. Registrar um nome que o pai já possui lança uma exceção, em vez de sombreá-lo.
• Contains(name) — primeiro o próprio, depois o pai, Ordinal.
• SetClrTypeName(name, fullTypeName) — preenche um nome CLR depois de um registro somente-string. O nome do assembly permanece vazio porque o tipo ainda não existe.

Templates de "Criar planilha" (SheetForge.Core.Model)

Tipos de célula personalizados (SheetForge.Core.Model)

Constantes da gramática da planilha (SheetForge.Core.Model)

Um pacote que lê ou grava texto de célula funciona com a mesma gramática que o importador usa — dividir uma célula de lista, compor uma string @type, verificar se um nome já está em uso.

Essas constantes são a única fonte de verdade dessa gramática, então um pacote nunca reafirma um separador próprio: um caractere copiado se desalinha no dia em que a gramática mudar. As listas são entregues como somente leitura, então nada que um pacote faça pode mudar a própria gramática. A notação que elas expressam está totalmente documentada na página Sintaxe da Planilha — isso é a interface programática para ela.

Marcadores

• CommentPrefix (#) · MarkerPrefix (@).
• Uma constante por linha de marcador embutido: NameMarker · TypeMarker · DescMarker · OverlapMarker · StyleMarker · EnumMarker · LocMarker.
• RequiredMarkers — os três que toda planilha precisa ter.
• ReservedMarkers — todo nome embutido. Consulte antes de nomear um marcador personalizado: uma colisão é recusada no registro.

Separadores

• ListSeparator (;) — entre elementos de lista.
• EntrySeparator (,), FieldSeparator (:), SectionSeparator (|), KeyTimeSeparator (@) — as camadas dentro de um único valor, e é por isso que ; nunca aparece no próprio texto de um valor.
• StyleKeyValueSeparator (=) — dentro de uma célula @style.

Notação de @type

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

Nomes de tipo

• Uma constante por nome embutido: IntTypeName · FloatTypeName · BoolTypeName · StringTypeName · RecordIdTypeName · IntIdTypeName · AssetRefTypeName · LocRefTypeName · ColorTypeName · AnimationCurveTypeName · GradientTypeName · EnumTypeName.
• BuiltinScalarTypes e IsBuiltinScalarTypeName(name) — respondem "esse nome já é embutido?" antes de um parser ser registrado sob ele.
• StyleKeyNames (title, color) · LocReservedColumns (smart, comment).

Valores

• TrueCanonical / FalseCanonical — o texto canônico de bool.
• NumberCellStyles — o NumberStyles com o qual toda célula numérica é lida. Separadores de milhar são excluídos e a cultura é sempre invariante, então uma vírgula decimal local falha ruidosamente em vez de mudar um número silenciosamente.

Validação de domínio (SheetForge.Core.Validation)

Costura de aresta (SheetForge.Core.Validation / .Edges)

ReferenceScanner — os dois predicados de referência:

• GetReferencedTab(TypeToken) — o único predicado que todo consumidor pergunta, "isto é uma referência, e para onde". Ele responde para RecordId@Tab, para IntId@Tab (o espaço de chave inteira), para o interior de um wrapper, e para um tipo personalizado marcado com IsCustomReference. É por isso que um único opt-in — e, para IntId@Tab, uma ampliação deste predicado — liga todos eles de uma vez.
• GetReferenceKind(TypeToken) → RefKeyKind — se a referência compara contra o espaço de chave em string ou em inteiro, então a propagação de renomeação, o dropdown e o seletor ramificam corretamente.
• GetReferenceKind(TypeToken, tables) — a sobrecarga ciente da tabela.

Uma referência do core declara o seu próprio espaço (RecordId / IntId). Um tipo personalizado com referência não tem notação para dizer isso — MyType@Tab é a única grafia — então o seu espaço é derivado da identidade da aba de destino: uma chave própria RecordId significa espaço em string, IntId sozinho significa espaço em inteiro, e uma aba desconhecida ou null tables recorre ao espaço em string, a mesma resposta que a sobrecarga só-com-token dá. Essa derivação é o que permite que uma implementação existente de IReferencingCellType mire em uma aba com chave em IntId sem uma única linha alterada.

Índice do grafo de referências (SheetForge.Core.Edges)

Um snapshot imutável que funde referências escaneadas pelo core e arestas de contribuidor em um único modelo, indexado nos dois sentidos. Material de exibição — nunca produz diagnósticos (o Diagnostics da projeção continua sendo a única fonte da verdade para problemas).

Canvas de registros do Data Studio (SheetForge.Core.Graphing)

O canvas decide o que desenhar por conta própria: ele percorre o índice de referências para fora, a partir do registro que você abriu (o terminus), e organiza o resultado de forma determinística. Um plugin não substitui esse quadro — ele acrescenta a ele. Dados puros do início ao fim: colunas são células de grade, não pixels, e cores são uma string Category livre que a janela mapeia para uma paleta.

CanvasAugmentBuilder — a superfície de gravação. Apenas quatro coisas:

• AddNode(tab, recordId, title = null, category = null) / AddNode(tab, recordId, title, category, CellCoordinate address) — um nó virtual para uma identidade que não é um registro de planilha (uma chave de evento, um átomo de código); a aba pode ficar vazia.
• AddEdge(fromTab, fromRecordId, toTab, toRecordId, label = null, fieldName = null, fieldOnTarget = false, isCyclic = false, cyclicNote = null) — uma aresta extra que o scanner do core não consegue ver. Nomear fieldName diz em qual célula o vínculo está escrito, fieldOnTarget diz que essa célula fica na chegada, e não na partida, e o par de ciclo marca um loop para exibição, com a nota que só o domínio conhece.
• SetLayer(tab, recordId, layer) — uma dica de camada absoluta (0 = mais à esquerda, negativo = ainda mais à esquerda, tudo se desloca para a direita para compensar). SetLayerRelative(tab, recordId, offset) — a mesma coisa, contada a partir do terminus (−1 = uma coluna à esquerda dele), resolvida contra a coluna do terminus antes de qualquer dica movê-la.
• SetSubtitle(tab, recordId, subtitle) — uma dica de exibição, a única coisa que se aplica a registros que já existem e a registros que não estão em tela (o seletor de conexão lê esses).

Itens com chave vazia são ignorados, e o que foi coletado é internal, porque as regras de fusão vivem em um único lugar. Toda ampliação é à direita (trailing), então uma sobreposição escrita contra uma superfície anterior continua compilando.

IAuthorableGraphShape — os dois padrões sem ela:

• A lista de abas criáveis que esta capacidade substitui — o eixo que também decide se um canvas sequer abre e até onde a varredura de linhas pendentes alcança — cobre toda aba alcançável a partir da aba em foco seguindo o esquema transitivamente.
• A cascata de vínculo que o usuário de fato vê começa a partir das abas para onde as portas atualmente desenhadas apontam.

Ambos descartam abas de registro de código e abas sem coluna-chave. Uma aba que isto retorna e que nenhuma porta desenhada aceita permanece listada na cascata de vínculo com o seu motivo anexado, e os próprios portões da janela ainda se aplicam por cima.

Predefinições de cor (SheetForge.Core.Theming)

Uma predefinição sobrescreve apenas os slots que ela nomeia; todo outro slot mantém o padrão do produto, então uma predefinição continua válida conforme slots são adicionados. Registrar nunca aplica uma predefinição — o usuário escolhe uma em Preferences ▸ SheetForge ▸ Theme.

Superfícies de autoria declarativas (SheetForge.Core.Studio)

Um plugin descreve o que mostrar — o invólucro como dado, o predicado e o efeito como delegates — e cada host o desenha com os seus próprios widgets: UIToolkit no editor, React no navegador. Nenhum número de layout aparece em lugar nenhum. O que dizer é do plugin; como posicioná-lo é do renderizador.

Todo enum aqui é somente-anexação, então um registro mantém o seu significado conforme o vocabulário cresce.

StudioUiNode — fábricas, leituras e a regra de URL:

• Fábricas: Row · Label · Chip · Badge · Button · Rule · Heading · KeyValue · Table(headerRow, rows) · List · Progress · Input · Link, mais WithTooltip(text), que retorna um novo nó em vez de mudar este.
• Leituras: Kind · Text · Tooltip · ThemeColorSlot? Tone (nunca uma cor fixa, então segue o tema) · ActionId · Detail · Ratio · Url · Children.
• static bool IsAllowedUrl(url) — apenas http/https. Um único predicado que os dois hosts consultam, então eles não podem discordar sobre o que é seguro abrir.

Strings de UI de plugin (SheetForge.Core.Model)

StringOverlayRegistry — correspondência e recusas. language é um código IETF ("en", "ko", "zh-Hans", "pt-BR", …), comparado sem diferenciar maiúsculas/minúsculas. A busca recorre a idioma pedido → inglês → nada encontrado, e o fallback vive aqui para que os dois hosts respondam de forma idêntica.

Quatro registros são recusados, cada um registrando um motivo voltado ao desenvolvedor, em vez de falhar silenciosamente:

• uma chave embutida do produto — uma sobreposição pode adicionar chaves, nunca sobrescrever as próprias frases ou caminhos de menu do produto;
• uma chave+idioma que outro pacote já registrou — o primeiro encontrado vence, porque senão a ordem de instalação decidiria a tela;
• uma chave ou valor vazio;
• um código de idioma que o produto não conhece, que nunca é dobrado em inglês.

Observação de pipeline (SheetForge.Core.Plugins / .Model)

Registros de código (SheetForge.Core.Graphing)

Alvos de referência que vivem no código, expostos à superfície de autoria como abas virtuais travadas. Consumidos pelo Data Studio (barra lateral / grafo / inspector), não pelo validador de importação.

O modelo de leitura do IR (SheetForge.Core.Model)

Referências de asset tipadas (SheetForge.Core.Model)

O <Type> em AssetRef@Group<Type> é resolvido pelo host — o Core não conhece nem o engine, nem os assemblies do projeto — e o Core apenas julga o resultado. Tudo aqui é dado puro.

O codegen lê o dicionário resolvido que o pipeline produz e emite AssetReferenceT<global::FullName> para um nome resolvido; um nome que ele não consegue encontrar nesse dicionário nunca é emitido ao pé da letra — o campo recorre a AssetReference e um aviso AssetTypeUnresolvedFallback é coletado. O nome completo resolvido também é misturado ao fingerprint do esquema.

Tipos de valor visual (SheetForge.Core.Model)

Modelos de valor livres de engine para os três tipos visuais embutidos. Cada um é imutável, IEquatable, e possui a sua própria forma de texto (TryParse / Render) — a mesma notação que a página de Sintaxe da Planilha documenta — então um tipo de plugin que armazena uma cor, uma curva ou um gradiente pode reutilizá-los em vez de inventar uma segunda notação. O Editor os coze (bake) em UnityEngine.Color / AnimationCurve / Gradient e os lê de volta; o navegador os amostra através dos avaliadores abaixo, em vez de reimplementar a matemática.

Erros e resultados (SheetForge.Core.Model / .Reporting)

ImportErrorCode — as famílias que ele cobre:

• marcadores, esquema, tipos, células, chaves/referências e chaves de asset;
• origens/arquivos, csv/xlsx, identificadores de codegen, addressables, baseline/exportação, Google/auth/Push e templates;
• plugins — PluginRegistrationConflict, mais PluginIncompatible quando a declaração de compatibilidade de um assembly cai fora do que este host lê;
• IntId — DuplicateIntId, e para referências IntId@Tab, UnresolvedIntId · TargetTabHasNoIntId;
• @overlap e DomainRuleViolation;
• planilhas de definição de enum — EnumSheetMarkerConflict · DuplicateEnumName · EnumSheetEmptyColumn · InvalidEnumIdentifier · InvalidEnumUnderlyingType · InvalidEnumMemberValue;
• DropdownNotSupportedByFormat, que é um aviso, e não um erro;
• referências de asset tipadas — UnknownAssetType · AmbiguousAssetType · AssetTypeNotReferenceable (uma vez por coluna, na linha @type), AssetTypeMismatch por célula, e o aviso de codegen AssetTypeUnresolvedFallback.

Índices e utilitários (SheetForge.Core.Validation / .Model / .Parsing / .Unparse)

Plano de Push (SheetForge.Core.Unparse)

Público porque IPushApprover.Approve(PushPlan) os expõe; dados puros.

Assembly Editor (SheetForge.Editor)

Configurações, localização, composição (SheetForge.Editor.Pipeline / .Localization)

PluginRegistry — o pacote e o isolamento de slot. O PluginBundle aninhado expõe o PluginSet Set montado — a única fonte de verdade de doze slots, o que é como um slot recém-crescido é lido sem ampliar o pacote — mais nove janelas de conveniência sobre ele: Enums · Parsers · Validators · EdgeContributors · Markers · Templates · GraphShapes · CodeRegistries · Themes. Os construtores anteriores de seis e oito argumentos permanecem como sobrecargas que definem os registries mais recentes como vazios por padrão, comportando-se de forma idêntica às versões anteriores a esses contratos existirem.

O isolamento é do Core, não deste tipo: um plugin que lança uma exceção ao se registrar é relatado pelo nome e pulado, e todo outro slot e plugin ainda se registram.

SheetForgeActions — semântica de conclusão. RunImport/RunPush são fire-and-forget. Seus corpos são async void, porque a thread principal do editor não pode bloquear em IO de rede, então o retorno não é a conclusão — inscreva-se em ImportEvents.ImportCompleted para isso. RunExport/RunHealthCheck/RunLocalizationSync se completam de forma síncrona — RunLocalizationSync percorre o caminho planilha → StringTable que uma conclusão de importação percorre, e sem o pacote Unity Localization ele mostra o aviso de instalação e não muda nada.

Costura de provedor de origem (SheetForge.Editor.Sources)

Pontos de extensão do Data Studio (SheetForge.Editor.Studio)

Do lado do Editor porque devolvem UIElements ou tocam estado de janela — a mesma assimetria justificada de ISheetSourceProvider. Os quatro contratos são descobertos pelo TypeCache (construtor sem parâmetros; sem chamada de registro), e todos são chamados dentro de try/catch. A própria janela (DataStudioWindow) é internal.

Qualquer coisa expressável como dado pertence ao vocabulário Core ISheetForgeStudioPlugin em vez disso, que também renderiza no navegador. Estas são as válvulas de escape sem teto para o que a descrição não consegue dizer.

As últimas quatro entradas não são contratos, mas ferramentas que um widget montado pode usar:

• os próprios valores de skin somente leitura da janela, para que ele possa parecer que pertence a ela;
• o dropdown de chave, para que um widget de célula escolha chaves da mesma forma que a célula embutida faz;
• e o reset do cache de descoberta, para que os seus próprios testes possam redescobrir uma sonda.

StudioInspectorContext — os dois delegates de preparação:

• StageCell recebe aba, recordId, campo e texto bruto canônico. A janela registra o passo de Undo, incrementa a geração da projeção e prepara o endereço lógico.
• StageCells faz o mesmo para várias células que precisam mudar juntas: um único passo de Undo nativo, tudo ou nada. Se uma sequer não puder ser preparada, a sessão não é tocada em nada.

Uma falha é silenciosa em tela de qualquer forma, e somente o portão se explica. Uma origem somente leitura, um pipeline já em execução, ou uma aba baseada em workbook escreve o seu motivo no console. Uma lista vazia, uma gravação sem a sua aba ou campo, e uma chave de registro que não resolve para nenhuma linha não fazem nada e não dizem nada.

StudioPalette — os membros:

• 33 slots de cor: 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.
• Espaçamento: SectionSpace · RowSpace · RuleHeight · ButtonHeight · PrimaryButtonHeight · GlyphWidth.
• Tamanhos de tipo: HeadingFontSize · SectionFontSize · CaptionFontSize.
• FromRgb(uint) · ToHex(uint).

Aprovação de Push (SheetForge.Editor.Push)

Motor de autoria (SheetForge.Editor.Structure / .Pipeline / .Export)

Tipos de valor de preparação (SheetForge.Editor.Structure; StagedCellEdit/StagedNewRow estão em SheetForge.Editor.Windows)

Auxiliares de autoria (SheetForge.Editor.Windows / .Structure)

Assembly Runtime (SheetForge.Runtime)

autoReferenced — utilizável a partir do código do jogo sem uma referência de asmdef.

Tipos gerados (padrão — por projeto, não é API distribuída)

Para cada aba Foo, o codegen emite no seu 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
}

Carregue com SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").

As duas classes são emitidas como partial, então você pode adicionar membros derivados — uma propriedade computada, uma implementação de interface, um operador — no seu próprio arquivo ao lado do gerado, e uma reimportação não vai sobrescrevê-lo.

Um limite: não adicione campos serializados na sua parte. O ScriptableObject cozido (bake) é reconstruído a partir da planilha a cada importação, então qualquer coisa que só a sua parte serializa volta ao seu padrão. Se um valor pertence aos dados, ele pertence a uma coluna.

(A palavra-chave partial não toca no SchemaFingerprint, que é computado somente a partir do esquema, então tornar as classes partial não invalidou um único bake existente.)

Outros assemblies

• SheetForge.Setup — o bootstrap sem dependências para a ausência do Addressables. Nenhuma API pública (tudo internal; ele existe para mostrar uma janela de orientação).

• SheetForge.PluginDemo (um asmdef mesclado + um asmdef Demo.Editor; o namespace do conteúdo permanece SheetForge.Skills) — o pacote de exemplo de referência, não é API do produto. Contém:

  • SkillsPlugin (sete interfaces de plugin — base, validador, aresta, template, grafo, registro de código, tema);
  • Modifier + ModifierCellParser (tipo de célula personalizado), ModifierStatEdgeContributor (contribuidor de aresta);
  • ExamplePipelineAugmenter / ExampleReactiveAugmenter (sobreposições de canvas), ExampleCodeAtoms (o registro de código _Refs);
  • ExampleStudioUi (ações declarativas, painel, selo de coluna e hint de editor de célula), ExampleImportObserver (observador de pipeline);
  • ExampleStageStripWidget / ExampleInspectorAction / ExampleStudioPanel (pontos de extensão Editor do Data Studio, pintados a partir da paleta pública), ExampleLocStrings (registra esses rótulos em dois idiomas — no assembly principal, para que o navegador também os mostre);
  • uma declaração SheetForgePluginCompat em nível de assembly;
  • SkillRunner (consumo em runtime), tipos Example* gerados no namespace padrão SheetForge.Generated (o isolamento é feito pelo prefixo Example*, não por um namespace separado).

  O exemplo sem plugin SheetForge.CoreDemo é distribuído com zero asmdefs (compila dentro de Assembly-CSharp).

Páginas relacionadas

• Autoria de Plugins — os contratos em uso, com exemplos completos
• Kernel de Autoria — os tipos do motor em contexto
• Capacidades e Limites — os limites comportamentais dessas APIs