GDScript style guide

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

    Style guides aren’t meant as hard rulebooks. At times, you may not be able to apply some of the guidelines below. When that happens, use your best judgment, and ask fellow developers for insights.

    In general, keeping your code consistent in your projects and within your team is more important than following this guide to a tee.

    Note

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

    Here is a complete class example based on these guidelines:

    • Use line feed (LF) characters to break lines, not CRLF or CR. (editor default)

    • Use one line feed character at the end of each file. (editor default)

    • Use UTF-8 encoding without a . (editor default)

    • Use Tabs instead of spaces for indentation. (editor default)

    Indentation

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

    Good:

    2.     print("hello")

    Bad:

    1. for i in range(10):
    2.   print("hello")
    4. for i in range(10):
    5.         print("hello")

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

    Good:

    1. effect.interpolate_property(sprite, "transform/scale",
    2.             sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
    3.             Tween.TRANS_QUAD, Tween.EASE_OUT)

    Bad:

    1. effect.interpolate_property(sprite, "transform/scale",
    2.     sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
    3.     Tween.TRANS_QUAD, Tween.EASE_OUT)

    Exceptions to this rule are arrays, dictionaries, and enums. Use a single indentation level to distinguish continuation lines:

    Good:

    1. var party = [
    2.     "Godot",
    3.     "Godette",
    4.     "Steve",
    5. ]
    7. var character_dict = {
    8.     "Name": "Bob",
    9.     "Age": 27,
    10.     "Job": "Mechanic",
    11. }
    13. enum Tiles {
    14.     TILE_BRICK,
    15.     TILE_FLOOR,
    16.     TILE_SPIKE,
    17.     TILE_TELEPORT,
    18. }

    Bad:

    1. var party = [
    2.         "Godot",
    3.         "Godette",
    4.         "Steve",
    5. ]
    7. var character_dict = {
    8.         "Name": "Bob",
    9.         "Age": 27,
    10.         "Job": "Mechanic",
    11. }
    13. enum Tiles {
    14.         TILE_BRICK,
    15.         TILE_FLOOR,
    16.         TILE_SPIKE,
    17.         TILE_TELEPORT,
    18. }

    Trailing comma

    Use a trailing comma on the last line in arrays, dictionaries, and enums. This results in easier refactoring and better diffs in version control as the last line doesn’t need to be modified when adding new elements.

    Good:

    1. enum Tiles {
    2.     TILE_BRICK,
    3.     TILE_FLOOR,
    4.     TILE_SPIKE,
    5.     TILE_TELEPORT,
    6. }

    Bad:

    1. enum Tiles {
    2.     TILE_BRICK,
    3.     TILE_FLOOR,
    4.     TILE_SPIKE,
    5.     TILE_TELEPORT

    Trailing commas are unnecessary in single-line lists, so don’t add them in this case.

    Good:

    1. enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT}

    Bad:

    1. enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT,}

    Blank lines

    Surround functions and class definitions with two blank lines:

    1. func heal(amount):
    2.     health += amount
    3.     health = min(health, max_health)
    4.     emit_signal("health_changed", health)
    7. func take_damage(amount, effect=null):
    8.     health -= amount
    9.     health = max(0, health)
    10.     emit_signal("health_changed", health)

    Use one blank line inside functions to separate logical sections.

    Note

    We use a single line between classes and function definitions in the class reference and in short code snippets in this documentation.

    Line length

    Keep individual lines of code under 100 characters.

    If you can, try to keep lines under 80 characters. This helps to read the code on small displays and with two scripts opened side-by-side in an external text editor. For example, when looking at a differential revision.

    One statement per line

    Never combine multiple statements on a single line. No, C programmers, not even with a single line conditional statement.

    Good:

    1. if position.x > width:
    2.     position.x = 0
    4. if flag:
    5.     print("flagged")

    Bad:

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

    The only exception to that rule is the ternary operator:

    1. next_state = "fall" if not is_on_floor() else "idle"

    Format multiline statements for readability

    When you have particularly long if statements or nested ternary expressions, wrapping them over multiple lines improves readability. Since continuation lines are still part of the same expression, 2 indent levels should be used instead of one.

    When wrapping a conditional expression over multiple lines, the and/or keywords should be placed at the beginning of the line continuation, not at the end of the previous line.

    Good:

    1. var angle_degrees = 135
    2. var quadrant = (
    4.         else "southeast" if angle_degrees <= 180
    5.         else "southwest" if angle_degrees <= 270
    6.         else "northwest"
    7. )
    9. var position = Vector2(250, 350)
    10. if (
    11.         position.x > 200 and position.x < 400
    12.         and position.y > 300 and position.y < 400
    13. ):
    14.     pass

    Bad:

    1. var angle_degrees = 135
    2. var quadrant = "northeast" if angle_degrees <= 90 else "southeast" if angle_degrees <= 180 else "southwest" if angle_degrees <= 270 else "northwest"
    4. var position = Vector2(250, 350)
    5. if position.x > 200 and position.x < 400 and position.y > 300 and position.y < 400:
    6.     pass

    Avoid unnecessary parentheses

    Avoid parentheses in expressions and conditional statements. Unless necessary for order of operations or wrapping over multiple lines, they only reduce readability.

    Good:

    Bad:

    1. if (is_colliding()):
    2.     queue_free()

    Prefer the plain English versions of boolean operators, as they are the most accessible:

    • Use and instead of &&.

    • Use or instead of ||.

    You may also use parentheses around boolean operators to clear any ambiguity. This can make long expressions easier to read.

    Good:

    1. if (foo and bar) or baz:
    2.     print("condition is true")

    Bad:

    1. if foo && bar || baz:
    2.     print("condition is true")

    Comment spacing

    Regular comments should start with a space, but not code that you comment out. This helps differentiate text comments from disabled code.

    Good:

    1. # This is a comment.
    2. #print("This is disabled code")

    Bad:

    1. #This is a comment.
    2. # print("This is disabled code")

    Note

    In the script editor, to toggle the selected code commented, press Ctrl + K. This feature adds a single # sign at the start of the selected lines.

    Whitespace

    Always use one space around operators and after commas. Also, avoid extra spaces in dictionary references and function calls.

    Good:

    1. position.x = 5
    2. position.y = target_position.y + 10
    3. dict["key"] = 5
    4. my_array = [4, 5, 6]
    5. print("foo")

    Bad:

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

    Don’t use spaces to align expressions vertically:

    1. x        = 100
    2. y        = 100
    3. velocity = 500

    Quotes

    Use double quotes unless single quotes make it possible to escape fewer characters in a given string. See the examples below:

    1. # Normal string.
    2. print("hello world")
    4. # Use double quotes as usual to avoid escapes.
    5. print("hello 'world'")
    7. # Use single quotes as an exception to the rule to avoid escapes.
    8. print('hello "world"')
    10. # Both quote styles would require 2 escapes; prefer double quotes if it's a tie.
    11. print("'hello' \"world\"")

    Numbers

    Don’t omit the leading or trailing zero in floating-point numbers. Otherwise, this makes them less readable and harder to distinguish from integers at a glance.

    Good:

    1. var float_number = 0.234
    2. var other_float_number = 13.0

    Bad:

    1. var float_number = .234
    2. var other_float_number = 13.

    Use lowercase for letters in hexadecimal numbers, as their lower height makes the number easier to read.

    Good:

    1. var hex_number = 0xfb8c0b

    Bad:

    1. var hex_number = 0xFB8C0B

    Take advantage of GDScript’s underscores in literals to make large numbers more readable.

    Good:

    1. var large_number = 1_234_567_890
    2. var large_hex_number = 0xffff_f8f8_0000
    3. var large_bin_number = 0b1101_0010_1010
    4. # Numbers lower than 1000000 generally don't need separators.
    5. var small_number = 12345

    Bad:

    1. var large_number = 1234567890
    2. var large_hex_number = 0xfffff8f80000
    3. var large_bin_number = 0b110100101010
    4. # Numbers lower than 1000000 generally don't need separators.
    5. var small_number = 12_345

    These naming conventions follow the Godot Engine style. Breaking these will make your code clash with the built-in naming conventions, leading to inconsistent code.

    File names

    Use snake_case for file names. For named classes, convert the PascalCase class name to snake_case:

    1. class_name Weapon
    2. extends Node

    This is consistent with how C++ files are named in Godot’s source code. This also avoids case sensitivity issues that can crop up when exporting a project from Windows to other platforms.

    Classes and nodes

    Use PascalCase for class and node names:

    1. extends KinematicBody

    Also use PascalCase when loading a class into a constant or a variable:

    1. const Weapon = preload("res://weapon.gd")

    Functions and variables

    1. var particle_effect
    2. func load_level():

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

    1. var _counter = 0
    2. func _recalculate_path():

    Use the past tense to name signals:

    1. signal door_opened
    2. signal score_changed

    Constants and enums

    Write constants with CONSTANT_CASE, that is to say in all caps with an underscore (_) to separate words:

    1. const MAX_SPEED = 200

    Use PascalCase for enum names and CONSTANT_CASE for their members, as they are constants:

    1. enum Element {
    2.     EARTH,
    3.     WATER,
    5.     FIRE,
    6. }

    This first section focuses on code order. For formatting, see . For naming conventions, see Naming conventions.

    We suggest to organize GDScript code this way:

    1. 01. tool
    2. 02. class_name
    3. 03. extends
    4. 04. # docstring
    6. 05. signals
    7. 06. enums
    8. 07. constants
    9. 08. exported variables
    10. 09. public variables
    11. 10. private variables
    12. 11. onready variables
    14. 12. optional built-in virtual _init method
    15. 13. built-in virtual _ready method
    16. 14. remaining built-in virtual methods
    17. 15. public methods
    18. 16. private methods

    We optimized the order to make it easy to read the code from top to bottom, to help developers reading the code for the first time understand how it works, and to avoid errors linked to the order of variable declarations.

    This code order follows four rules of thumb:

    1. Properties and signals come first, followed by methods.

    2. Public comes before private.

    3. Virtual callbacks come before the class’s interface.

    4. The object’s construction and initialization functions, _init and _ready, come before functions that modify the object at runtime.

    Class declaration

    If the code is meant to run in the editor, place the tool keyword on the first line of the script.

    Follow with the class_name if necessary. You can turn a GDScript file into a global type in your project using this feature. For more information, see GDScript basics.

    Then, add the extends keyword if the class extends a built-in type.

    Following that, you should have the class’s optional docstring as comments. You can use that to explain the role of your class to your teammates, how it works, and how other developers should use it, for example.

    1. class_name MyNode
    2. extends Node
    3. # A brief description of the class's role and functionality.
    4. # Longer description.

    Signals and properties

    Write signal declarations, followed by properties, that is to say, member variables, after the docstring.

    Enums should come after signals, as you can use them as export hints for other properties.

    Then, write constants, exported variables, public, private, and onready variables, in that order.

    1. signal spawn_player(position)
    3. enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN}
    5. const MAX_LIVES = 3
    7. export(Jobs) var job = Jobs.KNIGHT
    8. export var max_health = 50
    9. export var attack = 5
    11. var health = max_health setget set_health
    13. var _speed = 300.0
    15. onready var sword = get_node("Sword")
    16. onready var gun = get_node("Gun")

    Note

    The GDScript compiler evaluates onready variables right before the _ready callback. You can use that to cache node dependencies, that is to say, to get child nodes in the scene that your class relies on. This is what the example above shows.

    Member variables

    Don’t declare member variables if they are only used locally in a method, as it makes the code more difficult to follow. Instead, declare them as local variables in the method’s body.

    Local variables

    Declare local variables as close as possible to their first use. This makes it easier to follow the code, without having to scroll too much to find where the variable was declared.

    Methods and static functions

    After the class’s properties come the methods.

    Start with the _init() callback method, that the engine will call upon creating the object in memory. Follow with the _ready() callback, that Godot calls when it adds a node to the scene tree.

    These functions should come first because they show how the object is initialized.

    Other built-in virtual callbacks, like _unhandled_input() and _physics_process, should come next. These control the object’s main loop and interactions with the game engine.

    The rest of the class’s interface, public and private methods, come after that, in that order.

    1. func _init():
    2.     add_to_group("state_machine")
    5. func _ready():
    6.     connect("state_changed", self, "_on_state_changed")
    7.     _state.enter()
    10. func _unhandled_input(event):
    11.     _state.unhandled_input(event)
    14. func transition_to(target_state_path, msg={}):
    15.     if not has_node(target_state_path):
    16.         return
    18.     var target_state = get_node(target_state_path)
    19.     assert(target_state.is_composite == false)
    21.     _state.exit()
    22.     self._state = target_state
    23.     _state.enter(msg)
    24.     Events.emit_signal("player_state_changed", _state.name)
    27. func _on_state_changed(previous, new):
    28.     print("state changed")
    29.     emit_signal("state_changed")

    Since Godot 3.1, GDScript supports optional static typing.

    Declared types

    To declare a variable’s type, use <variable>: <type>:

    1. var health: int = 0

    To declare the return type of a function, use -> <type>:

    1. func heal(amount: int) -> void:

    In most cases you can let the compiler infer the type, using :=:

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

    However, in a few cases when context is missing, the compiler falls back to the function’s return type. For example, get_node() cannot infer a type unless the scene or file of the node is loaded in memory. In this case, you should set the type explicitly.

    Good:

    1. onready var health_bar: ProgressBar = get_node("UI/LifeBar")

    Alternatively, you can use the as keyword to cast the return type, and that type will be used to infer the type of the var.

    This option is also considered more than the first.