Nodos y terminología

Antes de continuar conviene recalcar que la terminología Nodo hay que usarla con cuidado. Cuando nos referimos a los Nodos de Visual Script (o generalmente Nodos) nos referimos a las pequeñas cajitas que conectas con líneas, y que son parte de un gráfico. Cuando nos referimos a Nodos de escena, esto implica que nos referimos a los elementos que configuran una escena, y que son parte del árbol de dicha escena. El nombre es similar pero su función es diferente. Cuando nos refiramos a Nodo aquí nos estaremos refiriendo a un Nodo de visual script si no se indica lo contrario.

../../../_images/visual_script16.png

Propiedades de los nodos

Como en otras implementaciones se lenguajes visuales de código, cada nodo tiene propiedades editables. En Godot, no obstante, intentamos evitar un excesivo uso de controles editables por el bien de la legibilidad.

Los nodos todavía muestran la información requerida como texto, pero la edición se realiza a través del Inspector. Para editarlos, selecciona cualquier nodo y edita sus propiedades en el Inspector.

Puertos y conexiones

La programación en Godot Visual Scripting se realiza a través de Nodos y Conexiones de Puertos dentro de cada función.

Puertos

Los nodos en Godot Visual Scripting tienen Puertos. Éstos son los puntos finales que aparecen a la izquierda y derecha de los nodos y que se pueden usar para hacer Conexiones: Hay dos tipos de Puertos: Secuencias y Datos.

../../../_images/visual_script17.png

Los Puertos de Secuencia (sequence ports) indican el orden en el que se ejecutan las operaciones. Típicamente cuando un Nodo es procesado, irá al siguiente nodo desde uno de los puertos a su derecha. Si no hay nada conectado, la función puede terminar, o se puede intentar otra salida Puerto de secuencia (esto depende del nodo). Gracias a esto, puede seguir el flujo lógico dentro de una función siguiendo las líneas blancas. No todos los Nodos tienen Puertos de Secuencia. De hecho, la mayoría no los posee.

Los Puertos de Datos contienen valores tipados. Los tipos pueden ser cualquier tipo regular de Godot, como un booleano, un entero, una cadena de texto, un Vector3, un array y cualquier Objeto o Escena, etc. Un Puerto de Datos en la parte derecha de un nodo se considera una salida, mientras que un puerto a la izquierda es una entrada. Conectando estos permitimos que la información fluya hacia el siguiente nodo.

No todos los tipos de Puertos de Datos son compatibles y permiten la interconexión. Presta especial atención a los colores y los iconos, cada tipo tiene una representación diferente:

../../../_images/visual_script18.png

Conexiones

La conexión es un proceso relativamente sencillo. Arrastra un Puerto de salida hacia un Puerto de entrada.

../../../_images/visual_script_connect.gif

Desconectar necesita un poco más de práctica. La desconexión de los Puertos de Datos se consigue arrastrando la Entrada hacia afuera, mientras que para los Puertos de Secuencia, esto se consigue arrastrando hacia fuera la Salida.

../../../_images/visual_script_disconnect.gif

Esto puede parecer extraño al principio, pero es así porque los Puertos de Datos son 1:N (una salida única puede conectarse a muchas entradas), mientras que los Puertos de Secuencia son N:1 (Muchas salidas pueden conectarse a una única entrada).

Conectando a un espacio vacío (arrastrar para conectar pero soltar en un espacio vacío) es sensible al contexto, mostrará una lista de operaciones comunes. Para secuencias, serán nodos condicionales:

../../../_images/visual_script52.png

Mientras que, para datos, se abrirá el menú contextual set/get/call:

../../../_images/visual_script53.png

Agregando nodos

Finalmente llegamos a la parte divertida! Pero, antes de explicar en detalle lo que hace cada tipo de nodo, echemos un vistazo a cómo son agregados y tratados los nodos más comunes.

Accediendo a nodos de la escena

Una de las tareas más comunes es acceder a Nodos del árbol de escena (de nuevo, no confundir con Nodos de Visual Script). Arrastrando del árbol de escena y soltando en el área de trabajo, pedirá seleccionar un método (a veces referido como función miembro) de este nodo.

../../../_images/visual_script19.png

