Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Configuração de importação

O Godot oferece várias maneiras de customizar os dados importados, como a aba Import, a janela de configurações avançadas de importação e cenas herdadas. Isso pode ser usado para fazer alterações adicionais na cena importada, como ajustar meshes, adicionar informações de física e adicionar novos nós. Você também pode escrever um script que executa códigos ao final do processo de importação para realizar uma customização arbitrária.

Note que, quando aplicável, modificar os dados originais deve ser preferido a configurar a cena após a importação. Isso ajuda a minimizar as diferenças entre o aplicativo de modelagem 3D e a cena importada. Veja os artigos Considerações sobre exportação de modelos e Customização do tipo de nó usando sufixos de nome para mais informações.

Fluxos de trabalho de importação

Como o Godot só pode salvar seu próprio formato de cena (.tscn/.scn), ele não pode salvar por cima do arquivo de cena 3D original (que usa um formato diferente). Esta também é uma abordagem mais segura, pois evita fazer alterações acidentais no arquivo de origem.

Para permitir a customização da cena e de seus materiais, o importador de cenas do Godot permite diferentes fluxos de trabalho em relação a como os dados são importados.

Importar painel depois de selecionar uma cena 3D no painel FileSystem (Sistema de Arquivos)

Este processo de importação é customizável usando 3 interfaces distintas, dependendo das suas necessidades:

• A aba Import, após selecionar a cena 3D clicando nela uma vez na aba FileSystem.

• The Advanced Import Settings dialog, which can be accessed by double-clicking the 3D scene in the FileSystem dock or by clicking the Advanced… button in the Import dock. This allows you to customize per-object options in Godot, and preview models and animations. Please see the Configurações Avançadas de Importação page for more information.

• As Dicas de importação, que são sufixos especiais adicionados aos nomes dos objetos no software de modelagem 3D. Isso permite customizar opções por objeto diretamente no software de modelagem 3D.

Para customizações básicas, usar a aba Import é suficiente. No entanto, para operações mais complexas, como definir sobreposições de material para cada material individualmente, você precisará usar a janela Advanced Import Settings (Configurações Avançadas de Importação), dicas de importação (import hints), ou possivelmente ambos.

Utilizando o painel Importar

As seguintes opções podem ser ajustadas na aba Import após selecionar uma cena 3D na aba FileSystem:

• Root Type: O tipo de nó a ser usado como nó raiz. É recomendado o uso de tipos de nós que herdam de Node3D. Caso contrário, você perderá a capacidade de posicionar o nó diretamente no editor 3D.

• Root Name: The name of the root node in the imported scene. This is generally not noticeable when instantiating the scene in the editor (or drag-and-dropping from the FileSystem dock), as the root node is renamed to match the filename in this case.

• Apply Root Scale: If enabled, Root Scale will be applied on the meshes and animations directly, while keeping the root node's scale to the default (1, 1, 1). This means that if you add a child node later on within the imported scene, it won't be scaled. If disabled, Root Scale will multiply the scale of the root node instead.

Malhas

• Ensure Tangents: Se marcado, gera tangentes de vértices usando Mikktspace se as meshes de entrada não possuírem dados de tangentes. Quando possível, é recomendado permitir que o software de modelagem 3D gere as tangentes na exportação, em vez de depender desta opção. As tangentes são necessárias para a exibição correta de mapas de normais e de altura, junto com quaisquer recursos de material/shader que exijam tangentes. Se você não precisa de recursos de material que exijam tangentes, desativar isso pode reduzir o tamanho do arquivo de saída e acelerar a importação se o arquivo 3D de origem não contiver tangentes.

• Generate LODs: Se marcado, gera variantes de menor detalhe da mesh que serão exibidas à distância para melhorar o desempenho de renderização. Nem todas as meshes se beneficiam de LOD, especialmente se nunca forem renderizadas de longe. Desativar isso pode reduzir o tamanho do arquivo de saída e acelerar a importação. Veja Nível de detalhe de malha (LOD) para mais informações.

• Create Shadow Meshes: Se marcado, ativa a geração de meshes de sombra na importação. Isso otimiza a renderização de sombras sem reduzir a qualidade, unindo (welding) vértices sempre que possível. Isso, por sua vez, reduz a largura de banda de memória necessária para renderizar as sombras. A geração de meshes de sombra atualmente não suporta o uso de um nível de detalhe inferior ao da mesh de origem (mas a renderização de sombras fará uso de LODs quando relevante).

• Light Baking: Configura o modo de iluminação global das meshes na cena 3D. Se definido como Static Lightmaps, define o modo de GI das meshes para Static e gera UV2 na importação para o lightmap baking.

