GDScript style guide

Description

This styleguide lists conventions to write elegant GDScript. The goal is to encourage writing clean, readable code and promote consistency across projects, discussions, and tutorials. Hopefully, this will also encourage development of auto-formatting tools.

Since GDScript is close to Python, this guide is inspired by Python’s PEP 8 programming styleguide.

Note

Godot’s built-in script editor uses a lot of these conventions by default. Let it help you.

Code structure

Indentation

Indent type: Tabs (editor default)

Indent size: 4 (editor default)

Each indent level should be one greater than the block containing it.

Good:

for i in range(10):
    print("hello")

Bad:

for i in range(10):
  print("hello")
for i in range(10):
        print("hello")

Use 2 indent levels to distinguish continuation lines from regular code blocks.

Good:

effect.interpolate_property(sprite, 'transform/scale',
            sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
            Tween.TRANS_QUAD, Tween.EASE_OUT)

Bad:

effect.interpolate_property(sprite, 'transform/scale',
    sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
    Tween.TRANS_QUAD, Tween.EASE_OUT)

Blank lines

Surround functions and class definitions with two blank lines:

func heal(amount):
    health += amount
    health = min(health, max_health)
    emit_signal("health_changed", health)
func take_damage(amount, effect=null):
    health -= amount
    health = max(0, health)
    emit_signal("health_changed", health)

Use one blank line inside functions to separate logical sections.

One statement per line

Never combine multiple statements on a single line. No, C programmers, not with a single line conditional statement (except with the ternary operator)!

Good:

if position.x > width:
    position.x = 0
if flag:
    print("flagged")

Bad:

if position.x > width: position.x = 0
if flag: print("flagged")

Avoid unnecessary parentheses

Avoid parentheses in expressions and conditional statements. Unless necessary for order of operations, they only reduce readability.

Good:

if is_colliding():
    queue_free()

Bad:

if (is_colliding()):
    queue_free()

Whitespace

Always use one space around operators and after commas. Avoid extra spaces in dictionary references and function calls, or to create “columns.”

Good:

position.x = 5
position.y = mpos.y + 10
dict['key'] = 5
myarray = [4, 5, 6]
print('foo')

Bad:

position.x=5
position.y = mpos.y+10
dict ['key'] = 5
myarray = [4,5,6]
print ('foo')

NEVER:

x        = 100
y        = 100
velocity = 500

Naming conventions

These naming conventions follow the Godot Engine style. Breaking these will make your code clash with the built-in naming conventions, which is ugly.

Classes and nodes

Use PascalCase: extends KinematicBody

Also when loading a class into a constant or variable:

const MyCoolNode = preload('res://my_cool_node.gd')

Functions and variables

Use snake_case: get_node()

Prepend a single underscore (_) to virtual methods (functions the user must override), private functions, and private variables: func _ready()

Signals

Use past tense:

signal door_opened
signal score_changed

Constants

Use CONSTANT_CASE, all caps, with an underscore (_) to separate words: const MAX_SPEED = 200

Static typing

Since Godot 3.1, GDScript supports optional static typing.

Type hints

Place the colon right after the variable’s name, without a space, and let the GDScript compiler infer the variable’s type when possible.

Good:

onready var health_bar: ProgressBar = get_node("UI/LifeBar")
var health := 0 # The compiler will use the int type

Bad:

# The compiler can't infer the exact type and will use Node
# instead of ProgressBar
onready var health_bar := get_node("UI/LifeBar")

When you let the compiler infer the type hint, write the colon and equal signs together: :=.

var health := 0 # The compiler will use the int type

Add a space on either sides of the return type arrow when defining functions.

func heal(amount: int) -> void: