FAQ e Solução de Problemas

Respostas organizadas por sintoma. Todo erro de importação também carrega sua própria frase de onde/o quê/por quê/como no relatório do console — comece por ali.

Configuração e primeira execução

"Importei o asset sem o Addressables — ele compila? Por que a importação está travada?"

O asset compila sem o Addressables: o código que usa o Addressables fica protegido atrás de uma version-define SHEETFORGE_ADDRESSABLES. O carregamento por endereço e o tipo AssetRef@Group realmente precisam do com.unity.addressables, então o pipeline inteiro (importação · exportação · push · gravação de volta) fica travado até você instalá-lo. Cada ponto de entrada mostra um aviso de instalação e para — nenhuma execução parcial.

Instale o com.unity.addressables via Package Manager. A linha do Addressables na janela Primeiros Passos tem um botão Open Package Manager, e essa janela roda normalmente em vez de ficar bloqueada pelo Safe Mode, porque o Editor compila sem o pacote.

Se você ainda vir erros de compilação depois de instalar, eles vêm de outro código do projeto — o SheetForge compila tanto com quanto sem o pacote.

"Atualizei para uma versão mais nova e agora o projeto não compila."

Uma importação de .unitypackage adiciona e atualiza arquivos, mas nunca os exclui. Então um arquivo que este produto aposentou em uma versão posterior pode ficar remanescente e referenciar uma API que não existe mais.

No carregamento do editor, o bootstrap SheetForge.Setup, sem dependências, detecta esses caminhos aposentados conhecidos e oferece para excluí-los, listando todo caminho antes de tocar em qualquer coisa. Aprove a caixa de diálogo e a compilação se recupera. Como ele vive em seu próprio assembly, continua funcionando enquanto os assemblies principais estão falhando. Para pular a solicitação por completo, exclua a pasta Assets/SheetForge antes de importar o novo pacote.

O que isso não cobre é o seu próprio código escrito contra um contrato que foi aposentado desde então. Porte-o manualmente usando a tabela Upgrade notes no CHANGELOG.md no repositório de origem — o pacote de lançamento não distribui esse arquivo — e Primeiros Passos resume o que ela diz.

"O Create Sheet só mostra os templates embutidos — onde está o template de demonstração de skill? / Como eu adiciono o meu próprio?"

A lista embutida do Create Sheet vem com dois templates — Exemplo de item (somente tipos básicos) e Enum definitions, que monta uma planilha @enum — mais "do zero".

Templates de domínio que precisam de um plugin (como a demonstração de skill) são registrados pelo próprio plugin, então eles só aparecem quando o plugin está presente. Importe o pacote Plugin Demo e o template Skill demo aparece. Para distribuir o seu próprio, implemente ISheetForgeTemplatePlugin — veja Autoria de Plugins §4.6.

"Por onde eu começo? / Uma janela fica abrindo toda vez que abro o Editor."

Essa é a janela Primeiros Passos. Ela abre automaticamente na primeira vez que o Editor carrega e é o ponto de entrada recomendado — status do Addressables, escolha do asset de configurações ativo, importação de um exemplo, e execução da sua primeira importação, tudo em um só lugar.

Desative a abertura automática com o alternador "Mostrar esta janela ao iniciar o Editor" na parte inferior, e reabra-a a qualquer momento em Tools ▸ SheetForge ▸ Primeiros Passos.

"Importei um pacote de demonstração, mas nada acontece — não há asset de configurações nem grupo addressable."

Cada pacote de demonstração empacota um asset de configurações pré-configurado, e importar o pacote o ativa automaticamente — mas apenas quando você não tem nenhuma configuração ativa própria. Se você já tem uma, a janela Primeiros Passos abre para sugerir a troca, em vez de mudar sua configuração silenciosamente.

Depois pressione ↓ Pull from source em Tools ▸ SheetForge ▸ Data Studio uma vez: isso cria o grupo addressable e os endereços por aba automaticamente. Fluxo: importar o pacote → (configurações ativadas automaticamente) → Run Import → Play.