• Lightmap Texel Size: Visível apenas se Light Baking estiver definido como Static Lightmaps. Controla o tamanho de cada texel no lightmap calculado. Um valor menor resulta em lightmaps mais precisos, ao custo de tamanhos de lightmap maiores e tempos de cálculo mais longos.

Visuais (Skins)

• Use Named Skins: Se marcado, usa Skins nomeadas para animação. O nó MeshInstance3D contém 3 propriedades relevantes aqui: um NodePath de esqueleto apontando para o nó Skeleton3D (geralmente ..), uma mesh e uma skin:

  • O nó Skeleton3D contém uma lista de ossos com nomes, suas poses e posições de descanso (rest), um nome e um osso pai.

  • A mesh contém todos os dados brutos de vértices necessários para exibir uma malha. Em termos de mesh, ela sabe como os vértices foram pintados por pesos (weight-painted) e usa uma numeração interna frequentemente importada do software de modelagem 3D.

  • A skin contém as informações necessárias para vincular essa mesh a este Skeleton3D. Para cada uma das IDs de ossos internas escolhidas pelo software de modelagem 3D, ela contém duas coisas. Primeiro, uma Matriz conhecida como Bind Pose Matrix, Inverse Bind Matrix ou IBM de forma abreviada. Segundo, a Skin contém o nome de cada osso (se Use Named Skins estiver ativado) ou o índice do osso dentro da lista do Skeleton3D (se Use Named Skins estiver desativado).

Juntas, essas informações são suficientes para dizer ao Godot como usar as poses dos ossos no nó Skeleton3D para renderizar a mesh de cada MeshInstance3D. Note que cada MeshInstance3D pode compartilhar vínculos, como é comum em modelos exportados do Blender, ou cada MeshInstance3D pode usar um objeto Skin separado, como é comum em modelos exportados de outras ferramentas, como o Maya.

Animação

• Import: Se marcado, importa animações da cena 3D.

• FPS: O número de quadros por segundo a ser usado para converter curvas de animação em uma série de pontos com interpolação linear. É recomendado configurar esse valor para corresponder ao valor que você está usando como base em seu software de modelagem 3D. Valores mais altos resultam em animações mais precisas com mudanças rápidas de movimento, ao custo de tamanhos de arquivo e uso de memória maiores. Graças à interpolação, geralmente não há muito benefício em ir além de 30 FPS (pois a animação ainda parecerá fluida em taxas de quadros de renderização mais altas).

• Trimming: Corta o início e o fim das animações se não houver mudanças de keyframe. Isso pode reduzir o tamanho do arquivo de saída e o uso de memória em certas cenas 3D, dependendo do conteúdo de suas faixas de animação.

• Remove Immutable Tracks: Remove faixas de animação que contêm apenas valores padrão. Isso pode reduzir o tamanho do arquivo de saída e o uso de memória em certas cenas 3D, dependendo do conteúdo de suas faixas de animação.

Script de Importação

• Path: Caminho para um script de importação, que pode executar códigos após o término do processo de importação para processamento customizado. Veja Usando scripts de importação para automação para mais informações.

glTF

• Embedded Texture Handling: Controla como as texturas embutidas em cenas glTF devem ser tratadas. Discard All Textures não importará nenhuma textura, o que é útil se você preferir configurar manualmente os materiais no Godot. Extract Textures extrai as texturas em imagens externas, resultando em tamanhos de arquivo menores e maior controle sobre as opções de importação. Embed as Basis Universal e Embed as Uncompressed mantêm as texturas embutidas na cena importada, com e sem compressão VRAM, respectivamente.

FBX

• Importer Qual método de importação é usado. O ufbx gerencia arquivos fbx nativamente como arquivos fbx. O FBX2glTF converte arquivos FBX para glTF na importação e requer configuração adicional. O FBX2glTF não é recomendado, a menos que você tenha um motivo específico para usá-lo em vez do ufbx ou esteja trabalhando com um formato de arquivo diferente.

• Allow Geometry Helper Nodes ativa ou desativa nós auxiliares de geometria

• Embedded Texture Handling: Controla como as texturas embutidas em cenas fbx devem ser tratadas. Discard All Textures não importará nenhuma textura, o que é útil se você preferir configurar manualmente os materiais no Godot. Extract Textures extrai as texturas em imagens externas, resultando em tamanhos de arquivo menores e maior controle sobre as opções de importação. Embed as Basis Universal e Embed as Uncompressed mantêm as texturas embutidas na cena importada, com e sem compressão VRAM, respectivamente.

Opções específicas do Blender

Visível apenas para arquivos .blend.

Nós

• Visible: All importa tudo, até mesmo objetos invisíveis. Visible Only importa apenas objetos visíveis. Renderable importa apenas objetos que estão marcados como renderizáveis no Blender, independentemente de estarem realmente visíveis ou não. No Blender, a renderização é alternada clicando no ícone de câmera ao lado de cada objeto no Outliner, enquanto a visibilidade é alternada pelo ícone de olho.

