KCC Blog on KCC Blog

Godot 101: Intro to 3D, Part 4

Sat, 23 Mar 2019 05:22:12 PDT

In the previous tutorial, we learned about transforms, a very important concept in 3D that records an object’s local orientation in space, and used it to move our KinematicBody character. This time, we’re going to look at another type of 3D node: the Area.

About this series

A word of warning: 3D development can be quite a bit more complex than working in 2D. While many of the same principles apply - such as working with nodes, writing scripts, and handling logic/data - 3D brings with it a number of other considerations. For this reason, it’s a good idea to stick to 2D for your first few projects, moving to 3D once you have a good understanding of the game development process. This tutorial will assume you have completed at least an introductory Godot 2D project.

You can also find a video version of this lesson here:

Areas

Area nodes are used for detection and influence. They can detect when objects overlap, and when an object enters or exits a region. An Area can also be used to override physics properties, such as gravity or damping, in a region.

We’re going to use Area to create three types of objects:

A coin the character can pick up
A bullet the character can shoot
Spikes that damage the character

To begin, let’s set up some collision layers so that we can more easily control what objects the areas can interact with. Open the Project Settings and find the “Layer Names/3D Physics” section. Name the first three layers “environment”, “player”, and “pickups”.

Coin

Create a new inherited scene from the CoinGold.glb object in the Kenney Platformer Kit (see Part 03). Right-click on the root node, choose “Change Type”, and pick Area. In the Inspector, set the collision mask and layer so that the coin is in “pickups” and scans “player”.

Now we need a collision shape, so add a CollisionShape node and choose a CylinderShape for it. If you rotate it 90 degrees around z, it will fit the coin shape pretty well.

Add a script to the Area and connect its body_entered signal, which we’ll use to remove the coin:

extends Area

func _on_Coin_body_entered(body):
    queue_free()

Add a few coins to your scene and see if you can pick them up:

Bullets

Make a new scene with an Area2D root, and name it “Bullet”. Add a MeshInstance, a CollisionShape, and a Timer. I’m using a sphere shape for the mesh and collision, scaled to a radius of 0.2 so that it won’t be too big compared with the character. The Timer is to give the bullet a time limit. Set its One Shot and Autostart properties both on.

Add a script and connect the Timer’s timeout signal and the Area’s body_entered signal. Then add the following:

extends Area

var speed = 15
var velocity = Vector3()

func start(xform):
    transform = xform
    velocity = -transform.basis.z * speed

func _process(delta):
    transform.origin += velocity * delta

func _on_Timer_timeout():
    queue_free()

func _on_Bullet_body_entered(body):
    if body is StaticBody:
        queue_free()

Since we want the bullet to start at a certain location and travel directly ahead of the player, we’ll pass the player’s transform to start() and use it to orient the bullet and make it move forward (remember in Godot’s orientation, “forward” is along the negative z axis).

Now we can go to the character scene and add a Position3D node, placing it at the tip of the character’s “arrow” mesh. Name this node “Muzzle”. Next, add the following code to the character’s script:

var Bullet = preload("res://Bullet.tscn")

func _unhandled_input(event):
    if event.is_action_pressed("shoot"):
        var b = Bullet.instance()
        b.start($Muzzle.global_transform)
        get_parent().add_child(b)

Spikes

Finally, we’re going to add some danger to the environment. Make in instance of the spikes.glb object and make it an Area like we did with the coin. Add a script and connect the body_entered signal, but this time, we want the object to do something to the character:

extends Area

func _on_Spikes_body_entered(body):
    if body.has_method("take_damage"):
        body.take_damage()

Now we need to define how the character reacts to taking “damage”. Since we haven’t really built a health system, we’re just going to “bounce” the character as if it got hurt. We need to add the following to the character script:

var can_move = true

func take_damage():
    velocity *= -1
    velocity.y = jump_speed
    can_move = false
    yield(get_tree().create_timer(1), "timeout")
    can_move = true

The purpose of this code is to disable input temporarily so the player will fly backwards from the spikes. If we just tried to set the velocity, it would immediately be overridden by the velocity set by the key inputs. So add this at the beginning of get_input():

    if !can_move:
        return

Add a spike instance to your level and try it out:

Wrapping Up

In this tutorial you learned how to use Area nodes to detect and react to 3D bodies.

In the next part: all about raycasting!

Next: Coming Soon

Support these lessons:

Godot 101: Intro to 3D, Part 3

Sun, 10 Mar 2019 05:22:12 PDT

In the previous tutorial, we covered how to import 3D objects and how to arrange them in a scene. In this installment, we’ll add more objects to the scene, including a user-controlled character.

About this series

You can also find a video version of this lesson here:

Building the Scene

We’re going to continue using the Kenney Platformer Kit we downloaded last time. Select all the “block*.glb” files and in the “Import” tab set their “Root Type” to StaticBody and click “Reimport”. Select “blockLarge.glb” and make a new inherited scene. Add a “Convex Collision Sibling” to the mesh using the menu as you did in the last tutorial. Rename the root node to “BlockLarge” and save the scene - I recommend making a separate folder for this, as soon you’re going to have a bunch of scenes representing the differently shaped platform parts.

You can download a starter project with all the block objects already configured and ready to use here: LINK

Open the scene from the last tutorial with the “Ground” plane and the crates. Delete the crates and add an instance of the large block. We want to be able to place these blocks so that they line up. To do this, select “Configure Snap” from the “Transform” menu at the top of the Viewport and set Translate Snap to 0.5. Then click on the “Snap Mode” button (or press the Y key). Now duplicate the block a few times and drag them to arrange.

If you like, go ahead and add scenes for some of the other platform blocks and arrange them into a pleasing level. Be creative!

Adding a Character

Now we’re going to make a character so we can walk around on the platforms. Open a new scene and start with a KinematicBody named “Character”. This PhysicsBody node behaves very much like its 2D equivalent (you’ve already done the 2D tutorials, right?). It has a move_and_slide() method that we’ll use to perform the movement and collision detection. Gravity will be added manually each frame, accelerating in the -Y direction.

Add a sphere-shaped MeshInstance and a matching CollisionShape. Remember, you can add a SpatialMaterial to the mesh and set its Albedo property to change the color.

The sphere is nice, but it’s going to be hard to tell what direction it’s facing. Let’s add another MeshInstance, this time with a PrismMesh shape. Set its Size to (0.5, 0.5, 0.1) and then its x rotation to -90 degrees. Arrange it so it’s pointing along the negative z axis. (You can tell which way is negative because the gizmo arrows point in the positive direction).

Let’s also add a Camera to the scene, so it will follow the player around. Position the camera behind and above the character, angling it down a bit. Click the “Preview” button to check the camera’s view.

Before we add a script, open the “Project Settings” and add the following inputs on the “Input Map” tab:

Input Action	Key
move_forward	W
move_back	S
strafe_right	D
strafe_left	A
jump	Space

Now let’s add a script to the body.

extends KinematicBody

var gravity = -12  # strength of gravity Vector3.DOWN * 12
var speed = 4  # movement speed
var jump_speed = 6  # jump strength
var spin = 0.1  # rotation speed

var velocity = Vector3()
var jump = false

func get_input():
    velocity.x = 0
    velocity.z = 0
    if Input.is_action_pressed("move_forward"):
        velocity.z -= speed
    if Input.is_action_pressed("move_back"):
        velocity.z += speed
    if Input.is_action_pressed("strafe_right"):
        velocity.x += speed
    if Input.is_action_pressed("strafe_left"):
        velocity.x -= speed

func _physics_process(delta):
    velocity += gravity * delta
    get_input(delta)
    velocity = move_and_slide(velocity, Vector3.UP)

The code in _physics_process() is pretty straightforward: add gravity to accelerate in the positive Y direction (downward), call get_input() to check for input, and then use move_and_slide() to move in the direction of the velocity vector.

In get_input() we check to see which key is pressed and then move in that direction. Run the program and test:

This is all good, but we need to be able to rotate. Let’s add a camera to the body and we’ll use the mouse to rotate. Place the camera above and behind the character so you have a good view, then add the following code to the character’s script:

func _unhandled_input(event):
    if event is InputEventMouseMotion:
        if event.relative.x > 0:
            rotate_y(-lerp(0, spin, event.relative.x/10))
        elif event.relative.x < 0:
            rotate_y(-lerp(0, spin, event.relative.x/10)

This will convert any mouse motion in the x direction into a rotation around the y axis. We use lerp() to smooth it out based on how fast you move the mouse.

Run the scene and confirm that moving the mouse rotates the character:

However, there’s a problem. No matter which way we’re facing, pressing W moves us along the Z axis. Our movement is using global coordinates, but we need to move in the object’s forward direction.

The Power of Transforms

This is where transforms come in. A transform is a mathematical matrix that contains the object’s translation, rotation, and scale information all in one. In Godot it’s stored in the Transform data type. The position information is called the transform.origin and the orientation information is in the transform.basis.

Remember how the 3D gizmo can be set to “Local Space Mode”? When in this mode, the gizmo’s X/Y/Z axes point along the object’s axes. This is the basis of the transform. The basis contains three Vector3 objects callsd x, y, and z that represent these directions. We can use this to ensure that pressing the W key will always move us in the object’s forward direction.

Change the get_input() function like so:

func get_input():
    var vy = velocity.y
    velocity = Vector3()
    if Input.is_action_pressed("move_forward"):
        velocity += -transform.basis.z * speed
    if Input.is_action_pressed("move_back"):
        velocity += transform.basis.z * speed
    if Input.is_action_pressed("strafe_right"):
        velocity += transform.basis.x * speed
    if Input.is_action_pressed("strafe_left"):
        velocity += -transform.basis.x * speed
    velocity.y = vy

Now forward and back will always move along the objects’ Z axis, and the strafe keys along its X.

Jumping

Let’s add one more movement to the player: jumping.

Add these lines to the end of get_input():

    jump = false
    if Input.is_action_just_pressed("jump"):
        jump = true

And add these to the end of _physics_process():

    if jump and is_on_floor():
        velocity.y = jump_speed

Wrapping Up

In this tutorial you learned how to build a more complex scene, and how to write movement code for a user-controlled character. You also learned about transforms, which are a very important concept in 3D - you’re going to be using a lot in the future.

In the next part, we’ll add some more objects to our 3D world.

Next: Godot 101: Intro to 3D, Part 4

Support these lessons:

Godot 101: Intro to 3D, Part 2

Sat, 09 Mar 2019 05:22:12 -0700

In the previous tutorial, we started a 3D project and looked at how to navigate and create 3D objects. In this part, you’ll learn how to import existing 3D objects that you’ve made or downloaded and how to use more of Godot’s 3D nodes.

About this series

You can also find a video version of this lesson here:

Importing 3D Objects

If you’re familiar with 3D modeling software such as Blender, you can make your own models to use in your game. If not, there are many sources where you can download objects or even collections of objects for particular game types. One of our favorite makers of free game art is Kenney.nl.

For our tutorials, we’re going to use Kenney’s Platformer Kit, which you can download here: https://kenney.nl/assets/platformer-kit

This kit has a wide selection of objects that we can use to practice our Godot 3D skills. Here’s a sample showing what the kit looks like:

Once you’ve downloaded the kit, you’ll find that the objects inside are provided in a variety of different formats. Godot is able to use several of these, but since GLTF is available in this pack, it’s preferred over the others. Copy the “GLTF Format” folder into your Godot project’s folder and rename it to “platformer kit”.

If you’re interested in the differences between the formats, here’s a brief summary: OBJ files are the simplest, each representing a mesh which you can load into a MeshInstance node. This is likely the most common file type you’ll find online. DAE (Collada) files are more robust - Godot loads them as individual scenes, and they can include additional data along with the mesh such as animations. GLTF files are similar, but represent a more modern format with additional features.

When you switch back to your Godot window, you’ll see progress bar while Godot scans the folder and imports all of the objects. Let’s click on one of them to see what’s going on. In the “FileSystem” tab, select the “crate.glb” and then click on the “Import” tab:

Here you can see the cube object will be imported as a scene, with its root type set to Spatial and named “Scene Root”. Let’s change these: set the root type to RigidBody and the root name to “Crate”, then click the “Reimport” button.

Now double-click on “crate.glb” and confirm that you want to make a new inherited scene. Here we have a classic game object: the crate. The root node of the scene is a RigidBody named “Crate” just as we wanted. However, there’s one small problem: it seems Kenney exported this model with an offset:

It would much better if the crate were centered relative to the parent node, so that when the RigidBody rotates about its center, so will the mesh. To fix this, select the MeshInstance node and set its Translation property to (-0.5, -0.25, 0.5).

Finally, we need to add a collision shape to the body. Add a CollisionShape node as a child of the Crate. In its Shape property, choose “New BoxShape”. Use the three handles (they look like orange circles) to size the box to fit the mesh. You can also set the extents directly in the Inspector:

Note that since the crate is 0.5 units wide, the Extents, which represent the distance from the center, becomes 0.25 units.

Now we’re finished setting up the object. Save your Crate scene and let’s see how we can use it.

Building a 3D Scene

Create a new scene with a Spatial root. The first child we’ll add is one to give us a “ground” to stack some crates on. Add a StaticBody called “Ground”, and to that add a MeshInstance. In the Mesh property, select “New PlaneMesh” and then click it to open its properties. Set Size to (10, 10) so that we have a nice large surface. However, it would look better if it weren’t plain white.

Also in the mesh properties is a Material property. Materials are how you define the appearance of an object. Select “New SpatialMaterial” and then click it to open a large list of properties. To set the color of the mesh, we need the Albedo property. Choose a color, such as brown or dark green.

If we add a crate, it will fall right through the mesh, so we also need to give it a collision shape. With the crate, we added a CollisionShape node and assigned a shape. That’s one way to add collision, let’s look at another: select the mesh and in the menu at the of the viewport, choose “Create Convex Collision Sibling”. This will automatically create a CollisionShape node as a sibling of the mesh and assign it a shape that matches the mesh.

Now instance a few crates in the scene and arrange them in a rough stack. Add a Camera and place it where it has a good view of the crates. Run the scene and watch your crates go tumbling!

Rotating Camera

Let’s make the camera a little more dynamic by having it slowly orbit around the scene. Add a Spatial, which will be located at (0, 0, 0) and name it “CameraHub”. In the scene tree, drag the camera to make it a child of this new Spatial. Now, if the Spatial rotates around the y axis, it will drag the camera along with it.

Add a script to the root node and add the following:

extends Spatial

func _process(delta):
    $CameraHub.rotate_y(0.01)

Run the scene to see what happens.

Lighting

There’s another thing we can add to the scene to improve how it looks: light. There are multiple light nodes available in 3D, but we’re going to start with DirectionalLight. Add one to the scene and use the green (Y) arrow to pull it up into the air.

A DirectionalLight simulates an infinite number of parallel rays of light, as if from a distant source like the sun. It will not cast shadows by default; to add shadows, click Enabled in the “Shadow” section. There is also a “DirectionalShadow” section, which contains a number of advanced properties for fine-tuning the shadow appearance. For full details see this document.

Note that it really doesn’t matter where you place the node - only the direction of the light arrow matters.

Wrapping Up

In this tutorial you learned how to import 3D objects from outside sources, and how to combine them into a simple scene. We also investigated lights and moving cameras.

In the next part, we’ll look at how to build a more complex scene and include a player-controlled character.

Next: Godot 101: Intro to 3D, Part 3

Support these lessons:

Godot 101: Intro to 3D

Fri, 08 Mar 2019 05:22:12 -0700

In this tutorial, we’ll look at how to start working in 3D in Godot. You’ll learn how to navigate in the 3D editor, how to create and manipulate 3D objects, and how to work with some of Godot’s essential 3D nodes, such as cameras and lighting.

About this series

You can also find a video version of this lesson here:

Getting Started in 3D

One of Godot’s strengths is its ability to handle both 2D and 3D games. While much of what you’ve learned working on 2D projects (nodes, scenes, signals, etc.) applies equally well in 3D, there is also a whole new layer of complexity and capabilities. First, you’ll find that there are some additional features available in the 3D editor window, so we’ll start there:

Orienting in 3D Space

When you first open a new project in Godot, you will see the 3D project view:

The first thing you should notice is the three colored lines in the center. These are the x (red), y (green), and z (blue) axes. The point where they meet is the origin, which has the coordinates (0, 0, 0). You’ll find that this color scheme will also apply elsewhere in the Inspector.

Note: Different 3D applications follow different conventions for orientation. Godot uses Y-Up orientation, so that when looking at the axes, if x is pointing to the left/right, then y is up/down, and z is forward/back. Some other popular 3D software uses Z-UP. It’s good to keep this in mind when moving between applications.

Navigation in 3D is performed using the mouse and keyboard. Here are the basic controls for the view camera:

Mousewheel up/down: zoom in/out
Middle button + drag: orbit camera around current target
Shift + middle button + drag: pan camera
Right-click + drag: rotate camera in place

In addition, if you’re familiar with popular 3D games, you might prefer Freelook mode, which you can toggle on/off using Shift+F. In this mode, you can use the WASD keys to fly around the scene while aiming with the mouse.

You can also alter the camera’s view by clicking on the [Perspective] label in the upper-left corner. Here, you can snap the camera to a particular orientation.

Adding 3D Objects

Now let’s add our first 3D node. Just as all 2D nodes inherit from Node2D, which provides properties such as position and rotation, 3D nodes inherit from Spatial. Add one to your scene and you’ll see the following object appear at the origin:

This object is not the node. It is something called a 3D gizmo. Gizmos are tools that allow you to move and rotate objects in space. The three rings control rotation, while the three arrows move (translate) the object along the three axes. Note that the rings and arrows are color-coded to match the axis colors.

Take a few minutes to experiment and get familiar with the gizmo. Use Undo if you find yourself getting lost.

Note: Sometimes you may feel the gizmos are getting in your way. You can click on the mode icons to restrict yourself to only one type of transformation: move, rotate, or scale:

Global vs. Local Space

By default, the gizmo controls operate in global space. When you rotate the object, the gizmo’s arrows still point along the axes. However, if you click the “Local Space Mode” button, the gizmo will switch to moving the body in local space.

Now when you rotate the object, the gizmo arrows point along the object’s axes and not the world’s. Switching back and forth between Local and World space can make it much easier to place an object exactly where you want it.

Transforms

Look at the Inspector for the Spatial node. Instead of a Position property, you have Translation, as well as Rotation Degrees, and Scale. Drag the object around with the gizmo and observe how these values change.

You’ll also find a Transform property, which changes as you move the object. A transform is a matrix that describes an object’s translation, rotation, and scale all in one. The math behind transforms can get quite complex - you’ll start working with them in a later tutorial.

Meshes

Just like a Node2D, a Spatial has no size or appearance of its own. In 2D, you would use a Sprite to add a texture to the node. In 3D, you need to add a mesh. A mesh is a mathematical description of a shape. It consists of a collection of points, called vertices. These vertices are connected by lines, called edges, and multiple edges (at least three) together make a face.

For example, a cube is made up of 8 vertices, 12 edges, and 6 faces.

Adding Meshes

Typically, meshes are created by using 3D modeling software, such as Blender. You can also find many collections of 3D models available for download, if you’re unable to create your own. However, often you just need a basic shape such as a cube or sphere. In this case, Godot provides a way to create simple meshes called primitives.

Add a MeshInstance node as a child of the Spatial and in the Inspector, click its Mesh property:

Here you can see the list of available primitives. They represent a handy collection of common useful shapes. Select “New CubeMesh” and you’ll see a plain cube appear on the screen. Note that the cube is white by default, although it may appear slightly blue on your screen due to the default ambient lighting. We’ll talk about lighting a little bit later.

Cameras

Try running the scene with your cube object. Did you see anything? In 3D, you won’t see anything in the game viewport without adding a Camera. Add one and use the camera’s gizmo to position it pointing towards the cube:

The pinkish-purple pyramid shape on the camera is called the fustrum and represents the camera’s view. Notice the small triangular arrow which represents the camera’s “up” orientation. As you’re moving the camera around, try pressing the “Preview” button in the upper-left to see what the camera sees. Play the scene to verify everything is working as expected.

Wrapping Up

In this tutorial you learned how to use Godot’s 3D editor, how to add 3D nodes such as Spatial, MeshInstance, and Camera, and how to use gizmos to place your objects. You also learned a bunch of new terminology. Hopefully you’re not overwhelmed.

In the next part, we’ll look at how to build a 3D scene by importing 3D assets and how to use more of Godot’s 3D nodes.

Next: Godot 101: Intro to 3D, Part 2

Support these lessons:

Procedural Generation in Godot - Part 8: Dungeons (part 3)

Tue, 18 Dec 2018 09:14:12 -0700

In this series, we’ll explore the applications of procedural generation to game development. While we’ll be using Godot 3.0 as our platform, much of the concepts and algorithms related to this subject are universal, and you can apply them to whatever platform you may be working on.

In this part, we’ll wrap up the procedurally generated dungeon by making it into a TileMap that we can explore.

You can watch a video version of this lesson here:

Generating a TileMap

Now that we’ve generated the rooms and connected them with a path, there’s one more step to having a dungeon to explore. We will use Godot’s TileMap node to create the walls. In a nutshell, we’ll fill the entire map with walls, carve out the locations of our rooms, and then carve paths between them according to our minumum spanning tree.

The tileset we’ll be using is a simple one with two tiles:

Grass tile: Stone tile:

Add a TileMap node to the Main scene and set its Cell/Size to (32, 32). Add the res://assets/tiles.tres TileSet resource to the Tile Set property (you can find this in the project download at the end of this document).

Since we still have the visualization running of our room generation, we’ll manually trigger building the TileMap by pressing <Tab>. Add this to _input():

if event.is_action_pressed('ui_focus_next'):
    make_map()

And then we’ll define the make_map() function:

func make_map():
    # Creates a TileMap from the generated rooms & path
    # find_start_room()
    # find_end_room()
    Map.clear()

    # Fill TileMap with walls and carve out empty spaces
    var full_rect = Rect2()
    for room in $Rooms.get_children():
        var r = Rect2(room.position-room.size,
                    room.get_node("CollisionShape2D").shape.extents*2)
        full_rect = full_rect.merge(r)
    var topleft = Map.world_to_map(full_rect.position)
    var bottomright = Map.world_to_map(full_rect.end)
    for x in range(topleft.x, bottomright.x):
        for y in range(topleft.y, bottomright.y):
            Map.set_cell(x, y, 1)

    # Carve rooms and corridors
    var corridors = []  # One corridor per connection
    for room in $Rooms.get_children():
        var s = (room.size / tile_size).floor()
        var pos = Map.world_to_map(room.position)
        var ul = (room.position/tile_size).floor() - s
        for x in range(2, s.x * 2-1):
            for y in range(2, s.y * 2-1):
                Map.set_cell(ul.x+x, ul.y+y, 0)

        # Carve corridors
        var p = path.get_closest_point(Vector3(room.position.x,
                                    room.position.y, 0))
        for conn in path.get_point_connections(p):
            if not conn in corridors:
                var start = Map.world_to_map(Vector2(path.get_point_position(p).x, path.get_point_position(p).y))
                var end = Map.world_to_map(Vector2(path.get_point_position(conn).x, path.get_point_position(conn).y))
                carve_path(start, end)
        corridors.append(p)

In the first part, we’re finding the rectangle that encloses the entire map, using the Rect2 method merge(). Then we fill the entire TileMap with stone tiles.

Note: For very large and/or sparse maps, this may take a bit of time. In those cases you may prefer to start with a pre-generated “solid” map and only do the “carving” for your created rooms.

The next step is to carve the rooms and corridors. We loop through the rooms and convert their coordinates to map space (world_to_map()). Note we’re carving out the room a bit smaller than the room’s actual size. This is so that adjacent rooms will still have walls between them, rather than merging into a single large room.

Carving corridors

To make the corridors, we check the mst path and carve a path for each connection the current room has. So that we don’t carve the same path twice, we keep a list (corridors) of the ones we’ve already done.

Finally, we need to call the carve_path() function to actually make the connection:

func carve_path(pos1, pos2):
    # Carves a path between two points
    var x_diff = sign(pos2.x - pos1.x)
    var y_diff = sign(pos2.y - pos1.y)
    if x_diff == 0: x_diff = pow(-1.0, randi() % 2)
    if y_diff == 0: y_diff = pow(-1.0, randi() % 2)
    # Carve either x/y or y/x
    var x_y = pos1
    var y_x = pos2
    if (randi() % 2) > 0:
        x_y = pos2
        y_x = pos1
    for x in range(pos1.x, pos2.x, x_diff):
        Map.set_cell(x, x_y.y, 0)
        Map.set_cell(x, x_y.y+y_diff, 0)  # widen the corridor
    for y in range(pos1.y, pos2.y, y_diff):
        Map.set_cell(y_x.x, y, 0)
        Map.set_cell(y_x.x+x_diff, y, 0)  # widen the corridor

There are a few important things going on in this function. First, we calculate the direction of the x and y difference in the start and end positions. If it’s 0, we pick a random direction. This is because we’re going to carve corridors that are 2 tiles wide.

Second, we need to randomize which of two options we choose when carving the path:

Adding a Player

As the final step, we’re going to add a player-controlled character that can walk around the map. Character.tscn and Character.gd are a generic top-down KinematicBody2D character with an attached camera, which we’ll instance when the dungeon is complete.

Add the following new variables to the main script:

var Player = preload("res://Character.tscn")

var start_room = null
var end_room = null
var play_mode = false
var player = null

Uncomment find_start_room() and find_end_room() from the start of make_map() and add the following functions:

func find_start_room():
    var min_x = INF
    for room in $Rooms.get_children():
        if room.position.x < min_x:
            start_room = room
            min_x = room.position.x

func find_end_room():
    var max_x = -INF
    for room in $Rooms.get_children():
        if room.position.x > max_x:
            end_room = room
            max_x = room.position.x

These functions pick the leftmost room as the start_room and the rightmost as the end_room. By making them separate functions, you can change the criteria as you choose.

As with the map generation, we’re going to manually choose “play mode” by pressing a key (<esc> in this case). Make the following changes to _input():

func _input(event):
    # Spacebar restarts and creates a new set of rooms
    if event.is_action_pressed('ui_select'):
        if play_mode:
            player.queue_free()
            play_mode = false
        Map.clear()
        for n in $Rooms.get_children():
            n.queue_free()
        path = null
        start_room = null
        end_room = null
        make_rooms()
    # Tab generates the TileMap
    if event.is_action_pressed('ui_focus_next'):
        make_map()
    # Esc spawns a player to explore the map
    if event.is_action_pressed('ui_cancel'):
        player = Player.instance()
        add_child(player)
        player.position = start_room.position
        play_mode = true

Conclusion

That wraps up our randomly generated dungeon tutorial. We used the physics engine to distribute the rooms, learned how to use a minimum spanning tree to connect them together, and turned the whole thing into a TileMap that can be used in a game.

Obviously this dungeon is very plain and uninteresting. Decorating the dungeon and populating it with treasure, monsters, and other features is beyond the scope of this demo (but might make a great future one!).

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Procedural Generation in Godot - Part 7: Dungeons (part 2)

Sun, 09 Dec 2018 09:14:12 -0700

In this part, we’ll continue working on the random dungeon generator, adding corridors to connect the rooms.

You can watch a video version of this lesson here:

Connecting the rooms

In the last part we created a random collection of rooms, using the physics engine to ensure they are spread out and not overlapping. Now we need to figure out how to connect the rooms together.

There are many different ways to approach this, but we’re going to use the minimum spanning tree (MST) method. Given a set of points (represented as a graph), an MST identifies the minimum number of connections that connects all points with the shortest total path length.

We’ll be using Prim’s Algorithm to generate our MST. We’ll also use Godot’s AStar node to store the data, as it is a built-in graph data structure.

Start by adding a variable to store the data in:

var path  # AStar pathfinding object

Now in the make_rooms() function, as we cull the rooms, we want to create an array of the positions of the remaining rooms. We’ll pass this array to the MST algorithm.

    # cull rooms
    var room_positions = []
    for room in $Rooms.get_children():
        if randf() < cull:
            room.queue_free()
        else:
            room.mode = RigidBody2D.MODE_STATIC
            room_positions.append(Vector3(room.position.x, room.position.y, 0))
    yield(get_tree(), 'idle_frame')
    # generate spanning tree (path)
    path = find_mst(room_positions)

Now we get to where the action happens. See the comments below in the code for a summary of what’s happening. You can read the link above if you’re curious about the details of the algorithm.

func find_mst(nodes):
    # Prim's algorithm
    # Given an array of positions (nodes), generates a minimum
    # spanning tree
    # Returns an AStar object

    # Initialize the AStar and add the first point
    var path = AStar.new()
    path.add_point(path.get_available_point_id(), nodes.pop_front())

    # Repeat until no more nodes remain
    while nodes:
        var min_dist = INF  # Minimum distance found so far
        var min_p = null  # Position of that node
        var p = null  # Current position
        # Loop through the points in the path
        for p1 in path.get_points():
            p1 = path.get_point_position(p1)
            # Loop through the remaining nodes in the given array
            for p2 in nodes:
                # If the node is closer, make it the closest
                if p1.distance_to(p2) < min_dist:
                    min_dist = p1.distance_to(p2)
                    min_p = p2
                    p = p1
        # Insert the resulting node into the path and add
        # its connection
        var n = path.get_available_point_id()
        path.add_point(n, min_p)
        path.connect_points(path.get_closest_point(p), n)
        # Remove the node from the array so it isn't visited again
        nodes.erase(min_p)
    return path

Now we’ll have a path, so all that’s left is to draw it on the screen so we can see it. We’ll use CanvasItem.draw_line() to draw each connection in the AStar path.

func _draw():
    for room in $Rooms.get_children():
        draw_rect(Rect2(room.position - room.size, room.size*2),
                  Color(0, 1, 0), false)
    if path:
        for p in path.get_points():
            for c in path.get_point_connections(p):
                var pp = path.get_point_position(p)
                var cp = path.get_point_position(c)
                draw_line(Vector2(pp.x, pp.y),
                          Vector2(cp.x, cp.y),
                          Color(1, 1, 0, 1), 15, true)

Run the game and you should see a beautiful minimum spanning tree connecting your rooms!

Conclusion

We’re almost there! We have a collection of rooms and a path connecting them. The final step is to convert all of this into a TileMap so that we can actually walk around the dungeon. We’ll do that in the next part.

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Procedural Generation in Godot - Part 6: Dungeons

Tue, 04 Dec 2018 09:14:12 -0700

In this part, we’ll look at a technique for generating random dungeon maps.

You can watch a video version of this lesson here:

Introduction

For this demo, we want to randomly generate a dungeon - a series of rooms connected by corridors - that the player can explore.

There are many different ways to approach this. Some popular methods use maze generation techniques like we have discussed previously. However, for this demo, I wanted to try a different approach. In this algorithm, we take advantage of Godot’s built-in physics engine to create the map.

Broadly speaking, we’ll break this up into three steps:

Generate the rooms
Find a “path” connecting the rooms
Create a TileMap to use in game

You can download the starting project which contains the minimal art assets we’ll use for this demo.

Generating Rooms

Because we’re going to use the physics engine to generate the basic layout of the dungeon, we’ll need to do a little bit of setup first. Let’s start by defining what we mean by a “room”.

Room object

A “room” in this context is a rectangular space, typically large enough for the player to walk around in and/or contain objects of interest like treasures or mobs. We’ll use a RigidBody2D to represent a room (remember, we’re going to be using physics here). Create a new scene with a RigidBody2D named “Room” and a CollisionShape2D child (but don’t add a shape to it yet). Attach a script to the
Room.

extends RigidBody2D

var size

func make_room(_pos, _size):
    position = _pos
    size = _size
    var s = RectangleShape2D.new()
    s.extents = size
    $CollisionShape2D.shape = s

In this script, we have a size property, which we will be able to randomize. It’s then used in make_room() to generate a RectangleShape2D for collision.

Make sure to set Default Gravity to 0 in the “Physics/2d” section of Project Settings. Also, in the Inspector, set the Mode of the Room to “Character”. This will ensure that the rooms can’t rotate.

Main scene

Now, let’s make a “Main” scene using a Node2D. Give it a Node child called “Rooms”, which will act as a container. Attach a script:

extends Node2D

var Room = preload("res://Room.tscn")

var tile_size = 32  # size of a tile in the TileMap
var num_rooms = 50  # number of rooms to generate
var min_size = 4  # minimum room size (in tiles)
var max_size = 10  # maximum room size (in tiles)

Here are our main input properties for the dungeon.

In _ready() we need to initialize the random number generator and then call our function to create the rooms:

func _ready():
    randomize()
    make_rooms()

The make_rooms() function is going to use our parameters to create the randomly sized rooms. For now, we’ll put them all at (0, 0):

func make_rooms():
    for i in range(num_rooms):
        var pos = Vector2(0, 0)
        var r = Room.instance()
        var w = min_size + randi() % (max_size - min_size)
        var h = min_size + randi() % (max_size - min_size)
        r.make_room(pos, Vector2(w, h) * tile_size)
        $Rooms.add_child(r)

Visualization

If you run the scene, you won’t be able to see anything on the screen. Try turning on “Visible Collision Shapes” from the “Debug” menu.

We can see the shapes, but they’re much larger than the screen. Add a Camera2D to the scene. Change its Zoom to (10, 10) and Current to “On”. Now you should be able to see most of the rooms as they sort themselves out.

It would be more convenient to draw the outlines rather than using the debug option (so turn that back off). Add this code to draw our room outlines:

func _draw():
    for room in $Rooms.get_children():
        draw_rect(Rect2(room.position - room.size, room.size*2),
                Color(32, 228, 0), false)

func _process(delta):
    update()

Let’s also add a way to redraw without starting the program all over again:

func _input(event):
    if event.is_action_pressed('ui_select'):
        for n in $Rooms.get_children():
            n.queue_free()
        make_rooms()

Now you can press the spacebar to generate a new set of rooms:

Room Adjustments

Now we can make a couple of adjustments to how the rooms are being generated. First, since they’re all starting from the same place you may end up with a “tall” or “wide” dungeon. That may be fine with you, but in some games, it may make more sense if the player travels horizontally more than vertically. Here’s how we can influence that:

Add this variable to Main:

var hspread = 400  # horizontal spread

Then, in make_rooms() change the position code to this:

var pos = Vector2(rand_range(-hspread, hspread), 0)

The larger you make this value, the more horizontally spread out the rooms will be.

Secondly, you may notice that it takes some time for the rooms to stop moving as they settle into their final locations. We can influence that by adding the following line to the make_room() function in Room.gd:

s.custom_solver_bias = 0.75

Culling rooms

Finally, we want to be able to remove some rooms to make the dungeon more or less “sparse”. For this, we’ll add another input parameter:

var cull = 0.4 # chance to cull room

And update make_rooms() like so:

func make_rooms():
    for i in range(num_rooms):
        var pos = Vector2(rand_range(-hspread, hspread), 0)
        var r = Room.instance()
        var w = min_size + randi() % (max_size - min_size)
        var h = min_size + randi() % (max_size - min_size)
        r.make_room(pos, Vector2(w, h) * tile_size)
        $Rooms.add_child(r)
    # wait for movement to stop
    yield(get_tree().create_timer(1.1), 'timeout')
    # cull rooms
    for room in $Rooms.get_children():
        if randf() < cull:
            room.queue_free()
        else:
            room.mode = RigidBody2D.MODE_STATIC

Note the use of yield() here. We need to wait until the physics engine has finished separating the rooms before we start removing them. The ones that are left can now be set to MODE_STATIC so they will no longer move at all.

Conclusion

We’ll stop here, as this is getting a bit long-winded - remember we said there were 3 main parts? In the next installment, we’ll look at how to connect the rooms together.

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Procedural Generation in Godot - Part 3: Tile-based Infinite Worlds

Mon, 24 Sep 2018 09:14:12 PDT

In the previous parts we looked at using maze generation algorithms. In this part, we’ll look at some other ways to generate a tile-based world.

You can watch a video version of this lesson here:

Project setup

In the starting project download you’ll find all the scenes and resources you’ll need to build the project below. Let’s review them briefly.

For this example, we’ll use an isometric TileMap using the Kenney road textures we used in the previous projects.

Note that this procedure will work in exactly the same way if you’re using standard orthogonal tiles.

Player Vehicle

We also have a scene for the vehicle the player will control (Truck.tscn).

Here’s a quick overview of how the truck is set up. An AnimatedSprite contains frames for each of the facing directions, and we’ll use a Tween to perform the movement from tile-to-tile.

First, the variables we’ll need - mapping the directions to the matching animations and direction vectors.

extends Area2D

const N = 0x1
const E = 0x2
const S = 0x4
const W = 0x8

var animations = {N: 'n',
                  S: 's',
                  E: 'e',
                  W: 'w'}
var moves = {N: Vector2(0, -1),
             S: Vector2(0, 1),
             E: Vector2(1, 0),
             W: Vector2(-1, 0)}

var map = null
var map_pos = Vector2()
var speed = 1 # time in seconds
var moving = false

Now we can capture the user’s input (arrow keys). Note that our movement vectors are orthogonal (ie (0, 1)) even though we’re on an isometric map. That’s because we’re only concerned with our tile position, not our screen position.

func _input(event):
    if moving:
        return
    if event.is_action_pressed('ui_up'):
        move(N)
    if event.is_action_pressed('ui_down'):
        move(S)
    if event.is_action_pressed('ui_right'):
        move(E)
    if event.is_action_pressed('ui_left'):
        move(W)

Next, we need a function to test if the move is possible. This will return true if the move is legal:

func can_move(dir):
    var t = map.get_cellv(map_pos)
    # if there's a wall in the desired direction, no move
    if t & dir:
        return false
    else:
        return true

Finally, we have the move() function itself. We use the map_to_world() function to let the TileMap handle the translation from map position to screen position.

If the tile we’re moving into has a value of -1 that means it’s unexplored. In that case we tell the map to fill that tile using generate_tile() which we’ll define in the next section.

Connect the Tween’s tween_completed signal so that the player will know it’s ok to move again.

func move(dir):
    if not can_move(dir):
        return
    moving = true
    $AnimatedSprite.play(animations[dir])
    map_pos += moves[dir]
    if map.get_cellv(map_pos) == -1:
        get_parent().generate_tile(map_pos)
    var destination = map.map_to_world(map_pos) + Vector2(0, 20)
    $Tween.interpolate_property(self, 'position', position, destination, speed,
                                Tween.TRANS_QUAD, Tween.EASE_IN_OUT)
    $Tween.start()

func _on_Tween_tween_completed(object, key):
    moving = false

TileMap Scene

In this scene we have a TileMap node and an instance of the Truck.

extends Node2D

const N = 0x1
const E = 0x2
const S = 0x4
const W = 0x8

var cell_walls = {Vector2(0, -1): N, Vector2(1, 0): E,
                  Vector2(0, 1): S, Vector2(-1, 0): W}

onready var Map = $TileMap

First, we’ll initialize the Truck by passing it a reference to the TileMap node and setting its position to the (0, 0) tile.

The generate_tile() function is called by the truck when it moves into an empty tile.

func _ready():
        $Truck.map = Map
        $Truck.map_pos = Vector2(0, 0)
        $Truck.position = Map.map_to_world($Truck.map_pos) + Vector2(0, 20)

func generate_tile(cell):
        var cells = find_valid_tiles(cell)
        Map.set_cellv(cell, cells[randi() % cells.size()])

Here’s where the magic happens. We need to try each tile from the set, checking its walls against each of the target space’s neighbors. Any mismatch we find means the tile is discarded. Any tiles that don’t conflict are added to the valid_tiles array to be returned.

func find_valid_tiles(cell):
    var valid_tiles = []
    # check all possible tiles, 0 - 15
    for i in range(16):
        # check the target space's neighbors (if they exist)
        var is_match = false
        for n in cell_walls.keys():
            var neighbor_id = Map.get_cellv(cell + n)
            if neighbor_id >= 0:
                # id == -1 is a blank tile
                if (neighbor_id & cell_walls[-n])/cell_walls[-n] == (i & cell_walls[n])/cell_walls[n]:
                    is_match = true
                else:
                    is_match = false
                    # if we found a mismatch, we don't need to check the remaining sides
                    break
        if is_match and not i in valid_tiles:
            valid_tiles.append(i)
    return valid_tiles

Comparing walls

In reading the code above, you may find be confused by the wall comparison, specifically the division: i & cell_walls[n])/cell_walls[n]. This is necessary because of the way the & (bitwise and) operator works.