Mientras que acceder a propiedades es deseable en la mayoría de los casos (más sobre esto a continuación), a veces llamar métodos puede ser útil también. Los métodos ejecutan acciones en objetos. En el caso anterior, el puntero del ratón puede ser transportado a una posición en coordenadas locales del control. Otro caso de uso común poner en cola un nodo para borrarlo, lo que se hace con el método queue_free.

../../../_images/visual_script20.png

Se debe tener en cuenta que esto sólo funciona si la escena siendo editada contiene el Visual Script en uno de los nodos! De otro modo, se mostrará una advertencia.

Accediendo a propiedades de nodos de la escena

Este es el modo más común de editar Nodos de la escena en Visual Scripting. Seleccione un Nodo de la escena del Árbol de escena, vaya al Inspector, encuentre el Nombre de la propiedad que quiere editar (el nombre, no el valor!) y arrástrelo al área de trabajo:

../../../_images/visual_script21.png

El resultado será que este valor podrá ser cambiado desde el script escribiendo a un Puerto de Datos (Data Port).

Si en cambio deseas leer este valor, arrastra el nodo de nuevo pero mantén presionada la tecla Control (o Comando en Mac). Esto creará un getter:

../../../_images/visual_script22.png

En este caso, el valor podrá ser leído desde un Puerto de datos.

Variables

Las variables son contenedores de memoria locales al script que pueden contener un valor. Este valor se puede leer desde cualquiera de las funciones del script o desde otros scripts mediante el método descrito en el paso anterior.

Para agregar una variable, presione el botón «+» en la sección Variables del panel Miembros. Doble clic en la nueva variable para renombrarla:

../../../_images/visual_script23.png

Clic derecho en la variable permite configurar sus propiedades:

../../../_images/visual_script24.png ../../../_images/visual_script25.png

Como puede verse, el tipo y valor iniciales de la variable pueden ser cambiados, así como algunos hints (tipos) de propiedades. Seleccionando la opción «Export» se hace que la variable sea visible en el Inspector cuando se selecciona el nodo. Esto también la hace disponible a otros scripts mediante el método descrito en el paso anterior.

../../../_images/visual_script28.png

Para utilizar una variable en el script, simplemente arrástrela al área de trabajo para crear un getter:

../../../_images/visual_script26.png

Del mismo modo, manteniendo presionado Control (Command en Mac) para crear un setter:

../../../_images/visual_script27.png

Señales

También es posible crear tus propias señales en un script y usarlas. Para esto, realiza los mismos pasos utilizados para variables en el paso anterior, pero para la sección Signals:

../../../_images/visual_script29.png

Una señal también puede ser editada con el menú de clic derecho para personalizar sus argumentos:

../../../_images/visual_script30.png

La señal que has creado aparecerá en el Inspector junto con las señales de nodo incorporadas. Esto permite conectarlo desde otro script procedente de otro Nodo de la Escena:

../../../_images/visual_script31.png

Finalmente, para emitir la señal, simplemente arrástrela al área de trabajo:

../../../_images/visual_script32.png

Recuerde que emitir una senal es una operación secuenciada, así que debe venir de un puerto Sequence.

Agregando más nodos

Ahora que lo básico está cubierto, hablemos de la gran la gran cantidad de nodos de utilidad (utility nodes) disponibles para tu área de trabajo! En el panel de miembros de abajo, existe la lista de todos los tipos de nodos disponibles:

../../../_images/visual_script33.png

Ctrl-F (Command-F en Mac) le permite buscar en la lista.

Cualquiera de ellos peude ser arrastrado a la escena. A diferencia de los nodos(ejemplo, arrastrar una propiedad del inspector establece que el contexto del nodo se edita automáticamente), éstos se añaden sin ninguna información «contextual», por eso se tiene que hacer manualmente.

../../../_images/visual_script34.png

Recuerda que puedes verificar la clase de referencia a cada nodo que se realiza, ya que estan documentados, que se mencionan, en un breve resumen de los siguientes tipos de nodos:

Constantes

Nodos constantes pueden proveer valores que, aunque no cambian con el tiempo, pueden ser útiles como valores de referencia. En la mayor parte del tiempo son enteros o flotantes.

../../../_images/visual_script36.png

La primera es «Constant» que permite seleccionar cualquier valor de cualquier tipo como constante, desde un entero (42) hasta una cadena («Hello!»). En general, este nodo no se utiliza tan a menudo debido a los valores de entrada por defecto en Data Ports, pero es bueno saber que existe.

