GDScript

Description

A script implemented in the GDScript programming language, saved with the .gd extension. The script extends the functionality of all objects that instantiate it. Calling new() creates a new instance of the script. Object.set_script() extends an existing object, if that object's class matches one of the script's base classes. If you are looking for GDScript's built-in functions, see @GDScript instead. Nullable static types: By default, a statically-typed value cannot be null. Writing ? after a type hint makes the value nullable, allowing it to hold null in addition to values of the base type. Untyped values and Variant can already hold null, so Variant is always nullable and does not take the ? suffix. The suffix is allowed on variables, members, parameters, and return types:

		var health: int?             # An int or null; uninitialized nullable values start as null.
		var player_name: String? = null

		func find_target() -> Node?: # May return null.
			return null
		

The ? suffix works on built-in value types (int?, String?, Vector2?, and so on), enums (including nested enums such as Vector2.Axis?), objects (such as Node?), and collections, where the collection itself is nullable (Array?, Array[int]?, Dictionary[String, int]?). It is not allowed on Variant (already nullable), on void, or on element types: Array[int?] is rejected; write Array[int]? instead. After a null check, the analyzer narrows the value to its non-nullable type, so it can be used safely:

		func take(v: int?) -> int:
			if v == null:
				return -1
			return v + 1 # v is known to be non-null here.
		

Narrowing is recognized for == and != null guards and truthiness checks such as if value:, including else branches, while conditions, and and/or expressions. Local variables of non-object built-in types, including structs, with a non-null initializer or assignment are also narrowed. A false truthiness check does not prove that a value is null, because values such as 0 are also false. Plain member and static variables can be narrowed after a guard; member and self.member refer to the same value. Member narrowing is discarded by calls, property accessors, assignments that may change the value, and await. Properties with a getter or setter are not narrowed. Check the value again after these operations, or copy it into a local variable before checking it. Narrowing is not recognized across break and continue guards or assert statements. Using a nullable value of a non-object built-in type (such as int?, Array?, or Dictionary?) directly (in an operator, subscript, property access, or for loop), or transferring any nullable value to a non-nullable target (assigning, returning, or passing it as an argument), raises the UNSAFE_NULLABLE_ACCESS warning. Set its severity with ProjectSettings.debug/gdscript/warnings/unsafe_nullable_access, or silence a single line with @GDScript.@warning_ignore. Enforcement depends on the type. For non-object built-in types and enums, a null reaching a non-nullable value raises a runtime error. Object references keep GDScript's existing behavior — they may hold null whether or not the type uses ? — so on object types ? only enables narrowing and the transfer warning. Accessing a member or calling a method directly on a nullable object or enum is not flagged, but it still fails at runtime if the value is actually null, so narrow with a null check first.

Methods

				var MyClass = load("myclass.gd")
				var instance = MyClass.new()
				print(instance.get_script() == MyClass) # Prints true
				

Tutorials

• GDScript documentation index