Say we have tile #15 (all walls solid). We can check if the E wall is there by using 15 & E which returns 1. However, if we are checking the S wall we use 15 & S which gives 2. Similarly, 15 & W == 4 and 15 % N == 8. This is fine if we are just checking for the wall’s presence - the result is either 0 or a number.

However, if we’re comparing two tiles for compatibility, we need to check the opposite walls:

In this case we need to see if the E wall of tile “7” matches the W wall of tile “11”. 7 & E is 2 while 11 & W is 4. These values are not equal, but if we divide each result by the wall value itself, we’ll “normalize” them to 1:

(7 & E) / E == (11 & W) / W

Run the project and you can explore in any direction, expanding the world as you go.

Conclusion

Now that we have the basic functionality of our tile-exploration map, there are many things we could do to build on top of it. In the next video we’ll look at ways to expand it, as well as some of the issues to watch out for when using this technique.

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Procedural Generation in Godot - Part 2: Using Mazes

Mon, 10 Sep 2018 09:14:12 PDT

In the previous part we explored how to generate a random maze using Godot’s TileMap node. In this part, we’ll look at some ways to use these mazes in your game projects.

You can watch a video version of this lesson here:

Maze applications

In the sections below, we’ll be using the project we built in part 1. You can download the project here.

Note: many of the following features can be combined for even more variety and effect. If you do so, it’s likely that they can be coded in a much more efficient way, but I’ve chosen to demonstrate them separately for clarity.

