Criação de códigos do Unreal Editor usando Python

Esta página descreve como começar a usar o Python no Unreal Editor.

Por que Python?

Nos últimos anos, o Python se tornou a linguagem padrão para pipelines de produção e interoperabilidade entre aplicativos 3D, principalmente no setor de mídia e entretenimento. Isso se deve, em parte, ao grande número de aplicativos compatíveis com essa linguagem. À medida que a complexidade dos pipelines de produção e o número de aplicativos envolvidos continuam crescendo, ter uma linguagem para criação de códigos comum facilita criar e manter sistemas de gerenciamento de ativos em grande escala.

Mesmo sem essas considerações externas ou a necessidade de trabalhar com outros aplicativos, o Python é uma ótima opção se você deseja automatizar seus fluxos de trabalho no Unreal Editor. É relativamente fácil para os iniciantes em programação começarem com o Python, pois ele oferece a capacidade de criar interfaces de usuário complexas e completas por meio de módulos como o PySide. Além disso, há muitos outros módulos gratuitos e úteis disponíveis para a comunidade para facilitar sua vida.

Você pode usar o Python no Unreal Editor para fazer coisas como:

• Construir pipelines ou fluxos de trabalho de gerenciamento de ativos de maior escala que conectem o Unreal Editor a outros aplicativos 3D que você usa em sua organização.

• Automatizar tarefas demoradas de gerenciamento de ativos no Unreal Editor, como gerar níveis de detalhe (LODs) para malhas estáticas.

• Organizar proceduralmente o conteúdo em um nível.

• Controlar o Unreal Editor a partir de interfaces que você cria no Python.

Configure seu projeto para usar Python

O suporte a Python no Unreal Editor é fornecido pelo Plugin de Código do Editor Python. Você precisará habilitar esse plugin para o seu projeto atual antes de poder executar códigos em Python no Editor.

Para habilitar o plugin:

1. Abra seu projeto e escolha Editar > Plugins no menu principal.

2. Na janela Plugins, acesse a seção Códigos.
   Localize o Plugin de Código do Editor Python no painel direito e marque a caixa Habilitado.

   

   Você também deve habilitar o plugin Utilitários de Código do Editor, que oferece APIs simplificadas para muitas tarefas comuns do Editor. Para obter mais detalhes, consulte Criação de códigos e automatização do Editor.

3. Reinicie o editor.

Python 3.11.8

O Plugin de Código do Editor Python contém uma versão embutida do Python 3.11.8.

Isso significa que você não precisa instalar o Python separadamente no computador.

Formas de executar código Python no Unreal Editor

Existem várias maneiras diferentes de executar códigos Python no Unreal Editor, cada uma projetada para um cenário de uso ligeiramente diferente. Você pode escolher a que melhor se adapta às suas necessidades.

O console Python no Log de Saída

Você pode mudar a barra de entrada do console do Unreal Editor para aceitar código Python em vez de comandos de console Unreal.

Você pode fazer isso no painel Log de Saída, como mostrado acima, ou pressionando a tecla ~ para abrir a barra de entrada do console.

Quando o console está no modo Python:

• Você pode inserir linhas de código Python neste console e fazer com que o Editor execute cada uma imediatamente, exatamente como se estivesse usando um console Python interativo em uma janela de comando. Essa é a única maneira de executar o código Python linha por linha. Todas as outras abordagens listadas abaixo executam um arquivo de código que você especifica.

• Você pode executar várias linhas de código ao mesmo tempo usando Shift+ Enter para separar cada linha ou colando um bloco de várias linhas copiado de um editor de texto.

• Para executar arquivos de código Python, basta digitar o nome do arquivo no console. Se o código Python exigir argumentos de linha de comando adicionais, inclua-os após o nome do código.

O comando de console py

Com o console em modo Cmd, você pode usar o comando py para executar o restante da linha como código Python, exatamente como se tivesse digitado no console Python descrito acima.

Por exemplo, este comando executa o arquivo de código especificado:

Linha de comando

py "C:\MyScripts\my_script.py"

