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.

Checking the stable version of the documentation...

Criando instâncias

Nota

This tutorial refers to instantiating scenes in the editor. To learn how to instantiate scenes from code, see Instâncias de nós e cenas.

Godot's approach to instantiation described below should not be confused with hardware instancing that can be used to render large amounts of similar objects quickly. See Otimização usando MultiMeshes instead.

Na parte anterior, nós vimos que uma cena é uma coleção de nós organizados em uma estrutura de árvore, com um único nó como sua raiz. Você pode dividir seu projeto em qualquer número de cenas. Essa funcionalidade ajuda você a dividir e organizar os diferentes componentes do seu jogo.

Você pode criar quantas cenas quiser e salvá-las como arquivos com a extensão .tscn, que significa “text scene” (cena em texto). O arquivo label.tscn da lição anterior foi um exemplo disso. Chamamos esses arquivos de “Packed Scenes” (cenas empacotadas), pois eles guardam (empacotam) as informações sobre o conteúdo da sua cena.

Aqui está o exemplo de uma bola. Ela é composta por um nó RigidBody2D como sua raiz chamado Ball, que permite que a bola caia e quique nas paredes, um nó Sprite2D e um CollisionShape2D.

Once you have saved a scene, it works as a blueprint: you can reproduce it in other scenes as many times as you'd like. Replicating an object from a template like this is called instantiation.

As we mentioned in the previous part, instantiated scenes behave like a node: the editor hides their content by default. When you instantiate the Ball, you only see the Ball node. Notice also how each duplicate has a unique name.

Cada instância da cena Ball começa com a mesma estrutura e propriedades que ball.tscn. No entanto, você pode modificar cada uma de forma independente, como alterar o quanto quicam, o quão pesadas são ou qualquer propriedade exposta pela cena de origem.

Na prática

Let's use instantiation 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.

Extraia o arquivo compactado em seu computador. Para importá-lo, você precisa do Gerenciador de Projetos (Project Manager). O Gerenciador de Projetos é acessado abrindo o Godot ou, se você já tiver o Godot aberto, clicando em Project > Quit to Project List (Ctrl + Shift + Q, Ctrl + Option + Cmd + Q no macOS)

In the Project Manager, click the Import button.

In the file dialog that appears, navigate to the folder you extracted. Double-click the project.godot file to select it.

Finally, click the Import button to import the project.

Uma janela notificando que o projeto foi aberto pela última vez em uma versão mais antiga do Godot pode aparecer. Isso não é um problema. Clique em OK para abrir o projeto.

The project contains two packed scenes: main.tscn, containing walls against which the ball collides, and ball.tscn. The main scene should open automatically. If you're seeing an empty 3D scene instead of the main scene, click the 2D button at the top of the screen.

Vamos adicionar uma bola como um filho do nó principal. No painel da Cena, selecione o nó Principal. Depois, clique no ícone de ligação na parte superior do painel da cena. Este botão permite-lhe adicionar uma instância de uma cena como filho do nó atualmente selecionado.

Double-click the ball scene to instantiate it.

A bola vai aparecer no canto superior esquerdo da tela.

Clique nela e arraste-a para o centro da tela.

Jogue o jogo pressionando F5 (Cmd + B no macOS). Você deverá vê-la cair.

Now, we want to create more instances of the Ball node. With the ball still selected, press Ctrl + D (Cmd + D on macOS) to duplicate it. Click and drag the new ball to a different location.

Você pode repetir esse processo até que você tenha várias bolas na cena.

Jogue o jogo novamente. Agora você deve ver cada bola cair de forma independente uma da outra. Isso é o que instâncias fazem. Cama uma é uma reprodução independente de uma cena modelo.

Editando cenas e instâncias

Instâncias fazem mais do que isso. Com essa funcionalidade, você pode:

1. Altere as propriedades de uma bola sem afetar as outras usando o Inspector.

2. Altere as propriedades padrão de cada Ball abrindo a cena ball.tscn e fazendo a alteração no nó Ball ali. Ao salvar, todas as instâncias da Ball no projeto terão seus valores atualizados.

Nota

Mudar uma propriedade em uma instância sempre terá prioridade sobre os valores da Cena Empacotada correspondente.

