O Interchange Framework é o framework de importação e exportação da Unreal Engine. É um formato de arquivo independente, assíncrono, personalizável e pode ser usado durante o tempo de execução.
Interface de importação do Interchange
O Interchange usa uma base de código extensível e fornece uma pilha de pipeline personalizável. Isso dá a liberdade de editar o pipeline de importação usando C++, Blueprint ou Python para atender às necessidades do projeto.
Conceitos e termos importantes
Ao usar o Interchange, os seguintes conceitos e termos são importantes:
- Pipeline: um conjunto de operações que processa dados importados. O pipeline expõe as opções usadas para personalizar o processo de importação.
- Pipeline Stack: uma lista ordenada de pipelines que processam um arquivo importado. Os pipelines são combinados na pilha e atribuídos a formatos de arquivo específicos. As pilhas do pipeline estão localizadas em Project Settings > Interchange.
- Factory: uma operação que gera o ativo a partir dos dados importados.
Habilite os plugins do Interchange
O framework Interchange requer os plugins Interchange Editor e Interchange Framework, que vêm habilitados por padrão. Se esses plugins não estiverem habilitados no projeto, você poderá habilitá-los nas configurações do projeto para uso.
Para obter mais informações sobre como habilitar plugins, consulte Como trabalhar com plugins.
Importe um ativo
Os ativos são importados para a Unreal Engine usando um dos vários métodos diferentes.
Você pode importar ativos na Gaveta de Conteúdo ou no Navegador de Conteúdo, ou então selecionar File > Import Into Level.
Para obter mais informações sobre como importar arquivos, consulte Como importar ativos diretamente.
No momento, Import Into Level só funciona com os formatos de arquivo glTF e MaterialX.
Processo de importação
Inicie o processo de importação usando um dos métodos listados acima. Ao fazer isso, será aberta a janela Interchange Pipeline Configuration:
- Abra o menu suspenso Choose Pipeline Stack" e selecione na lista a pilha de pipeline a ser usada.
- Defina as configurações.
- Pressione Import para concluir o processo.
Use a interface para selecionar as configurações de importação e clique em "Import" para continuar.
A cada importação, a engine verifica se o formato do arquivo é compatível com o Interchange Framework. Se o arquivo for compatível, o Interchange usará a pilha de pipeline de importação apropriada para seu formato.
Em seguida, oInterchange passa pelo seguinte processo:
- O Interchange converte os dados importados em uma estrutura de nó intermediária na Unreal Engine.
- O Interchange de dados processa a pilha do pipeline e segue as instruções para a importação.
- Fábricas são usadas para gerar o ativo a partir do resultado.
Se o formato do arquivo não for compatível com o Interchange, a Unreal Engine usará o framework legado para importar o arquivo.
A janela "Interchange Pipeline Configuration" tem as seguintes opções:
| Opção | Descrição |
|---|---|
| Basic Layout | Filtra as opções do pipeline de importação para obter as propriedades básicas do pipeline. |
| Filter on Contents | Filtra as opções do pipeline de importação com base nos dados encontrados no arquivo de origem. |
| Choose Pipeline Stack | Seleciona a pilha do pipeline usada para a importação. |
A compatibilidade com o formato de arquivo FBX ainda é experimental. Para habilitar a importação de FBX com o Interchange, use os seguintes comandos do console:
| Comando do console | Descrição |
|---|---|
| Interchange.FeatureFlags.Import.FBX | Ativa o suporte experimental para importação de FBX usando o Interchange. |
| Interchange.FeatureFlags.Import.FBX.ToLevel | Ativa a compatibilidade experimental para FBX Import Into Level. |
Visualização do Interchange
Ao clicar no botão Preview na janela "Interchange Pipeline Configuration", a janela do editor "Interchange Preview" é aberta:
A janela "Interchange Preview" mostra uma lista de ativos que serão criados.
Nesta janela, você verá:
- Uma lista de ativos que serão criados.
- Os tipos deles na forma de ícones, ou em texto em dicas de ferramenta (materiais, malha estática, textura 2D).
- As propriedades são definidas na etapa de pré-importação do pipeline.
Pré-visualização de conflitos
Se o processo de importação detectar alterações no material ou na estrutura do esqueleto de um ativo reimportado, o pipeline afetado será destacado. Ao clicar em Show Conflict, a janela "Conflicts Preview" é aberta:
A janela "Interchange Conflicts Preview" mostra as alterações feitas no material ou na estrutura do esqueleto durante a reimportação.
A janela destaca cada conflito para informar o que muda quando o ativo é reimportado.
Nas versões anteriores, você tinha a opção de preservar a atribuição de material original ou substituí-lo na janela de conflito. Você não pode mais fazer isso usando o Interchange. Para alterar o material atribuído de um ativo, faça a correção no arquivo de origem ou use o editor de malha estática. Para obter mais informações sobre como usar o editor de malha estática, consulte Como aplicar um material pelo editor de malha Estática.
Como reimportar ativos com o Interchange
Ao reimportar um ativo que foi importado anteriormente usando o Interchange, a Unreal Engine lembra a pilha do pipeline e as opções que foram usadas e exibe essas opções.
Importe um ativo usando Blueprint
Você pode usar Blueprint para importar ativos para a Unreal Engine pelo Interchange Framework.
O exemplo de Blueprint cria um objeto que importa arquivos durante o tempo de execução usando o Interchange.
Por exemplo, você pode usar Blueprint para importar arquivos usando o Interchange durante o tempo de execução num aplicativo baseado na Unreal Engine. O exemplo acima cria uma função que importa um arquivo de textura para um local de arquivo especificado usando a pilha de pipeline de textura padrão. No momento, esse método de importação não é compatível com malhas esqueléticas ou dados de animação.
Crie uma nova classe de Blueprint
Para recriar o exemplo, siga as etapas a seguir:
- No projeto, crie uma classe de Blueprint de ator para armazenar a função. Para criar o Blueprint de ator, clique com o botão direito no Navegador de Conteúdo, vá para o menu de contexto e selecione "Blueprint Class".
-
Na janela Pick Parent Class, selecione Actor e nomeie a nova classe de Blueprint como InterchangeActor.
Selecione a classe-pai do novo Blueprint.
Adicione uma função
Para adicionar uma função:
- Clique duas vezes no novo Blueprint para abrir o editor.
-
No painel My Blueprint , vá para a configuração "Functions", clique no botão + e dê o nome InterchangeImport para a nova função.
Crie uma nova função
Adicionar e conecte os nós
Para adicionar e conectar os nós:
- Adicione um nó Sequence e conecte-o à saída da função.
- Conecte a saída Then 0 e crie um nó Create Source Data para referenciar o arquivo existente a ser importado.
- Conecte a entrada In File Name em Create Source Data e, no menu de contexto, selecione Promote to Variable.
- Dê o nome FilePath para a nova variável de string. Contém o posição do arquivo que será importado.
- No Blueprint, selecione a nova variável e clique na caixa de caixa de seleção de Instance Editable.
- Promova a saída do nó Create Source Data a uma nova variável chamada SourceData.
- Arraste a partir da saída Then 1 na sequência e crie um nó Get Interchange Manager Scripted. Será criado um ponteiro para o Interchange Manager para ser usado na próxima etapa.
- Arraste a partir da saída Get Interchange Manager Scripted e crie um nó Import Asset. Conecte o valor de retorno de Get Interchange Manager Scripted à Target input em Import Asset.
- Arraste a partir da entrada Content Path e promova-a a uma variável chamada SavePath. Cntém o posição do arquivo recém-importado.
- No Blueprint, selecione a nova variável e marque a caixa de seleção de*Instance Editable**.
- Obtenha uma referência à variável Source Data e conecte-a à entrada Source Data em Import Asset.
-
Arraste da entrada Import Asset Parameters e crie um nó *Make Input Asset Parameters**.
Clique na imagem para ampliá-la.
Disponibilize a função em tempo de execução
Para tornar a função disponível em tempo de execução:
- Em My Blueprints, clique na função InterchangeImport e clique na caixa de seleção ao lado de Call In Editor, no painel Details. Essa opção disponibiliza a função durante o tempo de execução nos Details do objeto InterchangeActor.
- Salve e Compile o Blueprint.
Use seu novo Blueprint
- Arraste uma cópia do Blueprint "InterchangeActor" para o nível.
- Clique em Play.
- No Organizador, selecione InterchangeActor.
- No painel Details, preencha FilePath e SavePath.
- Clique no botão Interchange Import para importar o arquivo.
Se você usar um nó Import Scene com o Blueprint de exemplo acima, o ativo será gerado diretamente na cena.
Como usar o Interchange em um aplicativo preparado
Se planejar usar o Interchange Framework durante o tempo de execução de um aplicativo preparado, vá para Project Settings > Project - Packating > Additional Asset Directories to Cook e adicione a pasta Interchange.
Clique na imagem para ampliá-la.
Importe um ativo usando Python
Você pode usar código Python para importar ativos para a Unreal Engine através do Interchange Framework.
import unreal
import_path = "C:/Users/foo/Downloads/Fbx/SkeletalMesh/Animations/Equilibre.fbx"
import_extension = unreal.Paths.get_extension(import_path, False)
is_gltf = import_extension == 'glb' or import_extension == 'gltf'
is_fbx = import_extension == 'fbx'
# se você quiser importar um arquivo fbx, verifique se "Interchange fbx import" está habilitado
if is_fbx:
level_editor_subsystem = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
unreal.SystemLibrary.execute_console_command(level_editor_subsystem.get_world(), 'Interchange.FeatureFlags.Import.FBX true')
editor_asset_subsystem = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)
transient_path = "/Interchange/Pipelines/Transient/"
transient_pipeline_path = transient_path + "MyAutomationPipeline"
editor_asset_subsystem.delete_directory(transient_path)
# Duplique o pipeline de conteúdo de ativos padrão do Interchange, o gltf tem ativos especiais
if is_gltf:
pipeline = editor_asset_subsystem.duplicate_asset("/Interchange/Pipelines/DefaultGLTFAssetsPipeline", transient_pipeline_path)
else:
pipeline = editor_asset_subsystem.duplicate_asset("/Interchange/Pipelines/DefaultAssetsPipeline", transient_pipeline_path)
# Defina aqui as propriedades do pipeline necessárias para a importação de ativo
# force a importação da malha estática
pipeline.common_meshes_properties.force_all_mesh_as_type = unreal.InterchangeForceMeshType.IFMT_STATIC_MESH
# combine malhas estáticas
pipeline.mesh_pipeline.combine_static_meshes = True
#Prevent Material import
pipeline.material_pipeline.import_materials = False
# Impeça a importaçao de texturas
pipeline.material_pipeline.texture_pipeline.import_textures = False
# Crie dados de origem a partir do nome do arquivo
source_data = unreal.InterchangeManager.create_source_data(import_path)
# crie os parâmetros para a importação do Interchange
import_asset_parameters = unreal.ImportAssetParameters()
# Geralmente o script é uma importação automática
import_asset_parameters.is_automated = True
# Adicione o pipeline configurado aos argumentos da importação
import_asset_parameters.override_pipelines.append(unreal.SoftObjectPath(transient_pipeline_path + ".MyAutomationPipeline"))
# No importador de gltf, use 2 pipelines e adicione a segunda
if is_gltf:
import_asset_parameters.override_pipelines.append(unreal.SoftObjectPath("/Interchange/Pipelines/DefaultGLTFPipeline"))
interchange_manager = unreal.InterchangeManager.get_interchange_manager_scripted()
# importe o ativo
interchange_manager.import_asset("/game/AA0A/testpython/",source_data,import_asset_parameters)
editor_asset_subsystem.delete_directory(transient_path)
No exemplo acima, um código Python é usado para importar o arquivo Equilibre.fbx "Equilibre.fbx". O código verifica se o formato do arquivo é ".gltf" ou ".fbx" e atribui o pipeline correto.
Edite a pilha do pipeline
Uma das vantagens do Interchange Framework é a capacidade de selecionar e personalizar a pilha do pipeline, uma pilha personalizável de processos para trabalhar com os dados do ativo. Você pode acrescentar pipelines à pilha padrão de pipeline para adicionar comportamentos durante o processo de importação.
A Unreal Engine vem com os seguintes pipelines padrão:
- Pipeline de ativos padrão
- Pipeline de material padrão
- Pipeline de textura padrão
- Pipeline de ativos de cena padrão
- Pipeline de nível de cena padrão
- Pipelime de inspetor de gráfico padrão
Cada pipeline padrão contém as opções mais comuns usadas para esse tipo de importação. Você pode personalizar essas pipelines para atender às necessidades específicas do seu projeto.
Edite um pipeline existente
Cada pipeline padrão é personalizável para atender às necessidades do projeto e da equipe.
Veja a seguir métodos para personalizar as opções de importação do projeto:
- Adicione, remova ou reordene a pilha de pipeline existente em Project Settings.
- Altera quais pipelines serão usados por padrão.
- Modifique os pipelines padrão existentes.
- Crie um pipeline personalizado.
Edite as configurações do projeto
Localize a pilha do pipeline em Project Settings, em Engine > Interchange:
A pilha do pipeline nas configurações do projeto.
A pilha de pipeline contém as configurações padrão para:
- Importar conteúdo
- Importar para nível
- Interface do editor
- Genérico
- Classe de pipeline genérico para o editor
Importe conteúdo
A Unreal Engine usa essas configurações para importar conteúdo para Content Drawer ou Content Browser.
Clique na imagem para ampliá-la.
Você pode alterar as configurações para cada tipo de conteúdo listado. Você também pode adicionar títulos, se necessário. Por exemplo, a configuração padrão contém Assets, Materials e Textures. Você pode adicionar um segmento à pilha do pipeline para animações e, em seguida, adicionar um ou mais pipelines personalizados para manipular arquivos de animação de entrada.
Importe para o nível
Na janela do editor, localize File > Import Into Level. Por padrão, essa função usa dois pipelines que funcionam juntos. Esses pipelines importam os dados do ator de um arquivo e geram um ator nele. A função de importação usa as seguintes configurações:
Clique na imagem para ampliá-la.
- DefaultSceneAssetPipeline se baseia na mesma classe de DefaultAssetPipeline e foi projetado para importação de cena.
- DefaultSceneLevelPipeline gera o ator no mundo depois que os dados passam por DefaultSceneAssetPipeline.
Modifique os pipelines padrão existentes
Modifique as propriedades dos pipelines padrão do Interchange para alterar o seguinte:
- Valores padrão
- Visibilidade
- Status de somente leitura
O painel de Detalhes do Pipeline do Interchange.
Para alterar as configurações dos pipelines padrão do Interchange, siga as etapas a seguir:
- Encontre o pipeline padrão na Gaveta de Conteúdo ou no Navegador de Conteúdo e clique duas vezes em um deles para abrir. Os pipelines estão localizados na pasta Engine > Plugins >Interchange Framework Content > Pipelines. Se você não conseguir ver a pasta Engine, clique em Settings no canto superior direito de Content Drawer ou Content Browser e marque a caixa de seleção de Show Engine Content.
- Edite o seguinte conforme necessário:
- Visibilidade durante o processo de importação e reimportação.
- Configuração padrão.
- Determina se a propriedade é somente leitura durante o processo de importação.
- Salve e feche a janela.
Crie um pipeline personalizado
Você pode criar pipelines do Interchange para personalizar ainda mais o processo de importação usando Blueprints, C++ ou Python.
Crie um pipeline personalizado usando Blueprints
Para criar um pipeline do Interchange usando Blueprints, siga as etapas a seguir:
- Em Content Drawer ou Content Browser, clique com o botão direito e selecione Create Blueprint Class.
- Na janela Pick Parent Class, expanda a categoria All Classes e selecione InterchangePipelineBase como a Parent Class.
- Clique duas vezes no novo Blueprint para abrir o Blueprint Editor.
Selecione "InterchangePipelineBase" como a classe-pai.
Um pipeline personalizado criado usando Blueprints tem as seguintes funções, que podem ser sobrepostas para adicionar um comportamento personalizado.
Funções de substituição de Blueprint do Interchange.
| Função de substituição | Descrição |
|---|---|
| Scripted Can Execute on Any Thread | Comunica ao gerenciador do Interchange que esse pipeline pode ser executado no modo assíncrono. |
| Scripted Execute Export Pipeline | É executada durante o processo de exportação (a funcionalidade atualmente não está funcional). |
| Scripted Execute Pipeline | É executada após a translação do arquivo. Cria a fábrica necessária para gerar os ativos. |
| Scripted Execute Post Factory Pipeline | É executada depois que a fábrica cria um ativo, mas antes de a função PostEditChange ser chamada. |
| Scripted Execute Post Import Pipeline | É executada após a importação completa do ativo e a chamada da função PostEditChange. |
| Scripted Set Reimport Source Index | É executada e informa ao pipeline qual índice de origem deve ser reimportado. Use esta função ao reimportar um ativo que pode ter mais que uma origem. Por exemplo, uma malha esquelética que tem um arquivo de origem para geometria e outro para informações de revestimento. |
Crie um pipeline personalizado usando C++
Para criar um pipeline do Interchange usando C++, crie um arquivo de cabeçalho que contenha o seguinte:
#pragma once
#include "CoreMinimal.h"
#include "InterchangePipelineBase.h"
#include "InterchangeSourceData.h"
#include "Nodes/InterchangeBaseNodeContainer.h"
#include "InterchangeMyPipeline.generated.h"
UCLASS(BlueprintType)
class INTERCHANGEPIPELINES_API UInterchangeMyPipeline : public UInterchangePipelineBase
{
GENERATED_BODY()
protected:
virtual void ExecutePipeline(UInterchangeBaseNodeContainer* BaseNodeContainer, const TArray<UInterchangeSourceData*>& SourceDatas) override;
virtual bool CanExecuteOnAnyThread(EInterchangePipelineTask PipelineTask) override
{
return true;
}
};
Em seguida, crie um arquivo de origem que contenha o seguinte:
#include "InterchangeMyPipeline.h"
void UInterchangeMyPipeline::ExecutePipeline(UInterchangeBaseNodeContainer* NodeContainer, const TArray<UInterchangeSourceData*>& InSourceDatas)
{
Super::ExecutePipeline(NodeContainer, InSourceDatas);
// Coloque a lógica necessária em nós traduzidos ou em nós de fábrica
}
Para obter mais informações sobre como trabalhar com C++ na Unreal Engine, consulte Programação com C++.
Crie um pipeline personalizado usando Python
Para criar um novo pipeline do Interchange usando código Python, crie um novo código Python e use as configurações do projeto para adicioná-lo aos códigos de inicialização. Para obter mais informações sobre como trabalhar com código em Python na Unreal Engine, consulte Como criar códigos para o Unreal Editor usando Python.
No código de exemplo a seguir, o código Python é usado para criar um pipeline básico de importação de ativo.
import unreal
@unreal.uclass()
class PythonPipelineTest(unreal.InterchangePythonPipelineBase):
import_static_meshes = unreal.uproperty(bool,meta=dict(Category="StaticMesh"))
import_skeletal_meshes = unreal.uproperty(bool,meta=dict(Category="SkeletalMesh"))
def cast(self, object_to_cast, object_class):
try:
return object_class.cast(object_to_cast)
except:
return None
def recursive_set_node_properties(self, base_node_container, node_unique_id):
node = base_node_container.get_node(node_unique_id)
# Defina o estado de habilitação do nó da fábrica de malha estática
static_mesh_node = self.cast(node, unreal.InterchangeStaticMeshFactoryNode)
if static_mesh_node:
static_mesh_node.set_enabled(self.import_static_meshes)
# Defina o estado de habilitação do nó da malha esquelética
skeletal_mesh_node = self.cast(node, unreal.InterchangeSkeletalMeshFactoryNode)
if skeletal_mesh_node:
skeletal_mesh_node.set_enabled(self.import_static_meshes)
# Itere os filhos
childrens = base_node_container.get_node_children_uids(node.get_unique_id())
for child_uid in childrens:
self.recursive_set_node_properties(base_node_container, child_uid)
@unreal.ufunction(override=True)
def scripted_execute_pipeline(self, base_node_container, SourceDatas):
root_nodes = base_node_container.get_roots()
for node_unique_id in root_nodes:
self.recursive_set_node_properties(base_node_container, node_unique_id)
return True