• Active Collection Only: Se marcado, importa apenas os nós que estão na coleção ativa no Blender.

• Punctual Lights: Se marcado, importa luzes (direcionais, omni e spot) do Blender. "Punctual" não deve ser confundido com "positional", razão pela qual as luzes direcionais também estão incluídas.

• Cameras: Se marcado, importa câmeras do Blender.

• Custom Properties: Se marcado, importa propriedades customizadas do Blender como extras do glTF. Esses dados podem então ser usados a partir de um plugin do editor que utilize GLTFDocument.register_gltf_document_extension(), o qual pode definir metadados de nós na importação (entre outros casos de uso).

• Modifiers: Se definido como No Modifiers, os modificadores de objetos são ignorados na importação. Se definido como All Modifiers, aplica os modificadores aos objetos na importação.

Malhas

• Colors: Se marcado, importa cores de vértices (vertex colors) do Blender.

• UVs: Se marcado, importa as UV1 e UV2 de vértices do Blender.

• Normals: Se marcado, importa as normais de vértices do Blender.

• Export Geometry Nodes Instances: Se marcado, importa instâncias de geometry nodes do Blender.

• GPU Instances Se marcado, importa instâncias e sistemas de partículas como dados de buffer/accessor do GLTF em vez de vários objetos Mesh3D singulares. Isso não inclui o instanciamento de Geometry Nodes.

• Tangents: Se marcado, importa tangentes de vértices do Blender.

• Skins: None ignora a importação de dados de esqueleto (skin data) do Blender. 4 Influences (Compatible) importa dados de skin para serem compatíveis com todos os renderizadores, ao custo de menor precisão para certos rigs. All Influences importa dados de skin com todas as influências (até 8 no Godot), o que é mais preciso, mas pode não ser compatível com todos os renderizadores.

• Export Bones Deforming Mesh Only: Se marcado, importa apenas os ossos que deformam a mesh a partir do Blender.

Materiais

• Unpack Enabled: Se marcado, descompacta as imagens originais para o sistema de arquivos do Godot e as utiliza. Isso permite alterar as configurações de importação de imagem, como a compressão VRAM. Se desmarcado, permite que o Blender converta as imagens originais, como recompilar rugosidade (roughness) e metálico (metallic) em uma única textura de rugosidade + metálico. Na maioria dos casos, essa opção deve ser deixada marcada, mas se as imagens do arquivo .blend não estiverem no formato correto, ela deve ser desativada para o comportamento correto.

• Export Materials: Se definido como Placeholder, não importa os materiais, mas mantém os slots de superfície para que materiais separados possam ser atribuídos a superfícies diferentes. Se definido como Export, importa os materiais como estão (note que materiais procedurais do Blender podem não funcionar corretamente). Se definido como Named Placeholder, importa os materiais, mas não importa as imagens que estão compactadas no arquivo .blend. As texturas terão que ser atribuídas manualmente nos materiais importados.

Animação

• Limit Playback: Se marcado, limita a importação da animação ao intervalo de reprodução definido no Blender (as opções Start e End à direita da linha do tempo da animação no Blender). Isso pode evitar a inclusão de dados de animação não utilizados, tornando a cena importada menor e mais rápida de carregar. No entanto, isso também pode resultar na perda de dados de animação se o intervalo de reprodução não estiver definido corretamente no Blender.

• Always Sample: Se marcado, força a amostragem (sampling) da animação na importação para garantir a consistência entre a forma como o Blender e o glTF realizam a interpolação da animação, ao custo de tamanhos de arquivo maiores. Se desmarcado, pode haver diferenças na forma como as animações são interpoladas entre o que você vê no Blender e a cena importada no Godot, devido a diferentes semânticas de interpolação entre ambos.

• Group Tracks: Se marcado, importa animações (ativas e em faixas NLA) como faixas separadas. Se desmarcado, todas as ações atribuídas atualmente tornam-se uma única animação glTF.

Usando scripts de importação para automação

É possível fornecer um script especial para processar toda a cena após a importação. Isso é excelente para pós-processamento, alteração de materiais, manipulação da geometria e muito mais.

Crie um script que não esteja anexado a nenhum nó clicando com o botão direito na aba FileSystem e escolhendo New > Script…. No editor de script, escreva o seguinte:

@tool # Needed so it runs in editor.
extends EditorScenePostImport

# This sample changes all node names.
# Called right after the scene is imported and gets the root node.
func _post_import(scene):
    # Change all node names to "modified_[oldnodename]"
    iterate(scene)
    return scene # Remember to return the imported scene

