Scripting

Introducción
Before Godot 3.0, the only choice for scripting a game was to use GDScript. Nowadays, Godot has
four (yes, four!) official languages and the ability to add extra scripting languages dynamically!

Esto es genial, sobre todo debido a la gran cantidad de flexibilidad proporcionada, pero también hace
que nuestro trabajo de apoyo a los idiomas sea más difícil.

Sin embargo, los lenguajes «principales» en Godot son GDScript y VisualScript. La razón principal
para elegirlos es su nivel de integración con Godot, ya que esto hace que la experiencia sea más
agradable; ambos tienen una integración con el editor muy fluida, mientras que con C# y C++ se
necesita editarlos en un IDE separado. Si eres un gran fan de los lenguajes de tipado estático, utiliza
C# y C++ en su lugar.

GDScript

GDScript is, as mentioned above, the main language used in Godot. Using it has some positive
points compared to other languages due to its high integration with Godot:

 Es simple, elegante, y diseñado para que resulte muy familiar a los usuarios de otros idiomas
como Lua, Python, Squirrel, etc.
 Carga y compila a toda velocidad.
 Es un placer trabajar con la integración del editor, con completado de código para nodos, señales
y muchos otros elementos relacionados con la escena que se está editando.
 Tiene tipos de vectores propios (tales como Vector, transforms, etc.), haciéndolo eficiente para el
uso intensivo del álgebra lineal.
 Soporta múltiples hilos de forma tan eficiente como los lenguajes de tipado estático - una de las
limitaciones que nos hizo evitar VMs como Lua, Squirrel, etc.
 No utiliza ningún recolector de basura, por lo que intercambia un poco de automatización (de
todos modos, la mayoría de objetos son pasados por referencia), por determinismo.
 Su naturaleza dinámica hace que sea fácil optimizar secciones de código en C++ (vía GDNative)
si se requiere más rendimiento, todo ello sin recompilar el motor.

Si estás indeciso y tienes experiencia en programación, especialmente con lenguajes de tipado

dinámico ¡decídete por GDScript!

VisualScript
A partir de la versión 3.0, Godot ofrece Visual Scripting. Esta es una implementación típica de un
lenguaje de «bloques y conexiones», pero adaptado a cómo funciona Godot.

Visual scripting es una gran herramienta para no-programadores, o incluso para desarrolladores
experimentados que quieren hacer partes del código más accesibles a otros, como diseñadores o
artistas de juegos.

También lo pueden utilizar programadores para construir máquinas de estado o flujos de trabajo de
nodos visuales personalizados - por ejemplo, un sistema de diálogo.

.NET / C#

Dado que Microsoft C# es uno de los favoritos entre los desarrolladores de juegos, hemos añadido
soporte oficial para él. C# es un lenguaje maduro con una gran cantidad de código escrito para él, y
el soporte se añadió gracias a una generosa donación de Microsoft.

Tiene un excelente equilibrio entre rendimiento y facilidad de uso, aunque uno debe ser consciente
de su recolector de basura.

Puesto que Godot utiliza el runtime [Link], en teoría cualquier librería o framework .NET de
terceros se puede utilizar para scripting en Godot, así como cualquier lenguaje de programación
compatible con Common Language Infrastructure, como F#, Boo o ClojureCLR. Sin embargo, en la
práctica, C# es la única opción compatible oficialmente con .NET.

GDNative / C++

Finalmente, una de nuestros añadidos más brillantes para la versión 3.0: GDNative permite la
creación de scripts en C++ sin necesidad de recompilar (o incluso reiniciar) Godot.

Se puede utilizar cualquier versión de C++, y la combinación de marcas y versiones de compiladores

para las bibliotecas compartidas generadas funciona perfectamente, gracias al uso de nuestro C API
Bridge interno.

Este lenguaje es la mejor opción por rendimiento y no es necesario que se use en todo el juego, ya
que otras partes se pueden escribir en GDScript o Visual Script. Sin embargo, la API es clara y fácil
de usar, ya que se parece, en su mayoría, a la API C++ actual de Godot.

Se podrían utilizar más lenguajes a través de la interfaz de GDNative, pero debes tener en cuenta
que no tenemos soporte oficial para ellos.
Scripting de una escena
Para el resto de este tutorial configuraremos una escena GUI que consistirá en un botón y una
etiqueta, donde al pulsar el botón se actualizará la etiqueta. Esto lo demostrará:

 Escribir un script y añadirlo a un nodo.

 Conexión de los elementos de la UI mediante señales.
 Escribir un script que pueda acceder a otros nodos de la escena.

Before continuing, please make sure to read the GDScript reference. It’s a language designed to be
simple, and the reference is short, so it will not take more than a few minutes to get an overview of
the concepts.

Configuración de la escena

