Constructor method

The constructor method is a special function that runs when you create a new object from a class. Think of it as a setup recipe that runs automatically to make your new object ready for use: it's a place to give default values to properties and do other setup work.

In GDScript, you define a constructor by writing the _init() method in your script.

For example, when you write Sprite2D.new(), you're telling Godot to create a new sprite object. Behind the scenes, Godot runs that sprite's _init() method to set up all its initial properties and get it ready to use.

You can use the constructor to define exactly how you want new objects to be configured when they're created. This is where you set starting values for variables, connect signals, or do any other setup work that needs to happen right away.

Note that _init() runs as soon as you create an instance of the class. For example, if you create a script called HurtBox3D with the following code:

class_name HurtBox3D extends Area3D

signal took_hit(hit_box: HitBox3D)

func _init() -> void:
	monitoring = true
	monitorable = true
	area_entered.connect(func _on_area_entered(area: Area3D) -> void:
		if area is HitBox3D:
			took_hit.emit(area)
	)

The _init() method will run whenever you write the code var hurt_box = HurtBox3D.new() in your project. It will also run for any HurtBox3D node you add to your scene in the editor.

The constructor runs before nodes are ready

The constructor method _init() runs before adding nodes to the scene tree. So, accessing other nodes or resources that have not been loaded yet in the _init() method is not safe.

If you need to access the properties of other nodes, the constructor method is not the right place to do it. Instead, use the _ready() method or signals like ready or tree_entered. For more information, see our study guide on Node creation and the ready function.

Passing arguments to the constructor

You can pass arguments to the constructor method when you create a new class instance. To do this, you need to define a constructor method that accepts parameters.

For example, here's a HitBox3D class that represents an area that deals damage when another object enters it. You can define a constructor method that takes a damage parameter:

class_name HitBox3D extends Area3D

var damage := 1

func _init(p_damage: int) -> void:
	damage = p_damage

When you create a new instance of the HitBox3D class, you can pass the damage value as an argument. The following line creates a new HitBox3D instance that deals 5 damage:

var hit_box := HitBox3D.new(5)

Why did you name the parameter p_damage and not just damage?

Using the prefix p_ in front of parameter names is a convention used in some programming languages like C++. It differentiates the parameter from the class property with the same name.

You could also write the code like this in GDScript:

func _init(damage: int) -> void:
	self.damage = damage

In GDScript, local variables and parameters take precedence over class properties with the same name. So, you can use the same name for the parameter and the class property and use the self keyword to refer to the class property when needed.

Either convention is fine. You'll see both used in the Godot community.

Gotcha: Be careful with constructor arguments

You should be careful when adding constructor arguments to your scripts, as we did on the hitbox above:

func _init(p_damage: int) -> void:
	damage = p_damage

When you create objects only by calling ClassName.new() in code, you can freely use constructor arguments. However, there's an important limitation to keep in mind: Godot's built-in systems, like creating a node from the Scene dock, always call _init() without any arguments.

If you create nodes in the editor or if you're using Godot's resource loading functions like load() and preload(), your script's _init() method should either take no arguments or use optional arguments. If your _init() method requires arguments, these core Godot features won't work with your script.

To make the hitbox example work with creating new nodes in the editor, you can define a default value for the p_damage parameter:

func _init(p_damage := 1) -> void:
	damage = p_damage

Also, using required constructor arguments can complicate inheritance. If you inherit from a class that has constructor arguments, you'll need to handle passing those arguments up to the parent class.

There are ways around these limitations: You can use either custom constructor methods or fluent interfaces to use required arguments while staying compatible with Godot's built-in loading and editor tools.