On random seeds

While using random generation guarantees you’ll get a unique maze every time you run the game, there are times when you want to be able to also get repeatable results. By using the same seed for the random number generator, you can ensure you’ll get the same sequence of “random” numbers every time.

Here is a brief example of how to do this. Add the following to the maze script:

var map_seed = 0

func _ready():
    randomize()
    if !map_seed:
        map_seed = randi()
    seed(map_seed)
    print("Seed: ", map_seed)
    tile_size = Map.cell_size
    make_maze()

Here, we are creating a variable to store the seed for our map. Setting this to 0 indicates we want a random seed. When you run, you’ll see printed a value something like 111556094. If you make this number your seed, you’ll always get the same map.

Games such as Minecraft use this technique to allow users to share their randomly generated worlds. They only need to share a single number, their map’s seed, and no matter how far they explore the vast, generated world, both players’ worlds will match.

If you want to use something like this in your game, you can save the seed value as part of your game’s save file.

Adding loops

The recursive backtracker algorithm we’re using creates “perfect” mazes - meaning there are no loops and only one path between any two points in the maze. However, you might want the map to feel more “natural”, and add more connections allowing the player to explore different paths through the map.

To do this, after the maze generation is complete, we randomly go through the map and remove walls. Depending on how many walls you remove, you can get just a few extra connections, or an almost fully connected grid.