O menu Arquivo

O menu Arquivo na janela principal do Unreal Editor oferece novas opções que você pode usar para executar arquivos de código Python.

• Use Executar código Python se quiser navegar até um novo arquivo de código no computador que ainda não foi executado.

• Use a lista de Códigos Python recentes para executar novamente qualquer código executado anteriormente. O arquivo é lido do disco novamente, então se você alterou o código nesse meio tempo, a sua nova versão será executada.

A linha de comando

Se você iniciar o Unreal Editor pela linha de comando ou por meio de um código, poderá especificar um arquivo de código Python nos argumentos de linha de comando. Se o código Python exigir argumentos de linha de comando adicionais, inclua-os após o nome do código.

Há duas maneiras diferentes de executar um código Python pela linha de comando. Nas duas abordagens, o Editor é encerrado imediatamente após a execução do código Python.

Opção 1: Editor completo Nesta abordagem, o Unreal Editor completo é inicializado, abre o projeto especificado, carrega o nível de inicialização padrão e executa o código Python quando tudo está carregado e pronto. Esta abordagem é boa se você precisar que o código interaja com o conteúdo do projeto ou de um nível que pode levar algum tempo para carregar.

Adicione o argumento ExecutePythonScript à linha de comando e defina seu valor como o caminho e o nome do arquivo do código Python que deseja executar. Por exemplo:

Linha de comando

> UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

Opção 2: Commandlet Esta abordagem é de execução muito rápida e pode até executar seus códigos no modo sem interface sem abrir a IU do editor.

Adicione os seguintes argumentos à linha de comando para UnrealEditor-Cmd.exe: -run=pythonscript -script=<script_file_or_code>. <script_file_or_code> assume um dos seguintes valores:

• O caminho e o nome do arquivo de um código Python que você deseja executar.

• Instruções e comandos Python que deseja executar. Se necessário, você pode usar \n na string para escapar quebras de linha.

Por exemplo:

Linha de comando

> UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

Ou:

Linha de comando

> UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="a=5 \nb=10 \nc=a+b \nf=open('D:\myfile.txt','w+') \nf.write(str(c)) \nf.close()"

Esse commandlet não carrega níveis automaticamente, portanto, ao escrever o código, adicione a seguinte linha como a primeira coisa que ele fará:

Linha de comando

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

O arquivo init_unreal.py

Se o editor detectar um arquivo de código chamado init_unreal.py em qualquer um dos caminhos configurados para uso (consulte "Caminhos Python no Unreal Editor" a seguir), ele executará o código imediatamente.

Essa é uma boa abordagem em situações em que você está trabalhando em um projeto ou plugin e sabe que todas as pessoas que trabalham com esse conteúdo precisam executar o mesmo código de inicialização sempre que o editor for iniciado. Você pode colocar o código de inicialização dentro de um arquivo de código com esse nome e colocá-lo na pasta Content/Python do projeto ou plugin.

Códigos de inicialização

Em Configurações de Projeto, você pode especificar o número de códigos Python que deseja executar sempre que abrir o projeto. O editor executa esses códigos após o nível de inicialização padrão ser totalmente carregado.

Selecione Editar > Configurações de Projeto.... Na lista de Plugins, selecione Python. Em seguida, adicione os códigos à configuração Códigos de inicialização:

Reinicie o Unreal Editor quando terminar. Na próxima vez que o Editor carregar o projeto, os novos códigos de inicialização devem ser executados.

A partir de Blueprints exclusivos do Editor

O Plugin de Código Python expõe novos nós ao script visual de Blueprint que você pode usar para executar trechos de código Python ou arquivos durante a avaliação de um grafo de Blueprint.

