godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-09-03 18:14:53 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11627 from Ivorforce/gdscript-guidelines

Browse Source 
Migrate GDScript language design guidelines to contributing docs.
This commit is contained in:
Lukas Tenbrink
2026-01-18 15:53:14 +01:00
committed by GitHub
parent 6222cd617d 24e8c8865c
commit 40bb648ad1
3 changed files with 2 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
_static/redirects.csv
View File

@@ -443,7 +443,7 @@ source,destination
/contributing/development/core_and_modules/inheritance_class_tree.html,/engine_details/architecture/inheritance_class_tree.html
/contributing/development/core_and_modules/internal_rendering_architecture.html,/engine_details/architecture/internal_rendering_architecture.html
/contributing/development/core_and_modules/object_class.html,/engine_details/architecture/object_class.html
/contributing/development/core_and_modules/scripting_development.html,/engine_details/architecture/scripting_development.html
/contributing/development/core_and_modules/scripting_development.html,https://contributing.godotengine.org/en/latest/engine/guidelines/gdscript_language_guidelines.html
/contributing/development/core_and_modules/unit_testing.html,/engine_details/architecture/unit_testing.html
/contributing/development/core_and_modules/variant_class.html,/engine_details/architecture/variant_class.html
/contributing/documentation/class_reference_primer.html,engine_details/class_reference/index.html
@@ -486,3 +486,4 @@ source,destination
/engine_details/development/debugging/using_cpp_profilers.html,/engine_details/development/profiling/index.html
/engine_details/development/debugging/profiling/sampling_profilers.html,/engine_details/development/profiling/index.html
/engine_details/development/debugging/profiling/tracing_profilers.html,/engine_details/development/profiling/index.html
/engine_details/architecture/scripting_development.html,https://contributing.godotengine.org/en/latest/engine/guidelines/gdscript_language_guidelines.html
Can't render this file because it has a wrong number of fields in line 450.

1
engine_details/architecture/index.rst
View File

@@ -25,7 +25,6 @@ This section covers the basics that you will encounter in (almost) every source
inheritance_class_tree
internal_rendering_architecture
2d_coordinate_systems
scripting_development
.. rubric:: Extending Godot by modifying its source code
:heading-level: 2

65
engine_details/architecture/scripting_development.rst
View File

@@ -1,65 +0,0 @@
.. _doc_scripting_development:
Scripting development
=====================
GDScript
--------
Annotation guidelines
~~~~~~~~~~~~~~~~~~~~~
In Godot 3 we had a lot of keywords (including ``tool``, ``export``, ``onready``).
This had the following disadvantages:
- Overcomplication of the language grammar.
- Possible conflicts with user identifiers.
- Need to touch the parser in a major way to add a new keyword.
So in Godot 4 we introduced the concept of annotations. An annotation is a modifier
(an attribute, a marker) that can be applied to an entire script, a declaration,
a statement, or a location in the source code. Annotations can optionally take
additional arguments, listed in parentheses. Annotation arguments must be constant
expressions or string literals (in a few special cases where the argument value
must be resolved in the parser rather than in the analyzer).
Currently, an annotation target can be a combination of the following
``GDScriptParser::AnnotationInfo::TargetKind`` flags:
+-----------------+----------------------------------------------+-----------------------------+
| **Target Kind** | **Description** | **Example** |
+=================+==============================================+=============================+
| ``SCRIPT`` | The entire script. | ``@tool`` |
+-----------------+----------------------------------------------+-----------------------------+
| ``CLASS`` | A class (both the outermost and inner ones). | ``@abstract`` |
+-----------------+----------------------------------------------+-----------------------------+
| | ``VARIABLE`` | Other types of class members. | ``@export`` |
| | ``CONSTANT`` | | |
| | ``SIGNAL`` | | |
| | ``FUNCTION`` | | |
+-----------------+----------------------------------------------+-----------------------------+
| ``STATEMENT`` | Statements inside a function. | ``@warning_ignore`` |
+-----------------+----------------------------------------------+-----------------------------+
| ``STANDALONE`` | Some place inside a class or a line | | ``@export_category`` |
| | in the source code. | | ``@warning_ignore_start`` |
| | | |
| | 1. Class pseudo-members. | |
| | 2. Markers for the start and end | |
| | of a warning-ignoring region. | |
+-----------------+----------------------------------------------+-----------------------------+
**When to use a keyword and when an annotation to implement a new feature?**
- **General rule:** Do not use keywords unless they are required by the language grammar
and the parser. Do not use annotations for independent syntactic units.
- Use keywords for class member declarators (``var``, ``const``, ``func``).
- Use annotations for class member modifiers (``@export``, ``@onready``, ``@abstract``).
- Use keywords for operators within expressions (``and``), for delimiters in statements
(``in``, ``when``), and declarations (``extends``).
.. note::
For historical reasons, some existing annotations and keywords do not strictly
follow these guidelines. Choosing between implementing a feature as an annotation
or as a language keyword is a nuanced decision that should be made through discussion
with other GDScript developers.