Sistema de herramientas programables

El sistema de herramientas programables proporciona funciones y un modo editor para crear herramientas interactivas personalizadas. El objetivo del sistema es hacer posible que los programadores que no dominan C++ creen herramientas interactivas en Unreal Engine.

El punto principal de referencia para una herramienta interactiva es el modo del editor de modelado. Sin embargo, el sistema de herramientas programables no tiene conexión directa con el modo de modelado o con la secuenciación de comandos de geometría.

El complemento del sistema de herramientas programables expone el marco de herramientas interactivas a un blueprint (BP), proporcionando a creadores y artistas técnicos los medios para diseñar herramientas que se comporten de forma similar al modo de modelado.

Recomendamos entender bien los conceptos básicos de los blueprints para empezar a utilizar las herramientas programables. Para obtener más información, consulta Introducción a los blueprints.

Al crear subclases de Blueprint (BP) de clases base, puedes añadir herramientas personalizadas al modo del editor de herramientas programables. Con el modo del editor, los artistas pueden acceder a estas herramientas personalizadas para sus proyectos.

Para qué sirve una herramienta programable

Puedes utilizar una herramienta programable para:

• Ejecutar grafos de Blueprint (BP) arbitrarios al configurar y apagar la herramienta, así como en el tic.
• Dibujar geometría 3D básica (por ejemplo, líneas y puntos) y geometría 2D del HUD (por ejemplo, texto en ubicaciones 3D proyectadas).
• Añadir un conjunto de propiedades a una herramienta mediante blueprints que actúan como ajustes de herramienta visibles para el usuario.
• Escuchar y responder a los cambios de los parámetros con propiedades definidas.
• Crear uno o más gizmos 3D, controlar sus posiciones y responder a los cambios del transformador.
• Proporciona mensajes de respuesta al usuario.
• Añadir comportamientos de dispositivo de entrada, como clics del ratón, pasar el ratón por encima y observadores de teclado, y ejecutar grafos de Blueprint en sus eventos clave.
• Integrar con widgets de Slate de Blueprint (UMG) para proporcionar una interfaz de usuario personalizada como en widgets de visor.
• Definir condiciones personalizadas para que la herramienta se inicie en función de las selecciones de escena actuales.

Puedes emparejar las herramientas programables con otras funciones del motor, como la generación procedimental de contenido (PCG) y el diseño de grafismos en movimiento.

Para obtener una visión general del sistema y de cómo el desarrollador lo ha utilizado con otras funciones para construir una mazmorra, consulta el vídeo sobre secuenciación de comandos de geometría y herramientas programables Geometry Scripting and Scriptable Tools | UE Fest 2024.

Cómo acceder al modo del editor y a los nodos de herramientas programables

Cómo habilitar el complemento

Para utilizar el modo del editor de herramientas programables y acceder a los nodos, debes activar el complemento asociado.

Para activar el complemento o comprobar que ya está activado, sigue estos pasos:

1. En la barra de menús, selecciona Editar > Complementos.

2. En la barra de búsqueda, escribe «herramientas programables».

3. Activa el complemento Scriptable Tools Editor Mode y selecciona Sí en el cuadro de diálogo emergente.

No es necesario activar el módulo Scriptable Tools Framework. El modo del editor lo incluye automáticamente.

Modo del editor

Puedes acceder a todas las herramientas que admiten secuencias de comandos desde el modo del editor de herramientas programables. Para abrir el modo del editor, haz clic en el menú desplegable Modo de selección en el editor de niveles.

Cada herramienta aparece en una paleta de herramientas gestionada automáticamente en el modo del editor, y los conjuntos de propiedades de una herramienta activa aparecen en el panel de ajustes. Para obtener más información sobre los modos del editor, consulta Modos del editor de niveles.

La paleta de herramientas incluye una opción de filtro que muestra herramientas en función de una etiqueta de agrupación. La función proporciona los medios para agrupar herramientas y seleccionar qué grupos de herramientas cargar en el modo del editor. La agrupación ayuda a organizar un proyecto con muchas herramientas, lo que puede reducir la carga cognitiva de verlas todas juntas.

Nodos de Blueprint