Você encontrará os nós a seguir na seção Python > Execução da paleta de Blueprints.

	Execute Python Script	Executa o código Python literal que você passa ou digita na entrada de Comando Python. É a maneira recomendada de chamar Python a partir de Blueprints e substitui a criação de um tipo BlueprintFunctionLibrary(BPFL) em Python. O método BPFL mencionado acima causa problemas quando um ativo é salvo ou carregado devido à natureza transitória dos tipos gerados em Python, e não é mais oficialmente suportado. Execute Python Script pode ter pins de entrada e saída personalizados, que estão disponíveis como variáveis no código Python no nó e podem ser adicionados pelas propriedades do nó. -As entradas são definidas antes da execução do código Python no nó e podem ser lidas no código. -As saídas são lidas após a execução do código Python no nó e podem ser definidas no código. Execute Python Script pode conter várias linhas de código Python, e novas linhas podem ser inseridas usando as teclas Shift+Enter. A saída de Sucesso? será verdadeira se o código Python tiver sido executado com sucesso, ou falsa, caso contrário. Se for falsa, você encontrará os erros no Log de Saída. Este nó não pode executar arquivos. Ele pode executar apenas linhas de código Python.
	Execute Python Command	Executa o código Python literal ou o arquivo que você passa ou digita na entrada de Código Python. O nó tentará determinar, com base na entrada, se é um código literal ou um nome de arquivo. -A saída do Valor de Retorno é verdadeira se o código ou arquivo Python tiver sido executado com sucesso ou falsa, caso contrário. Se for falsa, você encontrará os erros no Log de Saída.
	Execute Python Command (Advanced)	Executa o código Python literal ou o arquivo que você passa ou digita na entrada de Código Python. Este nó é semelhante a Execute Python Command, mas oferece algumas entradas e saídas adicionais que podem ser úteis em algumas situações. Modo de Execução indica como você deseja interpretar a entrada do Código Python. Selecione Executar arquivo para forçar o comando a tratar a entrada como o nome de um arquivo e tentar encontrar e executar esse arquivo. Todos os valores retornados por esse código são exibidos no log. Selecione Executar código para forçar o comando a tratar a entrada como código Python literal e a executá-la como está. Todos os valores retornados por esse código são exibidos no log. Selecione Avaliar código para forçar o comando a tratar a entrada como um código Python literal, avaliá-la como está e retornar os valores produzidos pelo código na saída de Resultado do Comando. Se você passar um nome de arquivo à entrada do Código Python, o Escopo de Execução do Arquivo determinará se o arquivo será executado no escopo global (Público) ou em um escopo limitado (Privado). Se quiser que o código no arquivo consiga acessar variáveis, funções e outros elementos que já foram definidos no ambiente Python, selecione Público. No entanto, isso também dá ao arquivo Python a capacidade de redefinir variáveis e funções. Isso pode causar um comportamento inesperado por acidente. Portanto, pode ser mais seguro usar o escopo Privado. A saída de Resultado do Comando depende do Modo de Execução. Quando a entrada do Código Python é executada ou avaliada com sucesso, e o Modo de Execução está definido como Avaliar código, a saída retorna o valor produzido pelo código. Quando a entrada do Código Python é executada ou avaliada com sucesso e o Modo de Execução está definido como Executar arquivo ou Executar código, a saída retorna None. Quando a entrada do Código Python não é executada ou avaliada com sucesso, a saída contém as informações do erro. O Log de Saída fornece acesso à lista completa de mensagens gravadas no log do Python durante a execução do código ou arquivo inserido. Você pode iterar nessa matriz se precisar procurar mensagens específicas escritas pelo código. A saída de Valor de Retorno será verdadeira se o código Python tiver sido executado com sucesso, ou falsa, caso contrário. Se for falsa, você encontrará os erros no Log de Saída da engine, no pin de saída de Saída do Log e no Resultado do Comando.

Ambiente e caminhos Python no Unreal Editor

Quando você usa um caminho relativo para executar um código Python ou para importar outro módulo usando o comando import em um dos seus códigos, o código executado ou importado pode estar em qualquer caminho listado na variável sys.path do seu ambiente Python.

O Unreal Editor adiciona automaticamente vários caminhos à lista do sys.path:

• A subpasta Content/ Python na pasta do seu projeto.

• A subpasta Content/Python na instalação principal da Unreal Engine.

• A subpasta Content/ Python na pasta de cada plugin habilitado.

