Primeiros Passos

Requisitos

• Unity 6 (desenvolvido e testado na 6000.0.79f1, template URP).
• Pacote Addressables (com.unity.addressables) — obrigatório. O carregamento por endereço é o caminho de execução, e o tipo AssetRef@Group precisa do Addressables.
  • Sem o pacote, o asset ainda compila, porque todo código que usa o Addressables fica protegido atrás de uma version-define SHEETFORGE_ADDRESSABLES.
  • Mas o pipeline — importação · exportação · push · gravação de volta da autoria — permanece travado. Cada ponto de entrada mostra um aviso de instalação, e a janela Primeiros Passos orienta a instalação.

Instalando o Addressables

• Caminho principal: quando você importa o asset a partir da Asset Store, o aviso "Package Manager dependencies" aparece antes da compilação — escolha Install e o Addressables é instalado junto.
• Rede de segurança: se você clicou em Skip (ou importou manualmente), o pipeline permanece travado e a janela Primeiros Passos orienta você a instalar a partir da sua linha de status do Addressables. Essa janela roda mesmo sem o Addressables, porque o Editor continua compilando.
  • A janela de bootstrap sem dependências SheetForge.Setup também detecta o pacote ausente ao carregar o editor e mostra um aviso uma vez por sessão. Como ela não tem dependências, continua funcionando mesmo quando outros erros de compilação bloqueiam os assemblies principais.
• Não existe uma instalação programática em um clique: as regras de submissão da Asset Store restringem a instalação programática de pacotes, então a janela apenas orienta você.
• O aviso reflete o estado real de instalação. Ele explica que o produto compila mas suas funcionalidades ficam travadas até o pacote ser instalado, e aponta você para a janela Primeiros Passos em seguida. Você pode reabri-la a qualquer momento em Tools ▸ SheetForge ▸ Addressables Setup (esse menu sobrevive mesmo se os assemblies principais falharem ao compilar por algum outro motivo).

Atualizando a partir de uma versão anterior

Uma importação de .unitypackage adiciona e atualiza arquivos, mas nunca os exclui. Então um arquivo que uma versão mais nova aposentou pode ficar remanescente em Assets/SheetForge, ainda referenciando uma API que não existe mais. A compilação quebra, e parece que a atualização quebrou o seu projeto. Duas redes de proteção cobrem isso:

• Detecção automática. No carregamento do editor, o bootstrap SheetForge.Setup, sem dependências, verifica os caminhos que este produto aposentou. Se encontrar algum, oferece para excluí-los — listando todo caminho na caixa de diálogo primeiro e não tocando em nada até você aprovar. Ele vive em seu próprio assembly justamente para sobreviver aos erros de compilação que existe para corrigir.
• Ponto de partida limpo. Para uma atualização com limpeza garantida, exclua a pasta Assets/SheetForge existente, importe o novo pacote e depois execute Executar Importação uma vez para reconstruir o que a exclusão levou junto. Os assets de configurações e os SOs do bake (Assets/SheetForgeBaked) ficam fora dessa pasta e não são afetados, e o mesmo vale para o código gerado assim que ele estiver no seu local padrão Assets/SheetForgeGenerated. Se o seu projeto ainda gera código no local antigo dentro do produto (Assets/SheetForge/Runtime/Generated), excluir a pasta remove esse código e a reimportação passa a escrevê-lo em Assets/SheetForgeGenerated. Essa é a forma suportada de mover um projeto existente para o novo local. O que nenhuma reimportação consegue reconstruir é o que você colocou dentro de Assets/SheetForge por conta própria — um asset de configurações salvo ali, seus próprios scripts de plugin, arquivos de planilha — então mova isso para fora primeiro.

Um limite que vale a pena declarar com clareza: a limpeza automática exclui os arquivos aposentados do próprio SheetForge, nunca os seus. Se o seu próprio código de plugin implementa um contrato que foi aposentado desde então, ele precisa ser portado manualmente. Em resumo:

• um construtor de grafo por aba (IGraphShapeBuilder / GraphSpecBuilder) se torna o augmenter do canvas de registros (IRecordCanvasAugmenter / CanvasAugmentBuilder), que acrescenta ao fechamento que o canvas já construiu em vez de construir o quadro inteiro;
• GraphMode desapareceu, já que a direção agora é controle do próprio canvas;
• StudioGraphContext.ShapeId / ModeId ainda compilam, mas cada um retorna uma constante, então qualquer comparação AppliesTo contra eles deve simplesmente ser excluída;
• IAuthorableGraphShape.CreatableTabs permanece inalterado.