# Recursive function that is called on every node
# (for demonstration purposes; EditorScenePostImport only requires a `_post_import(scene)` function).
func iterate(node):
    if node != null:
        print_rich("Post-import: [b]%s[/b] -> [b]%s[/b]" % [node.name, "modified_" + node.name])
        node.name = "modified_" + node.name
        for child in node.get_children():
            iterate(child)

A função _post_import(scene: Node) recebe a cena importada como argumento (o parâmetro é, na prática, o nó raiz da cena). A cena que será efetivamente utilizada deve ser retornada (mesmo que seja completamente diferente da cena original).

Para usar seu script, localize o script na opção "Path" da aba de importação, sob a categoria "Import Script".

Utilizando bibliotecas de animação

Você também pode optar por importar apenas as animações de um arquivo glTF e mais nada. Isso é usado em algumas pipelines de assets para distribuir animações separadamente dos modelos. Por exemplo, isso permite que você use um conjunto de animações para vários personagens, sem ter que duplicar os dados de animação em cada personagem.

Para fazer isso, selecione o arquivo glTF na aba FileSystem e mude o modo de importação para Animation Library na aba Import:

Alterando o tipo de importação para Animation Library na aba Import

Clique em Reimport e reinicie o editor quando solicitado. Após reiniciar, o arquivo glTF será importado como uma AnimationLibrary em vez de uma PackedScene. Esta biblioteca de animações pode então ser referenciada em um nó AnimationPlayer.

As opções de importação que ficam visíveis após alterar o modo de importação para Animation Library agem da mesma forma que ao usar o modo de importação Scene. Veja Utilizando o painel Importar para mais informações.

Script de filtro

É possível especificar um script de filtro em uma sintaxe especial para decidir quais faixas de quais animações devem ser mantidas.

O script de filtro é executado para cada animação importada. A sintaxe consiste em dois tipos de instruções: o primeiro para escolher quais animações serão filtradas e o segundo para filtrar trilhas individuais dentro das animações correspondentes. Todos os padrões de nome utilizam correspondência de expressões sem distinção entre maiúsculas e minúsculas, com suporte aos curingas ? e * (utilizando String.matchn() internamente).

O script deve começar com uma instrução de filtro de animação (indicada pela linha que começa com @). Por exemplo, se quisermos aplicar filtros a todas as animações importadas cujo nome termine em "_Loop":

@+*_Loop

Da mesma forma, padrões adicionais podem ser adicionados à mesma linha, separados por vírgulas. Aqui está um exemplo modificado para incluir também todas as animações cujos nomes começam com "Arm_Left", mas também excluir todas as animações cujos nomes terminam em "Attack":

@+*_Loop, +Arm_Left*, -*Attack

Seguindo a declaração do filtro de seleção de animação, adicionamos padrões de filtragem de faixa para indicar quais faixas de animação devem ser mantidas ou descartadas. Se nenhum filtro de faixa for especificado, todas as faixas dentro das animações encontradas serão descartadas!

É importante notar que as declarações do filtro de faixa são aplicadas para cada faixa dentro da animação, isso significa que uma linha pode incluir uma faixa, uma regra posterior ainda pode descartá-la. Da mesma forma, uma faixa excluída por uma regra inicial pode então ser reincluída mais uma vez por uma regra de filtro mais para baixo no script do filtro.

Por exemplo: inclua todas as faixas em animações com nomes terminados em "_Loop", mas descarte quaisquer faixas que afetem um "Skeleton" e terminem em "Control", a menos que contenham "Arm" no nome:

@+*_Loop
+*
-Skeleton:*Control
+*Arm*

No exemplo acima, faixas como ''Skeleton:Leg_Control'' seriam descartadas, enquanto faixas como ''Skeleton:Head'' ou ''Skeleton:Arm_Left_Control'' seriam retidas.

Todas as linhas de filtro de faixa que não começam com um + ou - são ignoradas.

Herança de cena

Em muitos casos, pode ser desejável realizar modificações manuais na cena importada. Por padrão, isso não é possível porque, se o ativo 3D de origem for alterado, o Godot reimportará a cena inteira.

Entretanto, é possível realizar modificações locais utilizando herança de cena. Se você tentar abrir a cena importada através de Cena > Abrir Cena… ou Cena > Abrir Cena Rapidamente…, a seguinte caixa de diálogo será exibida:

Janela ao abrir uma cena 3D importada no editor

Em cenas herdadas, as únicas limitações para modificação são:

• Nós da cena base não podem ser removidos, mas nós adicionais podem ser inseridos em qualquer lugar.

• Sub-recursos não podem ser editados. Ao invés disso, você precisa salvá-los externamente como descrito acima.

Fora isso, tudo é permitido.