Para crear herramientas que aparezcan en el modo del editor, utiliza las funciones de herramienta programable expuesta en blueprints. Puedes utilizar una clase de Blueprint o un blueprint de utilidades del editor para acceder a la clase base de la herramienta mediante secuencias de comandos. Para obtener más información sobre la clase y subclase base, consulta la sección Clases de la herramienta programable en esta página.

En el editor de blueprints, todos los nodos de herramientas programables se encuentran en el submenú Herramienta programable.

Submenú Herramienta programable en el editor de blueprints.

Para ver una lista completa de las funciones, consulta Blueprint y Python en la documentación de la API.

Diferencias entre la herramienta programable y el widget de utilidades del editor

Un widget de utilidades del editor (EUW) es una ventana de diálogo no modal que contiene una IU personalizada creada con un constructor de GUI visual, en el que puedes hacer cualquier tipo de secuenciación de comandos del editor. Se trata de una funcionalidad extremadamente potente, pero como diálogo no modal tiene varias limitaciones.

Una herramienta interactiva (la base de las herramientas programables) es modal. Esto significa que ninguna otra herramienta puede estar activa al mismo tiempo y el estado del editor se gestiona de forma más estricta. Por ejemplo, la herramienta se cierra automáticamente antes de guardar, cambiar de nivel o iniciar Reproducir en el editor (PIE), y el guardado automático se aplaza hasta que se sale de la herramienta. Esta función significa es más seguro hacer muchas cosas en una herramienta que en otro modo. Por ejemplo, si creas actores temporales en un nivel y los destruyes durante el apagado de la herramienta, no se guardarán accidentalmente.

Del mismo modo, como un estado modal, una herramienta puede capturar el ratón de forma más eficiente.

En términos de IU, una herramienta programable está más estructurada que un EUW. Puedes definir conjuntos de propiedades como objetos de Blueprint independientes con variables públicas. A continuación, esas variables públicas se muestran en un panel de configuración estándar del modo del editor.

Las herramientas programables están disponibles en tiempo de ejecución, sin embargo, es necesario configurar alguna infraestructura adicional para aprovecharlas en un proyecto de UE.

Además, las herramientas programables proporcionan una posición más central para descubrir y acceder a todas las herramientas que se encuentran en el proyecto, mientras que a los EUW se accede principalmente desde el explorador de contenido, dejando que el usuario gestione la detectabilidad y la organización.

Clases de herramientas programables

UScriptableInteractiveTool es la clase base para todas las herramientas programables. La clase incluye eventos, ajustes generales como el nombre de la herramienta, las opciones de renderizado, el gizmo, el mensaje, opciones de apagado de la herramienta y mucho más para las subclases. Puedes utilizar su variante de editor, UEditorScriptableInteractiveTool, para proporcionar acceso a funciones de Blueprint exclusivas del editor.

UScriptableModularBehaviorTool y UEditorScriptableModularBehaviorTool son las subclases que admiten las interacciones del ratón y el teclado dentro de la herramienta. Son las clases habituales de uso, a menos que no se necesiten los comportamientos de ratón y teclado.

UScriptableClickDragTool está en desuso. Sin embargo, la herramienta que hayas creado previamente a partir de la clase funcionará en la última versión del editor.

Cuando crees una clase de Blueprint o un blueprint de widget de utilidades, debes seleccionar una de las clases anteriores para acceder a los nodos de las herramientas programables. Para obtener más información sobre esta clase, consulta la sección Herramienta base modular de esta página.

Configuración de la herramienta programable

La clase base expone varios ajustes que son principalmente para el modo de interfaz de usuario del editor de herramientas programables, pero también para controlar el comportamiento de la herramienta. Al abrir el blueprint, el panel Detalles de la herramienta contiene las siguientes opciones.

Eventos de herramientas programables

La clase Herramienta programable proporciona un conjunto de eventos estándar para que tu herramienta haga distintas cosas en diferentes momentos. Hay eventos estándar que tiene cada clase de la herramienta, y varias funciones adicionales están disponibles en las herramientas base.

• Event On Script Setup: se ejecuta una sola vez al iniciar la herramienta. Por lo general, aquí es donde se añadirían conjuntos de propiedades, se crearía cualquier objeto de vista previa, etc.

• Event On Script Tick: ejecuta todos los tic del editor, igual que cualquier otro tic.