"A cena de demonstração só mostra uma mensagem de texto em vez da demonstração."

A demonstração carrega pelo endereço do Addressables, e esses endereços só existem depois de uma importação na sua máquina (o asset do grupo é um cache não versionado e autorreparável). Importe o pacote de demonstração (suas configurações são ativadas automaticamente) e execute Executar Importação uma vez — veja Primeiros Passos §5.

(Os tipos versionados das demonstrações usam o namespace padrão SheetForge.Generated, então nenhuma configuração generatedNamespace é necessária — a reimportação os regenera no próprio lugar.)

"A primeira importação da demonstração do plugin falha com `UnknownAssetGroup 'Scripts'`."

A demonstração do plugin tem uma coluna script tipada como List<AssetRef@Scripts>, que precisa de um grupo do Addressables chamado Scripts. Grupos do Addressables são específicos de cada máquina (não versionados), então uma demonstração recém-importada ainda não o tem.

A demonstração configura esse grupo automaticamente na importação (PluginDemoAddressableSetup, disparado no domain reload e ao abrir a cena de demonstração), então uma importação normal simplesmente funciona. Se você ainda vir o erro, reabra a cena de demonstração (Tools ▸ SheetForge ▸ Open Plugin Demo Scene) para disparar a configuração, depois reimporte.

Isso se aplica somente à demonstração do plugin — os seus próprios grupos AssetRef@… são aqueles que você mesmo registra.

"Qual asset de configurações é usado quando eu tenho mais de um?"

O ativo. Menus, o Data Studio e importações usam todos o asset de configurações ativo. Escolha-o na janela Primeiros Passos ou no dropdown da barra de ferramentas do Data Studio (mostrado apenas quando existe mais de um).

Com um único asset de configurações, a primeira importação o seleciona automaticamente. A escolha é armazenada por projeto e por usuário (um ponteiro EditorPrefs — sem gerar ruído no VCS), e se autorrepara se o asset ativo for excluído.

"Já tenho uma pasta de planilhas — qual é a forma mais rápida de apontar o SheetForge para ela?"

Abra o Data Studio e arraste a pasta (ou um único arquivo .tsv/.csv/.xlsx) sobre ele.

Ele oferece para criar um asset de configurações de importação que lê a partir dessa pasta e o torna ativo, sem preenchimento manual de campos. Se você já tem configurações ativas, a caixa de diálogo avisa isso e oferece para trocar.

"Como eu verifico se o meu projeto está configurado corretamente / por que a importação não roda?"

Escolha ⋯ ▸ Verificação de integridade na barra de ferramentas do Data Studio. Ela relata ✓/✗ com uma correção sugerida para:

as configurações ativas;
a alcançabilidade da origem — uma pasta local que existe, ou um id do Google + caminho da chave de conta de serviço, sem chamada de rede;
o baseline de importação;
a atualidade do código gerado/bake/addressable.

Os resultados vão para o Console mais uma caixa de diálogo de resumo.

"Os menus e a UI abriram em um idioma que eu não escolhi."

Na primeira abertura de um projeto, o SheetForge define sua UI a partir do idioma do sistema do seu Editor (nove idiomas mapeados, caso contrário inglês). Ele nunca sobrescreve um idioma que você mesmo definiu. Mude-o a qualquer momento em Preferences ▸ SheetForge — veja Localização.

(Mudar o idioma dispara uma recompilação curta, porque os rótulos de menu são regenerados.)

"Cloneei o repositório e minhas referências de cena para SOs do bake estão Missing."

Esperado: SOs do bake são caches específicos de cada máquina, com GUIDs específicos de cada máquina. Nunca os referencie diretamente a partir de cenas — carregue por endereço (SheetForgeDatabases.LoadAsync("Tab")). Execute a importação uma vez para reconstruir o seu cache local.

"Meu build foi abortado com uma mensagem do SheetForge."

Isso é o hook de verificação de atualização pré-build te protegendo de publicar um cache vazio/desatualizado. Faça o que a frase diz — pressione ↓ Pull from source em Tools ▸ SheetForge ▸ Data Studio — e faça o build novamente.

