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 seu primeiro script

Nesta lição, você escreverá seu primeiro script para fazer o ícone do Godot girar em círculos. Como mencionamos na introdução, presumimos que você possua noções básicas de programação.

Este tutorial foi escrito em GDScript, e o código equivalente em C# está incluído em outra aba de cada bloco de código para conveniência.

../../_images/scripting_first_script_rotating_godot.gif

Ver também

Para saber mais sobre o GDScript, suas palavras-chave e sua sintaxe, acesse a seção GDScript. Para saber mais sobre o C#, acesse a seção C#/.NET.

Configuração do projeto

Por favor, crie un novo projeto para começar do zero. Seu projeto deve conter uma imagem: o ícone do Godot, que usamos frequentemente para prototipagem na comunidade.

Precisamos criar um nó Sprite2D para exibi-lo no jogo. Na aba Scene, clique no botão Other Node.

../../_images/scripting_first_script_click_other_node.webp

Digite "Sprite2D" na barra de pesquisa para filtrar os nós e clique duas vezes em Sprite2D para criar o nó.

Sua aba Scene agora deve ter apenas um nó Sprite2D.

../../_images/scripting_first_script_scene_tree.webp

Um nó Sprite2D precisa de uma textura para ser exibido. No Inspector à direita, você pode ver que a propriedade Texture diz <empty>. Para exibir o ícone do Godot, clique e arraste o arquivo icon.svg da aba FileSystem para o slot da Texture.

../../_images/scripting_first_script_setting_texture.webp

Nota

Você pode criar nós Sprite2D automaticamente arrastando e soltando imagens na viewport.

E então, clique e arraste o ícone no viewport para centralizá-lo na visualização do jogo.

Criando um novo script

Para criar e anexar um novo script ao nosso nó, clique com o botão direito em Sprite2D na aba Scene e selecione Attach Script.

../../_images/scripting_first_script_attach_script.webp

A janela Attach Node Script aparece. Ela permite que você selecione a linguagem do script e o caminho do arquivo, entre outras opções.

Altere o campo Template de Node: Default para Object: Empty para começar com um arquivo limpo. Deixe as outras opções definidas com seus valores padrão e clique no botão Create para criar o script.

../../_images/scripting_first_script_attach_node_script.webp

Nota

Os nomes do scripts em C# devem ser iguais aos nomes de sua classe. Neste caso você deve nomear o arquivo `MySprite2D.cs.

A área de trabalho Script deve aparecer com o seu novo arquivo sprite_2d.gd aberto e a seguinte linha de código:

extends Sprite2D

using Godot;
using System;

public partial class MySprite2D : Sprite2D
{
}

Cada arquivo GDScript é implicitamente uma classe. A palavra-chave extends define a classe que este script herda ou estende. Neste caso, é Sprite2D, o que significa que nosso script terá acesso a todas as propriedades e funções do nó Sprite2D, incluindo as classes que ele estende, como Node2D, CanvasItem e Node.

Nota

No GDScript, se você omitir a linha com a palavra-chave extends, sua classe estenderá implicitamente o RefCounted, que o Godot usa para gerenciar a memória do seu aplicativo.

As propriedades herdadas incluem as que você pode ver na aba Inspector, como a texture do nosso nó.

Nota

Por padrão, o Inspector exibe as propriedades de um nó em "Title Case", com palavras maiúsculas separadas por um espaço. No código GDScript, essas propriedades ficam em "snake_case", que é em letras minúsculas com cada palavra separada por um sublinhado (underline).

Você pode passar o mouse sobre o nome de qualquer propriedade no Inspector para ver uma descrição e o seu identificador no código.

Olá, mundo!

Nosso script por enquanto não está fazendo nada. Vamos fazê-lo imprimir o texto "Olá, mundo!" no painel de Saída em baixo para começarmos.

Adicione o seguinte código no seu script:

func _init():
    print("Hello, world!")

public MySprite2D()
{
    GD.Print("Hello, world!");
}

Vamos decompô-lo. A palavra-chave func define uma nova função chamada _init. Este é um nome especial para o construtor da nossa classe. A engine chama o _init() em cada objeto ou nó ao criá-lo na memória, se você definir esta função.

Nota

GDScript é uma linguagem baseada em recuo. A aba no início da linha que diz print() é necessária para que o código funcione. Se você omitir ou não recuar uma linha corretamente, o editor a destacará em vermelho e exibirá a seguinte mensagem de erro: "Esperado recuo do bloco".

Salve a cena como sprite_2d.tscn se ainda não o fez, então pressione F6 (Cmd + R no macOS) para executá-la. Observe o painel inferior Output que se expande. Ele deve exibir "Hello, world!".

../../_images/scripting_first_script_print_hello_world.webp

Delete a função _init(), para que reste apenas a linha extends Sprite2D.

Adicionando movimento

É hora de fazer nosso nó se mover e rotacionar. Para fazer isso, vamos adicionar duas variáveis de membro ao nosso script: a velocidade de movimento em pixels por segundo e a velocidade angular em radianos por segundo. Adicione o seguinte após a linha extends Sprite2D.

var speed = 400
var angular_speed = PI

private int _speed = 400;
private float _angularSpeed = Mathf.Pi;

