Your first game — Godot Engine (3.1) documentation in English (2024)

Note

This project is an introduction to the Godot engine. Itassumes that you have some programming experience already. Ifyou’re new to programming entirely, you should start here:Scripting.

Note

For this tutorial, we will assume you are familiar with theeditor. If you haven’t read Scenes and nodes, do so nowfor an explanation of setting up a project and using the editor.

Organizing the project¶

In this project, we will make 3 independent scenes: Player,Mob, and HUD, which we will combine into the game’s Mainscene. In a larger project, it might be useful to make folders to holdthe various scenes and their scripts, but for this relatively smallgame, you can save your scenes and scripts in the project’s root folder,referred to as res://. You can see your project folders in the FileSystemDock in the lower left corner:

Node structure¶

To begin, click the “Add/Create a New Node” button and add an Area2Dnode to the scene.

With Area2D we can detect objects that overlap or run into the player.Change its name to Player by clicking on the node’s name.This is the scene’s root node. We can add additional nodes to the player to addfunctionality.

Before we add any children to the Player node, we want to make sure we don’taccidentally move or resize them by clicking on them. Select the node andclick the icon to the right of the lock; its tooltip says “Makes sure the object’s childrenare not selectable.”

Save the scene. Click Scene -> Save, or press Ctrl+S on Windows/Linux or Command+S on Mac.

Sprite animation¶

Click on the Player node and add an AnimatedSprite node as achild. The AnimatedSprite will handle the appearance and animationsfor our player. Notice that there is a warning symbol next to the node.An AnimatedSprite requires a SpriteFrames resource, which is alist of the animations it can display. To create one, find theFrames property in the Inspector and click “[empty]” ->“New SpriteFrames”. This should automatically open the SpriteFrames panel.

On the left is a list of animations. Click the “default” one and renameit to “right”. Then click the “Add” button to create a second animationnamed “up”. Drag the two images for each animation, named playerGrey_up[1/2] and playerGrey_walk[1/2],into the “Animation Frames” side of the panel:

The player images are a bit too large for the game window, so we need toscale them down. Click on the AnimatedSprite node and set the Scaleproperty to (0.5, 0.5). You can find it in the Inspector under theNode2D heading.

Finally, add a CollisionShape2D as a childof Player. This will determine the player’s “hitbox”, or thebounds of its collision area. For this character, a CapsuleShape2Dnode gives the best fit, so next to “Shape” in the Inspector, click“[empty]”” -> “New CapsuleShape2D”. Using the two size handles, resize theshape to cover the sprite:

When you’re finished, your Player scene should look like this:

Moving the player¶

Now we need to add some functionality that we can’t get from a built-innode, so we’ll add a script. Click the Player node and click the“Add Script” button:

In the script settings window, you can leave the default settings alone. Justclick “Create”:

Start by declaring the member variables this object will need:

extends Area2Dexport var speed = 400 # How fast the player will move (pixels/sec).var screen_size # Size of the game window.

