Godot Enum: How to Use Enums in GDScript

An enum is a set of named constants. It replaces magic numbers like state = 2 with words like state = State.JUMP:

extends Node

enum State { IDLE, RUN, JUMP }

var state: State = State.IDLE

func _ready():
	print(State.IDLE, " ", State.RUN, " ", State.JUMP)
	state = State.JUMP
	if state == State.JUMP:
		print("In the air")

0 1 2
In the air

Values start at 0 and count up. Enum names use PascalCase and their keys UPPER_SNAKE_CASE.

Custom Values

Give a key a value with =. Keys after it continue counting from that value:

extends Node

enum Rarity { COMMON = 1, RARE = 5, EPIC, LEGENDARY = 20 }

func _ready():
	print(Rarity.COMMON, " ", Rarity.RARE, " ", Rarity.EPIC, " ", Rarity.LEGENDARY)

1 5 6 20

Getting the Name of an Enum Value

An enum value is an int, so print(state) prints a number. To show the name, look it up in the enum. A named enum is a read-only dictionary of names to values:

extends Node

enum State { IDLE, RUN, JUMP }

func _ready():
	var state := State.RUN
	print(state)
	print(State.find_key(state))
	print(State.keys()[state])
	print(State)

1
RUN
RUN
{ "IDLE": 0, "RUN": 1, "JUMP": 2 }

find_key() always works. keys()[value] only works when the values are 0, 1, 2 and so on with no gaps, because it indexes the list of names.

Looping Over an Enum

Because the enum is a dictionary, the usual dictionary methods work on it:

extends Node

enum Weapon { SWORD, BOW, STAFF }

func _ready():
	for weapon_name in Weapon:
		print(weapon_name, " = ", Weapon[weapon_name])
	print(Weapon.size(), " weapons")
	print(Weapon.has("BOW"), " ", Weapon.values())

SWORD = 0
BOW = 1
STAFF = 2
3 weapons
true [0, 1, 2]

Unnamed Enums

An enum without a name puts its keys straight into the script as constants:

extends Node

enum { LEFT, RIGHT, UP, DOWN }

func _ready():
	var direction := UP
	print(direction)
	print(direction == UP)

2
true

They are shorter to type but cannot be used as a type and have no keys(). Prefer named enums.

Enums with match

match reads well with enums, one branch per state. This is the core of a simple state machine:

extends Node

enum State { IDLE, RUN, JUMP }

func describe(state: State) -> String:
	match state:
		State.IDLE:
			return "standing still"
		State.RUN:
			return "running"
		State.JUMP:
			return "jumping"
	return "unknown"

func _ready():
	for state in State.values():
		print(describe(state))

standing still
running
jumping

See match for patterns, guards and wildcards.

Exporting an Enum

An exported variable with an enum type shows a drop-down in the Inspector:

extends CharacterBody2D

enum Team { RED, BLUE, GREEN }

@export var team: Team = Team.RED
@export_enum("Warrior", "Mage", "Rogue") var job: int

@export_enum gives the same drop-down without declaring an enum. It stores the index (0, 1, 2) in an int, or the text itself if you type the variable as String.

Enums from Another Script

An enum belongs to its class. Other scripts reach it through the class name, so a Player script with class_name Player and enum State is used as Player.State.RUN:

extends Node

class Door:
	enum Lock { OPEN, LOCKED, JAMMED }
	var lock: Lock = Lock.LOCKED

func _ready():
	var door := Door.new()
	print(door.lock == Door.Lock.LOCKED)
	print(Door.Lock.find_key(door.lock))

true
LOCKED

Enums as Bit Flags

Give each key a power of two and combine them with |. Test one with &:

extends Node

enum Element { FIRE = 1, ICE = 2, POISON = 4 }

func _ready():
	var resist := Element.FIRE | Element.POISON
	print(resist)
	print(resist & Element.ICE != 0)
	print(resist & Element.POISON != 0)

5
false
true

For flags edited in the Inspector, use @export_flags("Fire", "Ice", "Poison") var resist := 0.