A tabela completa do que cada contrato aposentado se tornou está na seção Upgrade notes do CHANGELOG.md no repositório de origem (o pacote de lançamento não o distribui). Membros aposentados que ainda compilam são marcados [Obsolete] em vez de removidos, então uma atualização os expõe como avisos em vez de quebrar o build.

A janela Primeiros Passos (comece aqui)

Depois que o Addressables está instalado, uma janela Primeiros Passos abre automaticamente uma vez por sessão do editor — a cada início do Editor, mas não de novo depois de um domain reload. Ela continua fazendo isso enquanto o alternador "Mostrar esta janela ao iniciar o Editor" estiver ativado, o que acontece por padrão.

É o ponto de entrada recomendado. Você pode reabri-la a qualquer momento em Tools ▸ SheetForge ▸ Primeiros Passos, e desativar a abertura automática com esse alternador na parte inferior (a escolha é armazenada por projeto e por usuário).

Ela reúne todo o fluxo de primeira execução em um só lugar:

1. Painel de status — um semáforo de três linhas: Addressables instalado, um asset de configurações de importação ativas, e primeira importação concluída. Cada linha mostra ✓ ou ✗, e o que ainda precisa de atenção tem um botão de ação bem ao lado (New settings asset, ou Run Import).
2. Configurações de importação — lista todo asset SheetForgeSettings com um botão de rádio para escolher qual está ativo, além de um botão New settings asset e um botão Reveal para localizar cada asset.
3. Exemplos — um clique importa o pacote Plugin Demo ou Core Demo.
4. Começar a partir de um template — escolha um dos dois embutidos, escolha "from scratch" para definir os campos você mesmo, ou use um template registrado por plugin. "Use" abre o painel de criação do Data Studio já preenchido com ele. Isso exige um asset de configurações ativo com uma origem gravável; se você ainda não tem um, o requisito é mostrado.
   • Os embutidos são Exemplo de item, que usa somente tipos básicos, e Enum definitions, que monta uma planilha @enum.
   • As abas de demonstração de skill só aparecem aqui quando um plugin de template, como o Plugin Demo, está presente.
5. Executar — Run Import (usa as configurações ativas) e Abrir Data Studio.
6. Open Full Guide — um link para este site de documentação.

As seções abaixo explicam cada etapa em detalhe; você pode fazer tudo a partir da janela, ou pelos menus e pela janela Project como descrito.

Ainda mais rápido — arrastar e soltar. Se você já tem uma pasta de arquivos de planilha, abra o Data Studio e arraste essa pasta sobre ele — ou um único arquivo .tsv/.csv/.xlsx. Ele oferece para criar um asset de configurações de importação que lê a partir dessa pasta e torná-lo ativo, sem configuração manual.

Aberto sem nenhuma configuração ativa, o Studio mostra um painel "Comece agora" com os mesmos botões de criar / importar demonstração / Primeiros Passos, em vez de uma tabela vazia.

Verificação de integridade. A qualquer momento, abra o Data Studio e escolha ⋯ ▸ Verificação de integridade na barra de ferramentas para um diagnóstico rápido e sem rede. Ele relata ✓/✗ — cada um com uma correção sugerida — para:

• as configurações ativas;
• se a origem está alcançável (uma pasta local que existe, ou um id do Google + caminho da chave);
• se existe um baseline de importação;
• se o código gerado, os SOs do bake e os addressables estão atualizados.

Idioma da UI. Na primeira vez que você abre um projeto, o SheetForge define seu idioma de UI a partir do idioma do sistema do seu Editor (mapa de nove idiomas; qualquer outro permanece em inglês). Ele nunca sobrescreve um idioma que você já escolheu; mude-o a qualquer momento em Preferences ▸ SheetForge (veja Localização).

1. Escolha um asset de configurações de importação

Crie um a partir do botão New settings asset da janela Primeiros Passos, ou clique com o botão direito na janela Project → Create ▸ SheetForge ▸ Import Settings (os rótulos do menu seguem a configuração do seu idioma — veja Localização).

Você pode manter vários assets de configurações (por exemplo, um por origem de dados) e escolher qual está ativo. Menus, o Data Studio e importações usam todos o ativo. A escolha é armazenada por projeto e por usuário — um ponteiro EditorPrefs, então sem gerar ruído no VCS e independente por colega de equipe — e se o asset ativo for excluído, o ponteiro se autorrepara.

