unity-technologies/gerenciar-sprite-atlas

Unity SpriteAtlas V2

Fornece conhecimento procedural seguro para o editor para scripts de atlases em projetos Unity. V2 impõe separação estrita entre autoria no editor e acesso em tempo de execução.

⚠️ Princípio Crítico da V2: SpriteAtlas é apenas para tempo de execução. SpriteAtlasAsset é apenas para o editor. Nunca misture contextos. Sempre use V2.

🚨 CRÍTICO: Verificações e Entradas do Usuário Obrigatórias Antes da Implementação

SEMPRE execute estas verificações e faça estas perguntas ANTES de gerar qualquer código:

Leia os recursos fornecidos antes de escrever código (OBRIGATÓRIO)

Esta skill fornece C# funcional em resources/, e o código de atlas que dá errado é quase sempre código escrito sem lê-lo primeiro. Abra os arquivos para o caminho que você está seguindo e depois escreva.

Seguindo este caminho	Leia primeiro
Qualquer trabalho com atlas	resources/authoringvsruntime.cs, references/common-errors.md
Geração via pré-build (o padrão)	resources/spriteatlasprebuildgenerator.cs, resources/enablespritepacking.cs, resources/savespriteatlasasset.cs
Opção B, late-binding com Addressables	resources/buildaddressablespostprocess.cs, resources/spriteatlaslatebinding.cs, resources/handlelatebinding.cs
Qualquer coisa que possa usar uma API antiga	resources/deprecatedmethods.cs, resources/dontscriptspriteatlasineditor.cs, resources/dontpackinruntimebuilds.cs

resources/ contém 38 arquivos no total, cobrindo empacotadores personalizados, variantes, configurações de plataforma e acesso em tempo de execução. Navegue pelo diretório quando sua tarefa não estiver na tabela acima, em vez de inventar uma abordagem. Recorrer à API da memória em vez de ler esses arquivos é a causa mais comum de um atlas que importa perfeitamente e não faz nada em tempo de execução.

0. Verificar Scripts Existentes (PRIMEIRA ETAPA OBRIGATÓRIA)

ANTES de gerar qualquer código, verifique o projeto em busca de scripts SpriteAtlas existentes gerados por esta skill.

Pesquise arquivos que contenham o identificador: // [UNITY-SKILL:SPRITEATLAS]

Se scripts existentes forem encontrados, SEMPRE pergunte ao usuário com este formato:

"Encontrei scripts SpriteAtlas existentes no seu projeto:

Gerador de Pré-build:

• Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs

Construtor Addressables:

• Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs

Carregador em Tempo de Execução:

• Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs

O que você gostaria de fazer?"

Em seguida, apresente as opções:

• Opção A: Atualizar scripts existentes (Recomendado se os requisitos mudaram)

  • Regenera scripts nos caminhos existentes
  • Preserva os locais dos arquivos
  • Atualiza para a versão mais recente
  • ⚠️ Pode sobrescrever modificações personalizadas

• Opção B: Criar novos scripts com nomes diferentes

  • Gera junto com os scripts existentes
  • Permite múltiplas configurações de atlas
  • Os scripts originais permanecem inalterados
  • Você precisará especificar novos nomes/caminhos

• Opção C: Abortar (manter o existente sem alterações)

  • Nenhuma geração de código
  • Nenhuma alteração no projeto
  • Use se quiser manter a configuração atual

Tratamento da Escolha do Usuário:

• Se A for escolhido: Regenerar nos caminhos existentes, incrementar a versão para 2.0.1+
• Se B for escolhido: Perguntar por novos nomes de script (ex.: "SpriteAtlasPrebuild_Custom.cs"), depois gerar
• Se C for escolhido: Parar imediatamente, informar ao usuário que nenhuma alteração foi feita

1. Mecanismo de Entrega (OBRIGATÓRIO)

Pergunte: "Como você deseja entregar os sprite atlases?"

Opção A: Dados Embutidos (Carregamento Imediato)

• Os atlases são incluídos no build e carregados imediatamente
• Defina includeInBuild = true
• Adequado para: UI principal, sprites de gameplay principais, assets sempre necessários
• Prós: Simples, sem pacotes adicionais, acesso instantâneo
• Contras: Aumenta o tamanho inicial do build, não pode atualizar sem um novo build