Vamos tentar isso. Dê um duplo clique em ball.tscn no FileSystem para abri-la.

Na aba Scene(Cena) à esquerda, selecione o nó Ball(Bola). Então, no Inspector à direita, clique na propriedade PhysicsMaterial para expandi-la.

Defina sua propriedade Bounce para 0.5 clicando no campo numérico, digitando 0.5 e pressionando Enter.

Jogue o jogo pressionando F5 (Cmd + B no macOS) e observe como todas as bolas agora quicam muito mais. Como a cena Ball é um modelo para todas as instâncias, modificá-la e salvá-la faz com que todas as instâncias sejam atualizadas de acordo.

Let's now adjust an individual instance. Head back to the main scene by clicking on the corresponding tab above the viewport.

Select one of the instantiated Ball nodes and, in the Inspector, set its Gravity Scale value to 10.

A gray "revert" button appears next to the adjusted property.

Este ícone indica que você está substituindo um valor da cena empacotada de origem. Mesmo que você modifique a propriedade na cena original, a substituição do valor será preservada na instância. Clicar no ícone de reversão restaurará a propriedade para o valor na cena salva.

Rode o jogo de novo e perceba que essa bola agora caí muito mais rápida que as outras.

Nota

Você pode notar que não consegue alterar os valores do PhysicsMaterial da bola. Isso ocorre porque o PhysicsMaterial é um recurso (resource) e precisa ser tornado único antes que você possa editá-lo em uma cena que está vinculada à sua cena original. Para tornar um recurso único para uma instância, clique com o botão direito na propriedade Physics Material no Inspector e clique em Make Unique no menu de contexto.

Recursos são outro bloco de construção essencial de jogos Godot que cobriremos em uma lição posterior.

Instâncias de cena como linguagem de design

Instâncias e cenas no Godot oferecem uma excelente linguagem de design, distinguindo a engine de outras. Concebemos o Godot em torno deste conceito desde o início.

Nós recomendamos ignorar padrões de código de arquitetura, tal como o Model-View-Control (MVC) ou diagramas Relação-Entidade, ao fazer jogos com Godot. Ao invés disso, você pode começar imaginando os elementos que jogadores verão em seu jogo e estruturar seu código ao redor deles.

Por exemplo, você pode dividir um jogo de tiro da seguinte forma:

Você pode criar um diagrama como este para quase qualquer tipo de jogo. Cada retângulo representa uma entidade que é visível no jogo a partir da perspectiva do jogador. As setas apontam para o instanciador de cada cena.

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

Os programadores tendem a gastar muito tempo projetando arquiteturas abstratas e tentando encaixar componentes nelas. O design baseado em cenas torna o desenvolvimento mais rápido e direto, permitindo que você se concentre na própria lógica do jogo. Como a maioria dos componentes do jogo é mapeada diretamente para uma cena, usar um design baseado em instanciamento de cenas significa que você precisará de muito menos código arquitetural.

Aqui está o exemplo de um diagrama de cena para um jogo de mundo aberto com muitos assets e elementos aninhados:

Imagine we started by creating the room. We could make a couple of different room scenes, with unique arrangements of furniture in them. Later, we could make a house scene that uses multiple room instances for the interior. We would create a citadel out of many instantiated houses and a large terrain on which we would place the citadel. Each of these would be a scene instantiating one or more sub-scenes.

Mais tarde, poderíamos criar cenas representando guardas e adicioná-los à cidadela. Eles seriam adicionados indiretamente ao mundo geral do jogo.

Com Godot, é fácil iterar em seu jogo assim, pois tudo o que você precisa fazer é criar e instanciar mais cenas. Nós fizemos o editor ser mais acessível a programadores, designers e artistas. Um processo típico de desenvolvimento de equipe pode envolver artistas 2D ou 3D, designers de níveis, designers de jogos e animadores, todos trabalhando com o editor Godot.

Resumo

Instantiation, the process of producing an object from a blueprint, has many handy uses. With scenes, it gives you:

• A capacidade de dividir seu jogo em componentes reutilizáveis.

• Uma ferramenta para estruturar e encapsular sistemas complexos.

• Uma linguagem para pensar sobre a estrutura do seu projeto de jogo de uma forma natural.