How to use enums in the Godot Engine

Last Updated on 14. March 2023 by Victor Karp

This Godot Engine tutorial explains how to create enums, compare enum values, get enum items and their names and how to format them.

Table of Contents

What are enums?

Enum is short for “enumeration”. Enums are often used for selecting something from a list, where every item is mutually exclusive. Some examples:

CharacterClass (Fighter, Rogue, Mage)
Time of day (Morning, Noon, Evening, Night)
Color (Red, Green, Blue, Yellow, Orange, Purple)
WeaponType (Knife, Bow, Crossbow, Sword, Lance)

Enums are created like this:

enum CharacterClass {
  FIGHTER,
  ROGUE,
  MAGE,
}

You don’t have to write each item in a new line, but doing so makes long enums easier to read.

Godot’s convention for enum names is to use CamelCase for the name and UPPERCASE for the items.

How to assign an enum item to a variable

You assign the value of an item like this:

enum CharacterClass {FIGHTER, ROGUE, MAGE}
var character_class = CharacterClass.FIGHTER

How to make choices based on an enum

You can use enums to make choices depending on the enum’s value. You can do this by simple comparisons using the equal operator ‘==’ or with the ‘match’ and ‘case’ keywords.

var strength : int
var mana : int
enum CharacterClass {Fighter, Mage}
# Our character is a Fighter
var character_class = CharacterClass.Fighter

func is_mage():
  # This will return 'false'
  return character_class == CharacterClass.Mage

func set_stats_from_character_class():
  # Compare character_class to something
  match character_class:
    # This will be executed
    CharacterClass.Fighter: 
      strength = 10
      mana = 2
    # This will not be executed
    CharacterClass.Mage:
      strength = 2
      mana = 10

How to export enum variables to the Inspector

Like any other variable, enums can be made accessible in a scene by using the ‘export’ keyword. There are two ways to do this.

This tutorial was written for Godot 3. If you are using Godot 4, write @export instead of export.

enum CharacterClass {FIGHTER, ROGUE, MAGE}

# This defaults to the first enum item, which is Fighter
export (CharacterClass) var default_class

# Default to Rogue
export (CharacterClass) var my_class = CharacterClass.ROGUE

Exported variables of the enum type can be changed in the Inspector

Enums are saved as integers, their names don’t matter

Enum values are compared and saved as integers, not by their name. This can lead to some nasty surprises. The following code defines three character classes and exports them, so a scene that uses this script can select as class in the Inspector:

enum CharacterClass {FIGHTER, ROGUE, MAGE}
export (CharacterClass) var my_class

Let’s say you have selected ‘Mage’ in the Inspector. You now add a new character class between Fighter and Rogue:

enum CharacterClass {FIGHTER, BARD, ROGUE, MAGE}
export (CharacterClass) var my_class

Suddenly the scene that previously used ‘Mage’ switches to ‘Rogue’, because Rogue now has the index that Mage previously had. You can prevent this by explicitly assigning integer values to every enum item:

enum CharacterClassWithInts {FIGHTER = 0, ROGUE = 1, MAGE = 2}

The integer values can be arbitrary. The important part is that they are unique and don’t change.

How to get an enum item’s string value

Sometimes you’ll want to use an enum’s name for a Label. However, printing an enum’s value only returns its position in the enum as an integer:

enum CharacterClass {FIGHTER, ROGUE, MAGE}
var my_class = CharacterClass.MAGE

func get_my_class():
  # This returns '2'
  print(my_class)

To get the string instead, we have to get the enum’s keys (the items it holds) and then ask for the string value at a certain position.

enum CharacterClass {FIGHTER, ROGUE, MAGE}
var my_class = CharacterClass.MAGE

func get_my_class_as_string():
  # This returns 'MAGE'
  print(CharacterClass.keys()[my_class])

The parentheses and brackets can make this difficult to read. Here’s the same code, but split up:

enum CharacterClass {FIGHTER, ROGUE, MAGE}
var my_class = CharacterClass.MAGE

func get_my_class_as_string():
  var keys = CharacterClass.keys()
  var my_class_name = keys[my_class]
  # This returns 'MAGE'
  print(my_class_name)

How to format the enum’s name nicely

You could now assign the string to a Label, but you’ll most likely not want to have all letters capitalized. You can convert the string using different methods.

var my_class = "FIRE_MAGE"

func print_as_formatted_string():
  print(my_class.to_lower()) # 'fire_mage'
  print(my_class.to_upper()) # 'FIRE_MAGE'
  print(my_class.capitalize()) # 'Fire Mage'

The capitalize() method is especially useful for enum names that use underscores, because it converts all underscores to spaces, capitalizes every first letter of every individual word and makes all other letters lowercase .