TileSetScenesCollectionSource in Godot – Complete Guide

Creating dynamic and interactive game worlds in Godot often requires the intricate use of tiles. But what if you could take your tile-based worlds to a whole new level by integrating complete scenes as tiles? This is exactly what the TileSetScenesCollectionSource class in Godot 4 is designed to do, and we’re going to dive into this powerful feature that can add depth and functionality to your game.

What is TileSetScenesCollectionSource?

Understanding TileSetScenesCollectionSource

The TileSetScenesCollectionSource class is a magnificent tool that broadens the horizon for developers using the Godot engine. It inherits a lineage of classes which gives it a unique position within Godot’s ecosystem: TileSetSource < Resource < RefCounted < Object. Fundamentally, this feature allows you to expose a set of scenes as tiles within a TileSet resource – that means actual Godot scenes can be utilized as individual, interactable tiles on a TileMap.

The Role of TileSetScenesCollectionSource in Game Development

When you place these scene-enabled tiles on a TileMap, they are not just static visual elements; they are fully-fledged scenes that contain their own nodes and scripts. These scenes are instantiated as children of the TileMap right where you need them, bringing abundant possibilities for adding complexity and interactivity to your game levels.

Why Incorporate Scene Tiles into Your Games?

Leveraging scenes as tiles offers several advantages for your game development process:

– Enhance interactivity: Create tiles that are not just part of the background but can trigger events, animations, or even complex gameplay mechanics.
– Streamline workflow: By encapsulating functionality within scenes, you can keep your project organized and reusable.
– Dynamize level design: With scene tiles, each tile can represent a whole new layer of depth in your game world, from interactive NPCs to complex machinery.

Unlocking the power of TileSetScenesCollectionSource can elevate your gamedev skills and give you access to a broader canvas for creativity. Let’s embark on this journey and learn how to integrate scene-based tiles into your next Godot project.

CTA Small Image

Creating a Basic Scene for a Tile

Before we can integrate a scene as a tile in Godot, we need a basic scene to work with. Let’s assume you want to create an interactive tree that players can harvest.

func _ready():
    # Basic interactive tree behavior

func _input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_LEFT and event.pressed:
        if get_global_rect().has_point(get_global_mouse_position()):
            # Replace this with your harvest logic
            print("Tree harvested!")

In this code snippet, we’ve outlined a simple interactive behavior for our tree. When the player clicks on the tree, “Tree harvested!” is printed to the console. This will serve as the foundation for our tile scene.

Setting Up the TileSetScenesCollectionSource

Once your scene is ready, it’s time to incorporate it into a TileSet using the TileSetScenesCollectionSource class. Here’s how you set up the TileSet:

var my_scene_tileset := TileSet.new()
var my_scene_source := my_scene_tileset.create("res://path_to_your_scene.tscn", 0)

You now have a TileSet that contains your interactive tree scene as a source. The “0” passed to the `create` function is the id of the TileSet source.

Configuring the Scene Tile within the TileSet

Just adding the scene to the TileSet isn’t enough. To place it on a TileMap, we must configure the tile properties. This includes setting up the shape and texture for your tile:

var my_tile_id := my_scene_source.get_last_unused_tile_id()

my_scene_source.tile_set_texture(my_tile_id, preload("res://path_to_tree_texture.png"))
my_scene_source.tile_set_shape(my_tile_id, 0, collision_shape)

In this snippet, we create a new tile within our scene source, assign it a texture, and define its collision shape. `collision_shape` is typically a `Shape2D` resource representing your tile’s physical boundaries.

Placing Your Scene Tile on a TileMap

Finally, you can add your scene tile to a TileMap, just like you add any regular tile:

var my_tile_map := $TileMap # Assume TileMap is part of the current scene.
my_tile_map.tile_set = my_scene_tileset

# Set the cell at position (10,10) to use your scene tile
my_tile_map.set_cell(10, 10, my_scene_source.get_last_unused_tile_id())

By setting the TileMap’s `tile_set` property to your custom TileSet and using `set_cell` with the correct tile ID, your scene will now instantiate as a tile on the grid!

Remember, this is a simplified example for illustration purposes. You would need to add error checking, resource management, and perhaps advanced interactivity depending on your game’s requirements. Nonetheless, what we’ve covered is the basic flow you’d follow to incorporate complete scenes as tiles, providing a vast range of possibilities for your Godot projects. Stay tuned for the next segment, where we’ll expand upon our scene tiles and explore how to manage multiple scenes within a single TileSet.Managing multiple scenes within a single TileSet is a powerful feature of Godot that allows for varied and dynamic level design. By following a similar process to what we’ve done with a single scene, we can add a collection of scenes to the TileSetScenesCollectionSource. Here’s how you manage multiple scene tiles:

Adding Multiple Scenes to TileSet

Let’s assume you have several interactive elements you’d like to use as tiles (a tree, a rock, and a treasure chest). After creating basic scenes for each (let’s call them tree.tscn, rock.tscn, and chest.tscn), we can add them to the TileSet like this:

var my_tileset := TileSet.new()
var tree_source := my_tileset.create("res://tree.tscn", 0)

var rock_source := my_tileset.create("res://rock.tscn", 1)

var chest_source := my_tileset.create("res://chest.tscn", 2)

Each scene is registered with a unique ID to distinguish it within the TileSet.

Setting Up Properties for Multiple Tiles

Next, we need to set up the properties for each tile to define their appearance and behavior on the TileMap:

func setup_tile(tile_id, texture_path, collision_shape):
    var source = my_tileset.get_source(tile_id)
    source.tile_set_texture(tile_id, preload(texture_path))
    source.tile_set_shape(tile_id, 0, collision_shape)

# Assuming you have predefined collision shapes for each tile
setup_tile(0, "res://tree_texture.png", tree_collision_shape)
setup_tile(1, "res://rock_texture.png", rock_collision_shape)
setup_tile(2, "res://chest_texture.png", chest_collision_shape)

By creating a helper function, `setup_tile`, we can streamline the configuration of multiple tiles.

Placing Multiple Scene Tiles on the TileMap

When it comes to adding these newly configured scene tiles to the TileMap, it’s as easy as referencing the correct ID for each tile:

# Reference to your TileMap node
var my_tile_map := $TileMap
my_tile_map.tile_set = my_tileset

# Add tree tile at position (10, 10)
my_tile_map.set_cell(10, 10, 0)

# Add rock tile at position (15, 10)
my_tile_map.set_cell(15, 10, 1)

# Add chest tile at position (10, 15)
my_tile_map.set_cell(10, 15, 2)

With the `set_cell` method, each tile can now easily be placed onto the TileMap with its scene ready to be instantiated.

Instantiating Scene Tiles Programmatically

You may find yourself in a situation where you want to instantiate these scene tiles programmatically. If so, Godot offers the flexibility to do just that:

# Instantiate a new rock scene at runtime
var rock_scene_instance = rock_source.instantiate_tile(1)
rock_scene_instance.global_position = Vector2(100, 100)

This code example takes a rock scene tile and instantiates it as an actual node within the game world. By controlling the `global_position`, you can dynamically place these interactive elements exactly where you need them during gameplay.

Remember to take care when managing resources and references during runtime instantiation to avoid memory leaks or performance drops.

Editing Scenes after Adding as Tiles

Sometimes, after adding a scene as a tile, you might need to make changes to the original scene. Godot makes it easy to reflect those changes across all instances of the tile:

# Assuming you've updated the scene in Godot's editor
# You can reload the scene source to refresh the tile instances
my_tileset.reload_source(0)  # 0 is the ID for the tree source

By calling `reload_source` with the correct ID, the updates you made to the scene are loaded into the active TileSet, ensuring a seamless development workflow.

Integrating complete scenes as tiles with TileSetScenesCollectionSource enables you to create rich and customizable game worlds. By understanding how to programmatically manage these tiles, you unlock a whole new level of game development within the Godot engine. Happy coding, and create wonderful, interactive environments that stand out!Great, let’s dive deeper into the intricacies of managing interactive scene tiles and explore advanced techniques that can bring your game environments to life.

Interactive Tiles with Signals

Signals in Godot are a powerful feature that can be used to create interactive tiles. Let’s say you want your tree tile to emit a signal when it’s harvested. First, we define the signal inside the tree scene script:

extends Node2D
# Define a harvested signal
signal tree_harvested

func _ready():

func _input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_LEFT and event.pressed:
        if get_global_rect().has_point(get_global_mouse_position()):

When the tree is clicked, it emits the `tree_harvested` signal, which can be connected to any other part of your game logic.

Connecting Tile Signals

After you’ve instantiated your interactive tile and added it to the scene tree, you can connect it to a function in another node:

# Assuming you have a GameManager node that listens for tree harvesting
var tree_instance = my_scene_source.instantiate_tile(0)
tree_instance.connect("tree_harvested", $GameManager, "on_tree_harvested")

In this example, when the tree emits the `tree_harvested` signal, the `GameManager`’s `on_tree_harvested` function will be called, allowing you to trigger game logic like increasing resources or updating the UI.

