Introduction to GDScript in Godot 4 Part 1

Scripting is a fundamental skill for any game developer. You can implement just about any game mechanic you can think of by writing one or more scripts that tells the game engine what to do. From making a character move to creating enemy AI that taunts you from behind a cover, it’s all possible by writing some code.

In this tutorial, you’ll learn the basics of GDScript 2.0, the main programming language of Godot 4. You’re going to create a simple game inspired by Winterbells, a classic Flash game from 2006 by Ferry Halim. The goal of this game is to jump higher and higher by hitting the bells with your white rabbit friend.

The game you’ll be making involves hitting energy orbs with a robot to boost yourself up as high as you can.

There’s nothing better than creating a small game to get a feel for a programming language! The tutorial is split into two parts, in this first part you’ll learn about:

• The fundamentals of GDScript and the built-in script editor.
• Creating and using variables to change and balance the gameplay.
• Using Godot’s powerful signal system to pass values from one node to another.
• Polling for player input and using it to change the game state.
• Scripting jumping and gravity.

Getting Started

This tutorial uses the most recent version of Godot 4, which you can download here.

Download the projects by clicking Download Materials at the top or bottom of the tutorial and extract the zip file to a location of your choosing. After extracting the zip, you’ll see two folders: starter and final. The starter project is what you’ll be using to build upon.
To import the project, open Godot and click the Import button in the Project Manager. Now either paste the starter folder path in the text field, or click the Browse button to navigate to the folder.

Next, click the Import & Edit button to load the project in Godot’s editor. Make sure that the 2D screen is active and the game scene is opened. If this is not the case, open it by double-clicking game.tscn in the scenes folder.

Before taking a look around the different scenes that I set up, try to run the game by pressing F5 on your keyboard or clicking the Run Project button at the top right. You should see a blue robot standing at the bottom of the screen while some music plays in the background.

If that’s working as expected, it’s time to give a quick tour around the starter project.

Project Tour

I’ve prepared some basic scenes and assets so you can focus primarily on scripting. To start off, take a look at the FileSystem dock and the folders and files inside:

• music: A single audio file that’s used for the background music.
• scenes: All scenes used throughout the project. More on those below.
• sounds: A glass-shattering sound effect.
• sprites: This contains the background graphics and the sprite sheets for the robot and jumper orbs.
• credits.txt: A list of sources and attributions for the included assets.

Next up is a brief overview of the scenes.

Game Scene

The first and most important one is game. This the main scene and it contains the following nodes:

• A Camera2D with a repeating background Sprite2D as a child
• A ground Sprite2D node
• An instance of the player_avatar scene named PlayerAvatar
• An AudioStreamPlayer that automatically plays and loops a music track
• An instance of the ui scene named UI

At the end of this tutorial, this will be the scene where all the action happens as the avatar will move about and hit energy orbs called “jumpers” to launch itself upwards. Speaking of jumpers, double-click the jumper.tscn scene file to take a look what’s inside.

Jumper Scene

In this scene, the root node Jumper is an AnimatedSprite2D which holds its animations. The Area2D node and its CollisionShape2D are used to detect collisions with the player avatar. Finally, ShatterSound is an AudioStreamPlayer2D that references the glass shatter sound effect found in the sounds folder.

Now open the player_avatar scene and take a peek at its nodes.

Player Avatar Scene

At its root is a Node2D node which is used to group its children together: an AnimatedSprite2D with several animations and an Area2D used for detecting collisions. Simple but effective!

The final scene to take a look at is the UI scene, which you can find in ui.tscn.

UI Scene

The UI scene contains the user interface for the game, which is a CanvasLayer that has two text labels to keep track of the height and score. The MarginContainer and HBoxContainer nodes align these labels to the bottom of the screen with some margin from the borders of the screen.

That concludes the project tour. Don’t worry if you’re not sure what the scenes are supposed to do just yet, you’ll get familiar with the smaller details while adding logic via scripts and playtesting. With the bird’s eye view out of the way, it’s time to start your GDScript adventures!

Why GDScript?

GDScript is a high-level, object-oriented programming language that was built specifically for use with the Godot game engine. While other languages like C# and C++ can also be used with Godot, GDScript is often the language of choice due to the wealth of examples, questions, and tutorials available online. It’s also the first-class citizen in Godot as it’s fully supported by the built-in script editor.

If you’re familiar with Python, then you’ll find GDScript’s syntax to be intuitive and easy to learn. Even with minimal knowledge of other programming languages, you’ll be comfortable with the language with a few days of practice.

In this tutorial, all scripting will be done using Godot’s built-in script editor, so you won’t need anything else to get started. If you prefer to write your code in a different window or IDE, you can use an external editor like Visual Studio Code, Vim or Sublime Text. Personally, I recommend using Visual Studio Code with the godot-vscode-plugin, even though some functions like debugging are not yet compatible with Godot 4.

As a final recommendation, here are two editor settings for the built-in script editor you might want to change via Editor ▸ Editor Settings in the top menu:

• Disable Text Editor ▸ Behavior ▸ Smooth Scrolling. This is a personal preference, but I find smooth scrolling slows down the speed to navigate a script by scrolling.
• Enable Text Editor ▸ Completion ▸ Add Type Hints. This adds static typing to variables and functions generated by Godot, which improves performance, autocompletion and decreases the likelihood of bugs. I’ll explain why this is the case later in the tutorial.