Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Creando instancias

En la parte anterior, vimos que una escena es una colección de nodos organizados en una estructura de árbol, con un solo nodo como raíz. Puede dividir su proyecto en cualquier número de escenas. Esta función te ayuda a desglosar y organizar los diferentes componentes de tu juego.

You can create as many scenes as you'd like and save them as files with the .tscn extension, which stands for "text scene". The label.tscn file from the previous lesson was an example. We call those files "Packed Scenes" as they pack information about your scene's content.

Here's an example of a ball. It's composed of a RigidBody2D node as its root named Ball, which allows the ball to fall and bounce on walls, a Sprite2D node, and a CollisionShape2D.

../../_images/instancing_ball_scene.png

Una vez guardada una escena, funciona como plantilla: puedes reproducirla en otras escenas tantas veces como quieras. Replicar un objeto a partir de una plantilla de este tipo se denomina instanciación.

../../_images/instancing_ball_instances_example.png

Como mencionamos en la parte anterior, las escenas instanciadas se comportan como un nodo: el editor oculta su contenido por defecto. Cuando crea una instancia de Ball, solo ve el nodo Ball. Observe también cómo cada duplicado tiene un nombre único.

Every instance of the Ball scene starts with the same structure and properties as ball.tscn. However, you can modify each independently, such as changing how they bounce, how heavy they are, or any property exposed by the source scene.

En la práctica

Let's use instancing in practice to see how it works in Godot. We invite you to download the ball's sample project we prepared for you: instancing_starter.zip.

Extract the archive on your computer. To import it, you need the Project Manager. The Project Manager is accessed by opening Godot, or if you already have Godot opened, click on Project -> Quit to Project List (Ctrl + Shift + Q, Ctrl + Option + Cmd + B on macOS)

In the Project Manager, click the Import button to import the project.

../../_images/instancing_import_button.png

En la ventana emergente que aparece, haga clic en el botón Examinar y navegue hasta la carpeta que extrajo.

../../_images/instancing_import_browse.png

Haz doble clic en el archivo project.godot para abrirlo.

../../_images/instancing_import_project_file.png

Finalmente, haga clic en el botón Importar y editar.

../../_images/instancing_import_and_edit_button.png

The project contains two packed scenes: main.tscn, containing walls against which the ball collides, and ball.tscn. The Main scene should open automatically.

../../_images/instancing_main_scene.png

Agreguemos una bola como elemento secundario del nodo Main. En el panel Escena, seleccione el nodo Main. Luego, haga clic en el ícono de enlace en la parte superior del panel de escena. Este botón le permite agregar una instancia de una escena como elemento secundario del nodo seleccionado actualmente.

../../_images/instancing_scene_link_button.png

Haga doble clic en la escena de la pelota para instanciarla.

../../_images/instancing_instance_child_window.png

La pelota aparece en la esquina superior izquierda de la ventana gráfica.

../../_images/instancing_ball_instanced.png

Haga clic en él y arrástrelo hacia el centro de la vista.

../../_images/instancing_ball_moved.png

Play the game by pressing F5 (Cmd + B on macOS). You should see it fall.

Ahora, queremos crear más instancias del nodo Ball. Con la pelota aún seleccionada, presione Ctrl-D (Cmd-D en macOS) para llamar al comando duplicado. Haga clic y arrastre para mover la nueva bola a una ubicación diferente.

../../_images/instancing_ball_duplicated.png

Puedes repetir este proceso hasta que tengas varios en la escena.

../../_images/instancing_main_scene_with_balls.png

Ejecuta el juego de nuevo. Ahora debería ver que cada bola cae independientemente una de la otra. Esto es lo que hacen las instancias. Cada uno es una reproducción independiente de una escena de plantilla.

Edición de escenas e instancias

Hay más en las instancias. Con esta función, puede:

  1. Cambia las propiedades de una bola sin afectar a las demás usando el Inspector.

  2. Change the default properties of every Ball by opening the ball.tscn scene and making a change to the Ball node there. Upon saving, all instances of the Ball in the project will see their values update.

Nota

Cambiar una propiedad en una instancia siempre anula los valores de la escena empaquetada correspondiente.

Let's try this. Open ball.tscn and select the Ball node. In the Inspector on the right, click on the PhysicsMaterial property to expand it.

../../_images/instancing_physics_material_expand.webp

Set its Bounce property to 0.5 by clicking on the number field, typing 0.5, and pressing Enter.

../../_images/instancing_property_bounce_updated.webp

