GDScript Constants: const, preload and Read-Only Data

A constant is a name for a value that never changes. Declare it with const:

extends Node

const MAX_HEALTH = 100
const GRAVITY := 980.0
const GAME_TITLE: String = "Star Hopper"

func _ready():
	var health := MAX_HEALTH
	print(GAME_TITLE, ": ", health, "/", MAX_HEALTH, " HP, gravity ", GRAVITY)

Star Hopper: 100/100 HP, gravity 980.0

Constants use UPPER_SNAKE_CASE. Like variables, they may carry a type (: String) or infer one (:=).

A Constant Cannot Change

Assigning to a constant is an error the editor shows at once:

const MAX_HEALTH = 100

func _ready():
	MAX_HEALTH = 200
	# Parse Error: Cannot assign a new value to a constant.

Its value must also be known before the game starts. Numbers, strings, other constants, math on them and a few built-in functions work. Anything that needs the running game does not: const START = Time.get_ticks_msec() is an error, so use a var for it.

Constant Arrays and Dictionaries Are Read-Only

A constant array or dictionary cannot be changed, not even with a method like append():

extends Node

const LEVELS = ["forest", "cave", "castle"]
const PRICES = {"sword": 50, "shield": 30}

func _ready():
	print(LEVELS[1], " costs nothing, a sword costs ", PRICES["sword"])
	print(LEVELS.size(), " levels")
	print(LEVELS.is_read_only())

cave costs nothing, a sword costs 50
3 levels
true

Calling LEVELS.append("tower") here prints Array is in read-only state. as an error and the array stays the same. If you need a list that grows, declare it with var, or copy the constant: var levels := LEVELS.duplicate().

Constants on a Class

A constant belongs to its class, so other scripts can read it through the class name:

extends Node

class Weapon:
	const MAX_LEVEL = 5
	const DAMAGE_PER_LEVEL = 8

func _ready():
	print(Weapon.MAX_LEVEL * Weapon.DAMAGE_PER_LEVEL)

40

The same works with a script that has a class_name: Player.MAX_SPEED from any other script. See classes.

const with preload

preload() loads a file when the script loads, so it fits in a constant. This is the usual way to keep a scene you spawn often:

const BulletScene = preload("res://scenes/bullet.tscn")

func shoot():
	var bullet := BulletScene.instantiate()
	add_child(bullet)

The name is often written in PascalCase when the constant holds a scene or a class, because you use it like a type. When the path is only known at run time, use load(path) and a variable instead.

Built-in Constants

Godot defines a few math constants you can use anywhere:

extends Node

func _ready():
	print(PI)
	print(TAU)
	print(INF > 1e300)
	print(is_nan(NAN))

3.14159265358979
6.28318530717959
true
true

TAU is 2 * PI, one full turn in radians. Enum values are constants too: see enums.