Skip to content

Commit

Permalink
Update style guide and static typing pages
Browse files Browse the repository at this point in the history
Currently, the style guide uses what seem like good reasonable policies to me (notably, PascalCase adjectives for trait names, and `uses` after `extends`). We'll need to make sure this is agreed-upon as the good way to do it before merging, though
  • Loading branch information
Meorge committed Dec 10, 2024
1 parent c4b5a31 commit bf521f2
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 23 deletions.
53 changes: 33 additions & 20 deletions tutorials/scripting/gdscript/gdscript_styleguide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Here is a complete class example based on these guidelines:

class_name StateMachine
extends Node
uses Activatable
## Hierarchical State machine for the player.
##
## Initializes states and delegates engine callbacks ([method Node._physics_process],
Expand Down Expand Up @@ -629,6 +630,8 @@ code. As a summary table:
+---------------+----------------+----------------------------------------------------+
| Class names | PascalCase | ``class_name YAMLParser`` |
+---------------+----------------+----------------------------------------------------+
| Trait names | PascalCase | ``trait_name Interactable`` |
+---------------+----------------+----------------------------------------------------+
| Node names | PascalCase | ``Camera3D``, ``Player`` |
+---------------+----------------+----------------------------------------------------+
| Functions | snake_case | ``func load_level():`` |
Expand All @@ -647,7 +650,7 @@ code. As a summary table:
File names
~~~~~~~~~~

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

# This file should be saved as `weapon.gd`.
Expand All @@ -660,20 +663,26 @@ name to snake_case::
class_name YAMLParser
extends Object

::
# This file should be saved as `interactable.gdt`.
trait_name Interactable
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:
Use PascalCase for class, trait, and node names:

::

extends CharacterBody3D

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

::

Expand Down Expand Up @@ -766,23 +775,24 @@ We suggest to organize GDScript code this way:
01. @tool
02. class_name
03. extends
04. ## docstring

05. signals
06. enums
07. constants
08. @export variables
09. public variables
10. private variables
11. @onready variables

12. optional built-in virtual _init method
13. optional built-in virtual _enter_tree() method
14. built-in virtual _ready method
15. remaining built-in virtual methods
16. public methods
17. private methods
18. subclasses
04. uses
05. ## docstring

06. signals
07. enums
08. constants
09. @export variables
10. public variables
11. private variables
12. @onready variables

13. optional built-in virtual _init method
14. optional built-in virtual _enter_tree() method
15. built-in virtual _ready method
16. remaining built-in virtual methods
17. public methods
18. private methods
19. subclasses

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
Expand All @@ -808,6 +818,8 @@ global type in your project using this feature. For more information, see
:ref:`doc_gdscript`.

Then, add the ``extends`` keyword if the class extends a built-in type.
If the class uses any traits, add the ``uses`` keyword along with all of the trait
names (or filepaths, if the traits are unnamed) of the traits it uses.

Following that, you should have the class's optional
:ref:`documentation comments <doc_gdscript_documentation_comments>`.
Expand All @@ -818,6 +830,7 @@ and how other developers should use it, for example.

class_name MyNode
extends Node
uses MyTrait
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
Expand Down
22 changes: 19 additions & 3 deletions tutorials/scripting/gdscript/static_typing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,10 @@ Here is a complete list of what can be used as a type hint:
7. Global, native and custom named enums. Note that an enum type is just an ``int``,
there is no guarantee that the value belongs to the set of enum values.
8. Constants (including local ones) if they contain a preloaded class or enum.
9. :ref:`Global traits <doc_gdscript_basics_trait_name>`.
10. :ref:`Inner traits <_doc_gdscript_basics_inner_traits>`.

You can use any class, including your custom classes, as types. There are two ways
You can use any class or trait, including your custom classes and traits, as types. There are two ways
to use them in scripts. The first method is to preload the script you want to use
as a type in a constant::

Expand All @@ -135,6 +137,20 @@ and you can use it anywhere, without having to preload it into a constant::

var my_rifle: Rifle

These methods also work with traits, except using ``trait_name`` and ``uses`` in place
of ``class_name`` and ``extends``::

const Shootable = preload("res://player/weapons/shootable.gdt")
var something_shootable: Shootable

::

class_name Rifle
uses Shootable

# Somewhere else...
var my_shootable_thing: Shootable

Specify the return type of a function with the arrow ``->``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -151,7 +167,7 @@ as with variables::
health_points -= damage
return health_points <= 0

You can also use your own classes as return types::
You can also use your own classes or traits as return types::

# Adds an item to the inventory and returns it.
func add(reference: Item, amount: int) -> Item:
Expand Down Expand Up @@ -199,7 +215,7 @@ To define the type of an ``Array``, enclose the type name in ``[]``.

An array's type applies to ``for`` loop variables, as well as some operators like
``[]``, ``[]=``, and ``+``. Array methods (such as ``push_back``) and other operators
(such as ``==``) are still untyped. Built-in types, native and custom classes,
(such as ``==``) are still untyped. Built-in types, native and custom classes and traits,
and enums may be used as element types. Nested array types
(like ``Array[Array[int]]``) are not supported.

Expand Down

0 comments on commit bf521f2

Please sign in to comment.