Com um único asset de configurações, a sua primeira importação o seleciona automaticamente; nenhuma escolha explícita é necessária. Quando existem vários, escolha o ativo na janela Primeiros Passos ou no dropdown que aparece na barra de ferramentas do Data Studio.

Configure o asset SheetForgeSettings:

O inspetor de configurações mostra apenas os campos relevantes para o modo de origem atual — o modo Local oculta os campos do Google; o gidMap aparece somente no modo Google ExportUrl.

2. Segurança da chave de conta de serviço (origem Google)

Usando uma origem LocalFile? Pule esta seção.

Usar o Planilha do Google no modo SheetsApi exige uma chave JSON de conta de serviço. Se você nunca criou uma, Configuração da Planilha do Google percorre todo o processo passo a passo. Mantenha essa chave fora de Assets/ e fora do seu repositório — nunca faça commit dela.

• Recomendado: defina a variável de ambiente SHEETFORGE_SHEETS_KEY com o caminho absoluto do seu arquivo de chave. Ela tem precedência sobre o campo de caminho da chave no asset de configurações, então cada desenvolvedor injeta sua chave local sem deixar nenhum caminho no repositório.
• Se você precisar colocar um caminho no campo de configurações, aponte-o para fora do repositório (por exemplo, C:/keys/service-account.json). Um arquivo de chave dentro de Assets/ vazaria para builds e commits.

3. Execute sua primeira importação

Tools ▸ SheetForge ▸ Data Studio, depois pressione ↓ Pull from source na barra de ferramentas.

• O pipeline busca → valida → (em caso de sucesso) gera código → faz o bake. Os diagnósticos são impressos no console como um relatório amigável no seu idioma.
• A primeira importação se completa automaticamente em dois estágios internos. Quando um esquema é novo ou foi alterado, a importação grava o código gerado, o que dispara uma recompilação/domain reload. Ela então retoma automaticamente o bake depois do reload. Uma única ação do usuário; nenhum novo disparo manual. Se a compilação falhar, a retomada automática realiza um safe-abort (limite de 3 tentativas) e deixa uma frase acionável no console.
• A validação coleta todos os diagnósticos no momento da importação (ela nunca para no primeiro erro). Se existir sequer um erro, nenhuma saída é produzida (sem montagem parcial).
• A importação registra automaticamente o Database SO de cada aba no grupo Addressables SheetForge, no endereço "SheetForge/{tab}" — o seu jogo carrega por esse endereço estável (veja Conceitos Fundamentais).

4. Carregue dados no seu jogo

using SheetForge.Runtime;
using UnityEngine.ResourceManagement.AsyncOperations;
 
AsyncOperationHandle<DefinitionDatabase> handle = SheetForgeDatabases.LoadAsync("Items");
await handle.Task;   // or coroutine yield / handle.WaitForCompletion()
if (handle.Status == AsyncOperationStatus.Succeeded)
{
    DefinitionDatabase db = handle.Result;
    // For strong typing: SheetForgeDatabases.LoadAsync<ItemsDatabase>("Items")
}
SheetForgeDatabases.Release(handle);   // Addressables is ref-counted — release what you load

O assembly SheetForge.Runtime é autoReferenced, então o código do jogo pode usá-lo sem uma referência de asmdef.

Nunca referencie um SO do bake diretamente a partir de uma cena. SOs do bake são caches não versionados e específicos de cada máquina — os GUIDs deles diferem entre máquinas e entre re-bakes, então uma referência direta de cena fica Missing na máquina de um colega de equipe. O carregamento por endereço absorve isso por design.

5. Experimente as cenas de demonstração

Dois exemplos são distribuídos como pacotes de importação seletiva. O exemplo de plugin SheetForge.PluginDemo (tipos personalizados, enums, validadores, arestas) e um exemplo sem plugin SheetForge.CoreDemo (apenas tipos embutidos do core) incluem, cada um, uma cena de demonstração "abrir e dar Play".

As importações de demonstração vivem em um único lugar — a seção Exemplos da janela Primeiros Passos — então não existe uma folha de menu para elas.

