SheetForge — Pipeline de Dados Orientado por Planilhas para Unity

O SheetForge transforma uma planilha (Planilha do Google ou TSV/CSV/xlsx local) em classes C# fortemente tipadas e ScriptableObjects gerados por bake que o seu jogo carrega por um endereço estável.

Cada célula é validada na importação. Um valor incorreto é detectado quando você importa, não quando a linha é atingida pela primeira vez em tempo de execução. Isso é relatado como uma frase com sua aba, linha, coluna e uma correção sugerida. O pipeline funciona como um compilador: ele coleta todos os erros em uma única passagem e monta as Definições imutáveis somente a partir de uma planilha totalmente limpa.

A planilha é sempre a única fonte da verdade; o SO do bake é apenas um cache de consulta. Em torno disso:

• Round-trip. A importação tem um caminho reverso: Exportação/Push grava valores de volta na planilha preservando sua estrutura.
• Autoria no editor. Uma janela de autoria no editor — o Data Studio — edita a planilha com desfazer via Ctrl+Z.
• UI localizada. A UI do produto é distribuída em 10 idiomas.
• Extensão por plugin. Plugins adicionam tipos de célula, regras de validação, arestas de grafo e origens de importação sem editar o Core. O limite é imposto pelo compilador C#.

A API pública é um kernel de autoria: uma segunda superfície de autoria, como um canvas de grafo de nós, pode ser construída sobre ela sem nenhuma alteração no Core ou no Editor — veja Kernel de Autoria.

Requisitos: Unity 6 e o pacote Addressables (com.unity.addressables) — o carregamento em tempo de execução é baseado em endereço. O asset compila sem o pacote, mas o pipeline permanece travado até que ele seja instalado. Primeiros Passos cobre a instalação guiada.

Como funciona (em resumo)

              ENTRANCES                    TRUTH                       EXITS
  ┌───────────────────────────┐   ┌──────────────────┐   ┌───────────────────────────────┐
  │ Google Sheets (SheetsApi/ │   │                  │   │ Strongly-typed C# classes     │
  │   ExportUrl)              │──▶│  Immutable IR    │──▶│   (codegen, last stage)       │
  │ Local TSV / CSV / xlsx    │   │  (Definitions)   │   │ Per-tab Database SO (bake)    │
  │ Data Studio (in-editor    │   │                  │   │   → Addressables address      │
  │   authoring, WYSIWYG)     │   │  built ONLY if   │   │   "SheetForge/{tab}"          │
  │ Custom source providers   │   │  validation is   │   │ Export / Push back to the     │
  │   (plugin, e.g. DB/REST)  │   │  100% clean      │   │   sheet (round-trip)          │
  └───────────────────────────┘   └──────────────────┘   └───────────────────────────────┘

Toda entrada produz o mesmo IR validado, e toda saída é derivada dele. Um erro em qualquer lugar significa nenhuma saída — sem montagem parcial.

Cada erro informa:

• onde — aba · linha · letra da coluna e nome do campo
• o quê — o valor problemático
• por quê — a regra violada
• como — uma sugestão acionável

Isso substitui o que uma equipe normalmente escreveria por tabela: o parser, o validador, o gerador de código e o caminho de carregamento.

Números principais

• Importação de 50,000 linhas × 20 colunas ≈ 628 ms no editor em execução (Mono); 50 abas × 2,000 linhas com 180k células de referência ≈ 294 ms.
• Códigos de erro estruturados — uma referência completa de validação.
• 10 idiomas para toda a UI do produto (menus, a janela de autoria, diálogos, relatórios, tooltips).
• Suíte de testes: um conjunto duplo de testes headless de .NET e testes Unity EditMode, 0 falhas — os números exatos estão em Capacidades e Limites ▸ Estado verificado.

Mapa da documentação

SheetForge Web (companheiro)

Um aplicativo web companheiro em web.sheetforge.workers.dev traz autoria, validação e reflexão de planilha para o navegador.

Ele compila o mesmo core em C# para WebAssembly — não uma reimplementação — de modo que o parser e o validador nunca podem divergir do asset da Unity, e uma DLL de plugin construída na Unity carrega sem modificação. Codegen e bake continuam sendo responsabilidade exclusiva da Unity; a saída web é a planilha refletida.

As três páginas web acima cobrem o aplicativo, seu mercado de plugins e seu acesso a Planilhas do Google. Toda regra de sintaxe de planilha deste site — incluindo a paridade de referência de IntId@Tab — vale de forma idêntica no navegador.

Princípios de design

1. A planilha é canônica. A edição direta do SO não é um fluxo de trabalho. Tudo passa pela planilha e pela validação de reimportação. (Existe uma opção de "Edição de teste" para experimentos temporários em tempo de execução — ela nunca é gravada de volta e desaparece na reimportação.)
2. Colete tudo, não monte nada quebrado. A validação nunca para no primeiro erro, e um único erro significa nenhuma saída. Você corrige uma lista completa, de uma vez, em vez de um loop de corrigir-um-reimportar.
3. Autoria WYSIWYG. No Data Studio, tudo que você prepara fica imediatamente visível exatamente como vai ficar no resultado final — colunas adicionadas aparecem, linhas excluídas somem, antes mesmo de qualquer gravação na planilha.
4. Totalmente automático. Após uma ação de autoria, codegen → recompilação → bake se completa sem que você precise disparar nada de novo, mesmo com o domain reload.
5. Extensão aberta-fechada. Novos tipos de célula, regras de validação, arestas de grafo e origens de importação se integram por registro — o pipeline nunca é modificado.
6. Limites documentados. O que o produto não consegue fazer é documentado com a mesma precisão do que ele consegue. Veja Capacidades e Limites.
7. Dados abertos. A verdade é um simples arquivo TSV/CSV/xlsx ou uma planilha do Google, legível por qualquer ferramenta. Remover o SheetForge remove o pipeline, não os seus dados.

Páginas relacionadas

• Comece aqui: Primeiros Passos
• Entenda o modelo: Conceitos Fundamentais