TileSetAtlasSource in Godot – Complete Guide

Tile-based video games have charmed players for decades, and one of the most enjoyable aspects of game development is bringing a world to life through its many little squares. In this tutorial, we’ll dive into the intricacies of the TileSetAtlasSource class in Godot 4. Whether you’re a coding newb or a seasoned gamedev veteran, understanding how to manipulate tilesets in Godot is a key skill that will help you craft engaging levels with ease.

As we explore the TileSetAtlasSource class, you’ll learn how this powerful tool can simplify the tile management process, making your game development experience smoother and more enjoyable. So gear up and let’s embark on a coding journey through the realm of tiles and textures!

What is TileSetAtlasSource?

In Godot 4, the TileSetAtlasSource class is an essential part of managing tilesets—a fundamental resource in tile-based games. It exposes a texture atlas, which is essentially a large image containing a collection of smaller images (tiles), as a set of tiles within a TileSet resource.

What is TileSetAtlasSource Used For?

TileSetAtlasSource is key for:

– Organizing tiles efficiently on a single texture
– Creating and indexing tiles by their position on the grid
– Configuring alternative versions for a given tile
– Assigning and managing tile-specific properties

This class streamlines the process of defining and accessing individual tiles and their various states, which can range from simple static ground tiles to intricate animated features.

Why Should I Learn About TileSetAtlasSource?

Here’s why mastering TileSetAtlasSource is essential:

– **Efficiency**: It allows for the optimal use of texture memory by packing multiple tiles into a single image.
– **Flexibility**: You can define tiles of varying sizes and manage multiple versions, facilitating diverse tileset designs.
– **Control**: Understanding TileSetAtlasSource gives you greater control over the look and feel of your game environments.

By learning how to use the TileSetAtlasSource class, you’ll be better equipped to create visually appealing game levels with a rich variety of tiles, enhancing the overall gaming experience. Let’s roll up our sleeves and start with some coding examples to put these concepts into action!

CTA Small Image

Setting Up TileSetAtlasSource

Beginning with the setup, we’ll establish a TileSetAtlasSource within Godot’s editor and see how to instantiate one using GDScript. This step is necessary to begin manipulating our tiles and turning them into tangible elements within our game world.

First, let’s start by opening the TileSet resource and creating a new Atlas Source:

var tile_set = TileSet.new()
var atlas_source = TileSetAtlasSource.new()

Following the initialization of our TileSet and TileSetAtlasSource, we’ll need to assign a texture to the atlas. This texture will represent our entire tile collection.

var texture = preload("res://path/to/your/tileset_image.png")

After assigning the texture, the next step is to define the tiles. Suppose our tiles are 64×64 pixels each, and we need to create them on a grid. Tiles can be created programmatically by specifying their region within the atlas texture:

var tile_size = Vector2(64, 64)
var tile_position = Vector2.ZERO
var region = Rect2(tile_position * tile_size, tile_size)


This code snippet creates a single tile at the top-left corner of the texture atlas (position (0,0)).

Configuring Tiles and Properties

Each tile can have unique properties that influence how it behaves in the game. This can include things from simple collision shapes to custom data. Let’s set up a collision shape for a tile:

var tile_id = atlas_source.find_tile_by_region(region)
var shape = RectangleShape2D.new()
shape.extents = tile_size * 0.5

tile_set.tile_set_shape(tile_id, 0, shape)

In this example, we first find the ID of the tile using its region, then create a basic rectangular collision shape which has half the extents of our tile size.

For adding custom data to a tile, you can assign it to the tile based on its ID:

tile_set.tile_set_script_variable(tile_id, "is_walkable", true)

This assigns a variable `is_walkable` to the tile and sets it to `true`. You can customize this according to the gameplay mechanics.

Tiles can also be animated by adding multiple regions to represent each frame of the animation:

var tile_frames = PoolVector2Array([
    Vector2(1, 0), 
    Vector2(2, 0)

var animation_speed = 0.1

foreach frame in tile_frames:
    var frame_region = Rect2(frame * tile_size, tile_size)
    atlas_source.add_tile_animation_frames(tile_id, [frame_region], animation_speed)

In this example, we define an array of positions for each frame of the tile’s animation and set an animation speed. We then loop over each position, create a frame region, and add it to the tile animation frames.

By mastering these basics of the TileSetAtlasSource, we lay a solid groundwork. Next, we will move on to diving into more intricate manipulation and usage scenarios that will bring your tilesets to life.Let’s delve further into the capabilities of TileSetAtlasSource by looking at how we can modify individual tiles and manage their interactions in our game world.

Modifying Tile Attributes at Runtime

Sometimes, you might want to adjust your tile’s attributes during gameplay, such as changing its collision layer or toggling whether it’s visible. You can do this through script:

var layer_bit = 1 # Represents the collision layer
tile_set.tile_set_collision_layer_bit(tile_id, layer_bit, true)

The above example enables the collision layer for the given tile identified by `tile_id`.

Toggle Visibility of Tiles

To toggle the visibility of a specific tile, you could use the following:

tile_set.tile_set_modulate(tile_id, Color(1, 1, 1, 0)) # Set alpha to 0 for invisibility

And to make it visible again:

tile_set.tile_set_modulate(tile_id, Color(1, 1, 1, 1)) # Full alpha for visibility

Adjusting Tile Z-Index

The Z-Index determines the draw order of tiles, allowing some to appear over others. Here’s how you change it:

tile_set.tile_set_z_index(tile_id, 10) # Higher z-index tiles are drawn over lower ones

Attaching Scripts to Tiles

You can even attach scripts to tiles to give them unique behaviors, like traps or collectibles:

var custom_script = preload("res://path/to/your/script.gd")
tile_set.tile_set_script(tile_id, custom_script)

Creating Autotile Rules

Autotiling can significantly speed up the map-making process by automatically selecting appropriate tiles according to their neighbors. Setting up autotiles can be a little complex, but here’s a start:

var bitmask_mode = TileSetAtlasSource.BITMASK_3X3_MINIMAL # Define the bitmask mode 
atlas_source.set_bitmask_mode(tile_id, bitmask_mode)

# Define bits as true (1) or false (0) based on desired autotiling rules
var bitmask = [
    1, 0, 1,
    0, 0, 0,
    1, 0, 1
atlas_source.set_bitmask(tile_id, bitmask)

With the bitmask defined, Godot will use the rules to automatically select the correct tile when populating your game map using this TileSet.

Defining Tileset Terrains

To make your map’s transitions between different types of tiles look smooth, you can define terrains:

var terrain_set = TileSet.TerrainSet.new()
tile_set.add_terrain_set(0, terrain_set)

var tile_terrain = PoolIntArray([0,0,0,0]) # Define the corners' terrain
tile_set.tile_set_tile_terrain(tile_id, tile_terrain)

This script defines a new terrain called “Grass” and assigns it to the corners of a tile, which can be used to create continuous terrain that fits together seamlessly.

By understanding how to apply these techniques with the TileSetAtlasSource class, you can build immersive, dynamic worlds that behave according to the ruleset you define. Getting comfortable with these examples will greatly enhance your ability to design intricate levels that not only look good but interact with your players in meaningful ways. We at Zenva pride ourselves in providing in-depth tutorials that help you make the most out of your game development journey—so keep experimenting and happy coding!Introducing additional layers of interactivity and refinement to your game’s tilesets can create a truly immersive environment. Let’s explore advanced techniques using Godot’s TileSetAtlasSource that can elevate your game development.

Handling Mouse and Touch Events on Tiles

To make your game interactive, you might want to handle click or touch events on tiles. One way to do this is by using the `_input` function and checking if the mouse’s position intersects with a tile’s rect.

func _input(event):
    if event is InputEventMouseButton and event.pressed:
        var mouse_position = get_global_mouse_position()
        var tile_map = $TileMap # Assuming the script is attached to the node that has a child TileMap node
        var clicked_tile_position = tile_map.world_to_map(mouse_position)
        var clicked_tile_id = tile_map.get_cellv(clicked_tile_position)
        if clicked_tile_id != TileMap.INVALID_CELL:
            # A tile was clicked - do something!
            print("Tile with ID", clicked_tile_id, "was clicked.")

Implementing Pathfinding on a TileMap

Pathfinding is a common requirement in tile-based games. Let’s assume you’ve already implemented an A* algorithm and want to integrate it with your TileMap.

var a_star = AStar2D.new()
for tile_position in tile_map.get_used_rect():
    if tile_map.get_cellv(tile_position) == TileMap.INVALID_CELL:
    var point_id = tile_position_to_id(tile_position)
    a_star.add_point(point_id, tile_map.map_to_world(tile_position))
    # Connect this point to adjacent points if they are walkable

func tile_position_to_id(tile_position):
    return tile_position.x + tile_position.y * tile_map.get_size().x

Using TileSetAtlasSource for Tile Variations

Different variations of a tile, like damaged states or environmental changes, can be managed with TileSetAtlasSource.

var damaged_region = Rect2(Vector2(3, 1) * tile_size, tile_size) # Assuming (3, 1) is the position of the damaged tile in the atlas
var damaged_tile_id = atlas_source.find_tile_by_region(damaged_region)
tile_set.tile_set_script_variable(damaged_tile_id, "is_damaged", true)

This snippet registers a variation of the original tile as a damaged one, which can be used to reflect changes during gameplay.

Animating Tiles with Physics

You might want to add some dynamic behavior to your tiles using physics. Here’s how you could make a simple floating animation using the built-in physics process:

extends Node2D

var floating_tile_id
var original_position
var float_height = 10
var float_speed = 2

func _ready():
    original_position = position

func _physics_process(delta):
    position.y = original_position.y + float_height * sin(float_speed * get_tree().time_since_start)

This creates a floating animation for a node, which could be used for tiles like moving platforms in your tile-based game.

Scripting for Automatic Tile-Based Events

Tiles can trigger events when a player character interacts with them, such as stepping on a trap or collecting an item.

func _on_TileMap_cell_entered(cell_position):
    var cell = tile_map.get_cellv(cell_position)
    if tile_set.has_method("trigger_event"):
        tile_set.call("trigger_event", cell, "entered", self, cell_position)

This function would be connected to a signal that fires when the character enters a cell. The tile’s associated script could define the “trigger_event” function, which handles what happens next.

By integrating these techniques into your Godot projects, you can ensure that your tilesets are not just static backgrounds but active components in your game’s mechanics. Remember that experimentation is key to discovering the best way to leverage these features in your unique game concepts. Dive into coding with these examples, and watch as your tile-based worlds come to life with detail and interaction.

Continue Your Game Development Journey with Godot

Embarking on the journey of mastering game development can be both an exhilarating and intricate endeavor. What we’ve explored with TileSetAtlasSource in Godot 4 scratches just the surface of what’s possible. If you’re looking to take your skills to the next level, Zenva Academy is here to guide you through the nuanced world of game creation.

Dive deeper into Godot’s extensive features with our Godot Game Development Mini-Degree. This tailored series of comprehensive courses offers a structured path from the fundamentals of game design to the complexities of crafting immersive cross-platform experiences. Our curriculum is brimming with practical know-how, taking you through various facets of game development, including but not limited to, asset control, GDScript, and gameplay mechanics, all while building a portfolio of real Godot projects.

For those who are eager for even more Godot content or want to navigate through different topics at their own pace, our broader collection of Godot courses may be just what you need. Whether you’re a beginner or a developer looking to refine your skills, Zenva provides the resources to support your growth. With flexible 24/7 access to our courses and an array of completion certificates, your game development adventure never has to hit ‘pause’. Keep coding, keep creating, and let Zenva be part of your success story. The world of game development awaits—let’s level up together!


In the boundless universe of game development, grasping the power of Godot’s TileSetAtlasSource truly opens up a world of possibilities. From crafting intricate levels with ease to injecting dynamic interactivity into every corner of your game world, the skills you’ve gained here lay down the groundwork for creating unforgettable gaming experiences. But remember, this is just the launching point of your game creation odyssey.

At Zenva, we’re committed to helping you turn your game development aspirations into reality, one lesson at a time. Continue to harness your passion and elevate your craft with our Godot Game Development Mini-Degree. Join us to gain the insights and hands-on experience needed to bring your most ambitious game ideas to life. Your journey into game development is sure to be as thrilling as the games you’re destined to create!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.