Ejecuta presionando F5 y observa cómo todas las bolas ahora rebotan mucho más. Como la escena Ball es una plantilla para todas las instancias, modificarla y guardarla hace que todas las instancias se actualicen en consecuencia.

Ahora ajustemos una instancia individual. Regrese a la escena principal haciendo clic en la pestaña correspondiente sobre la ventana gráfica.

../../_images/instancing_scene_tabs.png

Seleccione uno de los nodos Ball instanciados y, en el Inspector, establezca su valor de Gravity Scale en 10.

../../_images/instancing_property_gravity_scale.png

Aparece un botón gris "revertir" junto a la propiedad ajustada.

../../_images/instancing_property_revert_icon.png

Este icono indica que está anulando un valor de la escena empaquetada de origen. Incluso si modifica la propiedad en la escena original, la anulación del valor se conservará en la instancia. Al hacer clic en el icono de reversión, se restaurará la propiedad al valor de la escena guardada.

Vuelva a ejecutar el juego y observe cómo esta bola ahora cae mucho más rápido que las otras.

Nota

Si cambia un valor en PhysicsMaterial de una instancia, afectará a todos los demás. Esto se debe a que PhysicsMaterial es un recurso, y los recursos se comparten entre instancias. Para hacer que un recurso sea único para una instancia, haga clic derecho sobre él en el Inspector y haga clic en Hacer único en el menú contextual.

Los recursos son otro bloque de construcción esencial de los juegos de Godot que cubriremos en una lección posterior.

Instancias de escena como lenguaje de diseño

Las instancias y escenas en Godot ofrecen un excelente lenguaje de diseño, lo que diferencia al motor de los demás. Diseñamos a Godot en torno a este concepto desde cero.

Recomendamos descartar los patrones de código arquitectónico al hacer juegos con Godot, como los diagramas Modelo-Vista-Controlador (MVC) o Entidad-Relación. En su lugar, puede comenzar imaginando los elementos que los jugadores verán en su juego y estructurar su código en torno a ellos.

Por ejemplo, podrías desglosar un juego de disparos así:

../../_images/instancing_diagram_shooter.png

Puede crear un diagrama como este para casi cualquier tipo de juego. Cada rectángulo representa una entidad que es visible en el juego desde la perspectiva del jugador. Las flechas te dicen qué escena posee cuál.

Once you have a diagram, we recommend creating a scene for each element listed in it to develop your game. You'll use instancing, either by code or directly in the editor, to build your tree of scenes.

Los programadores tienden a pasar mucho tiempo diseñando arquitecturas abstractas y tratando de encajar componentes en ellas. El diseño basado en escenas hace que el desarrollo sea más rápido y sencillo, lo que le permite concentrarse en la lógica del juego en sí. Debido a que la mayoría de los componentes del juego se asignan directamente a una escena, el uso de un diseño basado en la creación de instancias de escena significa que necesita poco más código arquitectónico.

Aquí está el ejemplo de un diagrama de escena para un juego de mundo abierto con toneladas de activos y elementos anidados:

../../_images/instancing_diagram_open_world.png

Imagina que comenzamos creando la habitación. Podríamos hacer un par de escenas de habitaciones diferentes, con arreglos únicos de muebles en ellas. Más tarde, podríamos hacer una escena de casa que use instancias de varias habitaciones para el interior. Crearíamos una ciudadela a partir de muchas casas instanciadas y un gran terreno en el que colocaríamos la ciudadela. Cada uno de estos sería una escena que ejemplifica una o más sub-escenas.

Más tarde, podríamos crear escenas que representaran a los guardias y agregarlos a la ciudadela. Se agregarían indirectamente al mundo general del juego.

Con Godot, es fácil iterar en tu juego de esta manera, ya que todo lo que necesitas hacer es crear e instanciar más escenas. Diseñamos el editor para que fuera accesible a programadores, diseñadores y artistas por igual. Un proceso típico de desarrollo en equipo puede involucrar a artistas 2D o 3D, diseñadores de niveles, diseñadores de juegos y animadores, todos trabajando con el editor Godot.

Sumario

La creación de instancias, el proceso de producción de un objeto a partir de un plano, tiene muchos usos prácticos. Con escenas, te da:

  • La habilidad para dividir tu juego en componentes reutilizables.

  • Una herramienta para estructurar y encapsular sistemas complejos.

  • Un lenguaje para pensar en la estructura de tu proyecto de juego de forma natural.