• A pasta Documents/UnrealEngine/Python dentro do seu diretório de usuário. Por exemplo, no Windows 10, isso é equivalente a C:/Users/NomeDoUsuário/Documentos/UnrealEngine/Python

Você também pode adicionar seus próprios caminhos a essa lista usando qualquer uma das seguintes abordagens:

• Nas suas Configurações de Projeto. Selecione Editar > Configurações de Projeto.... Na lista de Plugins, selecione Python. Em seguida, adicione os caminhos à configuração de Caminhos Adicionais. Reinicie o Unreal Editor quando terminar.

  

• Adicione os caminhos ao valor da variável de ambiente UE_PYTHONPATH (ou PYTHONPATH se você desabilitou a opção de ambiente do interpretador isolado do Editor) no seu sistema operacional e, em seguida, reinicie o Unreal Editor.

• Adicionar os caminhos diretamente à lista de sys.path em um código Python ou no console Python.

Para obter mais informações, confira a documentação Python sobre sys.path

Por padrão, o intérprete Python embutido da Unreal Engine é executado no modo isolado. Você pode desativar o modo isolado selecionando Editar > Configurações de Projeto > Plugins > Python > Isolar ambiente do interpretador.

Para mais informações, consulte a documentação da opção -I da linha de comando do Python.

A variável de ambiente UE_PYTHONPATH é sempre analisada pela engine e seu conteúdo é adicionado a sys.path, independentemente das opções de modo de isolamento selecionadas. UE_PYTHONPATH tem o mesmo propósito da variável PYTHONPATH, mas nunca deve ser modificada por software de terceiros.

Sobre a API Python do Unreal Editor

O Plugin de Código do Editor Python expõe um amplo intervalo de classes e funções que você pode usar para interagir com o Unreal Editor, os ativos em seu projeto e o conteúdo em seus níveis. Essa API está contida no módulo unreal. Para acessá-la, importe esse módulo no início de qualquer código Python executado no ambiente Python do Editor:

import unreal

O módulo unreal expõe quase tudo o que é exposto do C++ para Blueprints no seu ambiente do Editor. Não é pré-gerado; ele refletirá automaticamente o que estiver disponível nos Blueprints no seu Editor. À medida que você habilita novos plugins no Unreal Editor, tudo que esses plugins expõem para Blueprints também fica disponível em Python. O mesmo vale para qualquer código C++ que você escrever no seu projeto e expor para Blueprints.

A API Python faz todo o possível para expor as APIs Unreal nativas da maneira mais amigável possível para os desenvolvedores de Python. Por exemplo:

• Tipos de dados simples são convertidos entre Python e tipos nativos de forma transparente sempre que necessário.
  Quando você passa uma list, set ou dict em Python, eles são convertidos automaticamente em uma matriz, conjunto ou mapa da Unreal. Quando você recupera uma list, set ou dict retornada por uma função da API, na verdade está obtendo uma instância de uma classe Unreal, mas sua API é totalmente compatível com o tipo base Python list, set ou dict.

• As classes Python mantêm a mesma hierarquia de herança dos tipos nativos que representam. Isso significa, por exemplo, que você pode usar as funções integradas do Python isinstance() e type() para testar se um objeto deriva de ou corresponde a uma determinada classe.

• A API tenta encontrar um bom equilíbrio entre as convenções de nomenclatura usadas na Unreal para C++ e Blueprints, por um lado, e as convenções de nomenclatura para Python, por outro. Classes e objetos na API Python têm os mesmos nomes que têm nos Blueprints. Em geral, é o mesmo que seus tipos nativos, omitindo o prefixo (por exemplo, U ou T). Nomes de função e propriedade são expostos automaticamente como snake_case em letras minúsculas. Por exemplo, você costuma chamar funções como unreal.StaticMeshActor.get_actor_transform(). Os nomes dos valores de enumeração são expostos automaticamente como SNAKE_CASE em letras maiúsculas.

