Classes in GDscript

The body of a script file is an unnamed class, and it can only be referenced externally as a resource or file. Class syntax is meant to be compact and can only contain member variables or functions. Static functions are allowed, but not a static member (this is in the spirit of thread-safety since scripts can be initialized in separate threads without the user knowing). In the same way, member variables (including array and dictionaries) are initialized every time an instance is created.

Below is the example of a class file;

# Saved as a file named 'myclass.gd.' 

var a = 5

func print_value_of_a():
    print(a)

Inheritance

A class can inherit form

A global class
Another class file
An inner class inside another class file.

Multiple inheritances are not allowed.

Inheritance uses the extends keyword:

# Inherit/extend a globally available class.
extends SomeClass

# Inherit/extend a named class file.
extends "some file.gd."

# Inherit an inner class in another file.
Extends "somefile.gd."SomeInnerClass

To check if a given instance inherits form a given class, the is keyboard can be used:

# Cache the enemy class.
const Enemy = preload("enemy.gd")

# [...]

# Use 'is' to check inheritance.
if (entity is Enemy):
    entity.apply_damage()

To call a function in the base class (i.e., one extend –ed in our current class), prepend. (dot) to the function name:

It is useful because functions in extending classes replace functions with the same name in their base classes. So if we still want to call then, we can use it. (dot) like the super keyword in other languages:

func some_func(x):
    .some_func(x) # Calls the same function on the parent class.

Class Constructor

The class constructor, called on class instantiation, is named _init. The constructors of parent classes are called automatically when inheriting a class. So there is usually no need to call .init().

Unlike the class of a regular function like in the above example with .some_func, if the constructor from the inherited class takes arguments, they are passed like this:

func _init(args).(parent_args):
   pass

This is better explained through examples. Say we have this scenario:

# State.gd (inherited class)
var entity = null
var message = null

func _init(e=null):
    entity = e

func enter(m):
    message = m


# Idle.gd (inheriting class)
extends "State.gd."

func _init(e=null, m=null).(e):
    # Do something with 'e.'
    message = m

There are some things to keep in mind here:

If the inherited class (State.gd) defines an _init constructor that takes arguments (e in this case), then the inheriting class (Idle.gd) has to define _init as well and pass appropriate parameters to _init from gd.
gd can have a different number of arguments than the base class State.gd.
In the example above, e passed to the gd constructor is the same e moved into Idle.gd.
If gd's _init constructor takes 0 arguments, it still needs to pass some value to the State.gd base class even if it does nothing. Which brings us to the fact that we pass literals in the base constructor as well, not just variables.

Example

#Idle.gd
Func _init().(5):
pass

Inner classes

A class file can contain inner classes. Inner classes are defined using the class keyword. They are instanced using the ClassName.new() function.

# Inside a class file.

# An inner class in this class file.
class SomeInnerClass:
    var a = 5
    func print_value_of_a():
        print(a)

# This is the constructor of the class file's main class.
func _init():
    var c = SomeInnerClass.new()
    c.print_value_of_a()

Classes as resources

Classes stored as files are treated as the resources. They must be loaded form disk to access them in other classes. This is done using the load or preload functions. Instancing of a loaded class resource is completed by calling the new function on the class object;

# Load the class resource when calling load().
var my_class = load("myclass.gd")

# Preload the class only at compile time.
const MyClass = preload("myclass.gd")

func _init():
    var a = MyClass.new()
    a.some_function()

Exports

Class members can be exported. This means their value gets saved with the resource they are attached to. They are available for editing in the property editor. Exporting is done by using the export keyword:

extends Button
export var number = 5 # Value will be saved and visible in the property editor.

An exported variable must be initialized to a constant expression or have an export hint in the form of an argument to the export keyword:

One of the significant benefits of exporting member variables is to have them visible and editable in the editor. Shipping is done by using the export keyword.

One of the primary benefits of exporting members' variable is to have them visible and editable in the editor. This way, artists and game designers can modify values that later influence how the programs run. a special export syntax is provided.

# If the exported value assigns a constant or constant expression,
# the type will be inferred and used in the editor.

export var number = 5

# Export can take a primary data type as an argument which will be
# used in the editor.

export(int) var number

# Export can take a resource type to use as a hint.

export(Texture) var character_face
export(PackedScene) var scene_file

# Integers and strings hint enumerated values.

# Editor will enumerate as 0, 1 and 2.
export(int, "Warrior", "Magician", "Thief") var character_class
# Editor will enumerate with string names.
export(String, "Rebeca", "Mary", "Leah") var character_name

# Named Enum Values

