godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-03 05:48:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7412 from dalexeev/update-doc-bbcode

Browse Source
This commit is contained in:
Max Hilbrunner
2023-05-30 09:30:51 +02:00
committed by GitHub
parent 7cf7f139d8 d8e71f7453
commit 0f37d41577
3 changed files with 251 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
contributing/documentation/class_reference_primer.rst
View File

@@ -134,62 +134,93 @@ Linking
Whenever you link to a member of another class, you need to specify the class name.
For links to the same class, the class name is optional and can be omitted.
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| Tag | Effect | Usage | Result |
+=========================+=================================================+=========================================+=============================================================================+
| [Class] | Link to class ``Class`` | Move the [Sprite2D]. | Move the :ref:`class_Sprite2D`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [annotation Class.name] | Link to annotation ``name`` in class ``Class``, | See [annotation @GDScript.@export]. | See :ref:`@GDScript.@export<class_@GDScript_annotation_@export>`. |
| | many default annotations are in ``@GDScript`` | | |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [constant Class.name] | Link to constant ``name`` in class ``Class`` | See [constant @GlobalScope.KEY_ESCAPE]. | See :ref:`@GlobalScope.KEY_ESCAPE<class_@GlobalScope_constant_KEY_ESCAPE>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [enum Class.name] | Link to enum ``name`` in class ``Class`` | See [enum Mesh.ArrayType]. | See :ref:`ArrayType<enum_Mesh_ArrayType>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [method Class.name] | Link to method ``name`` in class ``Class`` | Call [method Node3D.hide]. | Call :ref:`hide<class_Node3D_method_hide>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [member Class.name] | Link to member ``name`` in class ``Class`` | Get [member Node2D.scale]. | Get :ref:`scale<class_Node2D_property_scale>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [signal Class.name] | Link to signal ``name`` in class ``Class`` | Emit [signal Node.renamed]. | Emit :ref:`renamed<class_Node_signal_renamed>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
| [theme_item Class.name] | Link to theme item ``name`` in class ``Class`` | See [theme_item GraphNode.position]. | See :ref:`position<class_GraphNode_theme_style_position>`. |
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| Tag and Description | Example | Result |
+===============================+=========================================+======================================================================+
| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. |
| | Link to class | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export <class_@GDScript_annotation_@export>`. |
| | Link to annotation | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
| | Link to constant | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`. |
| | Link to enum | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`. |
| | Link to method | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale <class_Node2D_property_scale>`. |
| | Link to member | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed <class_Node_signal_renamed>`. |
| | Link to signal | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font <class_Label_theme_font_font>`. |
| | Link to theme item | | |
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
.. note::
Currently only :ref:`class_@GDScript` has annotations.
Formatting text
"""""""""""""""
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| Tag | Effect | Usage | Result |
+============================+=====================================================+=====================================+===================================================================+
| [param name] | Formats a parameter name (as code) | Takes [param size] for the size. | Takes ``size`` for the size. |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
+--------------------------------------+--------------------------------------+------------------------------+
| Tag and Description | Example | Result |
+======================================+======================================+==============================+
| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. |
| | Formats a parameter name (as code) | | |
+--------------------------------------+--------------------------------------+------------------------------+
| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. |
| | Line break | | ``Line 2.`` | | Line 2. |
+--------------------------------------+--------------------------------------+------------------------------+
| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. |
| | Bold | | |
+--------------------------------------+--------------------------------------+------------------------------+
| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. |
| | Italic | | |
+--------------------------------------+--------------------------------------+------------------------------+
| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. |
| | Keyboard/mouse shortcut | | |
+--------------------------------------+--------------------------------------+------------------------------+
Formatting code
"""""""""""""""
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| Tag | Effect | Usage | Result |
+============================+=====================================================+=====================================+===================================================================+
| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* |
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
+----------------------------------------+---------------------------------------+--------------------------+
| Tag and Description | Example | Result |
+========================================+=======================================+==========================+
| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. |
| | Monospace | | |
+----------------------------------------+---------------------------------------+--------------------------+
| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* |
| | Multiline preformatted block | | |
+----------------------------------------+---------------------------------------+--------------------------+
| | ``[codeblocks]`` ``[/codeblocks]`` | *See below.* | *See below.* |
| | Codeblock for multiple languages | | |
+----------------------------------------+---------------------------------------+--------------------------+
| | ``[gdscript]`` ``[/gdscript]`` | *See below.* | *See below.* |
| | GDScript codeblock tab in codeblocks | | |
+----------------------------------------+---------------------------------------+--------------------------+
| | ``[csharp]`` ``[/csharp]`` | *See below.* | *See below.* |
| | C# codeblock tab in codeblocks | | |
+----------------------------------------+---------------------------------------+--------------------------+
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
always use **four spaces** for indentation. The parser will delete tabs. For
example:
.. note::
1. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
2. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
.. warning::
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
always use **four spaces** for indentation. The parser will delete tabs.
For example:
.. code-block:: none

196
tutorials/scripting/gdscript/gdscript_documentation_comments.rst
View File

@@ -35,29 +35,33 @@ Tags
| Description | Use one blank line to separate the description from |
| | the brief. |
+-------------------+--------------------------------------------------------+
| Tutorial | ``@tutorial[( The Title Here )]:`` |
| | |
| Tutorial | | ``@tutorial:`` |
| | | ``@tutorial(The Title Here):`` |
+-------------------+--------------------------------------------------------+
**Example:**
For example:
::
extends Node2D
## A brief description of your script.
## A brief description of the class's role and functionality.
##
## A more detailed description of the script.
## The description of the script, what it can do,
## and any further detail.
##
## @tutorial: https://the/tutorial1/url.com
## @tutorial(Tutorial2): https://the/tutorial2/url.com
.. warning:: If there is any space in between the tag name and colon, for example
``@tutorial :``, it won't be treated as a valid tag and will be ignored.
.. warning::
.. note:: When the description spans multiple lines, the preceding and trailing white
spaces will be stripped and joined with a single space. To preserve the line
break use ``[br]``. See also `BBCode and class reference`_ below.
If there is any space in between the tag name and colon, for example
``@tutorial :``, it won't be treated as a valid tag and will be ignored.
.. note::
When the description spans multiple lines, the preceding and trailing white
spaces will be stripped and joined with a single space. To preserve the line
break use ``[br]``. See also `BBCode and class reference`_ below.
Documenting script members
--------------------------
@@ -82,14 +86,13 @@ Members that are applicable for documentation:
- Enum
- Enum value
Examples
--------
Example
-------
::
extends Node2D
## A brief description of your script.
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
@@ -97,18 +100,6 @@ Examples
## @tutorial: https://the/tutorial1/url.com
## @tutorial(Tutorial2): https://the/tutorial2/url.com
## The description of the variable v1.
var v1
## This is a multi line description of the variable v2. The type
## information below will be extracted for the documentation.
var v2: int
## If the member has any annotation, the annotation should
## immediately precede it.
@onready
var v3 := some_func()
## The description of a constant.
const GRAVITY = 9.8
@@ -124,16 +115,34 @@ Examples
RIGHT = 3, ## Direction right.
}
## The description of a constant.
const GRAVITY = 9.8
## The description of the variable v1.
var v1
## This is a multiline description of the variable v2.[br]
## The type information below will be extracted for the documentation.
var v2: int
## If the member has any annotation, the annotation should
## immediately precede it.
@export
var v3 := some_func()
## As the following function is documented, even though its name starts with
## an underscore, it will appear in the help window.
func _fn(p1: int, p2: String) -> int:
return 0
# The below function isn't documented and its name starts with an underscore
# so it will treated as private and will not be shown in the help window.
func _internal() -> void:
pass
## Documenting an inner class.
##
## The same rules apply here. The documentation must
@@ -145,6 +154,7 @@ Examples
## Inner class variable v4.
var v4
## Inner class function fn.
func fn(): pass
@@ -158,73 +168,83 @@ URLs, animation effects, etc. can be added with the :ref:`bbcode <doc_bbcode_in_
Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also
be used in the documentation. See also :ref:`class reference bbcode <doc_class_reference_bbcode>`.
Whenever you link to a member of another class, you need to specify the class name.
For links to the same class, the class name is optional and can be omitted.
Here's the list of available tags:
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| Tag | Effect | Usage | Result |
+===========================+================================+=====================================+=========================================================================+
| [Class] | Link a class | Move the [Sprite2D]. | Move the :ref:`class_Sprite2D`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [annotation name] | Link to an annotation in this | See | See |
| | class | [annotation @export]. | :ref:`@GDScript.@export<class_@GDScript_annotation_@export>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [annotation Class.name] | Link to another class's | See | See |
| | annotation, many default | [annotation @GDScript.@export]. | :ref:`@GDScript.@export<class_@GDScript_annotation_@export>`. |
| | annotations are in | | |
| | ``@GDScript`` | | |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [constant name] | Link to a constant in this | See | See |
| | class | [constant KEY_ESCAPE]. | :ref:`@GlobalScope.KEY_ESCAPE<class_@GlobalScope_constant_KEY_ESCAPE>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [constant Class.name] | Link to another class's | See | See |
| | constant | [constant @GlobalScope.KEY_ESCAPE]. | :ref:`@GlobalScope.KEY_ESCAPE<class_@GlobalScope_constant_KEY_ESCAPE>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [enum enumname] | Link to an enum in this class | See [enum ArrayType]. | See :ref:`ArrayType <enum_Mesh_ArrayType>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [enum Class.enumname] | Link to another class's enum | See [enum Mesh.ArrayType]. | See :ref:`ArrayType <enum_Mesh_ArrayType>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [method methodname] | Link to a method in this class | Call [method hide]. | Call :ref:`hide <class_Node3D_method_hide>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [method Class.methodname] | Link to another class's method | Call [method Node3D.hide]. | Call :ref:`hide <class_Node3D_method_hide>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale <class_Node2D_property_scale>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale <class_Node2D_property_scale>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed <class_node_signal_renamed>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed <class_node_signal_renamed>`. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [br] | Line break | | Line 1.[br] | | Line 1. |
| | | | Line 2. | | Line 2. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* |
+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| Tag and Description | Example | Result |
+======================================+=========================================+======================================================================+
| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. |
| | Link to class | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export <class_@GDScript_annotation_@export>`. |
| | Link to annotation | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
| | Link to constant | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`. |
| | Link to enum | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`. |
| | Link to method | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale <class_Node2D_property_scale>`. |
| | Link to member | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed <class_Node_signal_renamed>`. |
| | Link to signal | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font <class_Label_theme_font_font>`. |
| | Link to theme item | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. |
| | Formats a parameter name (as code) | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. |
| | Line break | | ``Line 2.`` | | Line 2. |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. |
| | Bold | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. |
| | Italic | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. |
| | Keyboard/mouse shortcut | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. |
| | Monospace | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* |
| | Multiline preformatted block | | |
+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
.. warning:: Use ``[codeblock]`` for pre-formatted code blocks. Inside
``[codeblock]``, always use **four spaces** for indentation
(the parser will delete tabs).
.. note::
1. Currently only :ref:`class_@GDScript` has annotations.
2. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
3. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
.. warning::
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
always use **four spaces** for indentation (the parser will delete tabs).
::
## The do_something method for this plugin. before using the
## method you first have to initialize [MyPlugin].
## see : [method initialize]
## [color=yellow]Warning:[/color] always [method clean] after use.
## Do something for this plugin. Before using the method
## you first have to [method initialize] [MyPlugin].[br]
## [color=yellow]Warning:[/color] Always [method clean] after use.[br]
## Usage:
## [codeblock]
## func _ready():
## the_plugin.initialize()
## the_plugin.do_something()
## the_plugin.clean()
## [/codeblock]
## [codeblock]
## func _ready():
## the_plugin.initialize()
## the_plugin.do_something()
## the_plugin.clean()
## [/codeblock]
func do_something():
pass

