Conceitos Fundamentais

A planilha é a única fonte da verdade

Existe exatamente uma forma canônica dos seus dados: a planilha. Tudo o mais é derivado dela:

• O IR (Definições imutáveis) é a forma validada e montada da planilha.
• As classes C# geradas são o esquema do IR, tornado fortemente tipado.
• Os ScriptableObjects do bake são os valores do IR, tornados carregáveis — um cache de consulta, nunca uma verdade independente.

Toda modificação passa pela planilha e precisa passar pela validação de reimportação para se tornar real. Editar um SO do bake diretamente criaria uma segunda verdade e contornaria a validação — o produto deliberadamente não oferece suporte a isso como fluxo de trabalho.

(O alternador "Edição de teste" do inspector existe para experimentos temporários em tempo de execução. Ele nunca é gravado de volta, e a reimportação o apaga.)

Por que isso importa: projetos que tratam o SO como a fonte da verdade acabam com dados não validados se distanciando da planilha, sem nenhuma forma de reconciliá-los. Aqui, a reconciliação é estrutural — regenere a partir da planilha, sempre.

O IR — uma montagem imutável e validada

O IR é o que a validação produz. Para cada aba, ele contém uma SheetTable (esquema + registros) cujas células já são valores tipados: int, float, valores de enum, referências de registro, referências de asset, listas, tipos personalizados de plugin.

Propriedades principais:

• Sem montagem parcial. Se existir um único erro em qualquer lugar, o IR não é construído (ImportResult.Success == false ⇔ Registry == null — um invariante rígido).
• Sem nulls. Uma célula opcional vazia materializa imediatamente o valor padrão do seu tipo, sinalizado como IsDefaulted — os consumidores nunca precisam checar null.
• Imutável. O IR é somente leitura depois da montagem; as saídas (codegen, bake, export) o leem, nunca o modificam.

O pipeline

fetch → parse markers/schema → parse cells → validate (keys, references,
@overlap, asset keys, domain rules) → assemble IR → codegen (.cs) → bake (SO)
       └──────────────── collect ALL diagnostics ────────────────┘

• A validação coleta tudo. Você recebe a lista completa de problemas em uma única execução — onde / o quê / por quê / como, por erro — em vez de corrigir um erro por reimportação.
• O codegen é o último estágio, depois da validação e da montagem de valores, porque gravar arquivos .cs dispara um domain reload. O pipeline é estruturado de forma que o reload seja seguro e a cadeia retome automaticamente depois dele.
• Os erros são objetos estruturados, renderizados como frases. Cada erro carrega a aba, a linha (com base em 1), e a letra da coluna e o nome do campo. Ele também carrega o valor problemático, a regra violada e uma sugestão acionável (com propostas de correspondência mais próxima para erros de digitação). Os mesmos objetos também são renderizados como coordenadas de máquina para logs/CI.

A cadeia de importação automática

Quando um esquema é novo ou foi alterado, uma única execução de importação faz internamente:

1. Grava o código gerado → a Unity compila → domain reload.
2. Depois do reload, a cadeia retoma sozinha e completa o bake.

Você nunca precisa disparar nada manualmente de novo. Se a compilação falhar (por exemplo, se o código do seu jogo referenciar um campo que uma ação de Renomear acabou de alterar), a cadeia realiza um safe-abort com uma frase acionável no console em vez de entrar em loop (limite de 3 tentativas, log de retomada).

Tipagem forte, sem parsing em tempo de execução

O codegen lê @name / @type / @desc e emite, para cada aba Foo:

• FooDefinition — uma classe record fortemente tipada, um campo por coluna; @desc se torna o comentário de documentação XML e o tooltip do inspector.
• FooDatabase : DefinitionDatabase — o SO contêiner por aba, com Records, buscas de id preguiçosas (lazy) e um SchemaFingerprint.

O bake grava campos realmente tipados — zero parsing de texto em tempo de execução, nenhuma reflection em tempo de execução, o que o torna seguro para IL2CPP (sem riscos de stripping).

Carregamento por endereço — como o cache permanece compartilhável

SOs do bake são caches específicos de cada máquina, com GUIDs específicos de cada máquina. Referências diretas de cena a eles quebrariam entre máquinas diferentes. Em vez disso:

• A importação registra automaticamente cada Database SO no grupo Addressables SheetForge, no endereço estável "SheetForge/{tab}" (re-bakes reconectam o novo GUID ao mesmo endereço; abas excluídas são limpas).
• O código do jogo carrega por endereço: SheetForgeDatabases.LoadAsync<FooDatabase>("Foo").
• O asset do grupo Addressables é gitignored e autorreparável (recriado pela importação quando estiver ausente).

Baselines — como o round-trip preserva sua planilha

Na importação, um snapshot normalizado da estrutura de cada aba (linhas de marcador, ordem das colunas, comentários, texto escrito por humanos) é armazenado como o baseline. A Exportação então troca os valores atuais do SO na estrutura do baseline.

Então um round-trip planilha → importação → Exportação → planilha preserva sua planilha 100% estruturalmente, e preserva os valores semanticamente:

• 1.0 ↔ 1 é permitido porque o valor é idêntico.
• Floats usam o formato de round-trip mais curto.
• O separador decimal é sempre ., independente de localidade.

O que é versionado e o que é regenerado

Extensão sem modificação

Contratos de registro permitem que plugins se integrem ao pipeline com zero edições no Core:

• parsers de tipo de célula (incluindo tipos wrapper), validadores de domínio, contribuidores de aresta;
• marcadores estruturais personalizados, templates de "Criar planilha", provedores de origem de importação;
• as sobreposições de canvas, registros de código, widgets, ações, widgets de célula, predefinições de cor e strings de UI do Data Studio.

O Core nunca referencia um pacote de domínio; a dependência de mão única é imposta pelo compilador. A lista autoritativa — e a sua contagem — está em Autoria de Plugins.

Páginas relacionadas

• Sintaxe da Planilha — a gramática de marcadores e tipos que o parser lê
• Data Studio — autoria em cima deste modelo
• Fontes, Exportação e Envio — mecânica do round-trip
• Kernel de Autoria — o motor por trás da janela de autoria