Adjusting Tile Properties at Runtime

You might need to modify the properties of your scene-based tiles while the game is running. For instance, if a player harvests a tree, you might want to change its appearance to show that it’s been cut down:

func _on_tree_harvested():
    $TileMap.set_cellv(tree_cell_position, -1) # Clear the cut tree tile
    var stub_scene = preload("res://tree_stub.tscn").instance()
    stub_scene.global_position = tree_cell_position * $TileMap.cell_size

Here, we clear the original tree tile and replace it with a tree stump scene to visually indicate a state change.

Advanced Tile Interaction with Area2D

For more complex interactions, adding `Area2D` nodes to your scene tiles can provide sophisticated feedback:

extends Area2D

signal area_entered_by_player

func _on_Area2D_body_entered(body):
    if body.is_in_group("Player"):

In this script attached to an `Area2D` within a scene tile, a signal is emitted whenever a player enters the area. Now you can hook into that signal to trigger events or quests.

Making Scene Tiles Respond to Game Events

Let’s say you want your scene tiles to change based on certain game events, like the time of day. You can dynamically adjust properties using signals or by calling methods directly on the tile instances:

func _on_day_night_cycle_changed(is_night):
    for tile in $TileMap.get_used_cells_by_id(0): # 0 is the tree tile ID
        var tree = $TileMap.get_node_or_null(tile) # Returns the instance if exists
        if tree and is_night:
            tree.modulate = Color(0.5, 0.5, 0.5) # Darken the tree
        elif tree:
            tree.modulate = Color(1, 1, 1) # Restore normal color

In this example, every tree tile on the TileMap will darken when night falls and return to its original color when day comes.

Performance Considerations

When working with scene-based tiles, it is essential to consider performance. Instantiating and managing many individual scenes can become resource-intensive, especially on lower-end devices. To optimize, consider pooling and reusing scenes:

var tree_pool = []
var max_trees = 10

func _ready():
    # Pre-instantiate trees and hide them
    for i in range(max_trees):
        var tree = preload("res://tree.tscn").instance()
        tree.visible = false

func get_tree_from_pool():
    for tree in tree_pool:
        if not tree.visible:
            return tree
    return null

func _on_tree_harvested():
    var tree_to_reuse = get_tree_from_pool()
    if tree_to_reuse:
        tree_to_reuse.global_position = Vector2(100, 100) # Example position
        tree_to_reuse.visible = true

We create a pool of trees during `_ready` and reuse them when needed, instead of instantiating new ones every time a tree is harvested. This can significantly reduce the number of objects being managed by Godot at any one time, improving your game’s performance.

With these advanced techniques, your interactive scene tiles will not only enhance your game’s aesthetics but also act as dynamic, responsive elements in your game world. Utilizing signals, adjusting properties, implementing `Area2D` nodes, and mindful resource management will ensure that your Godot game levels remain engaging, performant, and memorable for your players.

Continue Your Game Development Journey

The world of game development is vast and always evolving, brimming with endless possibilities for creativity and innovation. As you’ve embarked on this journey with scene-based tiles in Godot, remember that this is just the beginning. To delve even deeper into the art of creating compelling games using the Godot 4 engine, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses is designed to equip you with the skills needed to build cross-platform games, covering everything from rendering graphics to mastering GDScript and crafting both 2D and 3D games.

With a flexible learning environment that accommodates any schedule and helps you compile a portfolio of real Godot projects, our Mini-Degree caters to both beginners and those looking to sharpen their existing skills. And since the Godot 4 engine is open-source and free to use, there’s nothing standing in your way.

For those seeking a broader array of lessons on this dynamic game engine, our collection of Godot courses provides even more content to satisfy your learning needs. Whether you’re eager to get started or ready to take your skills to the next level, Zenva is here to support you every step of the way in your game development career. Join us, and let’s bring your game ideas to life!


Embarking on your game development journey with Godot can transform your creative ideas into tangible, interactive experiences. By mastering the integration of scene-based tiles using classes like TileSetScenesCollectionSource, you’ve unlocked a new dimension of level design that can enhance your games beyond the ordinary. Remember, the scripts and methods we’ve shared are just the beginning. There’s a whole universe within Godot 4 ready for you to explore and exploit to its fullest potential.

At Zenva, we understand the thrill that comes with acquiring new skills and watching your virtual worlds come to life. That’s why our Godot Game Development Mini-Degree is crafted to take you further, whether you’re taking your first steps in game development or honing your expertise to craft the next indie hit. Join us in this adventure, and let’s continue to build amazing games together, one tile at a time.

Python Blog Image

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