Sistema de ferramentas programáveis por script

O sistema de ferramentas programáveis com scripts fornece funções e um modo de editor para criar ferramentas interativas personalizada. O objetivo do sistema é permitir que programadores que não usam C++ criem ferramentas interativas no Unreal Engine.

O principal ponto de referência para uma ferramenta interativa é o Modo de edição de modelagem. No entanto, o sistema de ferramentas programáveis com scripts não tem conexão direta com o modo de modelagem ou o script de geometria.

O plugin do sistema de ferramentas programáveis com script expõe o Framework das ferramentas interativas ao Blueprint (BP), fornecendo a criadores e artistas técnicos os meios para projetar ferramentas que se comportam de forma semelhante ao modo de modelagem.

Recomendamos entender os fundamentos de Blueprints para começar com ferramentas programáveis com Scrip. Para saber mais, consulte Introdução aos Blueprints.

Ao criar subclasses de Blueprints (BP) da classes-base, você pode adicionar ferramentas definidas personalizadas ao modo de editor de ferramentas programáveis por scripts. Com o modo de editor, os artistas podem acessar essas ferramentas personalizadas para seus projetos.

Para que serve uma ferramenta programável com scripts

Você pode usar uma ferramenta programável com scripts para:

• Execute gráficos de Blueprints (BP) arbitrários na configuração da ferramenta e no desligamento, bem como na marca de seleção.
• Desenhe geometria 3D básica (por exemplo, linhas e pontos) e geometria do HUD 2D (por exemplo, texto na posição 3D projetada)
• Adicione conjuntos de propriedades a uma ferramenta, definida por meio de Blueprints, que atuam como configurações de ferramenta visíveis ao usuário.
• Ouça e responda a alterações nos parâmetros desses conjuntos de propriedades.
• Crie um ou mais bugs em 3D, controle suas posições e responda às alterações de transformação.
• Fornecer mensagem de feedback ao usuário.
• Adicione comportamentos de dispositivos de entrada, como clicar com o mouse, passar o mouse e observadores de teclado e executar gráficos de Blueprints em seus eventos-chave.
• Integre com widgets de Slate de Blueprints (UMG) para fornecer uma interface de usuário (IU) personalizada como no widget da janela de visualização.
• Defina condições personalizadas para a ferramenta iniciar com base nas seleções de cena atuais.

Você pode emparelhar ferramentas programáveis com scripts com outras funcionalidades da engine, como geração procedural de conteúdo (PCG) e Design de movimento.

Para obter uma visão geral do sistema e de como o desenvolvedor o usou com outras funcionalidades para construir uma masmorra, veja o vídeo Ferramentas programáveis com script e scripts de geometria | Unreal Fest 2024.

Acesse os nós e o modo de editor das ferramentas programáveis com script

Habilite o plugin

Para usar o modo de editor de ferramentas programáveis com scripts e acessar os nós, você deve habilitar o plugin associado.

Para habilitar o plugin ou verificar se ele já está habilitado, siga estas etapas:

1. Na barra de menus, selecione Editar > Plugins.

2. Na barra de pesquisa, digite "scriptable tools".

3. Habilite o plugin Scriptable Tools Editor Mode e selecione Sim na janela pop-up da caixa de diálogo.

Você não precisa habilitar o módulo de framework da ferramenta programável com scripts. O modo de editor o inclui automaticamente.