122
tutorials/scripting/gdscript/gdscript_styleguide.rst
View File

@@ -19,8 +19,10 @@ 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.
.. 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:
@@ -28,9 +30,10 @@ Here is a complete class example based on these guidelines:
class_name StateMachine
extends Node
# Hierarchical State machine for the player.
# Initializes states and delegates engine callbacks
# (_physics_process, _unhandled_input) to the state.
## Hierarchical State machine for the player.
##
## Initializes states and delegates engine callbacks ([method Node._physics_process],
## [method Node._unhandled_input]) to the state.
signal state_changed(previous, new)
@@ -46,11 +49,11 @@ Here is a complete class example based on these guidelines:
func _init():
add_to_group("state_machine")
func _enter_tree():
print("this happens before the ready method!")
func _ready():
state_changed.connect(_on_state_changed)
@@ -287,8 +290,10 @@ Surround functions and class definitions with two blank lines:
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.
.. 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
~~~~~~~~~~~
@@ -331,7 +336,7 @@ The only exception to that rule is the ternary operator:
::
next_state = "idle" if is_on_floor() else "fall"
next_state = "idle" if is_on_floor() else "fall"
Format multiline statements for readability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -467,9 +472,9 @@ This helps differentiate text comments from disabled code.
.. note::
In the script editor, to toggle the selected code commented, press
:kbd:`Ctrl + K`. This feature adds a single # sign at the start
of the selected lines.
In the script editor, to toggle the selected code commented, press
:kbd:`Ctrl + K`. This feature adds a single # sign at the start
of the selected lines.
Whitespace
~~~~~~~~~~
@@ -636,7 +641,7 @@ Use PascalCase for class and node names:
::
extends CharacterBody3D
extends CharacterBody3D
Also use PascalCase when loading a class into a constant or a variable:
@@ -651,16 +656,16 @@ Use snake\_case to name functions and variables:
::
var particle_effect
func load_level():
var particle_effect
func load_level():
Prepend a single underscore (\_) to virtual methods functions the user must
override, private functions, and private variables:
::
var _counter = 0
func _recalculate_path():
var _counter = 0
func _recalculate_path():
Signals
~~~~~~~
@@ -745,22 +750,25 @@ Class declaration
If the code is meant to run in the editor, place the ``@tool`` annotation on the
first line of the script.
Follow with the `class_name` if necessary. You can turn a GDScript file into a
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
:ref:`doc_gdscript`.
Then, add the `extends` keyword if the class extends a built-in type.
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,
Following that, you should have the class's optional
:ref:`documentation comments <doc_gdscript_documentation_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.
::
class_name MyNode
extends Node
# A brief description of the class's role and functionality.
# Longer description.
class_name MyNode
extends Node
## A brief description of the class's role and functionality.
##
## The description of the script, what it can do,
## and any further detail.
Signals and properties
~~~~~~~~~~~~~~~~~~~~~~
@@ -776,32 +784,32 @@ variables, in that order.
::
signal spawn_player(position)
signal spawn_player(position)
enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN}
enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN}
const MAX_LIVES = 3
const MAX_LIVES = 3
@export var job: Jobs = Jobs.KNIGHT
@export var max_health = 50
@export var attack = 5
@export var job: Jobs = Jobs.KNIGHT
@export var max_health = 50
@export var attack = 5
var health = max_health:
set(new_health):
health = new_health
var health = max_health:
set(new_health):
health = new_health
var _speed = 300.0
var _speed = 300.0
@onready var sword = get_node("Sword")
@onready var gun = get_node("Gun")
@onready var sword = get_node("Sword")
@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.
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
~~~~~~~~~~~~~~~~
@@ -881,13 +889,13 @@ To declare a variable's type, use ``<variable>: <type>``:
::
var health: int = 0
var health: int = 0
To declare the return type of a function, use ``-> <type>``:
::
func heal(amount: int) -> void:
func heal(amount: int) -> void:
Inferred types
~~~~~~~~~~~~~~
@@ -902,8 +910,8 @@ otherwise prefer writing the type explicitly.
::
var health: int = 0 # The type can be int or float, and thus should be stated explicitly.
var direction := Vector3(1, 2, 3) # The type is clearly inferred as Vector3.
var health: int = 0 # The type can be int or float, and thus should be stated explicitly.
var direction := Vector3(1, 2, 3) # The type is clearly inferred as Vector3.
Include the type hint when the type is ambiguous, and
omit the type hint when it's redundant.
@@ -914,11 +922,11 @@ omit the type hint when it's redundant.
::
var health := 0 # Typed as int, but it could be that float was intended.
var direction: Vector3 = Vector3(1, 2, 3) # The type hint has redundant information.
var health := 0 # Typed as int, but it could be that float was intended.
var direction: Vector3 = Vector3(1, 2, 3) # The type hint has redundant information.
# What type is this? It's not immediately clear to the reader, so it's bad.
var value := complex_function()
# What type is this? It's not immediately clear to the reader, so it's bad.
var value := complex_function()
In some cases, the type must be stated explicitly, otherwise the behavior
will not be as expected because the compiler will only be able to use
@@ -932,7 +940,7 @@ should set the type explicitly.
::
@onready var health_bar: ProgressBar = get_node("UI/LifeBar")
@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.
@@ -941,8 +949,8 @@ that type will be used to infer the type of the var.
::
@onready var health_bar := get_node("UI/LifeBar") as ProgressBar
# health_bar will be typed as ProgressBar
@onready var health_bar := get_node("UI/LifeBar") as ProgressBar
# health_bar will be typed as ProgressBar
This option is also considered more :ref:`type-safe<doc_gdscript_static_typing_safe_lines>` than the first.
@@ -952,6 +960,6 @@ This option is also considered more :ref:`type-safe<doc_gdscript_static_typing_s
::
# The compiler can't infer the exact type and will use Node
# instead of ProgressBar.
@onready var health_bar := get_node("UI/LifeBar")
# The compiler can't infer the exact type and will use Node
# instead of ProgressBar.
@onready var health_bar := get_node("UI/LifeBar")