This study guide goes over how to read and browse the code reference, also called the technical reference. It summarizes and builds upon what we learned in this module.You can use the code reference to:
Discover new nodes, functions, and properties to use in your code.
Learn more about a code feature you already know.
Remind yourself of how a function or a property works or what it does.
Search for the name of a function or node you don't remember precisely.
However, it does not tell you how to apply the nodes and functions to specific game mechanics. The technical reference lays down a large selection of tools for you to pick from, and you need to use your creative problem-solving skills to combine them and produce gameplay.It's a resource you will come back to frequently. Even as a professional, it's completely normal to forget about functions and syntax, you name it. Godot has over a hundred nodes and thousands of functions. You can't know everything by heart!Developers memorize the functions and syntax they use frequently through repetition. But for the most part, we don't really get out of our way to learn anything by heart. Instead, we learn to search and find information fast.In this guide, we'll go over:
How to access and search the code reference.
How to read a code reference page.
Shortcuts to navigate reference pages fast.
We'll use the Area2D node as an example to show you how to search and find information, and take this opportunity to look at a few functions.
How to access and search the code reference
You can search the code reference by going to the Help menu. Click HelpSearch Help or press f1 (on Mac: ⌥space) on your keyboard to open the search window.You can type any term you want to search for in the search bar. For example, type "area2d" to find the Area2D node.The search works with case-insensitive partial matches. For example, you can type "area" to find the Area2D node and any entry that contains this word.The search is not fuzzy, however. If you search for "getnode", you won't find the get_node() function because of the underscore. You have to search for "get_", "_node", or any part of the function name.A drop-down menu at the top right of the window lets you filter what to search. For example, the option Classes Only filters the search to show only nodes and other types, removing the thousands of functions and properties from the results. It makes scanning the list of nodes and resources built into Godot easier.Search for "area2d" again, and double-click on the Area2D node or press ↵ to open the reference page.
How to read a code reference page
Every code reference page has the same structure. At the top, you find the classes this node inherits from (extend). You can click a type to jump to the corresponding reference page.The line that says Inherits lists all types this class inherits from. To have a complete picture of all the features available to this class, you need to check all the parent types.Most classes in Godot inherit the types on the right of the list. For example, every node extends the Node class. That's how every node has access to the add_child() function.Then, you get a short description followed by a long one. The description is most useful when learning about a new class you haven't used before, as it gives you an overview of the class's purpose.Sometimes, the long description refers to other related classes. They're good pages to check out to better understand the class you're looking at.If you scroll down, you may see links to the official manual in the Online Tutorials section. They may take you to a manual page dedicated to a related topic. They can sometimes be useful complements to the reference page and learning material.After that, you will find a table of contents. You will find lists of properties, methods, signals, and constants this class provides. You can scan the list to get a sense of the provided features. If you spot any interesting entry, click it to jump to the corresponding technical documentation. You can also scroll to read each entry sequentially.This image only includes the properties section, but you will also find sections for methods, signals, and constants (or enumerations, which are a specific kind of constants).
Reading method and property descriptions
Please scroll down a bit to the Methods section. Notice the get_overlapping_areas() function. In short, it's a very useful function that tells you which area nodes overlap with your area node. You can use it to detect, for example, a player in range of an interactable object.The line tells you respectively the function's return type, name, parameters, and a keyword, here "const". We'll detail what all that means in a second. Click on get_overlapping_areas() to jump to the function's description.Above the description, you can again find the return type, the function name, parameters, and the keyword "const".Each function description starts with the return value type. For example, if it says Array[Area2D], as here, it means that the function returns an array of Area2D nodes. You can store the returned value in a variable or use the function call anywhere you could pass an array.If the return type is void, like for the Node class's _process() function, the function does not return any value. Precisely, it will return the value null, which means no value.Then, you have the function name followed by each of its parameters and the type of each parameter in parentheses. This tells you what data the function needs as an input when calling it. Here's an example of a function with one parameter: Area2D.overlaps_area(). This function tells you if your Area2D node overlaps another specific Area2D node. To call it, you need to pass one node
What a strange type!
Surprisingly, the parameter type says Node instead of Area2D. This is because a TileMap node can contain areas, and the function needs to be compatible with both TileMap and Area2D nodes. The Node type is the parent of all nodes in Godot, so it can accept both.
as an argument in parentheses.After the name and parameters, you will see keywords like "const", "virtual", or nothing:
const means that the function does not modify the object it's called on. It's a read-only function. It doesn't change any properties of the object. The "const" keyword is a convention from the C++ language, that Godot uses under the hood.
virtual means that the function is designed for you to override in your scripts. You can think of it as a hook provided by the engine. You can override the function in your script to add custom behavior. If you don't override it, the function does nothing.
If the function does not have a keyword, it means that the function changes the state of the object: it changes the value of one or more properties.The get_overlapping_areas() function has the "const" keyword. This means that it doesn't modify the Area2D node it's called on; it only returns a list of overlapping areas.Functions like _process() and _unhandled_input() in the Node class are virtual functions. They're designed for you to override in your scripts. For example, you can add custom behavior to _process() to make your node do something every frame.The Node.add_child() function (the add_child() function of the Node class) has no keyword. It means it changes the object's state: It adds a child node to the node it's called on.The documentation of properties is slightly different. It starts with the value type followed by the name. Here, we can see that the monitoring property of the Area2D node is a boolean, which means that its value can only be true or false.Then, there's the default value of the variable. It's the property's value when you create a new instance of the Area2D node. You can also see it when creating a node of that type in a scene in the Inspector dock.Below that, you will also see two functions starting with the words "get" and "set." In Godot, while you generally work with the names of the built-in variables directly, you can also use corresponding setter and getter functions
Setters and Getters
Setters and getters are functions that respectively assign and return the value of a property. They are used to control access to the property and to ensure that the value is valid.Older versions of Godot used to work with setter and getter functions. You couldn't write monitoring = true directly. You had to call the setter function instead: set_monitoring(true). These days, Godot users tend to work with the property names directly.More on Setters and Getters
. When you change the monitoring property, Godot actually calls the set_monitoring() function under the hood. When you read the value of the monitoring property, it calls the get_monitoring() function, which returns the value.Let's wrap this tour of the reference page with signals. Scroll to the area_entered signal of the Area2D node. A signal doesn't have a type, so the entry starts with the signal name.In parentheses, you can see the signal parameters. They indicate the data that the signal sends when it's emitted. Here, the area parameter is an Area2D node. It's the area node that entered this Area2D node.
When connecting the signal to a function, you must ensure the function has the same number and type of required parameters. If you connect the area_entered signal to a function that doesn't accept an Area2D parameter or to a function that takes different parameter types, Godot will report an error.
That's it for how to read the reference page. To round out our overview, let's look at some useful tips to navigate reference pages quickly.
Shortcuts to navigate reference pages
How to quickly jump around a reference page
The little menu at the bottom left of the script editor allows you to quickly navigate to the main sections of a reference page. Click on any of the labels to jump to the corresponding section.In your scripts, this menu lists all the functions defined in the script. In the code reference, it lists the main sections of the reference page.Also, you can search the page by pressing ctrlf (on Mac: ⌘f). This lets you quickly jump to some terms or find functions you don't remember exactly.Lastly, you can go back and forward in your navigation history by pressing alt← (on Mac: ⌥←) and alt→ (on Mac: ⌥→). It's useful to go back to the previous section after clicking on a link or to go back to your script after reading a reference page.
How to jump to a reference page from your script
There's one more feature that's super useful for browsing a reference and navigating your code: control-clicking on symbols in your scripts.When working on a script, you can jump to the definition of any function, variable, or class by pressing the ctrl (on Mac: ⌘) key down and clicking on it.If you click on anything built into Godot, like a function, node type, or variable, you will instantly jump to the corresponding code reference.You can then press alt← (on Mac: ⌥←) to navigate back to your script quickly.If you control-click on a type, variable, function, or signal that you created in your project, it will take you to its definition.
Use this space for questions related to what you're learning. For any other type of support (website, learning platform, payments, etc...) please get in touch using the contact form.
Bonus shortcut for moving Back and ForwardMuseDoesFor those out there that have one of those fancy mice with the Forward and Backward buttons on their side, you can use them in place of Alt Left/Right.
Having said that, I never knew that Alt + Left/Right would move a page, like a webpage, back or forward in its history. So that's something I just learned today. 16May. 26, 2024
Getter & Setter video not workingBort_BortingtonAn error occurred. Please try again later. (Playback ID: N_bDFVuhuryw4LTt)
Anyone else get this error? or is this just on my end?30Sep. 03, 2024
Using SignalsStonemonkeyI'm trying to understand passing values using signals after reading the Glossary entry. I don't understand why in my code the `health` var doesn't update in the `Label` node when the signal is in the `ready` function.
The `Label` only updates if `health_changed.emit(health)` is inside both of the button pressed functions.
```gdscript
extends Control
signal health_changed(altered_health)
@onready var add_health: Button = $"Add Health"
@onready var remove_health: Button = $Remove_Health
@onready var health_display: Label = $Health_Display
var health := 0
func _ready() -> void:
health_changed.emit(health)
connect("health_changed", health_display_update)
func _on_remove_health_pressed() -> void:
health -= 5
print(str(health))
func _on_add_health_pressed() -> void:
health += 5
print(str(health))
func health_display_update(new_health):
health_display.text = str(health)
```20May. 01, 2024
Lesson Q&A
Use this space for questions related to what you're learning. For any other type of support (website, learning platform, payments, etc...) please get in touch using the contact form.