[

Modo de editor

Você acessa todas as ferramentas programáveis com scripts no modo de editor. Para abrir o modo de editor, clique no menu suspenso Modo de seleção no Editor de Níveis.

Cada ferramenta é exibida em uma paleta de ferramentas gerenciada automaticamente no modo de editor, e a propriedade definida para uma ferramenta ativa é exibida no painel de configurações. Para saber mais sobre os modos de editor, consulte Modos do Editor de Níveis.

A paleta de ferramentas inclui uma opção de filtro que exibe a ferramenta com base em um grupo de tags. A funcionalidade fornece os meios para agrupar as ferramentas e selecionar quais grupos de ferramentas carregar no modo de editor. O agrupamento ajuda a organizar um projeto com muitas ferramentas, o que pode reduzir a carga mental de ver toda a ferramenta.

Nós de Blueprints

Crie ferramentas que aparecem no modo de editor, use a função de ferramenta programável com scripts exposta em Blueprints. Você pode usar uma classe de Blueprint ou Blueprints de utilitário do editor para acessar a classe-base da ferramenta programável com scripts. Para saber mais sobre a classe-base e a subclasse, consulte a seção Classes de ferramentas programáveis com scripts nesta página.

No editor de Blueprint, todos os nó de ferramenta programável com scripts estão no submenu de ferramentas programáveis com scripts.

Submenu de ferramenta programável com scripts no Editor de Blueprint.

Para obter uma lista completa de funções, consulte Blueprints e a documentação de API Python.

Diferenças entre widgets de utilitário do editor e ferramentas programáveis com scripts

Um widget de utilitário do editor (UEW) é uma janela de diálogo não modal, contendo uma IU personalizada criada com um construtor de interface visual de elemento, na qual você pode executar qualquer tipo de script do editor. Essa é uma facilidade extremamente poderosa, mas, como um diálogo não modal, existem várias limitações.

Uma ferramenta interativa (a base da ferramenta programável com scripts) é modal. Modal significa que nenhuma outra ferramenta pode estar ativa enquanto a ferramenta estiver ativa, e o estado do editor é gerenciado de forma mais estrita. Por exemplo, a ferramenta é desligada automaticamente antes de ser salva, alterar o nível ou iniciar o Jogar no Editor (JNE), e o salvamento automático é adiado até que você saia da ferramenta. Essa funcionalidade significa que muitas coisas são mais seguras de fazer em uma ferramenta do que de outra forma. Por exemplo, se você criar atores temporários em um nível e os destruir durante o desligamento da ferramenta, eles não serão salvos acidentalmente.

Da mesma forma, como um estado modal, uma ferramenta pode capturar o mouse com mais eficiência.

Em termos de IU, uma ferramenta programável com scripts é mais estruturada do que um UEW. Você pode definir uma propriedade definida como um objeto de Blueprint separado com uma variável global. Essas variáveis globais são então exibidas em um painel de configurações de modo de editor padrão.

As ferramentas programáveis com scripts estão disponíveis no tempo de execução, mas alguma estrutura adicional deve ser configurada para aproveitar isso em um projeto da UE.

Além disso, a ferramenta programável com scripts fornece uma posição mais central para descobrir e acessa todas as ferramentas encontradas no projeto, enquanto os UEWs são acessados principalmente a partir do Navegador de Conteúdo, deixando para o usuário gerenciar a capacidade de descoberta e a organização.

Classes de ferramentas programáveis com scripts

"UScriptableInteractiveTool" é a classe-base para toda a ferramenta programável com scripts. A classe inclui eventos, configurações gerais como nome da ferramenta, opção de renderização, bugs, mensagem, opções de desligamento da ferramenta e muito mais para as subclasses. Você pode usar sua variante de editor, "UEeditorScriptableInteractiveTool", para fornecer acesso à função de Blueprint somente de editor.

"UScriptableModularBehaviorTool" e "UEeditorScriptableModularBehaviorTool" são as subclasses de suporte a interações de mouse e teclado dentro da ferramenta. Essas duas são a classe comum a ser usada, a menos que o comportamento de mouse e teclado não seja necessário.

A "UScriptableClickDragTool" foi desativada. No entanto, a ferramenta que você criou anteriormente a partir da classe funcionará na versão mais recente do editor.

Ao criar uma classe de Blueprint ou Blueprint de widget de utilitário, você deve selecionar uma das classes acima para acessar os nós de ferramentas programáveis com scripts. Para saber mais sobre essas classes, consulte a seção Ferramenta de base modular nesta página.

Configurações da ferramenta programável com scripts

A classe-base exporta várias configurações que são principalmente para a IU do modo de editor de ferramentas programáveis com scripts, mas também controla o comportamento da ferramenta de controle. Quando você abre seus Blueprints, o painel Detalhes da ferramenta contém a seguinte opção.

Eventos de ferramenta programável com scripts

A classe de ferramenta programável com scripts fornece um conjunto de eventos padrão para sua ferramenta fazer coisas diferentes em momentos distintos. Existem eventos padrão que cada classe de ferramenta tem, e várias funções adicionais estão disponíveis na ferramenta-base.

• Event On Script Setup: é executado uma única vez quando a ferramenta é iniciada. Geralmente é onde você adicionaria um conjunto de propriedades, criaria qualquer objeto de visualização e muito mais.

• Event On Script Tick: executa todas as marcas de seleção do editor, assim como outras marcas de seleção.

• Event On Script Shutdown: é executado quando a ferramenta é desligada. Por exemplo, quando o usuário fecha explicitamente a ferramenta, o modo força seu desligamento ou a ferramenta é desligada automaticamente.

• Evento Ao desenhar HUD com script: executa todos os quadros e onde a ferramenta pode desenhar um HUD 2D a partir de um objeto de API de HUD**. Para obter mais informações, consulte a seção abaixo.

• Event On Script Render é um método de desenho legado. O evento executa todos os quadros e permite que a ferramenta desenhe geometria 3D simples como linhas e pontos. Você pode usar a funcionalidade legada, mas deve observar o seguinte:

• O evento é em tempo real, então as linhas são redesenhadas a cada vez que o renderizador é chamado.

• Não há nenhuma referência persistente realizada na geometria, então você deve gerenciar as manipulações dos primitivos nos Blueprints.

Condições personalizadas

Você pode adicionar condições personalizadas com base nas seleções de cena atuais para iniciar a ferramenta. Defina as condições personalizadas em Padrões da classe > Painel Detalhes > Configurações da ferramenta programável com scripts > Requisitos de configuração da ferramenta > Personalizado.

A classe personalizada contém as seguintes funções:

• OnCanBuildTool: deve ser executada na marca de verificação.

• OnSetupTool: é executada após cliques do usuário e antes da ferramenta ser executada.

O gráfico do construtor de ferramentas é executado a cada marca de seleção, portanto condições complexas aqui podem correr o risco de deixar o desempenho do editor mais lento.

Renderização da ferramenta

É comum que uma ferramenta forneça feedback visual. Uma maneira de definir esse feedback é gerando atores temporários. Por exemplo, você pode gerar atores de malha dinâmica temporários com malhas geradas de maneira procedural por scripts de geometria. No entanto, uma linha ou um rótulo de texto geralmente é mais eficiente.

A ferramenta programável com scripts oferece suporte para essa renderização fornecendo ao objeto de API um conjunto de nós "UFunction".

Opção de renderização

A API de desenho da ferramenta programável com scripts inclui a opção de renderização definida para linhas, pontos e triângulo. Cada conjunto inclui opção relativa adicional na categoria Desenho.

Essas opções de desenho são alocadas pela ferramenta e contêm a geometria. Com isso definido, você pode adicionar e remover a respectiva geometria em qualquer ponto durante o tempo de vida da ferramenta e atualizá-la conforme necessário.

O nó Add Triangle Set inclui opções para quadrantes.

Opções de legado

Você executa os comandos de renderização legados no nó de evento Event On Script Render

Conforme observado anteriormente com este evento:

• Você pode substituir com a API de renderização.

• Desenhe linhas e pontos.

• É executado na marca de verificação e desaparece na próxima marca de verificação.

• Sem persistência.

O HUD de desenho 2D e o evento de renderização 3D são chamados com o objeto "DrawHUDAPI" e o objeto "RenderAPI", respectivamente. A ferramenta cria e gerencia esse objeto de API internamente. O único lugar em que você pode acessá-los é nesses eventos, pois eles dependem das informações de estado temporário por quadro fornecidas pela ferramenta.

A BP também tem uma biblioteca padrão de funções de desenho de depuração. Você pode usá-las como uma alternativa à função de DrawHUD e funções de renderização e chamá-las a qualquer momento. No entanto, elas ainda estão em desenvolvimento, e a API de renderização de ferramentas fornecerá mais funcionalidades.

Dispositivos

Outra funcionalidade da classe-base de ferramenta programável com scripts é a opção de criar vários dispositivos de transformação 3D. Este widget não é o dispositivo de edição padrão, mas sim o dispositivo do modo de modelagem. Um conjunto de funções é fornecido para desenvolver e gerenciar bugs e um evento para responder a alterações de bugs.

Os objetos de dispositivos não são expostos diretamente a Blueprints. Em vez disso, você gera um dispositivo com uma string identificador, e as várias funções e eventos do dispositivo funcionam a partir desse identificador.

O dispositivo básico TRS combina translação, rotação e elementos de escala para todos os eixos. No entanto, ao personalizar as opções de dispositivo, você pode criar um dispositivo mais simples para uma tarefa específica. Por exemplo, habilitando apenas a translação e a rotação no plano XY, ao desabilitar os outros subelementos do dispositivo.

Sistema de mensagens da ferramenta

A API de BP de ferramenta programável com scripts padrão fornece várias funções para sistemas de mensagens ao usuário.

• Display User Help Message: atualiza uma string de ajuda na parte inferior da IU do editor.

  

• Display User Warning Message: atualiza uma string no painel Configurações da ferramenta.

  
• Clear User Messages: remove mensagens atuais de ajuda ou avisos.
• Add Log Message: atualmente gera uma mensagem no log do editor.

A mensagem acima são strings FText e, portanto, localizáveis. Atualmente, apenas um único aviso pode ser exibido, isso pode ser melhorado no futuro.

Diversos

Uma ferramenta programável com scripts sempre é executada no contexto de um mundo atual. Por exemplo, no Editor de Níveis, é o mundo de nível padrão. Você pode usar a função Obter mundo da ferramenta para acessar esse mundo no contexto de uma ferramenta.

Desligamento da ferramenta

O fluxo padrão para sair de uma ferramenta programável com scripts é clicar em um botão Aceitar, Cancelar ou Concluir mostrado na IU. No entanto, você pode encerrar explicitamente uma ferramenta programável com scripts na função Solicitar desligamento de ferramenta, que a ferramenta pode chamar sozinha. Essa função recebe um sinalizador bAccept, que apenas é relevante para a ferramenta com a opção de desligamento "aceitar" ou "cancelar" e uma mensagem pop-up opcional do usuário.

Conjuntos de propriedades de ferramentas

Uma ferramenta programável com scripts pode exportar o widget de IU para o usuário a partir dos UObjects do conjunto de propriedades, que são mostrados em um painel de configurações de ferramenta padrão. Atualmente, não há como personalizar essa IU em Blueprints, então apenas as configurações de propriedade padrão (semelhantes ao que pode ser feito para um parâmetro em um Blueprint de ator) estão disponíveis.

Para criar um conjunto de propriedades, crie uma subclasse de Blueprint do tipo ScriptableInteractivetoolPropertySet, conforme mostrado abaixo.

Você pode então abrir o Blueprint de subclasse de conjunto de propriedades para edição e adicionar variável pública de membro. Um tipo booleano, inteiro e enum é adicionado abaixo.

Para criar o conjunto de propriedades em uma ferramenta programável com scripts específica, use o conjunto de propriedades Adicionar conjunto de propriedades de tipo. Essa função geralmente é usada em Event On Script Setup. No entanto, você pode usá-la a qualquer momento.

Você deve selecionar a classe correta de tipo para o parâmetro Property Set Type (Tipo de conjuntos de propriedades). Escolha o nome do tipo da sua subclasse de Blueprint que você criou acima. Além disso, você deve definir um identificador único para cada conjunto de propriedades (você pode combinar vários conjuntos de propriedades em uma única ferramenta). Você provavelmente precisará de acesso a esse objeto de conjunto de propriedades mais tarde. Recomendamos que você converta a saída de Adicionar conjunto de propriedades de tipo ao tipo de subclasse do seu BP e armazene-a em uma variável local.

Quando o usuário cria uma instância de sua ferramenta programável com scripts, as variáveis de membro público do seu conjunto de propriedades são mostradas no painel de configurações Ferramentas Programáveis com Scripts à esquerda, perto da paleta de ferramentas.

A classe de ferramenta programável com scripts tem várias funções auxiliares para trabalhar com o conjunto de propriedades. Você pode usar Remover conjunto de propriedades por nome para remover um conjunto de propriedades, mas observe que isso não é necessário na maioria dos casos. Se você simplesmente quiser ocultar ou mostrar um conjunto de propriedades com base em alguns critérios ou outra alteração de parâmetro, use Definir conjunto de propriedades visíveis por nome.

Além disso, você pode usar Salvar configurações do conjunto de propriedades ao desligar a ferramenta para armazenar o valor atual de um conjunto de propriedades, e Restaurar configurações do conjunto de propriedades pode recuperar esse valor salvo na configuração da ferramenta. Por padrão, os mesmos valores são restaurados em qualquer ferramenta usando a classe de conjunto de propriedades. No entanto, uma tecla de salvamento opcional pode ser fornecida para salvar ou restaurar diferentes valores em diferentes ferramentas ou até mesmo dentro da mesma ferramenta.

Observadores de propriedades

Uma função comum que você provavelmente desejará fazer com um conjunto de propriedades é reagir a alterações no valor da propriedade. A única solução totalmente confiável é pesquisar alterações de valor na função de marca de verificação. No entanto, como esse é um padrão comum, o sistema de ferramentas programáveis com scripts fornece funções utilitárias de observador de propriedade que podem fazer automaticamente essa sondagem.

Você pode usar a função abaixo em uma ferramenta programável com scripts para observar alterações em uma propriedade específica de um conjunto de propriedades e chamar um evento quando o valor for modificado.

No Blueprint, atualmente não é possível detectar automaticamente um tipo UProperty a partir de uma referência variável. Para configurar a detecção, verifique o seguinte:

• Certifique-se de usar a função que corresponde ao tipo da variável global no conjunto de propriedades.
• Transmita o nome da propriedade correto (nome da variável global no conjunto de propriedades).

Se o tipo não for simples (int, float, bool, string, FName, enumeração ou propriedade de objeto), use a versão Observar propriedade de uso geral. No entanto, seu evento de retorno de chamada é mais limitado.

Abaixo está um exemplo da função Observar propriedade de enumeração. Este é o mais complexo dos tipos simples, pois o tipo de enumeração é desconhecido. O parâmetro New Value (Novo Valor) que é passado para o evento de retorno de chamada é um uint8 e deve ser explicitamente convertido no tipo UEnum correto (nesse caso, EGeometryScriptAxis). No momento, não é possível verificar erros aqui. O editor converterá a função em qualquer teclado de enumeração.

Para parâmetros complexos, como um UStruct aninhado como uma variável de membro FVector, você pode usar a função Observar propriedade. Essa função pode detectar alterações em praticamente qualquer variável UProperty. No entanto, o evento de retorno de chamada não receberá um parâmetro New Value (Novo Valor) como outros camos. Se você criar uma variável de membro para a propriedade definida em sua ferramenta, poderá buscar o valor da propriedade diretamente no evento. Esse tipo de observador também é computacionalmente mais caro, e você só deve usá-lo quando necessário.

Ferramenta-base modular

As ferramentas-base são subclasses C++ do framework de ferramentas interativas programáveis com scripts que fornecem funcionalidades adicionais integradas para lidar com casos comuns e expor mais funcionalidades, como manipulação e captura de dispositivos de entrada. Você escolhe uma ferramenta-base conforme o tipo de ferramenta que você deseja criar. A versão de editor da ferramenta-base fornece acesso à função de Blueprint somente para editor.

A classe Ferramenta de comportamento modular programável com scripts e sua instância de editor fornecem acesso a funções de comportamento, que são parametrizadas por uma lista de retornos de chamada. Esse sistema substitui eventos integrados e fornece os meios para misturar e combinar comportamentos, potencialmente até mesmo com duplicação. Essa substituição é útil porque você pode criar vários comportamentos de clique em uma única ferramenta que aciona diferentes condições. Por exemplo, um clique com o botão esquerdo do mouse, outro com o botão direito e outro com o botão esquerdo + Ctrl.

Os comportamentos expostos incluem o seguinte:

• Clique e arraste
• Passagem do mouse
• Roda do mouse
• Vários cliques
• Clicar ou arrastar
• Entradas de teclado únicas e múltiplas

Entradas de comportamento de ferramenta programável com scripts.

Habilitar plugin somente para editor

Na Unreal Engine, você pode definir dependências de plugin para plugins e módulos de projeto.

Nos arquivos ".uproject" e ".uplugin" que exigem "UScriptabletoolsFramework" ou "UScriptabletoolsEditorMode" para uso no editor, configure a seção "TargetAllowList" como "Editor". Para saber mais sobre a configuração de plugins e arquivos, consulte plugin.

		{

			"Name": "ScriptabletoolsEditorMode",

			"Habilitado": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

{ "Name": "ScriptabletoolsEditorMode", "Habilitado": true, "TargetAllowList": [ "Editor" ] },

Próximos passos

Com uma compreensão básica do sistema de ferramentas programáveis com scripts, você pode começar a criar sua ferramenta com o tutorial Como criar uma ferramenta programável com scripts.