Guide to the Godot game engine/Keywords

<-- Global scope Keywords If statements-->

Note:

This page is for Godot 4.x. For the Godot 3.x version, see the archived page.

Keywords

Keywords in Godot are special words used for GDScript. Unfortunately, some of them are not recorded in Godot's class documentation in much detail.

await

The await keyword will wait for the passed signal to be emit.

print(1)
# Creates a 1 second timer
await get_tree().create_timer(1).timeout
print(2)

break

The break keyword ends a looping piece of code. Useful for "forever" loops:

var counter = 0

while true:
  counter += 1
  if counter == 15:
    break

This ends the loop after 15 runs of the code.

continue

The continue keyword is used inside loops. Similar to break, continue skips a single run at the loop. Like breaking it, but instead of ending the whole loop, it only skips the single iteration.

for num in range( 1,5 ):
  if num == 4:
    continue
  print( num )

The above runs 5 times. Num is 1, 2, 3, 4 then 5. If num is 4, it "continues" the loop. Otherwise it prints. So 4 is not printed, but 1, 2, 3 and 5 are.

const

The const keyword can be used in place of var to create a constant, a value that cannot change.

Unlike variables, constants can be used in static functions.

enum

The enum keyword is similar to making integer constants.

enum DrawMode ={
  PEN,
  FILL,
  ERASER,
  LINE,
  BOX,
  SHADING,
  CONTRAST,
  BLEND
}

The code above is a snippet of code from an image editor I once made in Godot. It shows the possible draw modes, like line and fill, as named ints for easier code debugging.

@export

Not to be confused with exporting. The @export keyword is a very powerful keyword.

It allows editing the value in the Inspector dock, and it saves changes per-instance.

For a basic one, try @export var max_health:int.

You can even use templates and ranges:

# This allows a range of 0 to 100 with a step of 2
@export_range( 0, 100, 2 ) var number := 50

# This allows linking a file path
@export_file() var file_path :String

# This asks for a file path that ends with ".json" or ".md"
@export_file(".json", ".md" ) var specific_extension_file_path :String

# You can also try "String" with this one
@export_enum( Number1, Number2, Number3 ) var dropdown_menu_int := 0

# This creates a slider to change the float with a step of 0.0001
@export ( 0, 1, 0.0001 ) var float_with_range := 0.5

extends

The extends keyword tells Godot that a script inherits the properties of the given Object.

It must be at the very top of a script. Only tool can go before it.

for

The for keyword runs the indented block of code after it for every item from a given value.

for i in ["Hello", "I", "am", "human", 1, 2, 3]:
  print( i )

in

Often used inside if statements. It evaluates as true if the value before it is inside the value after it. It can check:

If a value is in an Array
If a key is in a Dictionary
If a string of text contains another string of text
If an Object contains a property or constant of the same name

Among other things. "h" in "Hello" would be false. "Hello" does not have a lowercase "h" in it. If you want case insensitive search, call to_lower() on both values to convert every letter to lowercase (or to_upper() for uppercase - all capitals).

is

Often used in if statements. It checks if the value before it is of the type after it.

print( "Hello" is String ) # True
print( 52434 is int ) # True
print( bool( "52434" ) is bool ) # True
print( load( "res://icon.png" ) is StreamTexture ) # True
print( load( "res://icon.png" ) is Texture ) # True

load

Okay, load is technically described in global scope. However, it is very much defined as a keyword, so it would make no sense if it were not here.

It loads a file from your FileSystem when called. It takes a single argument: a file path.

File paths must be relative to your project folder or player save folder and not lead outside!

Valid examples:

load( "res://assets/weapons/sword.png" )
load( "res://entities/chicken_egg.tscn" )
load( "user://custom_entities/mutant_monster.tscn" )

res leads to your project folder. user leads to the player's save folder. This is typically %appdata%/roaming/godot/app_userdata/<project_name> unless the ProjectSetting Config/Use Custom User Dir and Config/Custom User Dir Name are set, in which case it's %appdata%/roaming/<ProjectSettings:Config/Custom User Dir Name>.

Note:

If you are using load to load files in runtime, you need to set ProjectSettings.editor/export/convert_text_resources_to_binary to false, or the files might not load as expected in an exported build.