As variáveis de definição ficam próximas ao topo do script, depois de qualquer linha "extends", mas antes das funções. Cada instância de nó com este script anexado a ela terá sua própria cópia das propriedades speed e angular_speed.

Nota

Os ângulos no Godot trabalham com radianos por padrão, mas há funções e propriedades embutidas disponíveis se você preferir calcular ângulos em graus ao invés de radianos.

Para mover nosso ícone, precisamos atualizar sua posição e rotação a cada quadro no loop do jogo. Podemos usar a função virtual _process() da classe Node. Se você a definir em qualquer classe que estenda a classe Node, como Sprite2D, a Godot chamará a função a cada quadro e passará um argumento chamado delta, o tempo decorrido desde o último quadro.

Nota

Os jogos funcionam renderizando muitas imagens por segundo, cada uma chamada de quadro, e fazem isso em um loop. Medimos a taxa na qual um jogo produz imagens em quadros por segundo (FPS). A maioria dos jogos aponta para 60 FPS, embora você possa encontrar números como 30 FPS em dispositivos móveis mais lentos ou 90 a 240 para jogos de realidade virtual.

A engine e os desenvolvedores de jogos fazem seu melhor para atualizar o mundo do jogo e renderizar imagens em um intervalo de tempo constante, mas sempre terá pequenas variações no tempo de renderização de frames. É por isso que a engine nos oferece o valor de tempo delta, fazendo com que o movimento ocorra independente da taxa de quadros.

No fim do script, defina a função:

func _process(delta):
    rotation += angular_speed * delta

public override void _Process(double delta)
{
    Rotation += _angularSpeed * (float)delta;
}

A palavra-chave func define uma nova função. Depois disso, devemos escrever o nome da função e os argumentos que ela recebe entre parênteses. Dois pontos terminam a definição e os blocos recuados que seguem são o conteúdo ou as instruções da função.

Nota

Observe como _process() e _init(), começam com um sublinhado à esquerda. Por convenção, as funções virtuais do Godot, ou seja, funções integradas que você pode substituir para se comunicar com a engine, começam com um sublinhado.

A linha dentro da função, rotation += angular_speed * delta, incrementa a rotação do nosso sprite a cada quadro. Aqui, rotation é uma propriedade herdada da classe Node2D, da qual Sprite2D deriva. Ela controla a rotação do nosso nó e trabalha com radianos.

Dica

No editor de código, você pode usar Ctrl + Clique (Cmd + Clique no macOS) em qualquer propriedade ou função integrada, como position, rotation ou _process, para abrir a documentação correspondente em uma nova aba.

Execute a cena para ver o ícone Godot girar.

../../_images/scripting_first_script_godot_turning_in_place.gif

Nota

Em C#, note como o argumento delta passado ao método `_Process() é do tipo `double. Nós, portanto, devemos converte-lo para o tipo float ao aplicarmos à rotação.

Adicionando movimento

Vamos agora fazer o nó se mover. Adicione as duas linhas seguintes dentro da função _process(), garantindo que as novas linhas estejam indentadas da mesma forma que a linha rotation += angular_speed * delta antes delas.

var velocity = Vector2.UP.rotated(rotation) * speed

position += velocity * delta

var velocity = Vector2.Up.Rotated(Rotation) * _speed;

Position += velocity * (float)delta;

Como já vimos, a palavra-chave var define uma nova variável. Se você colocá-lo no início do script, ela define uma propriedade da classe. Dentro de uma função, define uma variável local: ela só existe dentro do escopo da função.

Definimos uma variável local chamada velocity, um vetor 2D que representa tanto uma direção quanto uma velocidade. Para fazer o nó se mover para frente, começamos a partir da constante da classe Vector2 Vector2.UP, um vetor que aponta para cima, e o rotacionamos chamando o método rotated() de Vector2. Essa expressão, Vector2.UP.rotated(rotation), é um vetor que aponta para frente em relação ao nosso ícone. Multiplicado pela nossa propriedade speed, ele nos dá uma velocidade que podemos usar para mover o nó para frente.

Adicionamos velocity * delta à posição do nó para movê-lo. A própria posição é do tipo Vector2, um tipo embutido em Godot representando um vetor 2D.

Execute a cena para ver a cabeça do Godot se mover em círculos.

Nota

Mover um nó assim não leva em consideração a colisão com paredes ou o chão. Em Seu primeiro jogo 2D, você aprenderá outra abordagem para mover objetos enquanto detecta colisões.

Nosso nó atualmente se move sozinho. Na próxima parte, Capturando os controles de entrada do jogador, usaremos a entrada do jogador para controlá-lo.

Script completo

Aqui está o arquivo completo sprite_2d.gd para referência.

extends Sprite2D

var speed = 400
var angular_speed = PI

func _process(delta):
    rotation += angular_speed * delta

    var velocity = Vector2.UP.rotated(rotation) * speed

    position += velocity * delta

using Godot;
using System;

public partial class MySprite2D : Sprite2D
{
    private int _speed = 400;
    private float _angularSpeed = Mathf.Pi;

    public override void _Process(double delta)
    {
        Rotation += _angularSpeed * (float)delta;
        var velocity = Vector2.Up.Rotated(Rotation) * _speed;

        Position += velocity * (float)delta;
    }
}