Utiliza el cuadro de diálogo «Añadir nodo hijo» al que se accede desde la pestaña Escena (o
pulsando Ctrl+A ) para crear una jerarquía con los siguientes nodos:

 Panel

o Label
o Botón

El árbol de la escena debería verse así:

Utiliza el editor 2D para situar y redimensionar el Botón y la Etiqueta para que se parezcan a la
imagen de abajo. Puedes configurar el texto desde la pestaña Inspector.
Finalmente, guarda la escena con un nombre como [Link] .

Añadir un script

Haz clic con el botón derecho del ratón en el nodo Panel y selecciona » Adjuntar Script » en el menú
contextual:

Aparecerá el cuadro de diálogo de creación del script. Este cuadro de diálogo permite definir el
idioma del script, nombre de la clase y otras opciones relevantes.

En GDScript, el propio archivo representa la clase, por lo que el campo del nombre de la clase no se
puede editar.

El nodo al que estamos añadiendo el script es un panel, por lo que el campo Hereda se rellenará
automáticamente con «Panel». Esto es lo que queremos, ya que el objetivo del script es ampliar la
funcionalidad de nuestro nodo panel.
Finalmente, introduce un nombre de ruta para el script y haz clic en Crear:

A continuación, se creará el script y se añadirá al nodo. Puedes ver esto como un icono de «Abrir
script » al lado del nodo en la pestaña Escena, así como en la propiedad del script en el Inspector:
Para editar el script, pulsa cualquiera de estos botones, ambos resaltados en la imagen de arriba.
Esto te llevará al editor de scripts, donde se incluirá una plantilla predeterminada:
No hay mucho allí. La función _ready() se llama cuando el nodo, y todos sus hijos, entran a la
escena activa. Nota: _ready() no es el constructor, ese es _init() .

El papel del script

Un script agrega comportamiento al nodo. Este se utiliza para controlar cómo se quiere que el nodo
funcione y cómo debe interactuar con otros nodos: hijos (children), padre (parent), hermanos, etc. El
ámbito local del script es el nodo. En otras palabras, el script hereda las funciones provistas por ese
nodo.
Manejando una señal

Las señales son «emitidas» cuando alguna acción específica sucede, y se pueden conectar a
cualquier función de cualquier instancia de script. Las señales se utilizan sobre todo en nodos de la
IGU, aunque otros nodos también tienen señales, e incluso puedes definir señales en tu propio
script.

En este paso, conectaremos la señal pressed a una función personalizada. Formar conexiones es la
primera parte y definir la función personalizada es la segunda parte. Para la primera parte, Godot
proporciona dos maneras de crear conexiones: a través de una interfaz visual que proporciona el
editor o a través del código.

Aunque usaremos el método de código para el resto de esta serie de tutoriales, cubriremos cómo
funciona la interfaz del editor para futuras referencias.

Selecciona el nodo Button en el árbol de escenas y luego selecciona la pestaña Nodo .A

continuación, asegúrate de que has seleccionado Señales .
Si luego seleccionas «pressed()» dentro de «BaseButton» y presionas el botón Conectar... en la
parte inferior derecha del panel, abrirás la ventana de diálogo de conexión.
En la parte inferior izquierda se encuentran los elementos clave que necesitas para crear una
conexión: un nodo que implementa el método que quieres activar (representado aquí como un
NodePath) y el nombre del método a activar.
La parte superior izquierda muestra una lista de los nodos de la escena con el nombre del nodo
emisor resaltado en rojo. Selecciona aquí el nodo «Panel». Cuando seleccionas un nodo, el
NodePath en la parte inferior se actualizará automáticamente para apuntar a una ruta relativa desde
el nodo emisor al nodo seleccionado.

Por defecto, el nombre del método contendrá el nombre del nodo emisor («Button» en este caso),
resultando en «_on_[EmitterNode]_[signal_name]». Si tienes activada la casilla de verificación
«Make Function», el editor generará la función por ti antes de configurar la conexión.

Y así concluye la guía sobre cómo usar la interfaz visual. Sin embargo, este es un tutorial de
scripting, así que por el bien del aprendizaje, ¡vamos a sumergirnos en el proceso manual!

Para lograr esto, veremos una función que es probablemente la más usada por los programadores
de Godot: Node.get_node(). Esta función utiliza rutas para recuperar nodos en cualquier parte de la
escena, en relación con el nodo al que pertenece el script.

Para mayor comodidad, borra todo lo que se encuentra debajo de extends Panel . Rellenarás el resto
del script manualmente.

Dado que el Botón y la Etiqueta son hermanos en el Panel donde se adjunta el script, puedes
recuperar el Botón escribiendo lo siguiente debajo de la función _ready() :

GDScript
C#
func _ready():
get_node("Button")

A continuación, escribe una función que se llamará cuando se pulse el botón:

GDScript
C#
func _on_Button_pressed():
get_node("Label").text = "HELLO!"

Finalmente, conecta la señal «pressed» del botón a _ready() utilizando [Link]().

GDScript
C#
func _ready():
get_node("Button").connect("pressed", self, "_on_Button_pressed")

El script final debería verse así:

GDScript
C#
extends Panel
 func _ready():
get_node("Button").connect("pressed", self, "_on_Button_pressed")

func _on_Button_pressed():
get_node("Label").text = "HELLO!"

Ejecuta la escena y pulsa el botón. Deberías obtener el siguiente resultado:

¡Vaya, hola! Felicidades por el script de tu primera escena.

Nota

Un malentendido común con respecto a este tutorial es cómo funciona get_node(path) . Para un nodo
concreto, get_node(path) busca a sus hijos inmediatos. En el código anterior, esto significa que
Button debe ser hijo de Panel. Si Button fuera en cambio un hijo de Label, el código para obtenerlo
sería:
GDScript
C#
# Not for this case,
# but just in case.
get_node("Label/Button")

También, recuerda que los nodos se referencian por nombre, no por tipo.

Nota

El panel derecho del diálogo de conexión sirve para vincular valores específicos a los parámetros de
la función conectada. Puedes añadir y eliminar valores de diferentes tipos.

El enfoque de código también permite esto con un 4º parámetro Array que está vacío por defecto.
Tómate la libertad de leer sobre el método [Link] para más información.

Scripting (continuación)
Procesamiento
Varias acciones en Godot se activan por llamadas de retorno o funciones virtuales, así que no hay
necesidad de escribir código que se ejecute todo el tiempo.

Sin embargo, todavía es común necesitar un script para que se procese en cada frame. Hay dos
tipos de procesamiento: procesamiento en tiempo de espera y procesamiento físico.

El procesamiento en tiempo de espera (idle) se activa cuando el método Node._process() se

encuentra en un script. Se puede apagar y encender con la función Node.set_process().

Este método se llamará cada vez que se dibuje un cuadro, por lo que depende totalmente del
número de cuadros por segundo (FPS) en los que se esté ejecutando la aplicación:

GDScript
C#
func _process(delta):
# Do something...
pass

El parámetro delta contiene el tiempo transcurrido en segundos, como punto flotante, desde la
llamada anterior a _process() .

Este parámetro se puede utilizar para asegurarse de que las cosas siempre tardan la misma
cantidad de tiempo, independientemente de los FPS del juego.

Por ejemplo, el movimiento a menudo se multiplica por un tiempo delta para que la velocidad de
movimiento sea constante e independiente de la velocidad de fotogramas.

El procesamiento de la física con _physics_process() es similar, pero se debería usar para procesos
que deben ocurrir antes de cada paso de la física, como el control de un personaje. Siempre se
ejecuta antes de un paso de física y se llama en intervalos de tiempo fijos: 60 veces por segundo por
defecto. Puedes cambiar el intervalo desde la Configuración del proyecto, en Physics -> Common ->
Physics Fps.

La función _process() , sin embargo, no está sincronizada con la física. Su frecuencia de imagen no
es constante y depende de la optimización del hardware y del juego. Su ejecución se realiza después
del paso de la física en los juegos de un solo subproceso.

Una forma sencilla de comprobar esto es crear una escena con un único nodo Label, con el siguiente
script:
GDScript
C#
extends Label

var accum = 0

func _process(delta):
accum += delta
text = str(accum) # 'text' is a built-in label property.

Lo que mostrará un contador aumentando cada fotograma.

Grupos
Los nodos se pueden añadir a los grupos, tantos como se desee por nodo, y es una función útil para
organizar escenas de gran tamaño. Hay dos maneras de hacerlo. La primera es desde la UI, desde
el botón Grupos bajo el panel Nodos:

Y la segunda forma es por código. Un ejemplo sería etiquetar nodos que representan a los enemigos
(“enemies”):

GDScript
C#
func _ready():
add_to_group("enemies")

De esta manera, si se descubre al jugador entrando a escondidas en una base secreta, se puede
avisar a todos los enemigos de que está sonando la alarma usando SceneTree.call_group():

GDScript
C#
func _on_discovered(): # This is a purely illustrative function.
get_tree().call_group("enemies", "player_was_discovered")

El código anterior llama a la función player_was_discovered en cada miembro del grupo enemies .

También es posible obtener la lista completa de nodos enemies llamando

a SceneTree.get_nodes_in_group():

GDScript
C#
var enemies = get_tree().get_nodes_in_group("enemies")
La clase SceneTree proporciona muchos métodos útiles, como la interacción con escenas, su
jerarquía de nodos y grupos de nodos. Te permite cambiar escenas o recargarlas fácilmente, salir del
juego o pausar y despausar el juego. Incluso viene con señales interesantes ¡Así que échale un
vistazo si tienes tiempo!