El segundo es el nodo GlobalConstant, que contiene una larga lista de constantes para tipos globales en Godot. Allí encontrarás constantes útiles para referirse a nombres clave, botones de joystick o ratón, etc.

El tercero es MathConstant, el cual provee constantes típicas en matemáticas como PI, e, etc.

Datos

Los nodos Data tratan todo tipo de acceso a información. Cualquier información en Godot es accedida mediante esos nodos, esos son los más importantes para usar y también muy diversos.

../../../_images/visual_script37.png

Hay muchos tipos de nodo de interés aquí, a continuación hay una breve descripción de ellos:

Acción

Los nodos Action son vitales cuando se trata la entrada desde un dispositivo. En el siguiente ejemplo, el control es trasladado hacia la derecha cuando la acción «move_right» es presionada.

../../../_images/visual_script38.png

Engine Singleton

Los Engine Singletons son interfaces globales (pueden ser accedidas sin una referencia, y están siempre disponibles a diferencia de Nodos de la Escena). Tienen muchos propósitos pero, en general, son útiles para acceso a funciones de bajo nivel del SO.

../../../_images/visual_script39.png

Recuerda que arrastrando una conexión a un espacio vacío ayudará a llamar funciones o asignar/obtener (set/get) propiedades en los siguientes:

../../../_images/visual_script40.png

Variables locales

Estos son nodos que puedes usar como almacenamiento temporal para tus gráficos. Asegúrate que todos tienen el mismo nombre y tipo al usarlos y que hacen referencia a la misma parte de memoria.

../../../_images/visual_script41.png

Como se puede apreciar arriba, hay dos nodos disponibles: Un getter simple y un getter secuenciado (la asignación requiere un puerto secuenciado).

Nodo Scene

Esto es sólo una referencia a un nodo en el árbol, pero es más fácil usar este nodo arrastrando el nodo actual desde el árbol de escena hasta el área de trabajo (esto lo creará y configurará).

Propio

En raras ocasiones, se puede desear pasar este Nodo de Escena como argumento. Se puede usar para llamar funciones y establecer/obtener propiedades, o arrastrar nodos (o eventos del mismo nodo que tenga el script) desde el Árbol de Escenas hasta el área de trabajo para esto.

Árbol de Escenas

Este nodo es similar al nodo Singleton porque hace referencia al SceneTree, que contiene la escena activa. El SceneTree, sin embargo, sólo funciona cuando el nodo se encuentra activo en la escena, de lo contrario, el acceso a él devolverá un error.

SceneTree permite hacer muchas cosas de bajo nivel, como cambiar las opciones de ajuste de pantalla, llamar grupos, crear temporizadores o cargar otra escena principal. Es una clase con la que hay que estar familiarizado.

Precarga

Esto hace la misma función que preload() en GDScript. Mantiene este recurso cargado y listo para usar. En lugar de instanciar el nodo, es más sencillo arrastrar el recurso deseado desde el panel de Sistema de Archivos hasta el área de trabajo.

Ruta de Recursos

Este nodo es un simple helper para obtener una cadena con una ruta a un recurso que puedes elegir. Es útil en funciones que cargan cosas desde el disco.

Comentario

Un nodo Comentario funciona como un nodo que puede ser redimensionado para colocarlo alrededor de otros nodos. No tratará de obtener el foco o ser puesto al frente al seleccionarlo. También se puede utilizar para escribir texto en él.

../../../_images/visual_script42.png

Control de Flujo

Los nodos de control de flujo permiten que la ejecución tome diferentes caminos, normalmente dependiendo de una condición determinada.

../../../_images/visual_script43.png

Condición

This is a simple node that checks a bool port. If true, it will go via the «true» sequence port. If false, the second. After going for either of them, it goes via the «done» port. Leaving sequence ports disconnected is fine if not all of them are used.

Iterador

Algunos tipos de dato en Godot (por ejemplo array y diccionarios) son iterables. Esto significa que una porción de código puede ser ejecutada por cada elemento que tiene.

El nodo Iterator va a través de todos los elementos y, por cada uno, pasa por el puerto secuencia «each», haciendo que el elemento esté disponible en el puerto de datos «elem».

Cuando está listo, va por el puerto secuencia «exit».