• Event On Script Shutdown: se ejecuta cuando se apaga la herramienta. Por ejemplo, cuando el usuario cierra explícitamente la herramienta, el modo fuerza el cierre o la herramienta se apaga sola.

• Event On Script Draw HUD: se ejecuta cada fotograma y donde la herramienta puede dibujar un HUD 2D a partir de un objeto API del HUD. Para obtener más información, consulta la sección siguiente.

Event On Script Render es un método de dibujado heredado. El evento ejecuta cada fotograma y permite que la herramienta dibuje geometría 3D simple, como líneas y puntos. Puedes utilizar la función heredada, pero debes tener en cuenta lo siguiente:

• El evento es en tiempo real, por lo que las líneas se redibujan cada vez que se llama al renderizado.

• No hay referencias persistentes de la geometría, por lo que debes gestionar las manipulaciones de las formas primitivas en el blueprint.

Condiciones personalizadas

Puedes añadir condiciones personalizadas basadas en las selecciones de escena actuales para iniciar la herramienta. Define las condiciones personalizadas en Valores predeterminados de clase > Panel Detalles > Configuración de herramienta programable > Requisitos de configuración de herramientas > Personalizado.

La clase personalizada contiene la siguiente función:

• OnCanBuildTool: tiene que ejecutarse en el tic.

• OnSetupTool: se ejecuta después de que el usuario haga clic y antes de que se ejecute la herramienta.

El grafo del constructor de herramientas se ejecuta en cada tic, por lo que las condiciones complejas aquí pueden correr el riesgo de ralentizar el rendimiento del editor.

Renderizado de la herramienta

Es habitual que una herramienta proporcione información visual. Un modo de definir esta información es generando actores temporales. Por ejemplo, puedes generar actores temporales de malla dinámica con mallas de forma procedimental mediante secuenciación de comandos de geometría. Sin embargo, una línea o una etiqueta de texto suele ser más eficaz.

Las herramientas que admiten secuencias de comandos admiten este renderizado proporcionando al objeto de la API un conjunto de nodos UFunction.

Opciones de renderizado

La API Dibujado de las herramientas programables incluye un conjunto de opciones de renderizado para líneas, puntos y triángulos. Cada conjunto incluye opciones relativas adicionales en la categoría Dibujado.

Estas opciones de dibujado las asigna la herramienta y contienen la geometría. Con estos conjuntos, puedes añadir y eliminar la geometría correspondiente en cualquier momento durante la vida útil de la herramienta y actualizarlos según sea necesario.

El nodo Add Triangle Set incluye la opción para cuads.

Opciones heredadas

Ejecuta los comandos heredados de renderizado en el nodo del evento Event On Script Render.

Como se ha indicado anteriormente con este evento:

• Se puede anular con la API de renderizado.

• Dibuja líneas y puntos.

• Se ejecuta en el tic y desaparece en el siguiente tic.

• Sin persistencia.

Los eventos HUD de dibujado 2D y Renderizado 3D se llaman con objetos DrawHUDAPI y RenderAPI, respectivamente. La herramienta crea y gestiona internamente estos objetos de la API. El único lugar desde el que puedes acceder es desde estos eventos, ya que dependen de la información de estado temporal por fotograma proporcionada por la herramienta.

BP también tiene una biblioteca estándar de funciones de dibujado de depuración. Puedes utilizarlas como alternativa a las funciones del HUD de dibujado y de renderizado, y llamarlas en cualquier momento. Sin embargo, están en fase de desarrollo, y las API de renderizado de la herramienta proporcionarán más funciones.

Gizmos

Otra funcionalidad de la clase base de la herramienta programable es la opción de crear múltiples gizmos de transformación 3D. Este widget no es el gizmo estándar del editor, sino un gizmo del modo de modelado. Se proporciona un conjunto de funciones para desarrollar y gestionar el gizmo y un evento para responder a los cambios del gizmo.

Los objetos gizmo no están directamente expuestos a los blueprints. En su lugar, generas un gizmo con una cadena identificador y las distintas funciones y eventos del gizmo funcionan a partir de este identificador.