Importação e validação

"A importação rodou, encontrou erros, e não produziu nada."

Por design: um erro ⇒ nenhuma saída (sem montagem parcial). O relatório lista todo problema com coordenadas e correções sugeridas — corrija-os em uma única passagem e reimporte. Você nunca perde trabalho por causa disso; a planilha permanece intocada.

"Eu consigo pular direto para a célula que um erro está falando?"

Sim. Cada erro no relatório do Console legível por humanos tem um link clicável "Abrir no Data Studio"; clicar nele abre o Data Studio, muda para aquela aba e destaca aquela célula (apenas a aba, para erros no nível de arquivo/aba). A linha de coordenada legível por máquina permanece inalterada, então a coleta de CI/logs não é afetada.

"A importação gravou código, recompilou… ela terminou?"

Sim. Quando um esquema é novo/alterado, a importação é internamente em dois estágios (codegen → compilação/reload → bake), e o bake retoma automaticamente depois do reload. Observe o console para o relatório final.

Se o código do seu jogo não compila mais (por exemplo, depois de uma renomeação de coluna), a cadeia realiza um safe-abort com uma frase acionável; corrija o seu código e importe novamente.

"Erro de célula vazia, mas eu queria que a célula fosse opcional."

Tipos sem marcação são obrigatórios (proteção contra contaminação silenciosa). Para tornar uma célula opcional:

declare float? — padrão do tipo;
declare int=1 — padrão explícito;
ou use List<T>, onde uma célula vazia é uma lista vazia.

Veja Sintaxe da Planilha.

"`1.5` importa sem problema, mas `1,5` dá erro."

Deliberado: números são independentes de localidade — sempre decimal com .. Decimais com vírgula, NaN, e Infinity são bloqueados na entrada.

"A importação ficou muito lenta de repente."

O tempo de importação é linear em relação ao tamanho dos seus dados (50k linhas × 20 colunas ≈ 628 ms no editor), e permanece linear mesmo quando muitas referências quebram de uma vez — a busca por correspondência mais próxima tem um orçamento por campo e é pré-filtrada por comprimento (≈ 45 ms para 4,000 referências quebradas, headless).

Se uma importação de repente demorar muito mais do que isso, o tamanho da planilha é o que vale a pena olhar, não a contagem de erros.

"Erro de marcador desconhecido / tipo desconhecido com uma dica 'você quis dizer'."

Erros de digitação em nomes de @marker, nomes de tipo, ou membros de enum são erros com sugestões de correspondência mais próxima — aplique a sugestão. Um @ desconhecido em um nome de tipo não registrado também é um erro (segurança contra erros de digitação para referências no estilo RecordId@Tab).

Planilhas do Google

"A importação do Google falha com `PERMISSION_DENIED` (403)."

A planilha não está compartilhada com o endereço client_email da conta de serviço — a chave sozinha não concede nada. Abra a chave JSON, copie o client_email, e compartilhe a planilha com ele (Viewer para importar, Editor para Push). O passo a passo completo está em Configuração da Planilha do Google.

"O Push diz que exige o SheetsApi."

Você está no modo ExportUrl, que é somente leitura (sem autenticação). Qualquer gravação de volta precisa do modo SheetsApi com uma chave de conta de serviço. Veja Fontes, Exportação e Envio. Criar a conta de serviço e a chave é coberto em Configuração da Planilha do Google.

"A importação por ExportUrl falha pedindo um mapa de gid."

Obrigatório: uma URL de exportação sem gid retorna silenciosamente apenas a primeira aba, então o mapa (nome da aba → #gid=) é imposto. Ou mude para o modo SheetsApi, que não precisa de mapa.

"O Push relatou células ignoradas."

A nova busca ao vivo antes do envio encontrou conflitos (um colega de equipe editou uma célula, uma linha se moveu/desapareceu, uma chave duplicada). Células ignoradas são proteção, não falha — o relatório mostra as contagens de aplicadas/ignoradas. Reimporte para reconciliar, depois faça o Push novamente.

"Excluí linhas localmente, mas elas continuam na planilha do Google depois do Push."

Exclusões de linha nunca são enviadas por Push (exclusões posicionais contra uma planilha ao vivo são inseguras) — você recebe um aviso em vez disso. Exclua as linhas na planilha, depois reimporte.

Autoria

"O Ctrl+Z não está desfazendo minha alteração preparada."

Dois limites:

um campo de texto em foco consome o Ctrl+Z primeiro — clique em outro lugar, depois desfaça;
depois que "Refletir na planilha" tem sucesso, o histórico de preparação é limpo, então o undo funciona apenas dentro da sessão anterior ao reflect.

Depois do reflect, edite a planilha (ela é canônica).

"Algumas das minhas edições preparadas mostram um selo 'isolada' e não foram refletidas."

A planilha mudou externamente entre a preparação e o reflect, de uma forma que quebrou o endereço lógico dessas edições (chave da linha renomeada fora / linha excluída / conflito de chave). Elas são excluídas — não perdidas silenciosamente, não bloqueando o resto. Descarte-as individualmente e prepare-as novamente em relação ao novo baseline.

"Renomeei uma coluna/aba e agora o código do meu jogo não compila."

Esperado e divulgado na caixa de confirmação: renomeações mudam o nome do campo/classe gerado. Atualize o código do seu jogo; a cadeia de importação então se completa na próxima execução. Os valores de dado da coluna foram totalmente preservados.

"Posso trocar dois nomes de aba (A↔B), ou renomear abas em um ciclo, em um único lote?"

Sim. Trocas mútuas e ciclos (A→B→C→A) são preparados e refletidos em um único lote, e a UI só rejeita um conflito real: duas renomeações visando o mesmo nome. As referências seguem os dados e são reescritas atomicamente.

Um caso extremo permanece no Google: duas abas trocadas que referenciam uma à outra não são redirecionadas (o modo local é totalmente correto). Roteie a referência mútua através de uma terceira aba, ou reflita via um nome intermediário. Veja Data Studio e Capacidades e Limites.

"Minha renomeação de chave não atualizou uma referência que digitei no mesmo lote."

A propagação reescreve apenas células do baseline — nunca texto que você acabou de digitar (nenhuma reescrita silenciosa de entrada recente). A validação prévia sinaliza a referência pendente; corrija-a você mesmo.

"O reflect foi recusado por causa de uma aba xlsx."

Dois casos conhecidos:

abas de origem xlsx não podem ter a aba renomeada (proteção de workbook);
a propagação de renomeação de chave que tocaria uma aba xlsx bloqueia o lote inteiro (sem reflexão parcial).

Edite o workbook diretamente, depois reimporte.

"Editei um SO do bake no inspector e a reimportação apagou minha edição."

Por design — a planilha é a única fonte da verdade e o SO é um cache. A opção "Edição de teste" do inspector é explicitamente temporária. Faça alterações reais através da planilha ou do Data Studio.

Exportação e outros

"A exportação falha com uma incompatibilidade de esquema."

O seu bake está desatualizado em relação a uma mudança de esquema (ExportSchemaMismatch — checagem de fingerprint). Execute a importação para completar codegen + bake, depois Exporte/Push.

"Meu float exportado mostra `1`, mas a planilha tinha `1.0`."

Round-trip semântico: os valores são preservados exatamente; a notação se normaliza para a forma de round-trip mais curta. A estrutura (marcadores, ordem de colunas, comentários, o seu texto) é preservada 100%.

"A importação de xlsx rejeitou algumas células."

O leitor OOXML embutido é intencionalmente minimalista. Três coisas não são suportadas:

células de fórmula sem valores em cache;
células de erro;
tabulações/quebras de linha dentro da célula.

Materialize fórmulas em valores; use ; para listas.

Capacidades e Limites — a versão sistemática dessas respostas
Primeiros Passos — passos de configuração referenciados acima
Sintaxe da Planilha — regras de notação referenciadas acima