• Todas as funções expostas podem aceitar parâmetros ordenados ou nomeados em qualquer ordem. Por exemplo, as duas chamadas de função a seguir são exatamente equivalentes:

  C++

  unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(list_of_actors, my_options)
      unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(join_options=my_options, actors_to_join=list_of_actors)

  Copy full snippet(2 lines long)

Referência da API

Para obter detalhes sobre todas as classes e funções expostas pela API Python para Unreal, consulte a referência da API aqui:

Referência da API Python do Unreal Editor

Práticas recomendadas para usar a API Python

Esta seção aborda alguns itens importantes para lembrar ao usar a API Python.

Como Trabalhar com Ativos

Se precisar trabalhar com ativos no seu projeto, sempre use funções da API Python da Unreal para fazer isso. Nunca use módulos de gerenciamento de arquivos integrados ao Python para trabalhar diretamente com os arquivos de ativos no disco. Por exemplo, se precisar mover um ativo para uma pasta diferente, não use funções Python como os.rename ou shutil.move. Os projetos e ativos da Unreal contêm referências internas de conteúdo que você pode violar se não respeitar essa regra.

Em vez disso, recomendamos usar a API unreal.EditorAssetLibrary fornecida pelo plugin Utilitários de Código do Editor, ou a classe unreal.AssetTools integrada à API Python da Unreal.

Como alterar as propriedades do Editor

Você pode usar Python para acessar pbjetos no seu projeto e configurar muitas propriedades desses objetos programaticamente. Por exemplo, seu script Python pode acessar atores de malha estática no nível atual e definir propriedades, como se os atores podem ser danificados ou se devem estar ocultos no jogo. Ou você pode recuperar os componentes de malha estática e configurar propriedades nesses componentes, como suas configurações de Lightmass ou até mesmo o ativo de malha estática ao qual eles estão vinculados.

Essas propriedades podem ser expostas ao Python de duas maneiras diferentes:

• Itens com o sinalizador BlueprintReadOnly ou BlueprintReadWrite são expostos como propriedades simples no objeto.
  Você pode ler e modificar essas propriedades da mesma forma que acessa uma propriedade de objeto em Python

• Itens com o sinalizador ViewAnywhere ou EditAnywhere são expostos como propriedades do editor.
  Você pode ler e gravar esses valores usando um par especial de funções expostas por todo objeto: set_editor_property() e get_editor_property().

Na referência da API de cada classe, você encontrará uma lista de Propriedades do editor imediatamente após a descrição da classe. Elas são os valores que você pode definir e obter usando as funções set_editor_property() e get_editor_property(). Sempre que precisar definir ou obter uma propriedade de configuração para um objeto, verifique essa lista primeiro para ver se a propriedade desejada está listada.

• Quando você precisa ler um valor que está exposto como uma propriedade do objeto e como uma propriedade do editor, o resultado do acesso direto à propriedade costuma ser o mesmo que ao chamar a função get_editor_property(). No entanto, a função get_editor_property() geralmente tem acesso a propriedades que não estão expostas diretamente no objeto Python.

• Quando precisar definir um valor exposto como uma propriedade de objeto e uma propriedade do editor, na maioria dos casos, use a função set_editor_property() para definir o valor em vez de definir o valor diretamente no objeto. Quando você ajusta propriedades na IU, o editor geralmente realiza operações adicionais nos bastidores: alterações pré e pós-edição. Essas operações costumam responder às suas escolhas de alguma forma e mantêm a interface do editor sincronizada com o estado do objeto no mundo do jogo. Se você modificar essas propriedades diretamente no objeto Python, esse código do Editor não será executado automaticamente. Por outro lado, ao chamar set_editor_property() para definir o estado de uma propriedade, você aciona esse código de pré e pós-edição, exatamente como se tivesse alterado a configuração no painel Detalhes da interface do Editor.

Por exemplo, objetos Reprodutores de Mídia têm uma configuração Reproduzir ao abrir:

Isso é exposto na classe unreal.MediaPlayer no membro de classe play_on_open:

import unreal
		obj = unreal.MediaPlayer()
		# Modifying a property directly can have different results
		# than changing settings in the Editor UI.
		# Generally you'll want to avoid setting these values directly, like this:
		obj.play_on_open = True
		# This way of accessing the property will have exactly the same
		# result as changing the setting in the Editor UI:
		obj.set_editor_property("play_on_open", True)
		# Both ways of reading the value are equivalent.

Use tipos da Unreal sempre que possível

Sempre que precisar de utilitários disponíveis na API Python da Unreal, como classes para operações matemáticas ou manipulação de coordenadas 3D, recomendamos usar os utilitários da Unreal em vez de usar suas próprias implementações. As versões da Unreal são otimizadas para o melhor desempenho no ambiente da Engine.

Por exemplo, quando precisar manipular coordenadas em um espaço 3D, use a classe unreal.Vector:

import unreal
    v1 = unreal.Vector()
    v1.x = 10
    v2 = unreal.Vector(10, 20, 30)
    v3 = (v1 + v2) * 2
    print(v3)

Registros em log e feedback

O objeto unreal expõe funções que você pode usar no seu código para enviar mensagens de log, aviso e erro pelo mesmo sistema de mensagens usado por todos os subsistemas da Engine e do Editor. Recomendamos usar este framework de registro padronizado sempre que seu código precisar enviar uma messagem ao usuário.

• Use unreal.log() para messages informativas. Para sua conveniência, a função Python print() também foi implementada para passar pela unreal.log() internamente.

• Use unreal.log_warning() para alertar os usuários sobre possíveis problemas.

• Use unreal.log_error() para problemas graves que impedem a execução do código como esperado.

Suas mensagens aparecem no painel Log de Saída, junto com as mensagens enviadas por outros subsistemas:

Compatibilidade com desfazer e refazer (undo/redo)

Seus códigos podem aproveitar ao máximo o sistema de desfazer/refazer integrado ao Unreal Editor.

Cada transação que você definir pode conter qualquer número de operações Python. Usando essas transações, é possível agrupar operações grandes, ou operações em muitos objetos diferentes, em uma única entrada no histórico de desfazer/refazer. Normalmente, se o código pretende realizar uma determinada alteração em vários objetos, não é bom ter uma entrada separada no histórico de desfazer/refazer para cada alteração. É interessante ter uma entrada que irá desfazer as alterações em todos os objetos.

Para definir uma transação, use o escopo unreal.ScopedEditorTransaction. Por exemplo, se você executar este código:

import unreal
	obj = unreal.MediaPlayer()
	with unreal.ScopedEditorTransaction("My Transaction Test") as trans:
		obj.set_editor_property("play_on_open", False)
		obj.set_editor_property("vertical_field_of_view", 80)

O painel Histórico de ações desfeitas do Editor listará a transação por nome:

Como regra geral, suas transações com escopo podem conter quaisquer operações que também são desfeitas na IU do Editor. No entanto, nem toda operação do Editor pode ser desfeita. Por exemplo, não é possível desfazer a importação de um modelo na interface do Editor. Portanto, tentar importar um modelo dentro de uma unreal.ScopedEditorTransaction não funcionará como você espera.

Caixas de diálogo de progresso para operações lentas

Se os códigos precisarem trabalhar em muitos ativos ou atores na mesma operação, pode levar algum tempo para serem concluídos. No entanto, enquanto o Unreal Editor está executando um código Python, sua interface fica bloqueada para outras interações do usuário. Para fornecer ao usuário informações sobre o andamento de uma tarefa grande e evitar que o editor pareça travado, use o escopo unreal.ScopedSlowTask da Unreal.

Por exemplo:

import unreal
    total_frames = 100
    text_label = "Working!"
    with unreal.ScopedSlowTask(total_frames, text_label) as slow_task:
        slow_task.make_dialog(True)               # Makes the dialog visible, if it isn't already
        for i in range(total_frames):
            if slow_task.should_cancel():         # True if the user has pressed Cancel in the UI
                break
            slow_task.enter_progress_frame(1)     # Advance progress by one frame.
                                                # You can also update the dialog text in this call, if you want.