El gizmo básico de TRS combina elementos de traslación, rotación y escala para todos los ejes. Sin embargo, si personalizas las opciones del gizmo, puedes crear un gizmo más sencillo para una tarea específica. Por ejemplo, habilitando solo la traslación y la rotación en el plano XY o desactivando el otro subelemento del gizmo.

Mensajes de la herramienta

La API de BP estándar de la herramienta programable proporciona varias funciones para enviar mensajes al usuario.

• Mostrar mensaje de ayuda al usuario: actualiza una cadena de ayuda en la parte inferior de la IU del editor.

  

• Mostrar mensaje de advertencia al usuario: actualiza una cadena en el panel de ajustes de la herramienta.

  
• Borrar mensajes de usuario: borra los mensajes de ayuda o advertencia actuales.
• Añadir mensaje de registro: actualmente imprime un mensaje en el registro del editor.

Los mensajes anteriores son cadenas FText, por lo que son localizables. Actualmente solo se puede mostrar una única advertencia. Es posible que esto se mejore en el futuro.

Varios

Una herramienta programable siempre se ejecuta en el contexto de un mundo actual. Por ejemplo, en el editor de niveles, es el mundo del nivel estándar. Puedes utilizar la función Obtener mundo de la herramienta para acceder a este mundo en el contexto de una herramienta.

Cierre de la herramienta

El flujo estándar para salir de una herramienta programable es hacer clic en un botón Aceptar, Cancelar o Completar que aparece en la interfaz de usuario. No obstante, puedes apagar explícitamente una herramienta programable desde la función Solicitar cierre de la herramienta, a la que la propia herramienta puede llamar. Esta función toma un indicador bAccept, que solo es relevante para herramientas con la opción de aceptar o cancelar el cierre y un mensaje emergente opcional para el usuario.

Conjuntos de propiedades de la herramienta

Una herramienta programable puede exponer widgets de IU al usuario desde UOBjects de conjunto de propiedades, que se muestran en un panel de ajustes estándar de la herramienta. Actualmente, no hay forma de personalizar esta IU en los blueprints, por lo que solo están disponibles los ajustes estándar de propiedades (similar a lo que se puede hacer para un parámetro en un blueprint de actor).

Para crear un conjunto de propiedades, crea una subclase de BP del tipo ScriptableInteractivetoolPropertySet, como se muestra a continuación.

A continuación, puedes abrir el blueprint de la subclase del conjunto de propiedades para editar y añadir variables miembro públicas. Debajo se añade un tipo booleano, entero y enum.

Para crear el conjunto de propiedades en una herramienta programable concreta, utiliza la función Añadir conjunto de propiedades de tipo. Esta función se suele utilizar en Event On Script Setup. Sin embargo, puedes utilizarla en cualquier momento.

Debes seleccionar el tipo de clase correcto para el parámetro Property Set Type. Elige el nombre del tipo de la subclase de Blueprint que has creado anteriormente. Además, debes establecer un identificador único para cada conjunto de propiedades (puedes combinar varios conjuntos de propiedades en una sola herramienta). Es probable que necesites acceder a este objeto de conjunto de propiedades más adelante. Recomendamos convertir la salida de Añadir conjunto de propiedades de tipo al tipo de tu subclase de Blueprint y almacenarla en una variable local.

Cuando el usuario crea una instancia de tu herramienta programable, las variables miembro públicas de tu conjunto de propiedades se muestran en el panel de ajustes de Herramientas programables a la izquierda, junto a la paleta de herramientas.

La clase Herramienta programable tiene varias funciones de ayuda para trabajar con conjuntos de propiedades. Puedes utilizar Eliminar conjunto de propiedades por nombre para eliminar un conjunto de propiedades; sin embargo, ten en cuenta que esto no es necesario en la mayoría de los casos. Si simplemente quieres ocultar o mostrar un conjunto de propiedades en función de algún criterio o cambio de parámetro, utiliza Establecer conjunto de propiedades visible por nombre.

Además, puedes utilizar Guardar configuración del conjunto de propiedades al apagar la herramienta para almacenar el valor actual de un conjunto de propiedades y Restaurar ajustes del conjunto de propiedades para recuperar esos valores guardados en la configuración de la herramienta. De forma predeterminada, los mismos valores se restauran en cualquier herramienta que utilice la clase del conjunto de propiedades. Sin embargo, se puede proporcionar la opción Guardar clave para guardar o restaurar diferentes valores en distintas herramientas, o incluso dentro de la misma herramienta.