public class Player : Area2D{ [Export] public int Speed = 400; // How fast the player will move (pixels/sec). private Vector2 _screenSize; // Size of the game window.}

Using the export keyword on the first variable speed allows us toset its value in the Inspector. This can be handy for values that youwant to be able to adjust just like a node’s built-in properties. Click onthe Player node and you’ll see the property now appears in the “ScriptVariables” section of the Inspector. Remember, if you change the value here, itwill override the value written in the script.

The _ready() function is called when a node enters the scene tree,which is a good time to find the size of the game window:

func _ready(): screen_size = get_viewport_rect().size

public override void _Ready(){ _screenSize = GetViewport().GetSize();}

Now we can use the _process() function to define what the player will do._process() is called every frame, so we’ll use it to updateelements of our game, which we expect will change often. For the player, weneed to do the following:

• Check for input.
• Move in the given direction.
• Play the appropriate animation.

First, we need to check for input - is the player pressing a key? Forthis game, we have 4 direction inputs to check. Input actions are definedin the Project Settings under “Input Map”. Here, you can define custom events andassign different keys, mouse events, or other inputs to them. For this demo,we will use the default events that are assigned to the arrow keys on thekeyboard.

You can detect whether a key is pressed usingInput.is_action_pressed(), which returns true if it is pressedor false if it isn’t.

func _process(delta): var velocity = Vector2() # The player's movement vector. if Input.is_action_pressed("ui_right"): velocity.x += 1 if Input.is_action_pressed("ui_left"): velocity.x -= 1 if Input.is_action_pressed("ui_down"): velocity.y += 1 if Input.is_action_pressed("ui_up"): velocity.y -= 1 if velocity.length() > 0: velocity = velocity.normalized() * speed $AnimatedSprite.play() else: $AnimatedSprite.stop()

public override void _Process(float delta){ var velocity = new Vector2(); // The player's movement vector. if (Input.IsActionPressed("ui_right")) { velocity.x += 1; } if (Input.IsActionPressed("ui_left")) { velocity.x -= 1; } if (Input.IsActionPressed("ui_down")) { velocity.y += 1; } if (Input.IsActionPressed("ui_up")) { velocity.y -= 1; } var animatedSprite = GetNode<AnimatedSprite>("AnimatedSprite"); if (velocity.Length() > 0) { velocity = velocity.Normalized() * Speed; animatedSprite.Play(); } else { animatedSprite.Stop(); }}

We start by setting the velocity to (0, 0) - by default the playershould not be moving. Then we check each input and add/subtract from thevelocity to obtain a total direction. For example, if you hold rightand down at the same time, the resulting velocity vector will be(1, 1). In this case, since we’re adding a horizontal and a verticalmovement, the player would move faster than if it just moved horizontally.

We can prevent that if we normalize the velocity, which means we setit* length to 1, and multiply by the desired speed. This means nomore fast diagonal movement.

We also check whether the player is moving so we can start or stop theAnimatedSprite animation.

Now that we have a movement direction, we can update the player’s positionand use clamp() to prevent it from leaving the screen by adding the followingto the bottom of the _process function:

position += velocity * deltaposition.x = clamp(position.x, 0, screen_size.x)position.y = clamp(position.y, 0, screen_size.y)

Position += velocity * delta;Position = new Vector2( x: Mathf.Clamp(Position.x, 0, _screenSize.x), y: Mathf.Clamp(Position.y, 0, _screenSize.y));

Click “Play Scene” (F6) and confirm you can move the playeraround the screen in all directions. The console output that opens upon playingthe scene can be closed by clicking Output (which should be highlighted inblue) in the lower left of the Bottom Panel.

Choosing animations¶

Now that the player can move, we need to change which animation theAnimatedSprite is playing based on direction. We have a “right”animation, which should be flipped horizontally using the flip_hproperty for left movement, and an “up” animation, which should beflipped vertically with flip_v for downward movement.Let’s place this code at the end of our _process() function:

if velocity.x != 0: $AnimatedSprite.animation = "right" $AnimatedSprite.flip_v = false # See the note below about boolean assignment $AnimatedSprite.flip_h = velocity.x < 0elif velocity.y != 0: $AnimatedSprite.animation = "up" $AnimatedSprite.flip_v = velocity.y > 0

if (velocity.x != 0){ animatedSprite.Animation = "right"; // See the note below about boolean assignment animatedSprite.FlipH = velocity.x < 0; animatedSprite.FlipV = false;}else if(velocity.y != 0){ animatedSprite.Animation = "up"; animatedSprite.FlipV = velocity.y > 0;}

if velocity.x < 0: $AnimatedSprite.flip_h = trueelse: $AnimatedSprite.flip_h = false

if velocity.x < 0: animatedSprite.FlipH = trueelse: animatedSprite.FlipH = false

Play the scene again and check that the animations are correct in eachof the directions. When you’re sure the movement is working correctly,add this line to _ready(), so the player will be hidden when the gamestarts:

hide()

Hide();

Preparing for collisions¶

We want Player to detect when it’s hit by an enemy, but we haven’tmade any enemies yet! That’s OK, because we’re going to use Godot’ssignal functionality to make it work.

Add the following at the top of the script, after extends Area2d:

signal hit

// Don't forget to rebuild the project so the editor knows about the new signal.[Signal]public delegate void Hit();

This defines a custom signal called “hit” that we will have our playeremit (send out) when it collides with an enemy. We will use Area2D todetect the collision. Select the Player node and click the “Node” tabnext to the Inspector tab to see the list of signals the player can emit:

Notice our custom “hit” signal is there as well! Since our enemies aregoing to be RigidBody2D nodes, we want thebody_entered( Object body ) signal; this will be emitted when abody contacts the player. Click “Connect..” and then “Connect” again onthe “Connecting Signal” window. We don’t need to change any of thesesettings - Godot will automatically create a function in your player’s script.This function will be called whenever the signal is emitted - it handles thesignal.

Add this code to the function:

func _on_Player_body_entered(body): hide() # Player disappears after being hit. emit_signal("hit") $CollisionShape2D.set_deferred("disabled", true)

public void OnPlayerBodyEntered(PhysicsBody2D body){ Hide(); // Player disappears after being hit. EmitSignal("Hit"); GetNode<CollisionShape2D>("CollisionShape2D").SetDeferred("disabled", true);}

Each time an enemy hits the player, the signal is going to be emitted. We needto disable the player’s collision so that we don’t trigger the hit signalmore than once.

The last piece for our player is to add a function we can call to resetthe player when starting a new game.

func start(pos): position = pos show() $CollisionShape2D.disabled = false

public void Start(Vector2 pos){ Position = pos; Show(); GetNode<CollisionShape2D>("CollisionShape2D").Disabled = false;}

Node setup¶

Click Scene -> New Scene and we’ll create the Mob.

The Mob scene will use the following nodes:

• RigidBody2D (named Mob)
  • AnimatedSprite
  • CollisionShape2D
  • VisibilityNotifier2D (named Visibility)

Don’t forget to set the children so they can’t be selected, like you did with thePlayer scene.

In the RigidBody2D properties, set Gravity Scale to 0, sothe mob will not fall downward. In addition, under thePhysicsBody2D section, click the Mask property anduncheck the first box. This will ensure the mobs do not collide with each other.

Set up the AnimatedSprite like you did for the player.This time, we have 3 animations: fly, swim, and walk. Set the Playingproperty in the Inspector to “On” and adjust the “Speed (FPS)” setting as shown below.We’ll select one of these animations randomly so that the mobs will have some variety.

fly should be set to 3 FPS, with swim and walk set to 4 FPS.

Like the player images, these mob images need to be scaled down. Set theAnimatedSprite’s Scale property to (0.75, 0.75).

As in the Player scene, add a CapsuleShape2D for thecollision. To align the shape with the image, you’ll need to set theRotation Degrees property to 90 under Node2D.

Enemy script¶

Add a script to the Mob and add the following member variables:

extends RigidBody2Dexport var min_speed = 150 # Minimum speed range.export var max_speed = 250 # Maximum speed range.var mob_types = ["walk", "swim", "fly"]

public class Mob : RigidBody2D{ // Don't forget to rebuild the project so the editor knows about the new export variables. [Export] public int MinSpeed = 150; // Minimum speed range. [Export] public int MaxSpeed = 250; // Maximum speed range. private String[] _mobTypes = {"walk", "swim", "fly"};}

When we spawn a mob, we’ll pick a random value between min_speed andmax_speed for how fast each mob will move (it would be boring if theywere all moving at the same speed). We also have an array containing the namesof the three animations, which we’ll use to select a random one. Make sureyou’ve spelled these the same in the script and in the SpriteFrames resource.

Now let’s look at the rest of the script. In _ready() we randomlychoose one of the three animation types:

func _ready(): $AnimatedSprite.animation = mob_types[randi() % mob_types.size()]

// C# doesn't implement GDScript's random methods, so we use 'System.Random' as an alternative.static private Random _random = new Random();public override void _Ready(){ GetNode<AnimatedSprite>("AnimatedSprite").Animation = _mobTypes[_random.Next(0, _mobTypes.Length)];}

The last piece is to make the mobs delete themselves when they leave thescreen. Connect the screen_exited() signal of the Visibilitynode and add this code:

func _on_Visibility_screen_exited(): queue_free()

public void OnVisibilityScreenExited(){ QueueFree();}

This completes the Mob scene.

Note

See Instancing to learn more about instancing.

Spawning mobs¶

The Main node will be spawning new mobs, and we want them to appear at arandom location on the edge of the screen. Add a Path2D node namedMobPath as a child of Main. When you select Path2D,you will see some new buttons at the top of the editor:

Select the middle one (“Add Point”) and draw the path by clicking to addthe points at the corners shown. To have the points snap to the grid, make sure “Snap toGrid” is checked. This option can be found under the “Snapping options”button to the left of the “Lock” button, appearing as a series of threevertical dots.

After placing point 4 in the image, click the “Close Curve” button andyour curve will be complete.

Now that the path is defined, add a PathFollow2Dnode as a child of MobPath and name it MobSpawnLocation. This node willautomatically rotate and follow the path as it moves, so we can use itto select a random position and direction along the path.

Main script¶

Add a script to Main. At the top of the script, we useexport (PackedScene) to allow us to choose the Mob scene we want toinstance.

extends Nodeexport (PackedScene) var Mobvar scorefunc _ready(): randomize()

public class Main : Node{ // Don't forget to rebuild the project so the editor knows about the new export variable. [Export] public PackedScene Mob; private int _score; // We use 'System.Random' as an alternative to GDScript's random methods. private Random _random = new Random(); public override void _Ready() { } // We'll use this later because C# doesn't support GDScript's randi(). private float RandRange(float min, float max) { return (float)_random.NextDouble() * (max - min) + min; }}

Drag Mob.tscn from the “FileSystem” panel and drop it in theMob property under the Script Variables of the Main node.

Next, click on the Player and connect the hit signal. We want to make anew function named game_over, which will handle what needs to happen when agame ends. Type “game_over” in the “Method In Node” box at the bottom of the“Connecting Signal” window. Add the following code, as well as a new_gamefunction to set everything up for a new game:

func game_over(): $ScoreTimer.stop() $MobTimer.stop()func new_game(): score = 0 $Player.start($StartPosition.position) $StartTimer.start()

public void GameOver(){ GetNode<Timer>("MobTimer").Stop(); GetNode<Timer>("ScoreTimer").Stop();}public void NewGame(){ _score = 0; var player = GetNode<Player>("Player"); var startPosition = GetNode<Position2D>("StartPosition"); player.Start(startPosition.Position); GetNode<Timer>("StartTimer").Start();}

Now connect the timeout() signal of each of the Timer nodes (StartTimer,ScoreTimer, and MobTimer) to the main script. StartTimer will startthe other two timers. ScoreTimer will increment the score by 1.

func _on_StartTimer_timeout(): $MobTimer.start() $ScoreTimer.start()func _on_ScoreTimer_timeout(): score += 1

public void OnStartTimerTimeout(){ GetNode<Timer>("MobTimer").Start(); GetNode<Timer>("ScoreTimer").Start();}public void OnScoreTimerTimeout(){ _score++;}

In _on_MobTimer_timeout(), we will create a mob instance, pick arandom starting location along the Path2D, and set the mob inmotion. The PathFollow2D node will automatically rotate as itfollows the path, so we will use that to select the mob’s direction aswell as its position.

Note that a new instance must be added to the scene usingadd_child().

Now click on MobTimer in the scene window then head to inspector window,switch to node view then click on timeout() and connect the signal.

Add the following code:

func _on_MobTimer_timeout(): # Choose a random location on Path2D. $MobPath/MobSpawnLocation.set_offset(randi()) # Create a Mob instance and add it to the scene. var mob = Mob.instance() add_child(mob) # Set the mob's direction perpendicular to the path direction. var direction = $MobPath/MobSpawnLocation.rotation + PI / 2 # Set the mob's position to a random location. mob.position = $MobPath/MobSpawnLocation.position # Add some randomness to the direction. direction += rand_range(-PI / 4, PI / 4) mob.rotation = direction # Set the velocity (speed & direction). mob.linear_velocity = Vector2(rand_range(mob.min_speed, mob.max_speed), 0) mob.linear_velocity = mob.linear_velocity.rotated(direction)

public void OnMobTimerTimeout(){ // Choose a random location on Path2D. var mobSpawnLocation = GetNode<PathFollow2D>("MobPath/MobSpawnLocation"); mobSpawnLocation.SetOffset(_random.Next()); // Create a Mob instance and add it to the scene. var mobInstance = (RigidBody2D)Mob.Instance(); AddChild(mobInstance); // Set the mob's direction perpendicular to the path direction. float direction = mobSpawnLocation.Rotation + Mathf.Pi / 2; // Set the mob's position to a random location. mobInstance.Position = mobSpawnLocation.Position; // Add some randomness to the direction. direction += RandRange(-Mathf.Pi / 4, Mathf.Pi / 4); mobInstance.Rotation = direction; // Choose the velocity. mobInstance.SetLinearVelocity(new Vector2(RandRange(150f, 250f), 0).Rotated(direction));}

Note

Anchors and Margins: Control nodes have a position and size,but they also have anchors and margins. Anchors define theorigin - the reference point for the edges of the node. Marginsupdate automatically when you move or resize a control node. Theyrepresent the distance from the control node’s edges to its anchor.See Design interfaces with the Control nodes for more details.

ScoreLabel¶

• Text : 0
• Layout : “Top Wide”
• Align : “Center”

MessageLabel¶

• Text : Dodge the Creeps!
• Layout : “HCenter Wide”
• Align : “Center”

StartButton¶

• Text : Start
• Layout : “Center Bottom”
• Margin :
  • Top: -200
  • Bottom: -100

Now add this script to HUD:

extends CanvasLayersignal start_game

public class HUD : CanvasLayer{ // Don't forget to rebuild the project so the editor knows about the new signal. [Signal] public delegate void StartGame();}

The start_game signal tells the Main node that the buttonhas been pressed.

func show_message(text): $MessageLabel.text = text $MessageLabel.show() $MessageTimer.start()

public void ShowMessage(string text){ var messageLabel = GetNode<Label>("MessageLabel"); messageLabel.Text = text; messageLabel.Show(); GetNode<Timer>("MessageTimer").Start();}

This function is called when we want to display a messagetemporarily, such as “Get Ready”. On the MessageTimer, set theWait Time to 2 and set the One Shot property to “On”.

func show_game_over(): show_message("Game Over") yield($MessageTimer, "timeout") $MessageLabel.text = "Dodge the\nCreeps!" $MessageLabel.show() yield(get_tree().create_timer(1), 'timeout') $StartButton.show()

async public void ShowGameOver(){ ShowMessage("Game Over"); var messageTimer = GetNode<Timer>("MessageTimer"); await ToSignal(messageTimer, "timeout"); var messageLabel = GetNode<Label>("MessageLabel"); messageLabel.Text = "Dodge the\nCreeps!"; messageLabel.Show(); GetNode<Button>("StartButton").Show();}

This function is called when the player loses. It will show “GameOver” for 2 seconds, then return to the title screen and, after a brief pause,show the “Start” button.

func update_score(score): $ScoreLabel.text = str(score)

public void UpdateScore(int score){ GetNode<Label>("ScoreLabel").Text = score.ToString();}

This function is called by Main whenever the score changes.

Connect the timeout() signal of MessageTimer and thepressed() signal of StartButton.

func _on_StartButton_pressed(): $StartButton.hide() emit_signal("start_game")func _on_MessageTimer_timeout(): $MessageLabel.hide()

public void OnStartButtonPressed(){ GetNode<Button>("StartButton").Hide(); EmitSignal("StartGame");}public void OnMessageTimerTimeout(){ GetNode<Label>("MessageLabel").Hide();}

Connecting HUD to Main¶

Now that we’re done creating the HUD scene, save it and go back to Main.Instance the HUD scene in Main like you did the Player scene, andplace it at the bottom of the tree. The full tree should look like this,so make sure you didn’t miss anything:

Now we need to connect the HUD functionality to our Main script.This requires a few additions to the Main scene:

In the Node tab, connect the HUD’s start_game signal to thenew_game() function.

In new_game(), update the score display and show the “Get Ready”message:

$HUD.update_score(score)$HUD.show_message("Get Ready")

var hud = GetNode<HUD>("HUD");hud.UpdateScore(_score);hud.ShowMessage("Get Ready!");

In game_over() we need to call the corresponding HUD function:

$HUD.show_game_over()

GetNode<HUD>("HUD").ShowGameOver();

Finally, add this to _on_ScoreTimer_timeout() to keep the display insync with the changing score:

$HUD.update_score(score)

GetNode<HUD>("HUD").UpdateScore(_score);

Now you’re ready to play! Click the “Play the Project” button. You willbe asked to select a main scene, so choose Main.tscn.

Removing old creeps¶

If you play until “Game Over” and then start a new game the creeps from theprevious game are still on screen. It would be better if they all disappearedat the start of a new game.

We’ll use the start_game signal that’s already being emitted by the HUDnode to remove the remaining creeps. We can’t use the editor to connect thesignal to the mobs in the way we need because there are no Mob nodes in theMain scene tree until we run the game. Instead we’ll use code.

Start by adding a new function to Mob.gd. queue_free() will delete thecurrent node at the end of the current frame.

func _on_start_game(): queue_free()

public void OnStartGame(){ QueueFree();}

Then in Main.gd add a new line inside the _on_MobTimer_timeout() function,at the end.

$HUD.connect("start_game", mob, "_on_start_game")

GetNode("HUD").Connect("StartGame", mobInstance, "OnStartGame");

This line tells the new Mob node (referenced by the mob variable) to respondto any start_game signal emitted by the HUD node by running its_on_start_game() function.

Background¶

The default gray background is not very appealing, so let’s change itscolor. One way to do this is to use a ColorRect node.Make it the first node under Main so that it will be drawn behind the othernodes. ColorRect only has one property: Color. Choose a coloryou like and drag the size of the ColorRect so that it covers thescreen.

You could also add a background image, if you have one, by using aSprite node.

Sound effects¶

Sound and music can be the single most effective way to add appeal tothe game experience. In your game assets folder, you have two soundfiles: “House In a Forest Loop.ogg” for background music, and“gameover.wav” for when the player loses.

Add two AudioStreamPlayer nodes as children of Main. Name one ofthem Music and the other DeathSound. On each one, click on theStream property, select “Load”, and choose the corresponding audiofile.

To play the music, add $Music.play() in the new_game() functionand $Music.stop() in the game_over() function.

Finally, add $DeathSound.play() in the game_over() function.

Keyboard Shortcut¶

Since the game is played with keyboard controls, it would be convenient if wecould also start the game by pressing a key on the keyboard. One way to do thisis using the “Shortcut” property of the Button node.

In the HUD scene, select the StartButton and find its Shortcut propertyin the Inspector. Select “New Shortcut” and click on the “Shortcut” item. Asecond Shortcut property will appear. Select “New InputEventAction” and clickthe new “InputEvent”. Finally, in the Action property, type the name ui_select.This is the default input event associated with the spacebar.

Now when the start button appears, you can either click it or press the spacebarto start the game.