Notificaciones
Godot tiene un sistema de notificaciones. Por lo general, no son necesarios para la creación de
scripts, ya que es de muy bajo nivel y se proporcionan funciones virtuales para la mayoría de estas.
Pero es bueno saber que existen. Por ejemplo, puedes añadir una función Object._notification() en tu
script:

GDScript
C#
func _notification(what):
match what:
NOTIFICATION_READY:
print("This is the same as overriding _ready()...")
NOTIFICATION_PROCESS:
print("This is the same as overriding _process()...")

La documentación de cada clase en la Referencia de Clases muestra las notificaciones que puedes
recibir. Sin embargo, en la mayoría de los casos, GDScript proporciona funciones anulables más
simples.

Funciones anulables
Estas funciones, que se describen a continuación, se pueden aplicar a los nodos:

GDScript
C#
func _enter_tree():
# When the node enters the _Scene Tree_, it becomes active
# and this function is called. Children nodes have not entered
# the active scene yet. In general, it's better to use _ready()
# for most cases.
pass

func _ready():
# This function is called after _enter_tree, but it ensures
# that all children nodes have also entered the _Scene Tree_,
# and became active.
pass

func _exit_tree():
# When the node exits the _Scene Tree_, this function is called.
# Children nodes have all exited the _Scene Tree_ at this point
# and all became inactive.
pass

func _process(delta):
# This function is called every frame.
pass
func _physics_process(delta):
# This is called every physics frame.
pass

Como se mencionó anteriormente, es mejor utilizar estas funciones que el sistema de notificación.

Creación de nodos
Para crear un nodo desde código, se debe llamar al método .new() , como en cualquier otro tipo de
dato basado en una clase. Por ejemplo:

GDScript
C#
var s
func _ready():
s = [Link]() # Create a new sprite!
add_child(s) # Add it as a child of this node.

Para eliminar un nodo, ya sea dentro o fuera de la escena, se debe usar free() :

GDScript
C#
func _someaction():
[Link]() # Immediately removes the node from the scene and frees it.

Cuando un nodo se libera, también libera todos sus nodos hijos. Debido a esto, el borrado manual de
nodos es mucho más sencillo de lo que parece. Libera el nodo base y todo lo demás en el subárbol
desaparecerá con él.

Puede ocurrir una situación en la que queramos borrar un nodo que esté actualmente «bloqueado»,
porque esté emitiendo una señal o llamando a una función. Esto interrumpirá el juego. Ejecutar
Godot con el depurador a menudo detectará este caso y te advertirá al respecto.

La forma más segura de eliminar un nodo es usando Node.queue_free(). Esto borra el nodo de
forma segura mientras está inactivo.

GDScript
C#
func _someaction():
s.queue_free() # Removes the node from the scene and frees it when it becomes safe to do so.

Instanciación de escenas
La instanciación de una escena a partir de código se realiza en dos pasos. El primero es cargar la
escena desde el disco duro:

GDScript
C#
var scene = load("res://[Link]") # Will load when the script is instanced.

La precarga puede ser más conveniente, ya que ocurre en tiempo de análisis (sólo GDScript):

GDScript
var scene = preload("res://[Link]") # Will load when parsing the script.

Pero scene todavía no es un nodo. Está empaquetado en un recurso especial

llamado PackedScene. Para crear el nodo se debe llamar a la función [Link](). Esto
retornará el árbol de nodos que se puede añadir a la escena activa:

GDScript
C#
var node = [Link]()
add_child(node)

La ventaja de este proceso de dos pasos es que una escena empaquetada se puede mantener
cargada y lista para usar para que puedas crear tantas instancias como desees. Esto es
especialmente útil para identificar rápidamente varios enemigos, balas y otras entidades en la
escena activa.

Registrar scripts como clases

Godot tiene una funcionalidad de «Script Class» para registrar codigos individuales con el Editor. Por
defecto, solo puedes accesar codigos sin nombre cargando el archivo directamente.

Puedes nombrar un script y registrarlo como un tipo en el editor con la palabra

clave class_name seguida por el nombre de la clase. Puedes agregar una coma y una dirección
opcional a una imagen para usarla como ícono. De esta forma encontrarás un nuevo tipo en la
ventana Node o Resource creation.

GDScript
extends Node

# Declare the class name here

class_name ScriptName, "res://path/to/optional/[Link]"

func _ready():
var this = ScriptName # reference to the script
var cppNode = [Link]() # new instance of a class named MyCppNode

cppNode.queue_free()
Advertencia

En Godot 3.1:

 Únicamente GDScript o NativeScript, en otras palabras, C++ y otros lenguajes basandos en

GDNative, pueden registrar scripts.
 Únicamente GDScript crea variables globales para cada script nombrado.