master

The master keyword is part of a series 5 multiplayer keywords. It makes it so only the "master" calls a function if used.

remote master func take_damage( damage ):
  health -= damage
  rpc( "set_health", health )

You don't want to call this on a puppet to help prevent bugs.

@onready

The @onready keyword goes before the var keyword. It allows using a dynamic number that or getting a node using a nodepath, and is set before the _ready() function call.

@onready var sword_node = $hand/sword

pass

The pass keyword is used as a blank line of code. Use it after an "if" statement or "for" statement or after a function declaration to count as a "block of code" (to remove the error) without doing anything. This is called an "empty" if statement or a "stub function".

if true:
    pass

preload

See load. The file can be relative to the script that calls it or "res". The resource is loaded when the script is, preventing stalls during the running game. However, files must exist or there will be an error, and the path must be constant (i.e: not changeable).

res://game/game.gd:

preload( "entities/thing.tscn" )

or:

preload( "res://game/entities/thing.tscn" )

puppet

The puppet keyword is one of a series of 5 multiplayer keywords. Use it before "func" but after "remote". It makes a function only call to non-masters.

remote puppet func set_health( v ):
  health = v

You don't want to call this to the master to stop players cheating.

remote

Use the remote keyword before the "func" keyword to allow a function to be called remotely by other peers in multiplayer when calling "rpc", "rpc_id", "rpc_unreliable" or "rpc_unreliable_id". Beware of cheating and security threats when doing this!

func hit( ):
  health -= 1
  rpc( "player_hit", health )

remote func player_hit( hp ):
  if get_tree().get_rpc_sender_id( ) != get_network_master( ):
    return # This means a player is trying to cheat
  health = hp

See puppet and master for more info. Use remotesync to call the function locally as well as via the network.

WARNING: Malicious hackers can use your game to retrieve or delete data, or players can cheat, if you do not add checks to stop them. Don't ever add remote to functions that delete or create files unless you know what you're doing.

remotesync

See remote. This keyword also calls a function locally instead of only calling them over the network. Good for telling other peers as well as the master that the character has jumped.

return

The return keyword is used to end the function. For functions that are called and "return" a value, the return keyword is where to go.

func get_some_value( ):
  return "some string"

It also ends the function call, so can be used in an if statements to skip the rest of the function. It does not require a return value, and by default returns null.

static

Usually, to call an Object's function, you need an instance of it. If you use the static keyword before the "func" keyword, you'll be able to call it from a non-instance. However, you can only use other static functions or those in global scope. You cannot use member variables.

In the following example, Weapon is a custom Resource.

Weapon.gd

extends Resource
class_name Weapon

export var damage = 5
const DAMAGE = 5

static func get_damage( ):
  # Cannot use an outside variable here
  return DAMAGE # Can use a constant though

Weapon.new( ).get_damage( ) becomes Weapon.get_damage( ), saving memory and CPU resources if you were to want to find a value.

@tool

The @tool keyword tells Godot that a script runs in the editor. These sorts of scripts are commonly referred too as tool scripts. It won't run if the script is only open in the Script edit screen. It must be attached to a node in the scene, or a node with the script must be in the editor.

It must always be placed before the extends keyword. It can be placed on the same line as the extends if you find it more convenient.

If you have a tool script, scripts that it inherits and scripts that inherit it won't run, unless they are also tool scripts. All nodes themselves run in the editor, but only if placed into it's interface with editor plugins.

See also: editor plugins (and the plugins chapter), very powerful things.

var

The var keyword creates a variable. They are automatically freed from memory when they leave the scope (an indented block of code unindents, for example.)

var global_varible := 1

func _ready():
  some_function(7)
 
func some_function(argument):
  print(argument)
  print(global_variable)
  var temporary_variable = 2
  print(temporary_variable)
  if true:
    var another_variable = 3
    print(another_variable)
    print(temporary_variable)
  print(another_variable) # Error: the identifier "another_variable" isn't declared in the current scope, since it is not declared in an lower indentation.

while

The while keyword runs the indented block of code after it until the if-statement after it is no-longer true. It won't run if it starts as false.

var i = 0
while i < 50:
  print(i)
  i += 1

Guide to the Godot game engine edit

GDScript