Return

Algunas funciones pueden retornar valores. En general, para las funciones virtuales, Godot agregará el nodo Return. Un nodo return fuerza a la función a terminar.

Secuencia

Este nodo es útil principalmente para organizar el grafo. Llama a sus puertos secuencia en orden.

TypeCast

Este es un nodo útil y de uso común. Puedes usarlo para asignar argumentos u otros objetos al tipo deseado. Después, puedes arrastrar el objeto de salida para obtener su completa finalización.

../../../_images/visual_script55.png

También es posible convertir a un script, lo que permite obtener propiedades y funciones del script:

../../../_images/visual_script54.png

Switch

El nodo Switch es similar al nodo Condition, pero iguala muchos valores al mismo tiempo.

While

Esta es una forma primitiva de iteración. La salida de secuencia «repeat» será llamada tantas veces como la condición en el puerto de datos «cond» se cumpla.

Funciones

Los Function son ayudantes, la mayoría del tiempo deterministas. Toman algunos argumentos de entrada y devuelven una salida. En general no son secuenciados.

Funciones propias

There is a list of built-in helpers. The list is almost identical to the one from GDScript. Most of them are mathematical functions, but others can be useful helpers. Make sure to take a look at the list at some point.

By Type

Estos son los métodos disponibles para los tipos básicos. Por ejemplo, si quieres un producto punto, puedes buscar «punto» en lugar de la categoría Vector3. En la mayoría de los casos sólo hay que buscar en la lista de nodos, debería ser más rápido.

Call

Esta es la llamada a nodo genérica. Es raramente utilizada directamente, se utiliza arrastrando desde un nodo ya configurado.

Constructores

Esas son todas las funciones necesarias para crear tipos de datos básicos de Godot. Por ejemplo, si necesitas crear un Vector3 desde 3 floats, se debe utilizar un constructor.

../../../_images/visual_script44.png

Destructor

Es lo contrario al Constructor, permite separar tipos básicos en sus sub-elementos.

../../../_images/visual_script45.png

Emitir Señal

Emite señales desde cualquier objeto. En general no es tan útil, ya que arrastrar una señal al área de trabajo es lo más eficaz.

Get/Set

Nodo Setter/Getter genérico. Arrastrando propiedades desde el Inspector suele ser mejor, ya que aparecen configuradas al soltar.

Wait

El nodo Wait suspende la ejecución de la función hasta que suceda algo (de hecho, pueden pasar muchos frames hasta llegar resumirla). Por defecto los nodos permiten esperar un frame, un fixed frame o una cantidad de tiempo dada antes de resumir la ejecución.

Yield

Este nodo suspende completamente la ejecución del script y hará que la función retorne un valor que puede ser utilizado para continuar la ejecución.

Señal Yield

Lo mismo que Yield, pero espera a que determinada señal sea emitida.

Index

Operador de indexación genérico, no muy usado pero es bueno que esté por si acaso.

Operadores

Se trata en su mayoría de operadores genéricos como sumas, multiplicaciones, comparaciones, etc. De forma predeterminada, aceptan cualquier tipo de datos (y se producirá un error en tiempo de ejecución si los tipos introducidos no coinciden con los del operador). Siempre se recomienda configurar el tipo correcto para que los operadores detecten los errores rápidamente y faciliten la lectura del grafo.

../../../_images/visual_script46.png

Expression Node

Entre los operadores, el nodo Expression es el más potente. Si se usa bien, permite simplificar enormemente los visual scripts complejos desde el punto de vista matemático o lógico. Escribe cualquier expresión en él y se ejecutará en tiempo real.

Los nodos Expression pueden:

  • Ejecutar expresiones lógicas y matemáticas basadas en entradas personalizadas (ej. «a*5+b», donde a y b son tipos de entrada personalizados):
../../../_images/visual_script47.png
  • Acceder a variables locales o propiedades:
../../../_images/visual_script48.png
  • Utilizar la mayoría de las funciones built-in disponibles en GDScript, como sin(), cos(), print, así como constructores como Vector3(x,y,z),Rect2(…), etc.:
../../../_images/visual_script49.png
  • Funciones API Call:
../../../_images/visual_script50.png
  • Usar modo secuenciado, lo que tiene más sentido en caso de respetar el orden de procesamiento:
../../../_images/visual_script51.png