Tree in Godot – Complete Guide

Navigating through data structures is a fundamental skill in modern programming, and when it comes to graphical user interfaces, few structures are as intuitive and ubiquitous as the Tree View. In the realm of game development, particularly when using engines like Godot, trees play a pivotal role in organizing and manipulating hierarchical data, which can range from game objects in a scene to menu items in your game’s UI.

In our journey through Godot 4’s Tree Class, we’ll uncover how this powerful UI node can be utilized to enrich your games and applications. Whether you’re a budding developer taking your first steps or a seasoned developer brushing up on Godot’s UI components, this tutorial is designed to be a guiding light through the intricacies of the Tree Class, presenting this topic as both a cornerstone of UI design and a versatile tool in your development toolkit.

What Is the Tree Class in Godot 4?

The Tree Class in Godot is a Control node that allows developers to display and interact with a hierarchy of TreeItems. It is a versatile UI component designed to manage complex data structures within an application or game environment. Offering features like selection, expansion, collation, and custom control embedding, the Tree Class is integral for creating structured and navigable interfaces.

What Are Common Uses for the Tree Class?

You’ll find the Tree Class at the heart of many standard UI patterns, such as file system explorers, nested menus, or even for displaying in-game hierarchical data like skill trees or inventory categories. Its ability to embed custom controls also makes it adaptable for various use cases that require interactive lists with more complexity than a simple array of items.

Why Should I Learn to Use the Tree Class?

Understanding how to implement and manipulate the Tree Class in Godot 4 empowers you to construct intuitive and responsive interfaces for your players or users. By mastering the Tree Class, you can present complex information in an organized, hierarchical structure, greatly enhancing in-game navigation and overall user experience. The skills gleaned from this tutorial extend beyond just game development—they’re transferable across many aspects of programming where data organization and visual representation are key.

With these insights, let’s venture forth into the coding sections, where we’ll demonstrate practical uses of the Tree Class in Godot with hands-on examples.

CTA Small Image

Creating a Simple Tree

To begin our practical journey with the Tree Class in Godot 4, we’ll start by creating a simple Tree structure. This will serve as our foundational example.

func _ready():
    var tree =

    var root = tree.create_item()
    root.set_text(0, "Root")
    var child = tree.create_item(root)
    child.set_text(0, "Child")

In the snippet above:

– We first create a new Tree instance.
– We add the Tree as a child of the current node.
– We create a root item with `tree.create_item()` and set its initial text.
– Afterwards, we create a child item, specifying the root as its parent.

Manipulating Tree Items

Now that we’ve established our Tree, we can delve into how to manipulate TreeItems to change their properties and behaviors.

func _ready():
    # Previous tree setup code

    # Assign an icon to the root item
    var icon = preload("res://root_icon.png")
    root.set_icon(0, icon)

    # Disable the child item
    child.set_disabled(0, true)

    # Select the child item

In this section of code:

– We preload an icon and assign it to the Root’s first column.
– We then disable the Child TreeItem making it non-interactable.
– Lastly, we programmatically select the Child TreeItem.

Expanding and Collapsing Tree Items

An essential feature of the Tree Class is the ability to expand and collapse TreeItems. Let’s create a snippet that handles these actions.

func _ready():
    # Previous tree setup code

    # Expand the root item

    # Collapse the child item after a delay
    yield(get_tree().create_timer(2.0), "timeout")

Here, we:

– Uncollapse the root immediately, displaying its children.
– Utilize Godot’s built-in timer to collapse the child item after a 2-second delay.

Embedding Controls

A powerful feature of the Tree Class is the ability to embed other controls within TreeItems. In this example, we will embed a Button into a TreeItem.

func _ready():
    # Previous tree setup code

    # Create a button
    var button =
    button.text = "Click Me"

    # Embed the button into the child
    child.add_button(0, button)

    # Connect the button's 'pressed' signal
    button.connect("pressed", self, "_on_Button_pressed")
func _on_Button_pressed():
    print("Button was pressed!")

This code snippet describes:

– The creation of a Button instance with its `text` property set.
– The addition of this Button to the Child TreeItem’s first column.
– A connection of the Button’s ‘pressed’ signal to a print function.