• Demonstração do plugin: pressione Importar Plugin Demo no Primeiros Passos, ou dê duplo clique em Assets/SheetForge/Examples/SheetForgePluginDemo.unitypackage. Qualquer um dos dois restaura o pacote em Assets/SheetForge.PluginDemo/…. Cena: Demo/PluginDemo.unity (menu Tools ▸ SheetForge ▸ Open Plugin Demo Scene, adicionado pelo próprio exemplo). Ela carrega os bancos de dados de exemplo por endereço e mostra uma habilidade montada a partir dos dados da planilha (dano total da bola de fogo = Damage 10 + DamageOverTime 3×3 = 19).
• Demonstração somente do core: pressione Importar Core Demo no Primeiros Passos, ou dê duplo clique em Assets/SheetForge/Examples/SheetForgeCoreDemo.unitypackage. Isso restaura o pacote em Assets/SheetForge.CoreDemo/…. Cena: Demo/CoreDemo.unity (menu Tools ▸ SheetForge ▸ Open Core Demo Scene). Ela mostra equipamentos montados a partir de referências de item usando apenas tipos embutidos do core. A demo também traz uma planilha de localização (ExampleStrings) cujas chaves os itens referenciam por células LocRef — veja Planilhas de localização.

(Os rótulos finais desses menus de exemplo permanecem em inglês, pois ficam fora do pipeline principal de menus localizados.)

Cada pacote de demonstração empacota um asset de configurações pré-configurado. Quando você importa um pacote de demonstração, o SheetForge ativa automaticamente esse asset de configurações empacotado se você não tiver nenhuma configuração ativa própria. Se você já tem uma, ele abre a janela Primeiros Passos para sugerir a troca, em vez de sobrescrever silenciosamente a sua escolha. Então o fluxo de demonstração é simplesmente: importar o pacote → (configurações auto-ativadas) → Run Import → Play — nenhuma criação manual de configurações.

Uma demonstração só funciona depois de rodar uma importação na sua máquina — os endereços do Addressables que ela carrega existem somente depois que a importação rodou uma vez (o asset do grupo Addressables é um cache não versionado e autorreparável). Antes disso, a cena de demonstração mostra uma mensagem de orientação em vez de falhar.

Para finalizar uma demonstração (depois de importar o pacote de exemplo acima):

1. Garanta que o asset de configurações empacotado da demonstração esteja ativo (a janela Primeiros Passos o mostra, ou a importação o ativou automaticamente). Ele usa origem = LocalFile, pasta local = a pasta DemoSheets do exemplo, e o namespace padrão SheetForge.Generated, então a reimportação regenera os tipos versionados no próprio lugar.
2. Nenhuma ação necessária para a referência de script da demonstração do plugin. A aba ExampleEffects inclui um exemplo AssetRef@Scripts. O próprio exemplo registra DemoScripts/special_effect.lua.txt sob o endereço special_effect em um grupo Addressables Scripts, por conta própria e de forma idempotente, então a primeira importação passa na validação de referência. Só se ele registrar em log um aviso de que não conseguiu fazer isso (um asset ausente, por exemplo) é que você precisa adicionar essa entrada manualmente — ou excluir a linha, se você não quiser o exemplo do Addressables.
3. Pressione ↓ Pull from source em Tools ▸ SheetForge ▸ Data Studio uma vez (ou o botão Run Import no Primeiros Passos), depois abra a cena de demonstração e pressione Play.

6. Resumo do fluxo de trabalho em equipe

• SOs do bake (Assets/SheetForgeBaked) são um cache específico de cada máquina. Coloque-os no gitignore; depois de clonar, cada colega de equipe executa Executar Importação uma vez.
• O código gerado (Assets/SheetForgeGenerated) é o código-fonte do seu próprio projeto, e a recomendação é fazer commit dele. Assim, um clone novo compila antes de alguém ter rodado uma importação, e mudanças de esquema aparecem na revisão de código. É uma saída determinística, então a importação de um colega produz os mesmos bytes e não gera ruído. Colocá-lo no gitignore em vez disso também funciona; o Executar Importação pós-clone é então o que restaura a compilação.
• Um hook de verificação de atualização pré-build checa, para cada tipo de Database gerado versionado, se (i) o SO do bake existe, (ii) o fingerprint do esquema corresponde ao baseline, e (iii) o registro no Addressables existe. Se algo falhar, o build é abortado com uma frase acionável, então uma máquina clonada/de CI nunca consegue publicar um cache vazio silenciosamente.

Páginas relacionadas

• Conceitos Fundamentais — por que a planilha é canônica e quais são os estágios do pipeline
• Sintaxe da Planilha — como escrever sua primeira planilha
• Fontes, Exportação e Envio — detalhes da configuração do Google
• FAQ e Solução de Problemas — problemas na primeira execução