This cheatsheet is meant to be a handy reference for both beginners and experienced GDScript users. So, whether you're just starting out or looking to review up on your GDScript knowledge, this cheatsheet will be your go-to resource. We'll cover all the essential topics you need to know about GDScript, from basic syntax to advanced concepts, complete with code snippets and examples. So, let's get started!
Brief overview of GDScript
GDScript is a high-level, both static and dynamically typed programming language specifically designed for the Godot game engine. It's easy to learn, especially if you're familiar with Python, as its syntax and structure are quite similar. GDScript is powerful and versatile, allowing you to create complex game logic with minimal effort.
Some key benefits of using GDScript include:
Tight integration with Godot's engine and editor
Clear and concise syntax, allows you to focus on game development
Designed for rapid prototyping and iteration
Basic Syntax
Let's begin by going over the basic syntax of GDScript. Here are the topics we'll cover:
Comments
Single-line comments:
# This is a single-line commentMulti-line comments: For multi-line comments you need to prefix every line with
#hash, sadly in GDScript there's no easier way. Be careful with"""three quotes"""while it looks like multi-line comments, it's actually a multi-line strings and will be silently executed by the interpreter!
"""
This is a multiline string, not a comment!
And thus it will be parsed by interpreter...
"""
# Now this
# is a multiline comments
# Interpreter will not read this
Basic Output
To print output in GDScript, use the print() function:
print("Hello, Godot!")
Indentation
GDScript uses indentation to define code blocks, just like Python:
func _init():
pass
Variables
In GDScript, variables can be declared using the var keyword. You can also specify the type of the variable using a colon (:) followed by the type name.
Declare a variable:
var my_variable = 10Change the value of a variable:
my_variable = 20Declare a variable with a specific type:
var my_int: int = 5
Here are some common data types in GDScript:
int: Integer numbersfloat: Floating-point numbersbool: Boolean values (trueorfalse)String: Text strings
var x: int = 42
var y: float = 3.14
var is_active: bool = true
var name: String = "https://godot.community"
Arrays and Dictionaries
GDScript also provides built-in data structures like arrays and dictionaries:
Array: Ordered list of elementsDictionary: Key-value pairs
var my_array: Array = [1, 2, 3, 4, 5]
var my_dict: Dictionary = {"key1": "value1", "key2": "value2"}
Static Variables
Static variables belong to a class rather than an instance of the class. To define a static variables, use the static keyword:
Declare a static variable:
static var my_static_variable = 30Change the value of a static variable:
my_static_variable = 40Since statics belong to the class, you can also use
MyClass.my_static_variable = 40
Constants
- Declare a constant:
const MY_CONSTANT = 100
Operators
Arithmetic
Addition:
a + bSubtraction:
a - bMultiplication:
a * bDivision:
a / bModulus:
a % bPower:
a ** b
Comparison
Equal:
a == bNot equal:
a != bLess than:
a < bLess than or equal:
a <= bGreater than:
a > bGreater than or equal:
a >= b
Logical
And:
a and bora && bOr:
a or bora || bNot:
not aor!a
Bitwise
Bitwise AND:
a & bBitwise OR:
a | bBitwise XOR:
a ^ bBitwise NOT:
~aLeft shift:
a << bRight shift:
a >> b
Assignment
Assign:
a = bAdd and assign:
a += bSubtract and assign:
a -= bMultiply and assign:
a *= bDivide and assign:
a /= bModulus and assign:
a %= bPower and assign:
a **= bLeft shift and assign:
a <<= bRight shift and assign:
a >>= bBitwise AND and assign:
a &= bBitwise OR and assign:
a |= bBitwise XOR and assign:
a ^= b
Variable Typing
Dynamic Typing
In GDScript, variables are dynamically typed by default, meaning their type is interchangeable at runtime. For example:
var my_variable = 10
my_variable = "Hello, GDScript!" # This is allowed
Static Typing
Static typing can be used to explicitly specify the type of a variable, meaning their type is not interchangeable at runtime. This can help catch potential bugs and improve code readability:
var my_int: int = 5
my_int = "Hello, GDScript!" # This will cause an error
Static type can also be inferred by using := followed by value. Be careful when using this though, sometimes verbosity is better.
var my_int := 5
my_int = "Hello World" # Error, because my_int has been statically inferred as int
Control Structures
Control structures are the building blocks of your GDScript code, allowing you to create complex logic and control the flow of your program. Let's learn about the different types of control structures in GDScript:
Conditional statements
If
The if statement is used to execute a block of code if a certain condition is true:
if x > 0:
print("x is positive")
Else
The else statement is used to execute a block of code if the condition in the if statement is false:
if x > 0:
print("x is positive")
else:
print("x is not positive")
Elif
The elif (short for "else if") statement is used to test multiple conditions in a single if statement:
if x > 0:
print("x is positive")
elif x < 0:
print("x is negative")
else:
print("x is zero")
Loops
For
The for loop is used to iterate over a sequence, such as an array or a range of numbers:
for i in range(5):
print(i) # Prints 0, 1, 2, 3, 4
for item in my_array:
print(item) # Prints each item in my_array
While
The while loop is used to repeatedly execute a block of code as long as a certain condition is true:
var i = 0
while i < 5:
print(i) # Prints 0, 1, 2, 3, 4
i += 1
Break and Continue
The break statement is used to exit a loop prematurely:
for i in range(10):
if i == 5:
break
print(i) # Prints 0, 1, 2, 3, 4
The continue statement is used to skip the rest of the current iteration and proceed to the next one:
for i in range(5):
if i == 2:
continue
print(i) # Prints 0, 1, 3, 4
Functions
Functions are blocks of code that can be defined and called by name. They can take input, perform some action, and return a result. Let's learn how to work with functions in GDScript:
Defining functions
To define a function, use the func keyword followed by the function name and a pair of parentheses:
func my_function():
print("Hello, GDScript!")
Built-in functions
GDScript comes with a variety of built-in functions that you can use in your code. Some examples include:
print(): Prints a message to the consolerandi(): Returns a random integerlen(): Returns the length of a sequence (e.g., an array or a string)
Function arguments
Functions can take input in the form of arguments. To define a function with arguments, include the argument names inside the parentheses:
func add(a, b):
return a + b
You can also define the types of the arguments, it will spit out an error if you try to pass different types to the arguments.
func add(a: int, b: int):
return a + b
Return values
Functions can return a result using the return keyword:
func add(a, b):
return a + b
var result = add(2, 3) # result is 5
You can also define the type of the returned value by appending -> ReturnType to the function declaration, it will spit out an error if you try to return something that isn't the correct type.
# Returns integer
func add(a: int, b: int) -> int:
return a + b
# This won't work
func add(a, b) -> int:
return "Hello"
Optional argument values
Functions can have optional argument as value by assigning it at the definition:
func multiply(a: int, b: int = 2) -> int:
return a * b
var result = multiply(2, 3) # result is 6
var result = multiply(4) # result is 8
Note: Optional arguments can only be positioned after you've defined all mandatory arguments.
# Valid, optional placed last
func sum(a: int, b: int, c: int = 0) -> int:
return a + b + c
# Invalid, can't have optional before mandatory
func sum(a: int, b: int = 0, c: int) -> int:
return a + b + c
Static Functions
Static functions are functions that belong to a class rather than an instance of the class. To define a static function, use the static keyword:
class_name MyClass extends Node
static func my_static_function():
print("This is a static function.")
func _init() -> void:
my_static_function()
MyClass.my_static_function()
Since statics belong to the class, you can use MyClass.my_static_function() to invoke it.
Classes and Objects
In GDScript, a script file represents a class and objects are instances of classes. You can create instances of a class using the new() method.
Defining Classes
To define a class, simply create a new script file (e.g., my_class.gd). The name of the file should represents the name of the class. Create a new file called player.gd with the following content:
class_name Player
var health: int = 100
var name: String = "Unnamed"
func take_damage(amount: int):
health -= amount
if health <= 0:
print("Player", name, "has died!")
Creating Object
var player = Player.new()
player.name = "John Doe"
player.take_damage(50)
Properties
Properties are variables that belong to a class or an object. They can be used to store data or state:
class MyClass:
var my_property = 0
Methods
Methods are functions that belong to a class or an object. They can be used to perform actions or manipulate data:
class MyClass:
func my_method():
print("Hello, GDScript!")
Inheritance
Inheritance is a way for one class to inherit the properties and methods of another class. To inherit from another class, use the extends keyword:
# Derived class
class_name DerivedClass extends MyBaseClass
func my_method():
print("Hello from the derived class!")
Constructors
Constructors are special methods that are called when an object is initialized. In GDScript, the constructor is named _init:
class MyClass:
func _init():
print("Object initialized!")
Signals and Events
Signals are a way for objects to communicate with each other without relying on direct references. They can be used to decouple your code and make it more modular. Let's learn how to work with signals and events in GDScript:
Defining signals
To define a signal, use the signal keyword followed by the signal name:
signal my_signal
Emitting signals
To emit a signal, you can use the emit_signal method:
emit_signal("my_signal")
However, it's better to ditch those strings, by simply calling emit method inside the signal directly:
my_signal.emit()
Connecting signals to functions
Signals are a way to communicate between objects in Godot. They allow you to decouple your code and create more modular systems.
To connect a signal to a function, use the connect method:
my_object.my_signal.connect(on_my_signal)
func on_my_signal():
print("Signal received!")
There are actually four ways to connect signals, however, this is the recommended approach, instead of the other one (That might more error prone).
Error Handling
Error handling is an important aspect of programming, as it allows you to gracefully handle errors and exceptions that may occur at runtime. In GDScript, you can use the following constructs to handle errors:
Assert
The assert statement is used to check if a condition is true, and if not, raise an error:
assert(x > 0, "x must be positive")
Note: assert is a utility function meant for unit tests. Code inside assert is only executed in debug builds or when running the project from the editor.
Try, Catch, and Throw
GDScript does not have built-in support for try-catch blocks. There are many godot-proposals from people asking for it, however, It has already been stated that try-catch will never come into gdscript.
Quoting from Juan in his post:
Exceptions won't happen. Godot is designed for things to keep working even if state is inconsistent, while at the same time reporting errors
File I/O
Working with files is a common task in many applications. In GDScript, you can use the File class to read from and write to files:
Writing a file
To write to a file, use the store_string, store_line or other store_* methods:
var player_name = "Septian"
var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE)
file.store_string(player_name)
Reading and writing
To read from a file, use the get_as_text or other get_* method:
var file = FileAccess.open("user://save_game.dat", FileAccess.READ)
var player_name = file.get_as_text()
print(player_name)
Closing files
To close a file, use the close method:
file.close()
FileAccess will automatically closes the file when it goes out of scope or set to null. However it's better to be explicit when handling with I/O.
Useful Tips and Tricks
Here are some handy tips and tricks to help you write better GDScript:
Use clear and descriptive variable and function names
Keep your functions short and focused
Use comments to explain complex or important code
Follow the GDScript style guide
Follow the GDScript code ordering
String manipulation
- String interpolation:
var result = "The %s has defeated the %s in %s" % ["Player", "Boss", "Combat"]
print(result)
# Will prints:
# The Player has defeated the Boss in Combat
Concatenate strings:
var result = "Hello, " + "GDScript!"Format strings:
var result = "Hello, %s!" % "GDScript"Split strings:
var words = "Hello, GDScript!".split(", ")
Array and Dictionary operations
Add an item to an array:
my_array.append(item)Remove an item from an array:
my_array.erase(item)Get the length of an array:
var length = my_array.size()Check if a key exists in a dictionary:
if my_dict.has(key):
Type casting
- Cast a value to a specific type:
var my_int = int("42")
Debugging
Print a message to the console:
print("Hello, GDScript!")Set a breakpoint:
breakpoint
Resources
To learn more about GDScript and the Godot game engine, check out these great resources:
That's it for this GDScript Cheatsheet! I hope you found it useful and informative. Feel free to bookmark this post and refer back to it whenever you need a quick reference for GDScript. Happy coding!
This cheatsheet is updated for Godot 4.2, GDScript is an evolving language, if you find outdated information, please let me know so I can fix it!
Top comments (0)