With these examples, you have now learned to create a Tree structure, manipulate TreeItems, expand/collapse nodes, and embed other controls within TreeItems in Godot 4.Using these building blocks, you can start developing robust and interactive interfaces for your applications or games.The Tree Class in Godot is more than just a static display; it’s interactive and customizable. Let’s explore how we can detect user interaction with tree items and respond to it, handle multiple columns, and customize the appearance of our TreeItems.

To detect when a TreeItem is selected, you’ll want to connect the `item_selected` signal of the Tree node to a function. Here’s how:

func _ready():
    # Previous tree setup code

    # Connect the 'item_selected' signal
    tree.connect("item_selected", self, "_on_Tree_item_selected")

func _on_Tree_item_selected():
    var selected_item = tree.get_selected()
    if selected_item != null:
        print("Selected:", selected_item.get_text(0))

When a TreeItem is selected, `_on_Tree_item_selected` is called, and we can get which item was chosen using `tree.get_selected()`.

Next, we can look at handling multiple columns in our Tree:

func _ready():
    # Set up the tree with 2 columns
    tree.set_column_title(0, "Name")
    tree.set_column_title(1, "Type")

    var root = tree.create_item()
    root.set_text(0, "Root")
    root.set_text(1, "RootNode")

    var child = tree.create_item(root)
    child.set_text(0, "Child")
    child.set_text(1, "ChildNode")

Here we set our Tree to have two columns and give them titles: “Name” and “Type”. Then we create root and child items, setting text for both columns.

Handling double-click on an item is equally simple:

func _ready():
    # Previous tree setup code

    # Connect the 'item_activated' signal to handle double-clicks
    tree.connect("item_activated", self, "_on_Tree_item_activated")

func _on_Tree_item_activated():
    print("Item has been double-clicked!")

This snippet will print a message each time an item is activated (double-clicked). We’re connecting the `item_activated` signal to a function in this case.

Now, let’s give our TreeItems some custom styles. Customizing the background color of a TreeItem is accomplished by setting its custom bg color.

func _ready():
    # Previous tree setup code
    var child_2 = tree.create_item(root)
    child_2.set_text(0, "Child 2")
    # Set Custom Background Color
    var color = Color(0.25, 0.50, 0.75) # A nice blue
    child_2.set_custom_bg_color(0, color)

The above code sets a custom background color to the second child. We choose a color and then apply it to the first column of `child_2`.

Finally, to adjust the height of items in the tree to accommodate the controls or content you might embed:

func _ready():
    # Previous tree setup code

    # Set the height of each item

With this line, we’ve set the height for all items in the tree to 40 pixels. This can be helpful for making sure embedded controls fit properly.

By leveraging the Godot Engine’s Tree Class and TreeItems, you can create interactive, multi-column data structures. The customization and signal connection examples provide insight into just how dynamic and functional your game or application interfaces can be. With these tools at your disposal, your UI can be clear and intuitive, significantly enhancing the user experience.Using the Godot Tree Class allows for even greater interactivity and functionality. To further our understanding, we will explore sorting, managing selection mode, item customization, and reacting to signals such as mouse button presses.

First, let’s sort our TreeItems alphabetically:

func _ready():
    # Previous tree setup code
    # Sort the tree alphabetically

Here, `set_hide_root` hides the root TreeItem, making the first level of children act as the top level, and `set_sort_enabled` sorts all items alphabetically based on their text.

Next, we will address managing selection mode. The Tree Class allows both single and multiple selections:

func _ready():
    # Previous tree setup code

    # Set selection mode to multiple selections

Setting `SELECT_MULTI` on the Tree allows multiple items to be selected simultaneously. Conversely, if you change `SELECT_MULTI` to `SELECT_SINGLE`, only one item can be selected at a time.

Further customization of TreeItems can include adding checkboxes or setting the cell’s alignment to adjust the visual presentation:

func _ready():
    # Previous tree setup code

    var checkbox_item = tree.create_item(root)
    checkbox_item.set_text(0, "Checkbox Item")

    # Add a checkbox to the item
    checkbox_item.set_cell_mode(0, TreeItem.CELL_MODE_CHECK)
    checkbox_item.set_checked(0, true)
    # Set cell alignment
    checkbox_item.set_text_align(0, TreeItem.TEXT_ALIGN_CENTER)

This snippet creates an item with a checkbox by setting its cell mode to `CELL_MODE_CHECK` and checking it by default. The `set_text_align` function is used to center the text within the cell.

More advanced interactivity comes with responding to signals, such as detecting right mouse button clicks:

func _ready():
    # Previous tree setup code

    # Connect the 'button_pressed' signal
    tree.connect("button_pressed", self, "_on_Tree_button_pressed")

func _on_Tree_button_pressed(item, column, button):
    if button == BUTTON_RIGHT:
        print("Right-clicked on", item.get_text(column), "at column", column)

Binding the `button_pressed` signal allows us to capture right-clicks (BUTTON_RIGHT) on an item and respond as needed.

Lastly, let’s look at how we can dynamically add and remove items from the Tree:

func _ready():
    # Previous tree setup code
    # Add a new item dynamically
    var new_item = tree.create_item(root)
    new_item.set_text(0, "New Dynamic Item")
    # Remove an item dynamically

We first add a new item by creating it and giving it a name. To remove an item, we navigate the children of the root and free one.

Additionally, we can also update the Tree as user selections change:

func _ready():
    # Previous tree setup code

    # React to selection changes
    tree.connect("item_selected", self, "_on_Tree_selection_changed")

func _on_Tree_selection_changed():
    var selected_item = tree.get_selected()
    if selected_item != null:

func update_UI_based_on_selection(item):
    # Update your UI or logic based on the selected item
    print("Update UI for selected item:", item.get_text(0))

We connect to the `item_selected` signal and respond by calling `update_UI_based_on_selection`, where you would include logic to update your UI corresponding to the selected TreeItem.

By grasping these additional functionalities, you are well-equipped to make full use of the Tree’s rich feature set. This understanding is invaluable for creating user interfaces that are not just visually appealing but also interactive and efficient in allowing users to navigate and manage data.

Continue Your Game Development Journey

Having ventured through the foundational aspects of the Tree Class in Godot 4, you’re now equipped with the knowledge to enhance your games and UIs. But don’t let your learning journey end here! Expand your skills and dive deeper into the world of game development with our Godot Game Development Mini-Degree. Whether you’re crafting your first game or looking to master the latest techniques, this collection of courses has got you covered.

Our Mini-Degree, suitable for both hobbyists and professionals, offers a variety of levels from beginner to advanced, ensuring a smooth learning curve. You’ll build a diverse portfolio of real-world Godot projects, explore 2D and 3D game mechanics, and master the art of creating engaging, cross-platform games. The curriculum is self-paced, providing you the flexibility to learn on any device, at any time, all the while practicing with live coding lessons and reinforcing new concepts through quizzes.

If you wish to explore a broader range of topics or need a different starting point, check out our full collection of Godot courses. At Zenva, our mission is to provide you with the high-quality education necessary to take your development skills from beginner to professional. Continue your journey with us, and unlock your potential as a game developer!


As we bring this tutorial to a close, you’ve taken crucial steps in mastering the Tree Class in Godot 4, a powerful tool in any developer’s toolkit. Now with the capability to organize, manage, and display data hierarchically, you’re closer to presenting your users with a UI experience that’s not only intuitive but also engaging. Remember, this knowledge doesn’t operate in isolation—it’s a fundamental part of the broader canvas of game development skills that you’ll continuously expand as you create, experiment, and refine your work.

Embrace your newfound skills and channel them into your next project with confidence. And when you’re ready to push your boundaries even further, our Godot Game Development Mini-Degree awaits, poised to guide you through the exciting world of game creation. Leverage this opportunity to bring vibrant games to life, and join a community of developers who, like you, are on a quest to innovate and transform ideas into gaming realities. Keep learning, keep crafting, and let your journey with Zenva open an array of possibilities in your game development adventure.

Python Blog Image

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