GDScript Variables: var, Scope and Member Variables

A variable holds a value under a name. You create one with var:

extends Node

var player_name = "Ana"
var coins = 0

func _ready():
	coins = coins + 5
	coins += 10
	print(player_name, " has ", coins, " coins")

Ana has 15 coins

Names use snake_case: max_speed, jump_height. They may contain letters, digits and _, and must not start with a digit.

Three Ways to Declare

extends Node

func _ready():
	var a = 10          # dynamic: a can later hold any type
	var b: int = 10     # typed: b can only hold an int
	var c := 10         # inferred: typed as int from the value
	a = "now a string"
	print(a, " ", b, " ", c)

now a string 10 10

A dynamic variable accepts any value at any time. A typed one is checked: b = "text" stops the script with an error before it runs. The static typing page explains when to use each form. Most Godot code uses := because it is short and still typed.

Member Variables and Local Variables

Where you write var decides how long the variable lives:

extends Node

var health := 100  # member: belongs to the node

func _ready():
	take_damage(30)
	take_damage(25)
	print("Health left: ", health)

func take_damage(amount: int):
	var before := health  # local: exists only during this call
	health -= amount
	print(before, " -> ", health)

100 -> 70
70 -> 45
Health left: 45

health sits at the top of the script, so every function sees it and it keeps its value between calls. before is local to take_damage: each call gets a fresh one, and it is gone when the function returns.

Member variables are also what the editor can show in the Inspector, when you mark them with @export.

Default Values

A variable with no value starts as null when it has no type, or as its type's default when it has one:

extends Node

var anything
var count: int
var ratio: float
var alive: bool
var title: String
var spot: Vector2

func _ready():
	print(anything)
	print(count, " ", ratio, " ", alive, " [", title, "] ", spot)

<null>
0 0.0 false [] (0.0, 0.0)

Scope

A variable exists from the line that declares it to the end of its block. A variable declared inside an if or a loop is gone after it:

func _ready():
	if true:
		var message := "inside"
		print(message)
	print(message)  # Parse Error: Identifier "message" not declared in the current scope.

Declare the variable before the block when you need it after:

extends Node

func _ready():
	var message := "nothing yet"
	var roll := 6
	if roll == 6:
		message = "you win"
	print(message)

you win

Shadowing a Member Variable

A local variable may reuse a member's name. Inside that function the local one wins, and the member is untouched:

extends Node

var speed := 100

func _ready():
	var speed := 5  # a new local variable, not the member
	print(speed)
	print(self.speed)

5
100

The Godot editor marks this with a SHADOWED_VARIABLE warning, because it is usually a typo: you meant speed = 5. Use self.speed when you really need the member while a local has its name.

Global Variables

GDScript has no globals. Two patterns replace them:

• Autoload. Write a script such as game.gd with var score := 0, then add it under Project Settings > Globals > Autoload with the name Game. Every script can read Game.score.
• Static variables. static var high_score := 0 in a class keeps one value shared by every instance. See static functions.