Observadores de propiedades

Una función habitual que probablemente querrás hacer con un conjunto de propiedades es reaccionar a los cambios en el valor de la propiedad. La única solución totalmente fiable es sondear los cambios de valores en la función de tic. Sin embargo, dado que se trata de un patrón habitual, el sistema de herramientas programables proporciona funciones de observadores de propiedades de utilidad que pueden realizar automáticamente este sondeo.

Puedes utilizar las funciones siguientes en una herramienta programable para observar los cambios en un conjunto específico de propiedades y llamar un evento cuando se modifique el valor.

En BP, actualmente no es posible detectar automáticamente un tipo UProperty a partir de una referencia de variable. Para configurar la detección, asegúrate de lo siguiente:

• Utiliza la función que coincida con el tipo de la variable pública en el conjunto de propiedades.
• Pasa el nombre de propiedad correcto (el nombre de la variable pública en el conjunto de propiedades).

Si el tipo no es simple (Int, Float, Bool, String, FName, Enum u Object), utiliza la versión de uso general de la propiedad del observador. Sin embargo, su evento de devolución de llamada es más limitado.

A continuación se muestra un ejemplo de la función Propiedad de enumeración de observador. Este es el más complejo de los tipos simples, ya que se desconoce el tipo de enumeración. El parámetro New Value que se pasa al evento de devolución de llamada es un uint8 y debe convertirse explícitamente en el tipo de UEnum correcto (en este caso, EGeometryScriptAxis). Actualmente no es posible comprobar ningún error aquí. El editor convertirá la función en cualquier tipo de enumeración.

Para parámetros complejos, por ejemplo, un UStruct anidado como una variable miembro FVector, puedes utilizar la función Propiedad de observador. Esta función puede detectar cambios en casi cualquier variable UProperty. Sin embargo, el evento de devolución de llamada no recibirá un parámetro New Value como los otros campos. Si creas una variable miembro para el conjunto de propiedades en tu herramienta, puedes obtener directamente el valor de la propiedad en el evento. Este tipo de observador también tiene más coste computacional y solo debes utilizarlo cuando sea necesario.

Herramienta base modular

Las herramientas base son subclases de C++ del marco de herramientas interactivas programables que proporciona una función integrada adicional para controlar casos comunes y una función expuesta adicional, como el control y la captura de dispositivos de entrada. La herramienta base se elige en función del tipo de herramienta que se quiera crear. La versión de editor de la herramienta base proporciona acceso a funciones de Blueprint exclusivas del editor.

La clase Herramienta de comportamiento modular programable y su instancia del editor proporcionan acceso a funciones de comportamiento, que se parametrizan mediante una lista de devoluciones de llamada. Este sistema sustituye a los eventos integrados y proporciona los medios para mezclar y emparejar comportamientos, potencialmente incluso con duplicación. Esta sustitución es útil porque puedes crear múltiples comportamientos de clic dentro de una sola herramienta que active diferentes condiciones. Por ejemplo, un clic con el botón izquierdo del ratón, otro con el derecho, y otro con el izquierdo + Ctrl.

Los comportamientos expuestos son los siguientes:

• Hacer clic y arrastrar
• Pasar el ratón por encima
• Rueda del ratón
• Varios clics
• Hacer clic o arrastrar
• Entradas de teclado únicas y múltiples

Entradas de comportamiento de herramientas programables.

Cómo habilitar complementos exclusivos del editor

En Unreal Engine, puedes definir dependencias de complementos para módulos y complementos de proyectos.

En los archivos .uproject y .uplugin que requieren UScriptabletoolsFramework o UScriptabletoolsEditorMode para usarlos en el editor, configura la sección TargetAllowList como Editor. Para obtener más información más sobre los complementos y la configuración de archivos, consulta Complementos.

		{

			"Name": "ScriptabletoolsEditorMode",

			"Enabled": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

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

Siguientes pasos

Con unos conocimientos básicos del sistema de herramientas programables, puedes empezar a crear tus herramientas con el tutorial Cómo crear una herramienta programable.