# Editor will enumerate as THING_1, THING_2, ANOTHER_THING.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
export (NamedEnum) var x

# Strings as Paths

# String is a path to a file.
export(String, FILE) var f
# String is a path to a directory.
export(String, DIR) var f
# String is a path to a file, custom filter provided as a hint.
export(String, FILE, "*.txt") var f

# Using paths in the global filesystem is also possible,
# but only in tool scripts (see further below).

# String is a path to a PNG file in the global filesystem.
export(String, FILE, GLOBAL, "*.png") var tool_image
# String is a path to a directory in the global filesystem.
export(String, DIR, GLOBAL) var tool_dir

# The MULTILINE setting tells the editor to show a large input
# field for editing over multiple lines.
export(String, MULTILINE) var text

# Limiting editor input ranges

# Allow integer values from 0 to 20.
export(int, 20) var i
# Allow integer values from -10 to 20.
export(int, -10, 20) var j
# Allow floats from -10 to 20, with a step of 0.2.
export(float, -10, 20, 0.2) var k
# Allow values y = exp(x) where y varies between 100 and 1000
# while snapping to steps of 20. The editor will present a
# slider for easily editing the value.
export(float, EXP, 100, 1000, 20) var l

# Floats with Easing Hint

# Display a visual representation of the ease() function
# when editing.
export(float, EASE) var transition_speed

# Colors

# Color given as Red-Green-Blue value
export(Color, RGB) var col # Color is RGB.
# Color given as Red-Green-Blue-Alpha value
export(Color, RGBA) var col # Color is RGBA.

# Another node in the scene can be exported too.

export(NodePath) var node

It must be noted that even if the script is not while at the editor, the exported properties are still editable.

See below for (tool)

Exporting bit flags

Integers that are used in bitflag can store multiple true/ false values in one property. By using the export hint [int, FLAGS], they can be sent for an editor.

# individually edit a bit of integer.
Export(int,FLAGS) var spell/elements=ELEMENT/WIND|ELEMENT/WATER

Restricting a flag in any number of numbered flags is also possible. The syntax is similar to the enumeration syntax.

# Set any of the given flags from the editor.
export(int, FLAGS, "Fire", "Water", "Earth", "Wind") var spell_elements = 0

In the example, Fire has value 1, and Water has value 2, Earth has value 4, and wind corresponds to value 8. Usually, constants should be defined accordingly.

Using bit flags requires some understanding of bitwise operations. If in doubt, Boolean variables should be exported instead.

Exporting arrays

Exporting arrays works but with an important caveat: while regular arrays are created local to every class instance, exported arrays are shared between all instances. This means that editing in one instance will cause them to change in all other instances. Exported arrays can have initializers, but they must be constant expressions.

# Exported array, shared between all instances.
The # Default value must be a constant expression.

export var a = [1, 2, 3]

# Exported arrays can specify a type (using the same hints as before).

export(Array, int) var ints = [1,2,3]
export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
export(Array, Array, float) var two_dimensional = [[1, 2], [3, 4]]

# You can omit the default value, but then it would be null if not assigned.

export(Array) var b
export(Array, PackedScene) var scenes

# Typed arrays also work, only initialized empty:

export var vector3s = PoolVector3Array()
export var strings = PoolStringArray()

# Regular array created locally for every instance.
The # Default value can include run-time values, but can't
# be exported.

var c = [a, 2, 3]

Setters/getters

It is useful to know when a class' member variable changes for whatever reason. It may also be desired to encapsulate its access in some way.

For this, GDScript provides a setter/getter syntax using the setget keyword. It is used directly after a variable definition:

Whenever the value of a variable is modified by an external source (i.e., not from local usage in the class), the setter function (setterfunc above) will be called.

This happens before the value is changed. The setter must decide what to do with the new value. Vice-versa, when the variable is accessed, the getter function getterfunc above) must return the desired value.

Example:

var my_var setget my_var_set, my_var_get

func my_var_set(new_value):
    my_var = new_value

func my_var_get():
    return my_var # Getter must return a value.

Either of the setter or getter function can be omitted:

# Only a setter.
var my_var = 5 setget myvar_set
# Only a getter (note the comma).
var my_var = 5 setget ,myvar_get

Get/Setter is especially useful when exporting variables to the editor in tool scripts or plugins, for validating input.

Local access will not trigger the setter and getter. Here is an illustration of this:

func _init():
    # Does not trigger setter/getter.
    my_integer = 5
    print(my_integer)

    # Does trigger setter/getter.
    self.my_integer = 5
    print(self.my_integer)

Next TopicTool mode in GDscript

← prev next →