GDScript String Formatting: % Operator and format()

GDScript has two ways to put values into text: the % operator and the format() method. % is the one you see most:

extends Node

func _ready():
	var player := "Ana"
	var hp := 42
	var gold := 13.5
	print("%s has %d HP and %.2f gold" % [player, hp, gold])
	print("Score: %d" % 900)

Ana has 42 HP and 13.50 gold
Score: 900

Each placeholder takes the next value from the array on the right. With one placeholder, you can pass the value without an array.

Placeholders

%s works with every type, including arrays, vectors and null.

Width and Padding

A number between % and the letter sets the minimum width. - pads on the right, 0 fills with zeros, and + always shows the sign:

extends Node

func _ready():
	print("[%5d]" % 42)
	print("[%-5d]" % 42)
	print("[%05d]" % 42)
	print("[%+d]" % 42)
	print("[%8.3f]" % PI)
	print("%d%%" % 75)

[   42]
[42   ]
[00042]
[+42]
[   3.142]
75%

Padding lines up a score table in the Output panel:

extends Node

func _ready():
	var scores := {"Ana": 1200, "Bo": 85, "Chidi": 430}
	for player in scores:
		print("%-8s%6d" % [player, scores[player]])

Ana       1200
Bo          85
Chidi      430

format() with Named Placeholders

format() replaces {0}, {1} with array items, or {name} with dictionary keys:

extends Node

func _ready():
	print("{0} beat {1}".format(["Ana", "Bo"]))
	print("{0} vs {0}".format(["Mirror"]))
	var stats := {"name": "Ana", "level": 7}
	print("{name} reached level {level}".format(stats))

Ana beat Bo
Mirror vs Mirror
Ana reached level 7

Named placeholders keep long messages readable and let one value appear many times.

Rounding a Float for Display

Formatting and rounding are different jobs:

extends Node

func _ready():
	var ratio := 2.0 / 3.0
	print(ratio)
	print("%.2f" % ratio)          # text, always two digits
	print(snapped(ratio, 0.01))    # a rounded float
	print(String.num(ratio, 3))    # text, up to three digits
	print(round(ratio * 100) / 100)

0.66666666666667
0.67
0.67
0.667
0.67

Use "%.2f" for what the player sees, such as "%.1f s" on a timer label. Use snapped() when you need the rounded number for more math.

Common Mistakes

• Fewer values than placeholders. "%s and %s" % ["a"] prints the error String formatting error: not enough arguments for format string. and gives back the text unformatted, so the player sees %s and %s.
• Passing an array to one %s. "%s" % [1, 2] fails the same way, with not all arguments converted during string formatting., because the array is read as two values. Wrap it: "%s" % [[1, 2]].
• Joining numbers with +. "HP: " + hp is an error. Use "HP: %d" % hp or "HP: " + str(hp).