Call this function after the maze generation finishes:

var erase_fraction = 0.2  # amount of wall removal

func erase_walls():
    # randomly remove a percentage of the map's walls
    for i in range(int(width * height * erase_fraction)):
        # pick a random tile not on the edge
        var x = int(rand_range(1, width-1))
        var y = int(rand_range(1, height-1))
        var cell = Vector2(x, y)
        # pick a random neighbor
        var neighbor = cell_walls.keys()[randi() % cell_walls.size()]
        # if there's a wall between cell and neighbor, remove it
        if Map.get_cellv(cell) & cell_walls[neighbor]:
            var walls = Map.get_cellv(cell) - cell_walls[neighbor]
            var n_walls = Map.get_cellv(cell+neighbor) - cell_walls[-neighbor]
            Map.set_cellv(cell, walls)
            Map.set_cellv(cell+neighbor, n_walls)

Spacing out the path

Since we’re using roads, a natural extension would be to also generate decorations, buildings, and other objects in the green areas. However, our maze generating algorithm explores every tile and makes it part of the path. This means that there is not much space between adjacent roads. Let’s space out the road tiles so that there are empty tiles between them.

To begin, we change the cell_walls dictionary to indicate that each cell’s neighbors should be considered 2 spaces apart.

var cell_walls = {Vector2(0, -2): N, Vector2(2, 0): E,
                  Vector2(0, 2): S, Vector2(-2, 0): W}

In the maze generator, we also need to make sure we only count the even-numbered tiles or else our unvisited list will never be completed. Change the code at the start of the make_maze() function as follows:

    for x in range(width):
        for y in range(height):
            Map.set_cellv(Vector2(x, y), N|E|S|W)
    for x in range(0, width, 2):
        for y in range(0, height, 2):
            unvisited.append(Vector2(x, y))

If we only do this, the map is generated every two spaces, like so:

To keep the path continuous, whenever we remove the wall to a new adjacent cell, we need to include either a vertical or horizontal tile (tiles 10 and 5 ) between them.

if dir.x != 0:
    Map.set_cellv(current + dir/2, 5)  # vertical road
else:
    Map.set_cellv(current + dir/2, 10)  # horizontal road

Now our path is continuous again, and we have more green space available to place features such as trees, rocks, buildings, etc.

If you’re also using the erase_walls() function above, you’ll need to modify it to insert the “in-between” tiles as well:

# insert intermediate cell
if neighbor.x != 0:
    Map.set_cellv(cell+neighbor/2, 5)
else:
    Map.set_cellv(cell+neighbor/2, 10)

To be more flexible, you could generalize this process to use a spacing variable, which would allow you to create your map with an arbitrary number of spaces between paths.

Isometric

One of the coolest things about using this TileMap method to store the map data is that it is independent of the map type (orthogonal or isometric). An isometric version of the road tiles looks like this:

For an isometric map, you only need to change the Mode to “Isometric”, replace the TileSet with the one above (res://iso_roads.tres in the start project), and set the cell_size to (100, 50) and the map will be generated in the same way:

In the next part, we’ll explore mazes a bit further by generating some decorations and other features, as well as make a simple maze-navigation game using our maze generator.

Conclusion

This was just an introduction to the many possibile uses of maze generation in your game projects. In many cases, a maze generator such as the one(s) we’ve explored here is just the start of your content generation. For example, you might be making a dungeon by arranging a set of rooms, and then use the maze generator to fill in the “gaps” between the rooms with twisty corridors. You may see this technique appear again in later installments.

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Procedural Generation in Godot - Part 1: Mazes

Tue, 28 Aug 2018 09:14:12 PDT

You can watch a video version of this lesson here:

What is Procedural Generation?

In game development, procedural generation (“procgen” for short) is a method of creating game content via automated, rather than manual, means. In practice, it can cover a wide range of applications, from simple: such as random mazes or character names, to more complex: dungeons (including keys, locks, bosses, etc.) or spaceships, to the ultra-complex: like Dwarf Fortress, where everything in the world is generated - environmental and cultural history, weather, biology, personality traits, and much, much more.

If you don’t know about Dwarf Fortress, I highly recommend checking it out. Even if you don’t play the game - and the learning curve is tough - it can be fascinating and entertaining to read about. Start here

You can learn a lot about procgen and its applications at the Procedural Generation Wiki.

For this series, we’ll start by looking at one of the most popular applications of procgen: mazes. Maze generation is a well-explored area, and there are many algorithms you can use, depending on the type of maze you need.

You can read an overview of maze generation here:

Wikipedia: Maze Generation Algorithm

Making mazes

For this part, we’ll use the “Recursive Backtracker” algorithm. This is also known as “depth-first search”, and is one of the easiest maze algorithms to implement.

It works by exploring a grid (technically it works on a graph, which doesn’t have to be grid-shaped, but for this demo we’ll stick to a standard square grid) cell-by-cell, connecting each cell, but never crossing over.. In mathematical terms, it produces a spanning tree, meaning there are no loops and only one path from any one point to another.

The algorithm

The recursive backtracker algorithm works like this:

Set all cell walls to solid and mark each cell unvisited
Pick a starting cell and mark it visited
If any neighboring cell has not been visited
1. Pick a random neighboring cell that has not yet been visited
2. Remove the wall between the two cells
3. Add the current cell to the stack
4. Make the chosen cell the current cell and mark it visited
If the current cell has no unvisited neighbors, take the top cell from the stack and make it current
Repeat from #3 until there are no more unvisited cells

Data representation

First we need to decide how to represent the maze data. We’ll be using a Godot’s TileMap node which, like our maze itself, will be based on a grid. Each cell of the grid has four walls, which can be either open or closed:

With two states (open or closed), we can use a single bit to represent the state of each wall: 0 for open and 1 for closed. That means that a 4-bit (i.e. 4 digit) number can represent any given cell. We can do this in any order, but I’m going to use the order WSEN. So a cell with walls 1001 (9 in decimal) for example, would mean the N and W walls are present.

As a result, we can use the decimal numbers 0-15 to represent all of the possible cell configurations, and therefore all of the possible tiles:

A tile can be placed next to any tile that has the matching side value. This means you can use any tileset that matches this arrangement. For this demo I’ll be using Kenney’s Road Textures pack, which contains the following tiles following our pattern:

If we make these into a TileSet in Godot, with the tile id matching the wall pattern, we can use the TileMap data to record our maze data as well. This is really nice, because we won’t need a separate data structure to store information about the walls.

Download the Starting Project.

When you download the starting project, you’ll find I’ve created a TileSet for the 16 tiles we need, along with collision polygons for the walls (green areas). The filename for the TileSet resource is road_tiles.tres.

For the starting scene setup, we need a parent Node2D and a TileMap:

The script

A lot of the code we need for this project is very generic: it can apply to many similar types of problems. Keep that in mind as we move forward - what other applications of these algorithms can you think of?

extends Node2D

const N = 1
const E = 2
const S = 4
const W = 8

var cell_walls = {Vector2(1, 0): E, Vector2(-1, 0): W,
                  Vector2(0, 1): S, Vector2(0, -1): N}

We start by defining the four direction values for our tiles. Assigning them to the compass direction names isn’t strictly necessary, but makes it easier to reference them. You can see that in the cell_walls dictionary, where we establish the relationship between the direction vectors and the walls’ values.

Next, we have a few parameters to define:

var tile_size = 64  # tile size (in pixels)
var width = 25  # width of map (in tiles)
var height = 15  # height of map (in tiles)

# get a reference to the map for convenience
onready var Map = $TileMap

The _ready() function is fairly self-explanatory:

func _ready():
    randomize()
    tile_size = Map.cell_size
    make_maze()

Before we can generate the maze, we’re going to need a helper function that, given a cell, returns a list of its unvisited neighbors:

func check_neighbors(cell, unvisited):
    # returns an array of cell's unvisited neighbors
    var list = []
    for n in cell_walls.keys():
        if cell + n in unvisited:
            list.append(cell + n)
    return list

Now, on to our make_maze() function, where the magic happens:

func make_maze():
    var unvisited = []  # array of unvisited tiles
    var stack = []
    # fill the map with solid tiles
    Map.clear()
    for x in range(width):
        for y in range(height):
            unvisited.append(Vector2(x, y))
            Map.set_cellv(Vector2(x, y), N|E|S|W)
    var current = Vector2(0, 0)
    unvisited.erase(current)

First, we’re initializing the map and the variables we’ll need to keep track of unvisited tiles and the stack of tiles to process.

Note: GDScript doesn’t have an actual stack data type, but an Array will work just fine, as long as we use append() to add items to the end and pop_back() to remove them from the same end.

Then we loop through the map setting all of its tiles to solid ones (N|E|S|W) and adding each cell to the unvisited list. We’re using the top-left corner as the start tile, but you can start anywhere in the grid.

NOTE: The | symbol in GDScript (as in many languages) indicates bitwise OR. Combining the four direction values with | results in 1111 (decimal: 15), or our value for a tile with all four walls present.

A full explanation of bitwise operations is beyond the scope of this tutorial, but you can find out more here: Wikipedia: Bitwise operation

Now we can implement the algorithm:

while unvisited:
    var neighbors = check_neighbors(current, unvisited)
    if neighbors.size() > 0:
        var next = neighbors[randi() % neighbors.size()]
        stack.append(current)
        # remove walls from *both* cells
        var dir = next - current
        var current_walls = Map.get_cellv(current) - cell_walls[dir]
        var next_walls = Map.get_cellv(next) - cell_walls[-dir]
        Map.set_cellv(current, current_walls)
        Map.set_cellv(next, next_walls)
        current = next
        unvisited.erase(current)
    elif stack:
        current = stack.pop_back()

If you run this, you should see the map filled out with a nice branching path. If you want to see the process happen more slowly, add this line at the end of the while loop:

yield(get_tree(), 'idle_frame')

Pick two random tiles, one for “start” and one for “end”, and you have a solvable maze!

Conclusion

Now that we have a working maze generator, there are a lot of things we can do with it. In the next part, we’ll discuss some variations we can make to this algorithm, as well as some examples of using the maze in a project.

Please comment below with your questions and suggestions.

Download the code for this lesson

Helpful Links

Topdown Tank Battle: Part 11

Mon, 20 Aug 2018 14:14:12 PDT

In this tutorial series, we’ll walk through the steps of building a 2D top-down tank game using Godot 3.0. The goal of the series is to introduce you to Godot’s workflow and show you various techniques that you can apply to your own projects.

This is Part 11: Pickup items

You can watch a video version of this lesson here:

Introduction

In this installment, we’re going to create a “pickup” item: something the player can grab to provide them with healing/repairs, ammo, powerups, etc. To begin with, we’ll make a healing pickup, since we already have tank damage working.

Pickup scene

For the pickup object, we’ll use an Area2D node, with a Sprite and CollisionShape2D attached. I’ve chosen this crate image from the spritesheet:

Add a circular collision shape, sized to extend just past the edges of the crate. We don’t want enemy tanks to accidentally collect the pickups, so uncheck all of the Collision Layers and set the Collision Mask to “player”.

Now add a script:

extends Area2D

enum Items {health, ammo}

export (Items) var type = Items.health
export (Vector2) var amount = Vector2(10, 25)

In the enum we have a list of the pickup types we want to implement. Then we have a Vector2 representing the min/max value we want the pickup to supply. We’ll pick a random value in this range.

Attach the body_entered signal:

func _on_Pickup_body_entered(body):
    match type:
        Items.health:
            if body.has_method('heal'):
                print("healing")
                body.heal(int(rand_range(amount.x, amount.y)))
        Items.ammo:
            pass
    queue_free()

In this function, we’ll check the type, and apply healing if the player has a heal method (right now it doesn’t).

Instance one of these items in the map scene and verify that you can pick it up.

Juicing the crate

The crate works, but it’s pretty boring to look at. It’s hard for the player to tell the crate apart from other obstacles that may be on the map. To make it stand out a bit, we’re going to add some animation effects to “juice” up the crate.

Add an AnimationPlayer to the Pickup scene.

Bouncing animation

First, we’re going to make the crate bounce up and down a bit. Create a new animation called “bounce” and set it to Autoplay and Loop.

Click on the Sprite and add a keyframe for its Transform/Position property (which should be (0, 0) at this point). Then move the scrubber to 0.5, change the position to (0, -20), and add another keyframe.

Press the Play button and you will see the crate bounce up and down. However, it’s very linear and doesn’t look very bouncy. In the timeline, click on the dot for the first keyframe, then select the “edit keyframe” button. This will let you change the “Transition” curve of the keyframe. I selected a sine curve and adjusted it as shown (you can drag the line with the mouse, or click and type the -1.5 directly):

The bounce should look smoother at the ends now.

Drop shadow

We can also give a sense of depth by adding a drop shadow to the crate. Add another Sprite named “Shadow” and use the shadow texture:

Set the shadow’s Position to (0, 25) and its scale to (.25, .5). Add the scale as a new track in the “bounce” animation, then move the scrubber to 0.5 and keyframe the scale at ²⁄₃ (you can type (0.25/1.5, 0.5/1.5) in the Inspector and it will do the math).

We also want to animate the opacity of the shadow, as it’s a bit too dark, so put the scrubber back at the start and keyframe the Self Modulate with an alpha of a little over 50%. Then at the halfway point of the animation, key the alpha at around 25%. You should see a nice fading/shrinking effect on the shadow:

Icon

The last thing we need to add to the crate is a way to indicate what type of crate it is. The player needs to be able to see it and tell that it’s a repair crate.

Add another Sprite called “Icon” and use the wrench texture from the assets folder:

Move the Position to (0, -85) and Scale to (0.7, 0.7). Then we’re going to animate its scale and opacity. At the start of the animation track, keyframe both the Scale and Self Modulate properties. Then, at the end of the track, key them at values of (0.5, 0.5) and alpha of 0 respectively.

Finally, in the Modulate property, choose a nice bright shade of green. The result will be a flashing green wrench icon making it clear that this is a repair crate.

Conclusion

We’ve added some very simple effects to the pickup crate. In a later installment, we might get fancier with some shader effects and a repair animation on the tank itself.

That completes Part 11 of this series. For coming features and ideas, I’ve created a project tracker, which you can see here:

Topdown Tanks Project Tracker

Please comment below with your questions and suggestions.

Download the code for this part

Helpful Links

Topdown Tank Battle: Part 10

Sat, 04 Aug 2018 14:14:12 PDT

This is Part 10: Homing missiles

You can watch a video version of this lesson here:

Introduction

This time, we’re going to build on the existing bullet object to create a heat- seeking missile. We’ll also adjust the shooting code to allow for multiple shots in a spread.

Adjusting the Bullet script

We’re going to start by adding the homing functionality to the existing bullet script. First, we’ll adding some new variables:

export (float) var steer_force = 0

var acceleration = Vector2()
var target = null

steer_force represents the missile’s agility - how quickly it can turn and chase its target. A value of 0 will be a regular bullet that travels in a straight line.

When the missile spawns, we can pass it a target, but we want to be able to ignore that when spawning “dumb” bullets, so adjust the start() function like so:

func start(_position, _direction, _target=null):
    position = _position
    rotation = _direction.angle()
    velocity = _direction * speed
    target = _target

Next, in the _process() function, we need to apply a seeking behavior if there is a target assigned:

func _process(delta):
    if target:
        acceleration += seek()
        velocity += acceleration * delta
        velocity = velocity.clamped(speed)
        rotation = velocity.angle()
    position += velocity * delta

We’ll find our needed acceleration via the seek() function (more about that in a moment), and apply that to the current velocity. We also need to clamp the velocity so that when heading straight for the target, the missile doesn’t continue to accelerate above the maxiumum speed. Finally, we set the rotation so that the missile will point in the direction of motion.

Seeking behavior

“Steering behaviors” is the collective name for a number of algorithms that produce movement such as seeking, following, flocking, etc. If you’re not familiar with the topic, I highly recommend reading The Nature of Code, which has a fantastic chapter on the subject, along with interactive demos.

For our missile, we will be using the “seek” behavior:

func seek():
    var desired = (target.position - position).normalized() * speed
    var steer = (desired - velocity).normalized() * steer_force
    return steer

This works by first finding the desired movement vector, which is straight towards the target at maximum speed. However, to avoid “instant” turning, we then calculate the steer vector by finding the difference between the current velocity and the desired one. The “amount” we move our velocity (i.e. accelerate) is that difference scaled by the steer_force. The result: the bigger the steer_force, the faster the object turns to move towards its target.

Missile scene

The missile scene is an inherited scene created from Bullet.tscn. I’ve chosen the following image from the spritesheet for the missile:

Set its speed to 400 and steer_force to 25 in the Inspector and save the scene. Drop it in to the Bullet property of one of the enemy tanks in your map scene.

Launching missiles

If you ran it now, your missiles would still travel in a straight line, because they’re not getting the target value from the enemy. Update the shooting line in EnemyTank.gd to pass this data (the enemy already has the player set as its target):

shoot(target)

Now update the base Tank.gd script to pass this data along to the missile when it spawns:

func shoot(target=null):
    if can_shoot:
        can_shoot = false
        $GunTimer.start()
        var dir = Vector2(1, 0).rotated($Turret.global_rotation)
        emit_signal('shoot', Bullet, $Turret/Muzzle.global_position, dir, target)
        $AnimationPlayer.play('muzzle_flash')

Finally, the Map.gd script, when it receives the signal, needs to pass the target to the missile:

func _on_Tank_shoot(bullet, _position, _direction, _target=null):
    var b = bullet.instance()
    add_child(b)
    b.start(_position, _direction, _target)

Try running the scene and testing that the missiles seek the player. Try changing the steer_force and speed (and the missile’s lifetime) properties to see how they affect the missile’s behavior.

Missile trail

To make the missile look more appealing, we’re going to add a smoke trail. Add a Particles2D node to the missile scene. Particles nodes have a large number of properties, so I’ll list the adjustments in the table below:

Property	Value
Amount	`35`
Lifetime	`0.4`
Visibility/Show Behind Parent	`On`
RayCastUp	`(0, -32)`

For the texture, I found the following smoke animation on Open Game Art:

Add this to the Texture property and set the HFrames to 24.

Now add a new ParticlesMaterial in the Process Material property and set its values like so:

Property	Value
Gravity	`(0, 0, 0)`
Initial Velocity	`0`
Animation/Speed	`1`

Finally, in the Scale section, add a new Scale Curve and set its endpoints like the picture below:

This will make the smoke grow gradually larger as it dissipates.

The missiles should now have a pleasing smoke trail:

Multi-shot

One more improvement we can make to shooting: multi-shot. This will allow us to have an enemy (or player) shoot multiple shots at once in a spread.

Start by adding two more new properties to Tank.gd:

export (int) var gun_shots = 1 # number of projectiles per shot
export (float, 0, 1.5) var gun_spread = 0.2 # angle between them

Once more, we need to update the shoot() function:

func shoot(num, spread, target=null):
    if can_shoot:
        can_shoot = false
        $GunTimer.start()
        var dir = Vector2(1, 0).rotated($Turret.global_rotation)
        if num > 1:
            for i in range(num):
                var a = -spread + i * (2*spread)/(num-1)
                emit_signal('shoot', Bullet, $Turret/Muzzle.global_position, dir.rotated(a), target)
        else:
            emit_signal('shoot', Bullet, $Turret/Muzzle.global_position, dir, target)
        $AnimationPlayer.play('muzzle_flash')

If the number of shots is 1, we can just do as we already are doing. However, if the number is greater, we need a counting loop to generate each one and set its angle based on the spread. Calculating that angle (a) is complicated by the fact that num may be even or odd. If it’s odd, we want the center shot to go forward, and the others to its left and right. Howevef, if num is even, there is no center bullet, so we need an equal number to the left and right. The a formula will calculate that for us.

Now our player and enemy tanks need to pass these properties when they call shoot:

EnemyTank.gd:

if target_dir.dot(current_dir) > 0.9:
    shoot(gun_shots, gun_spread, target)

Player.gd:

if Input.is_action_just_pressed('click'):
    shoot(gun_shots, gun_spread)

Conclusion

That completes Part 10 of this series. For coming features and ideas, I’ve created a project tracker, which you can see here:

Topdown Tanks Project Tracker

Please comment below with your questions and suggestions.

Download the code for this part

Helpful Links

Godot 3.0: Splitscreen Demo (Using Viewports)

Tue, 10 Jul 2018 08:12:12 PDT

Introduction

In this demo, we’ll consider a local multiplayer game - a topdown-style maze game with two players (one using arrow keys and the other using WASD controls). This is not a problem if our game world all fits on one screen, but if the map is large, we’ll want to have a “split screen” view tracking the two players separately.

We’ll also look at a quick way to set up a minimap display.

You can watch a video version of this tutorial here:

Game setup

We won’t spend a lot of time on the setup of the game world. The two players are KinematicBody2D objects using no-frills 8-way movement.

If you need help setting up this part, see the following section in the official Godot docs: 2D Movement Overview

Each player has its input actions set up in the Project Settings -> Input Map section: “right_1” to Right Arrow, “right_2” to D, etc. Note that by naming them this way, we can save time in the code by using:

export var id = 0

func get_input():
    velocity = Vector2()
    if Input.is_action_pressed('right_%s' % id):
        velocity.x += 1
    # etc.

This way both characters can use the same script for movement. Just assign the appropriate value to id for each player.

The two players are added to a “World” scene containing a TileMap:

If you like, you can download the starting project, with the world already set up, here:

splitscreen_start.zip

Note that the map is much larger than the game screen, but aside from that everything works as intended. Setting up your game “world” separately like this will make setting up the viewports much easier and more flexible.

Viewports, Cameras, and Worlds

We’re going to start with a new scene that’s going to contain our two viewports. Create a node to serve as the root. I like to use Node since it has no properties of its own - it’s just there to contain the rest of the scene.

By themselves, Viewport nodes don’t have position information (they don’t inherit from Spatial or CanvasItem). We’re going to use ViewportContainer, a Control node, to hold each viewport. To keep them arranged side-by-side, we’ll use an HBoxContainer.

Set the HBoxContainer’s Alignment to “Center” and to have a small gap between the two viewports, set Custom Constants/Separation to 5. In the “Layout” menu, choose “Full Rect”.

Now add two ViewportContainers as children, naming them with a 2 and 1 (to match the player they’ll display). Set the Size Flags on both to “Fill, Expand” so that they will each expand to fill half of the screen. Also, check the Stretch property so that the Viewport will automatically be set to the size of the container.

Inside each of these containers add a Viewport. Note that if you set the viewport’s Size property, it will be reset by the container.

In order for a Viewport to display anything, we’ll need a Camera2D which will render onto the Viewport. Add one to each viewport. Don’t forget to check the Current property to activate the camera. We can also set each camera’s Zoom to (0.75, 0.75) to get a better view of the area around the player.

Your node setup should look like this:

 ┖╴Main (Node)
    ┖╴Viewports (HBoxContainer)
       ┠╴ViewportContainer2
       ┃  ┖╴Viewport2
       ┃    ┖╴Camera2D
       ┖╴ViewportContainer1
          ┖╴Viewport1
            ┖╴Camera2D

Note that we’ve put ViewportContainer1 second in the HBoxContainer. This will place it on the right side since Player 1 uses the arrow keys.

Adding the World

When we run the scene we won’t see anything because the viewports don’t have any “world” to render. A viewport’s world (for 3D) or world_2d property represent the source for the viewport’s environment and determine what will be rendered by its camera. The world can be set in code, but for 2D it will also display any child 2D nodes we add to it.

Let’s instance the “World” scene as a child of Viewport1. Now when we play the scene we see the world inside the left viewport.

We also need to add a world to Viewport2, but we want it to use the same one. We can handle this in code. Attach a script to Main and add the following:

extends Node

onready var viewport1 = $Viewports/ViewportContainer1/Viewport1
onready var viewport2 = $Viewports/ViewportContainer2/Viewport2
onready var camera1 = $Viewports/ViewportContainer1/Viewport1/Camera2D
onready var camera2 = $Viewports/ViewportContainer2/Viewport2/Camera2D
onready var world = $Viewports/ViewportContainer1/Viewport1/World

func _ready():
    viewport2.world_2d = viewport1.world_2d

The onready node references are for convenience - we’ll be using them as we move forward. Remember that when you type “$” Godot will autosuggest node paths so you don’t have to type them. You can also drag a node from the scene tree into the script editor and you’ll get the node’s path.

When we run the scene now, we see the world rendered in both viewports. However, neither camera is moving so we only see a small part of the world.

Setting up the cameras

Attach the following script to each camera:

extends Camera2D

var target = null

func _physics_process(delta):
    if target:
        position = target.position

Now we can assign a target to each camera and it will follow that node’s position. We’ll do that in the Main script:

func _ready():
    viewport2.world_2d = viewport1.world_2d
    camera1.target = world.get_node("Player_1")
    camera2.target = world.get_node("Player_2")

When we run the scene now, each player is centered in its viewport and our splitscreen setup works!

Note: I find it looks best if you disable the Drag Margin properties of the cameras.

Camera limits

Next, let’s add some limits to the player cameras so that they don’t scroll outside the bounds of the map. Add this function to the main script and call it in _ready():

func set_camera_limits():
    var map_limits = world.get_used_rect()
    var map_cellsize = world.cell_size
    for cam in [camera1, camera2]:
        cam.limit_left = map_limits.position.x * map_cellsize.x
        cam.limit_right = map_limits.end.x * map_cellsize.x
        cam.limit_top = map_limits.position.y * map_cellsize.y
        cam.limit_bottom = map_limits.end.y * map_cellsize.y

Minimap

Let’s add one more fun feature: a minimap showing a zoomed-out view of the entire map so the players can orient themselves.

We’ll need another ViewportContainer, this one a child of Main. This time, we don’t want to use Stretch. Add a Viewport and set its Size to (340, 200) then add a Camera2D. We’ll set the Camera2D’s Position to (512, 300) to center it on the screen. We’ll zoom out by setting Zoom to (9, 9). Don’t forget to click Current on this camera as well.

In the _ready(), set the minimap to use the same world as the other two viewports:

$Minimap/Viewport.world_2d = viewport1.world_2d

Use the “Layout” menu to align the Minimap container at “Center Bottom”. Let’s see what it looks like:

We need to get rid of that grey area around the edges. We could find the precise zoom level that matches our desired minimap size, but instead, we’ll check the Transparent Bg on the Viewport. Now our non-map areas aren’t visible and the minimap appears floating directly on top of the main viewports.

Conclusion

Viewports can be very powerful, but also confusing. One way of managing them is to try to keep them separate from the game logic and only use them as displays.

This demo is only a small example of what’s possible with Viewports. More demos and examples are coming soon.

Please comment below with your questions and suggestions.

Download the code for this tutorial

Helpful Links:

Godot 3.0: Simple Mobile UI (with transitions)

Sat, 16 Jun 2018 08:12:12 PDT

Mobile UI

Building the UI is usually the least fun part of your game. When I’m working on a project, I tend to ignore this part for as long as I can. On the plus side, once you’ve built a few game screens and UI systems, you can often use them across mulitiple projects.

In this tutorial, we’ll make a small UI system for a mobile game. We’ll focus on the UI screens only, with the goal that you can plug this into your own game to jump-start construction of your various game screens.

A simple setup might be to have four screens:

Title Screen
Settings
Gameplay (HUD)
End Screen

Here’s an example of what we want to accomplish, moving between screens with a nice animated transition:

You can download the example project here:

Mobile UI Example

Display setup

For this demo, we want to simulate a mobile device screen in Portrait mode. In Project Settings > Display > Window set the Width and Height to 480 and 854 and the Orientation to “portrait”.

Master screen

Because all of the screens are going to share some common layout, we can use Godot’s scene inheritance to make things a bit easier. We’ll create a master scene containing the common nodes and configuration and use that as the base for the individual screens.

Here’s the node setup (node types are in parentheses):

╴Screen (CanvasLayer)
    ┠╴Margins (MarginContainer)
    ┃  ┖╴Main (VBoxContainer)
    ┃     ┖╴Title (Label)
    ┖╴AnimationPlayer

Save this as “Screen.tscn” and set up the nodes as follows:

Screen (CanvasLayer)

We’re using a CanvasLayer node as the scene’s root, which will allow the UI screens to be independent of any Camera movement or other transformations you apply to the default layer. The menu screens will “float” on top of any game objects.

Margins

This node will be the root container, and allows us to arrange everything with a nice margin around the edges of the screen. Remember that in Godot’s UI hierarchy, containers will automatically control the size of their children, so you won’t be individually setting any other nodes’ layout. This automatic formatting will be especially useful if you change resolutions or rotate from portrait to landscape.

From the “Layout” menu select “Full Rect” and then in the “Custom Constants” section of the Inspector, set the four Margin properties to 20.

Note: Most control nodes have a “Custom Constants” section where their unique properties can be set.

Main

The VBoxContainer automatically “stacks” its children, spacing them out vertically from the top, midddle, or bottom (set by the Alignment property). The only setting we need to change is the Separation, which we’ll set to 100 to space out the container’s items.

Title

Most, if not all, of the screens will have some sort of title at the top, so we’ll give it a common configuration here. Set Align to “Center”. Put “Title” or any other word in the Text property so you can see the result.

Next, configure the “Custom Fonts” section with your preferred font. For this demo I’m using the free “Xolonium” font, which you can download here.

TIP: Once you’ve configured the font, click the “Save” icon to save the resource. Then you can add it to another node later and avoid having to set all the properties again.

Transitions

The next step is to set up the transition animation that will take the user from screen to screen. For this example, we’ll make the screens “slide” in and out from the right side. You could also add any other kinds of transitions, such as zooms, fades, etc.

First, we’ll make sure the screen starts in the right state. Add a new animation to the AnimationPlayer called “init” and set it to “Autoplay on Load”.

We want the screen’s starting position to be “offscreen”, to the right of the display, so set the CanvasLayer’s Offset to (500, 0) and click the key icon to add a keyframe.

Now add another animation called “transition”. Set the Length to 0.3 (or however long you want the transition to take - faster is probably better). Add a keyframe for Offset at the start of (500, 0) and at the end of (0, 0). Play the animation to test it out.

You can add any other transition effects here as well.

Common screen code

Add a script to the “Screen” scene:

extends CanvasLayer

func appear():
    $AnimationPlayer.play('appear')

func disappear():
    $AnimationPlayer.play_backwards('appear')

We’ll extend this script on other screens to process buttons, etc.

Individual screens

Let’s start with the title screen. Click Scene > New Inherited Scene and select res://Screen.tscn. Name the new scene “TitleScreen” and save it.

Change the Title’s Text to your game title and add the following new nodes:

╴TitleScreen
    ┠╴Margins
    ┃  ┖╴Main
    ┃     ┠╴Title
    ┃     ┖╴Buttons (HBoxContainer)
    ┃        ┠╴PlayButton (TextureButton)
    ┃        ┖╴SettingsButton (TextureButton)
    ┖╴AnimationPlayer

In the Buttons container, set the Alignment to “Center” and Custom Constants/Separation to 75. Add the appropriate texture to each button’s Textures/Normal property.

Disconnect the script and add a new one extending res://Screen.gd. Connect both buttons’ pressed signal:

extends "res://Screen.gd"

signal play
signal settings

func _on_PlayButton_pressed():
    emit_signal('play')

func _on_SettingsButton_pressed():
    emit_signal('settings')

Each screen you want will be set up like this. Add any buttons or other UI controls and if they need to trigger a transition, emit an appropriate signal. The main display script can then handle the signals and initiate the transition. In this way, the individual screens need no knowledge of each other or how they are connected.

Switching scenes

To switch between the screens, we’ll make a “main” script. In your game, this might be your main scene or a separate UI scene that you load when the game starts. For this demo, just make a new scene with a Node root and instance one of each of your screen scenes in it. For example, here’s how mine looks once I’ve made the four screens I described in the introduction:

Now add a script and connect each screen’s signals (which are emitted when the player pushes its buttons). Your script will look like this:

extends Node

# this signal can let your main scene know that the player
# started the game
signal start_game

var current_screen = null

func _ready():
    change_screen($TitleScreen)

# When changing screens, make sure to wait until the transition
# animation has finished before calling another
func change_screen(new_screen):
    printt('changing to:', new_screen.name)
    if current_screen:
        current_screen.disappear()
        yield(current_screen.get_node('AnimationPlayer'), 'animation_finished')
    current_screen = new_screen
    current_screen.appear()
    yield(current_screen.get_node('AnimationPlayer'), 'animation_finished')

# Below here are the functions connected to each screen's
# signals, i.e. your "map" of what screen connects to
# another.
func _on_TitleScreen_play():
    change_screen($PlayScreen)
    emit_signal('start_game')

func _on_TitleScreen_settings():
    change_screen($SettingsScreen)

func _on_SettingsScreen_return_to_title():
    change_screen($TitleScreen)

func _on_PlayScreen_game_over():
    change_screen($EndScreen)

func _on_EndScreen_home():
    change_screen($TitleScreen)

func _on_EndScreen_play():
    change_screen($PlayScreen)
    emit_signal('start_game')

That’s the basic idea.Download the project to see it in action and experiment with how everything is connected up.

Styling

I’ve purposely left this demo with very little styling beyond the container layout. Feel free to add your own button images and spice up the look-and-feel.

Some other things you can add to spice it up:

Additional transition effects
Color and background animation
Audio: play sound effects on transition and button press

Topdown Tank Battle: Part 9

Thu, 31 May 2018 14:14:12 PDT

This is Part 9: Obstacles (and tool scripts)

You can watch a video version of this lesson here:

Introduction

In this part, we’re going to add obstacles to the world and begin to think about how levels are going to be designed.

Small additions

Before tackling the obstacles, a couple of small changes to the code.

First, we’re adding a machine gun turret, which is a stationary enemy. It inherits from EnemyTank and has all the same features, but its speed is set to 0 so that it doesn’t move.

Second, change the EnemyTank script so that it doesn’t use the LookAhead raycasts when it’s not a moving object:

func control(delta):
    if parent is PathFollow2D:
        if $LookAhead1.is_colliding() or $LookAhead2.is_colliding():
            speed = lerp(speed, 0, 0.1)
        else:
            speed = lerp(speed, max_speed, 0.05)
        parent.set_offset(parent.get_offset() + speed * delta)
        position = Vector2()
    else:
        # other movement code
        pass

Obstacles

In the art pack there are sandbags, trees, barriers, and many other useful objects to decorate the world and make it less empty. However, because they are not all the same size or shape, they will require different collision shapes. This means we can’t really use a TileMap to place them. In addition, we also want to be able to place them at any angle, not just the orthogonal rotations allowed in TileMaps.

So what approach should we use? We could make a bunch of different StaticBody objects, but that is going to be hard to manage with so many. Instead, we can make a single collision object that can be made to represent all of the possible obstacles. The idea is that as we get further into the project, we could turn this into a full level-design tool.

Obstacle scene

Create a new Obstacle scene with a StaticBody, Sprite, and CollisionShape2D, saving it in a folder called “environment”. Drop the asset sheet into the Sprite’s Texture and set its Region on.

Now, rather than selecting the region manually in the editor, we want to automatically grab all the obstacle images out of the sheet. Fortunately, when Kenney creates his art packs, he includes an xml file like the following along with the spritesheets. This file lists the coordinates of every image, making it easy to find them programmatically. Since we don’t need all of the objects, just the obstacles, we can create a new file listing just those objects:

<TextureAtlas imagePath="onlyObjects_retina.png">
        <SubTexture name="barrelBlack_side.png" x="652" y="532" width="40" height="56"/>
        <SubTexture name="barrelBlack_top.png" x="645" y="220" width="48" height="48"/>
        <SubTexture name="barrelGreen_side.png" x="652" y="476" width="40" height="56"/>
        <SubTexture name="barrelGreen_top.png" x="597" y="220" width="48" height="48"/>
        <SubTexture name="barrelRed_side.png" x="648" y="420" width="40" height="56"/>
        <SubTexture name="barrelRed_top.png" x="645" y="172" width="48" height="48"/>
        <SubTexture name="barrelRust_side.png" x="652" y="588" width="40" height="56"/>
        <SubTexture name="barrelRust_top.png" x="597" y="172" width="48" height="48"/>
        <SubTexture name="barricadeMetal.png" x="596" y="532" width="56" height="56"/>
        <SubTexture name="barricadeWood.png" x="596" y="72" width="56" height="56"/>
        <SubTexture name="fenceRed.png" x="243" y="336" width="96" height="32"/>
        <SubTexture name="fenceYellow.png" x="128" y="216" width="104" height="32"/>
        <SubTexture name="sandbagBeige.png" x="436" y="164" width="64" height="44"/>
        <SubTexture name="sandbagBeige_open.png" x="348" y="518" width="84" height="55"/>
        <SubTexture name="sandbagBrown.png" x="440" y="622" width="64" height="44"/>
        <SubTexture name="sandbagBrown_open.png" x="248" y="596" width="84" height="55"/>
        <SubTexture name="treeBrown_large.png" x="0" y="0" width="128" height="128"/>
        <SubTexture name="treeBrown_small.png" x="592" y="694" width="72" height="72"/>
        <SubTexture name="treeGreen_large.png" x="0" y="128" width="128" height="128"/>
        <SubTexture name="treeGreen_small.png" x="520" y="694" width="72" height="72"/>
</TextureAtlas>

Click here to download this file.

Rotating spritesheet coordinates

However, now we have a problem. At the beginning of the project we rotated the spritesheet by 90 degrees so that it was oriented pointing right to match Godot’s zero angle. That means that the coordinates in the xml file are no longer valid!

Fortunately, I have a Python script from a previoius project that parses the Kenney xml, so we can use that. Python is a great choice for tool scripts like this.

Once we’ve parsed the xml and extracted the x, y, width, and height values, we need to do a little math to transform them to the new orientation:

In this image, you can see how a point rotated 90 degrees counter-clockwise is transformed. In addition to this, since Godot expects x & y to represent the rectangle’s top-left corner, we also have to subtract h from y.

Here is the Python script to do all that:

# Extract sprite coordinates from rotated
# Kenney spritesheet
import xml.etree.ElementTree as ET

datafile = 'obstacles.xml'
enum_name = 'Items'
sheet_width = 782
sheet_height = 782

# parse Kenney XML file
tree = ET.parse(datafile)
rects = {}
for node in tree.iter():
    if node.attrib.get('name'):
        name = node.attrib.get('name').replace('.png', '')
        rects[name] = []
        rects[name].append(int(node.attrib.get('x')))
        rects[name].append(int(node.attrib.get('y')))
        rects[name].append(int(node.attrib.get('width')))
        rects[name].append(int(node.attrib.get('height')))

enum = 'enum Items {'
for name in rects:
    enum += name + ', '
enum += '}'
print(enum)
print()
print("var regions = {")
for name, rect in rects.items():
    x, y, w, h = rect
    # offset center
    x -= sheet_width//2
    y -= sheet_height//2
    # rotate 90deg counter-clockwise
    # and use new top-left corner
    x, y = y, -x
    w, h = h, w
    y -= h
    # remove offset
    x += sheet_width//2
    y += sheet_height//2
    print("\t%s.%s: Rect2(%s, %s, %s, %s)," % (enum_name, name, x, y, w, h))
print("}")

In addition to applying the transform, we’re also printing the result in a particular format, so that we can use it in our GDScript code. We will be left with an enum called Items listing the various obstacles and a dictionary called regions containing the coordinates as Rect2 objects.

Obstacle Script

Paste the Python script’s output into the Obstacle script:

extends StaticBody2D

enum Items {barrelBlack_side, barrelBlack_top, barrelGreen_side,
            barrelGreen_top, barrelRed_side, barrelRed_top,
            barrelRust_side, barrelRust_top, barricadeMetal,
            barricadeWood, fenceRed, fenceYellow, sandbagBeige,
            sandbagBeige_open, sandbagBrown, sandbagBrown_open,
            treeBrown_large, treeBrown_small, treeGreen_large,
            treeGreen_small}

var regions = {
    Items.barrelBlack_side: Rect2(532, 90, 56, 40),
    Items.barrelBlack_top: Rect2(220, 89, 48, 48),
    Items.barrelGreen_side: Rect2(476, 90, 56, 40),
    Items.barrelGreen_top: Rect2(220, 137, 48, 48),
    Items.barrelRed_side: Rect2(420, 94, 56, 40),
    Items.barrelRed_top: Rect2(172, 89, 48, 48),
    Items.barrelRust_side: Rect2(588, 90, 56, 40),
    Items.barrelRust_top: Rect2(172, 137, 48, 48),
    Items.barricadeMetal: Rect2(532, 130, 56, 56),
    Items.barricadeWood: Rect2(72, 130, 56, 56),
    Items.fenceRed: Rect2(336, 443, 32, 96),
    Items.fenceYellow: Rect2(216, 550, 32, 104),
    Items.sandbagBeige: Rect2(164, 282, 44, 64),
    Items.sandbagBeige_open: Rect2(518, 350, 55, 84),
    Items.sandbagBrown: Rect2(622, 278, 44, 64),
    Items.sandbagBrown_open: Rect2(596, 450, 55, 84),
    Items.treeBrown_large: Rect2(0, 654, 128, 128),
    Items.treeBrown_small: Rect2(694, 118, 72, 72),
    Items.treeGreen_large: Rect2(128, 654, 128, 128),
    Items.treeGreen_small: Rect2(694, 190, 72, 72)
}

Next, we want to be able to choose the item from the Inspector, so we need to export a variable that uses the Items enum:

export (Items) var type setget _update

Setting the type variable will trigger the _update() function, which sets the Region and creates a correctly sized collision rectangle:

func _update(_type):
    type = _type
    $Sprite.region_rect = regions[type]
    var rect = RectangleShape2D.new()
    rect.extents = $Sprite.region_rect.size / 2
    $CollisionShape2D.shape = rect

We need this code to run when we’re in the editor, not when the game is running, so add tool as the first line of the script. This tells Godot that we want the code to run in the editor.

Adding Obstacles

Now add some obstacle instances to the map, choosing some different types and arranging them as you like. However, when you try and run the game, you’ll see an error message:

Invalid set index 'region_rect' (on base: 'null instance') with value of type 'Rect2'.

This happens because the setget is running before the Obstacle scene has finished loading - specifically before its child node Sprite has loaded. We can fix this by telling the node to wait until it’s ready when being run in the scene tree (i.e. not in the editor):

func _update(_type):
    type = _type
    if !Engine.editor_hint:
        yield(self, 'tree_entered')
    $Sprite.region_rect = regions[type]
    var rect = RectangleShape2D.new()
    rect.extents = $Sprite.region_rect.size / 2
    $CollisionShape2D.shape = rect

Now you can run the game and test that the obstacles are working:

Conclusion

That completes Part 9 of this series. Still to come: pickup items (i.e. supplies, goals, etc.) and more weapon types.

Please comment below with your questions and suggestions.