diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index 9dd84ad05da1..1f791b8820ca 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -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], @@ -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():`` | @@ -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`. @@ -660,6 +663,12 @@ 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. @@ -667,13 +676,13 @@ 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: :: @@ -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 @@ -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 `. @@ -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, diff --git a/tutorials/scripting/gdscript/static_typing.rst b/tutorials/scripting/gdscript/static_typing.rst index b7065ddd0584..a3d62ca2e432 100644 --- a/tutorials/scripting/gdscript/static_typing.rst +++ b/tutorials/scripting/gdscript/static_typing.rst @@ -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 `. +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:: @@ -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 ``->`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -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: @@ -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.