Opção B: Late-Binding via Addressables (Carregamento Sob Demanda)

• Os atlases NÃO são incluídos no build, carregados sob demanda via Addressables
• Defina includeInBuild = false
• Crie entradas Addressables para cada atlas
• Adicione a configuração do addressable como etapa de pré-build
• 🚨 OBRIGATÓRIO: Criar script de carregamento late-binding em tempo de execução
• 🚨 OBRIGATÓRIO: Construir conteúdo Addressables como etapa de build
• Adequado para: Conteúdo DLC, funcionalidades opcionais, assets grandes, conteúdo baixável
• Prós: Build inicial menor, pode ser atualizado independentemente, carregamento sob demanda
• Contras: Requer pacote Addressables, carregamento assíncrono, dependência de rede

Caso de Uso	Recomendado
Sprites de UI principal que estão sempre visíveis	Opção A: Embutidos
Sprites de tutorial ou integração	Opção A: Embutidos
Sprites específicos de nível (100+ níveis)	Opção B: Addressables
Conteúdo DLC ou sazonal	Opção B: Addressables
Sprites de UI localizados (múltiplos idiomas)	Opção B: Addressables
Skins ou cosméticos de personagens	Opção B: Addressables

2. Modo SpritePacker (OBRIGATÓRIO)

Ative o modo Sprite Packer antes de criar atlases, depois leia a configuração de volta e confirme que foi aplicada. Use o código em resources/enablespritepacking.cs; ele define EditorSettings.spritePackerMode e configura as configurações de empacotamento do importador.

Este é o passo que decide se o atlas que você produz é real. Disabled é o valor zero de SpritePackerMode, então qualquer projeto onde ninguém definiu carrega empacotamento Disabled, e um atlas criado enquanto está Disabled ainda importa, ainda aparece como um asset e ainda parece finalizado, mas nunca pode empacotar. A Unity diz isso no Inspetor: "O empacotamento do Sprite Atlas está desabilitado". Nada mais no fluxo de trabalho falha, então um atlas enviado desta forma é lido como um sucesso. Não presuma que um projeto já está configurado: leia o valor.

Portanto, não trate "Configurei" como concluído. Depois de defini-lo, leia EditorSettings.spritePackerMode de volta, confirme que não é Disabled e relate o valor que você realmente leu. Se não puder lê-lo de volta, diga isso em vez de presumir que a escrita foi aplicada.

NÃO edite arquivos meta DIRETAMENTE.

🚨 CRÍTICO: A Abordagem Padrão é a Geração via Pré-build

SEMPRE use IPreprocessBuildWithReport para gerar ou atualizar automaticamente SpriteAtlases durante o pipeline de build. Esta é a abordagem PADRÃO e OBRIGATÓRIA, a menos que o usuário SOLICITE EXPLICITAMENTE autoria manual.

❌ NÃO Crie Scripts de Item de Menu Manual

NUNCA crie scripts com atributos [MenuItem] para geração de atlas, a menos que seja explicitamente solicitado. A abordagem de pré-build elimina a necessidade de cliques manuais. Use autoria manual apenas para: Layouts otimizados à mão, arranjos específicos de sprites ou requisitos de pré-visualização no editor. Veja Avançado: Autoria Manual.

🚨 CRÍTICO: Restrição de Localização de Fonte de Sprite

Adicione APENAS sprites da pasta Assets do projeto. NUNCA adicione sprites de assets embutidos da Unity, pacotes ou locais externos. Assets embutidos da Unity não podem ser empacotados em SpriteAtlas, e assets de pacotes podem causar problemas de importação/dependência.

Arquitetura Crítica da V2

Contexto	Componente	Propósito	Uso Permitido
Tempo de Execução	SpriteAtlas	Carregar e referenciar atlases em tempo de execução	Usar spriteAtlas.GetSprite() e propriedades relacionadas
Editor	SpriteAtlasAsset	Criar e configurar atlases no editor	Usar para gerar via script, salvar como asset e configurar parâmetros