diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml
index 732fca19b7e..e908b453231 100644
--- a/.github/workflows/build_offline_docs.yml
+++ b/.github/workflows/build_offline_docs.yml
@@ -13,6 +13,7 @@ jobs:
matrix:
branch:
- master
+ - stable
- 3.6
steps:
- uses: actions/checkout@v4
@@ -29,7 +30,7 @@ jobs:
- name: Sphinx - Build HTML
run: make SPHINXOPTS='--color' html
- - uses: actions/upload-artifact@v3
+ - uses: actions/upload-artifact@v4
with:
name: godot-docs-html-${{ matrix.branch }}
path: _build/html
@@ -51,7 +52,7 @@ jobs:
make SPHINXOPTS='--color' epub
- - uses: actions/upload-artifact@v3
+ - uses: actions/upload-artifact@v4
with:
name: godot-docs-epub-${{ matrix.branch }}
path: _build/epub/GodotEngine.epub
diff --git a/.github/workflows/sync_class_ref.yml b/.github/workflows/sync_class_ref.yml
index 62afa39e57a..a2641cf008c 100644
--- a/.github/workflows/sync_class_ref.yml
+++ b/.github/workflows/sync_class_ref.yml
@@ -51,7 +51,7 @@ jobs:
./.engine-src/doc/tools/make_rst.py --color -o ./classes -l en ./.engine-src/doc/classes ./.engine-src/modules ./.engine-src/platform
- name: Submit a pull-request
- uses: peter-evans/create-pull-request@v5
+ uses: peter-evans/create-pull-request@v6
with:
commit-message: 'classref: Sync with current ${{ env.engine_rev }} branch (${{ steps.engine.outputs.rev_hash_short }})'
branch: 'classref/sync-${{ steps.engine.outputs.rev_hash_short }}'
diff --git a/_extensions/godot_descriptions.py b/_extensions/godot_descriptions.py
index 3f6f8c49210..a59cf3321b5 100644
--- a/_extensions/godot_descriptions.py
+++ b/_extensions/godot_descriptions.py
@@ -103,10 +103,11 @@ def generate_description(app, pagename, templatename, context, doctree):
doctree.walkabout(generator)
description = (
- '\n'
+ '\n'
)
- context["metatags"] += description
+ if not ' meta.name === "doc_pagename");
+ if (pageNameMetaElement == null) {
+ removeGiscusContainer();
+ return;
+ }
+
+ const pageNameDenyList = [
+ "search"
+ ];
+ if (pageNameDenyList.includes(pageNameMetaElement.content)) {
+ removeGiscusContainer();
+ return;
+ }
+
+ // Use https://giscus.app/ to regenerate the script tag if needed.
+ // data-term is set to be language-independent and version-independent, so that comments can be centralized for each page.
+ // This increases the likelihood that users will encounter comments on less frequently visited pages.
+ const scriptElement = document.createElement("script");
+ scriptElement.src = "https://giscus.app/client.js";
+ scriptElement.crossOrigin = "anonymous";
+ scriptElement.async = true;
+
+ const dataset = {
+ repo: "godotengine/godot-docs-user-notes",
+ repoId: "R_kgDOKuNx0w",
+ category: "User-contributed notes",
+ categoryId: "DIC_kwDOKuNx084CbANb",
+ mapping: "specific",
+ term: pageNameMetaElement.content,
+ strict: "1",
+ reactionsEnabled: "0",
+ emitMetadata: "0",
+ inputPosition: "bottom",
+ theme: "preferred_color_scheme",
+ lang: "en",
+ loading: "lazy",
+ };
+
+ for (const [key, value] of Object.entries(dataset)) {
+ scriptElement.dataset[key] = value;
+ }
+
+ giscusContainer.append(scriptElement);
+};
+
$(document).ready(() => {
// Remove the search match highlights from the page, and adjust the URL in the
// navigation history.
@@ -246,6 +305,17 @@ $(document).ready(() => {
Documentation.hideSearchWords();
}
+ window.addEventListener('keydown', function(event) {
+ if (event.key === '/') {
+ var searchField = document.querySelector('#rtd-search-form input[type=text]');
+ if (document.activeElement !== searchField) {
+ searchField.focus();
+ searchField.select();
+ event.preventDefault();
+ }
+ }
+ });
+
// Initialize handlers for page scrolling and our custom sidebar.
const mediaQuery = window.matchMedia('only screen and (min-width: 769px)');
@@ -414,6 +484,9 @@ $(document).ready(() => {
registerOnScrollEvent(mediaQuery);
}
+
+ // Giscus
+ registerGiscus();
});
// Override the default implementation from doctools.js to avoid this behavior.
diff --git a/_styleguides/de.md b/_styleguides/de.md
new file mode 100644
index 00000000000..649cdcefe15
--- /dev/null
+++ b/_styleguides/de.md
@@ -0,0 +1,555 @@
+# Stilregeln für die Übersetzung von Godot ins Deutsche
+
+## Einleitung
+
+Dieses Dokument soll dabei helfen, die deutsche Übersetzung von Godot, sowie
+der Godot-Dokumentation, stilistisch zu vereinheitlichen. Dabei sollen
+Lesbarkeit, Klarheit und Benutzbarkeit besonders im Vordergrund stehen.
+
+Für die Übersetzung selbst ist das Tool
+[Weblate](https://hosted.weblate.org/projects/godot-engine/) im Einsatz, das in der
+[offiziellen Dokumentation](https://docs.godotengine.org/de/4.x/contributing/documentation/editor_and_docs_localization.html) näher
+erläutert wird. Die Bedienung von Weblate ist nicht Bestandteil dieses
+Dokuments.
+
+Weblate verfügt über ein Glossar, in dem häufig verwendete Begriffe gelistet
+werden, damit sie einheitlich übersetzt werden können. In diesem Dokument
+wird daher darauf verzichtet, die Übersetzung einzelner Begriffe zu
+klären. Sollte es bei der Übersetzung eines Begriffs Uneinigkeit geben,
+so sollte dies zunächst im [Chatraum für die deutsche
+Godot-Übersetzung](https://chat.godotengine.org/channel/translation-de) diskutiert und dann ins Glossar eingetragen werden.
+
+## Technische Hilfsmittel
+
+### Automatische Übersetzungen und Workflow
+
+Die Erfahrung zeigt, dass eine Übersetzung von längeren Texten, z.B. aus der
+Anleitung oder der Klassenreferenz oft zu schnelleren und besseren Ergebnissen
+führt, wenn man den Originaltext von einer KI vorübersetzen lässt.
+
+Ein sehr zu empfehlender Übersetzungsdienst ist hier die Website
+https://www.deepl.com, die hervorragende Erstübersetzungen zur Verfügung stellt
+und selbst Formatierungszeichen, wie Fettdruck oder Links in vielen Fällen
+korrekt in die Übersetzung übernimmt.
+
+Ein weiterer Vorteil dieser Art zu übersetzen ist, dass ein und derselbe Text
+mit hoher Wahrscheinlichkeit strukturell wiederholt gleich übersetzt wird, was
+sehr hilfreich sein kann, wenn sich die Originaltexte leicht ändern und dann
+die vorgenerierte Übersetzung immer noch dicht an der vorigen Übersetzung ist.
+
+Hier ist ein empfohlener Workflow für die Übersetzung eines Textblocks:
+
+* Originaltext kopieren
+* In DeepL übersetzen lassen
+* In Übersetzungsfeld einfügen
+* Text auf Abweichungen zum Glossar prüfen und ggf. korrigieren
+* Eigene Änderungen vornehmen, wo sinnvoll
+
+Es ist zudem ratsam, Korrekturen direkt auf der rechten Seite von DeepL vorzunehmen,
+da das Tool bei wiederholten Korrekturen dazulernen kann. Begriffe, die
+hartnäckig falsch übersetzt werden, kann man zudem ins DeepL-Glossar eintragen
+und damit eine bestimmte Übersetzung erzwingen.
+
+## Stilregeln
+
+### Du oder Sie
+
+Die aktuelle Übersetzung von Godot verwendet „Sie” statt „Du” bei direkter
+Ansprache. Zwar wäre die freundlichere „Du”-Form im Gaming-Bereich ebenfalls
+eine gute Wahl, jedoch ist eine Umstellung mit sehr viel Arbeit verbunden.
+Die Diskussion einer Umstellung auf „Du” hängt daher in erster Linie an
+der Frage, ob sich eine hinreichend große Menge an Freiwilligen finden,
+um die *gesamte* Anleitung umzustellen. Bis dahin sollte aus
+praktischen Gründen die Übersetzung beim formelleren „Sie” bleiben.
+
+> :arrow_forward: You can also use the search function in the top-left corner.
+>
+> :x: Du kannst auch die Suchfunktion in der oberen linken Ecke verwenden.
+>
+> :heavy_check_mark: Sie können auch die Suchfunktion in der oberen linken Ecke verwenden.
+
+### Grammatikalische Prinzipien
+
+Die Godot-Übersetzung lässt sich in vier grobe Blöcke einteilen: *Editor*,
+*Properties*, *Anleitung* und *Klassenreferenz*.
+
+Jeder dieser Blöcke hat eigene Ansprüche
+an eine Übersetzung. Während die Anleitung in erster Linie auf Verständlichkeit
+ausgelegt ist und sich angenehm lesen soll, ist im Editor und den Properties
+häufig eine etwas knappere Sprache erforderlich, weil oft nur begrenzt
+Platz für die Texte zur Verfügung steht.
+
+Es ist daher sinnvoll, einige Grundregeln für die Übersetzung
+aufzustellen. Beachte, dass diese Regeln nicht absolut sind und im Zweifel
+mit Augenmaß übersetzt werden sollte. Trotzdem helfen solche Regeln,
+einen einheitlichen Sprachstil über die gesamte Dokumentation hinweg zu fördern.
+
+Folgende Grundregeln werden aktuell in der Übersetzung angewendet:
+
+#### Anleitung/Klassenreferenz
+
+In der *Anleitung* sollte die grammatikalische Form des Originaltexts beibehalten
+werden, es sei denn, die Lesbarkeit leidet darunter. Es sollte generell darauf
+verzichtet werden, an dieser Stelle bestimmte Sprachkonstrukte grundsätzlich
+zu vermeiden oder zu bevorzugen. Oft ist eine Anlehnung an den Originaltext
+die bessere Wahl. Insbesondere die direkte Ansprache mit
+„Sie” ist in diesem Teil der Dokumentation weit verbreitet und sollte
+so beibehalten werden.
+
+Beispiele:
+
+> :arrow_forward: The table of contents in the sidebar should let you easily
+> access the documentation for your topic of interest.
+>
+> :heavy_check_mark: Mithilfe des Inhaltsverzeichnisses in der Seitenleiste
+> können Sie leicht auf die Dokumentation zu Ihrem gewünschten Thema zugreifen.
+
+
+
+> :arrow_forward: To move our icon, we need to update its position and rotation
+> every frame in the game loop.
+>
+> :heavy_check_mark: Um unser Icon zu bewegen, müssen wir seine Position und
+> Drehung in jedem Frame der Spielschleife aktualisieren.
+
+
+
+> :arrow_forward: This build can be manually triggered by clicking the "Build"
+> button at the top right of the editor.
+>
+> :heavy_check_mark: Dieser Build kann manuell ausgelöst werden, indem man auf den
+> „Build”-Button oben rechts im Editor klickt.
+
+
+Bei manchen Abschnitten der Anleitung, wie bestimmten Überschriften oder Aufzählungen,
+bietet sich der [Infinitiv-Imperativ](https://de.wikipedia.org/wiki/Imperativ_(Modus)#Infinitiv) an:
+
+Beispiele:
+
+> :arrow_forward: Setting up the project
+>
+> :heavy_check_mark: Das Projekt einrichten
+
+
+
+> :arrow_forward: For the player, we need to do the following:
+> * Check for input.
+> * Move in the given direction.
+> * Play the appropriate animation.
+>
+> :heavy_check_mark: Für den Spieler müssen wir Folgendes tun:
+> * Auf Eingaben prüfen.
+> * Sich in die angegebene Richtung bewegen.
+> * Die entsprechende Animation abspielen.
+
+#### Properties
+
+Die *Properties* sind sehr knapp beschriebene Eigenschaften von Godot-Features,
+die im Editor oft nur wenig Platz zur Verfügung haben. Hier handelt es sich häufig
+um einzelne Begriffe, bei denen die Schwierigkeit eher im Finden der korrekten
+Vokabel besteht (dazu mehr unten), als in der grammatikalischen Form.
+
+Manchmal sind es jedoch kurze Sätze, die in den meisten Fällen am besten
+im Infinitiv-Imperativ (siehe Beispiele oben) zu übersetzen sind, da diese Form
+hier sprachlich gut passt und wenig Platz einnimmt. Auch sollten hier, wo möglich,
+Artikel weggelassen werden, genauso wie es im Original meist schon gemacht wird.
+
+
+> :arrow_forward: Keep Screen On
+>
+> :x: Der Bildschirm wird eingeschaltet gelassen
+>
+> :heavy_check_mark: Bildschirm eingeschaltet lassen
+
+#### Editor
+
+Die Texte des *Editors* bestehen sowohl aus kleinen Textblöcken, wenn z.B. ein Tooltip
+eine Einstellung näher beschreibt, als auch aus kurzen Begriffen, die oft wenig
+Platz zur Verfügung haben.
+
+Bei der Übersetzung des Editors gelten somit sowohl die Regeln für die Anleitung, als auch
+die für die Properties, je nachdem, ob der zu übersetzende Text eher in Langform
+oder in Kurzform geschrieben ist.
+
+### Keine Angst vor englischen Begriffen
+
+Manche Begriffe lassen sich nur schwer ins Deutsche übersetzen. Das sind zum
+Beispiel technische Begriffe, die bereits in ihrer englischen
+Form in den Sprachgebrauch Einzug gefunden haben (*Thread*, *Debuggen*,
+*Spawn-Punkt*).
+
+Andere Begriffe haben gängige deutsche Übersetzungen, wie z.B. *Knoten* für *node*.
+Da es in der Godot-Welt aber Objekte gibt, die feststehende Namen haben,
+etwa `Node2D`, wollen wir davon abgeleitete Vokabeln ebenfalls englisch lassen.
+
+> :arrow_forward: This feature is only available when connecting nodes in the editor.
+>
+> :x: Dieses Feature ist nur verfügbar, wenn Knoten im Editor verbunden werden.
+>
+> :heavy_check_mark: Dieses Feature ist nur verfügbar, wenn Nodes im Editor verbunden werden.
+
+Du wirst beim Lesen der Anleitung viele dieser absichtlich eingedeutschten
+Begriffe finden. Dies mag an der einen oder anderen Stelle etwas ungewohnt wirken,
+aber es gibt viele Situationen, in denen damit Übersetzungsprobleme vermieden werden können.
+
+Sollte es vorkommen, dass eine Regel unsinnig erscheint, sollte das im
+[Chat](https://chat.godotengine.org/channel/translation-de) diskutiert werden. Um einen Überblick über die dokumentierten Begriffe
+zu bekommen, die englisch bleiben sollen, lohnt sich ein
+Blick ins [Glossar](https://hosted.weblate.org/browse/godot-engine/glossary/de/).
+Sollte ein Begriff dort nicht hinterlegt sein, kann man die Suchfunktion
+von Weblate verwenden, um Beispiele in den vorhandenen Übersetzungen zu finden.
+
+Manchmal ist es auch notwendig, nach eigenem Empfinden eine Entscheidung zu
+treffen oder von einer der Glossar-Regeln abzuweichen.
+Das ist vollkommen okay, denn Sprache ist komplex, und man kann nicht für
+jeden Sonderfall eine vordefinierte Lösung festlegen.
+
+Beispiel 1:
+
+> :arrow_forward: Stereo Panning
+>
+> :x: Stereoverschiebung
+>
+> :heavy_check_mark: Stereo-Panning
+
+Beispiel 2:
+
+> :arrow_forward: Drag to pan the view
+>
+> :x: Ziehen, um den View zu pannen.
+>
+> :heavy_check_mark: Ziehen um den View zu verschieben
+
+
+Das erste Beispiel stammt aus dem Audio-Bereich, wo Stereo-Panning ein gängiger
+Begriff ist. Das zweite Beispiel verwendet das Wort „panning” als
+allgemeine Vokabel. Hier ist kein besonderer technischer Jargon
+gemeint, somit kann das Wort auch normal auf Deutsch übersetzt werden.
+
+Diese Unterscheidung wird im Glossar oft mit zwei Einträge desselben Wortes
+abgebildet. Dabei soll ein Beschreibungstext dabei helfen, zu erklären,
+in welchem Kontext welche Übersetzung passend ist.
+
+Weiter unten findest Du Recherchetipps, die dabei helfen können,
+eine passende Übersetzung zu finden, sollte ein Begriff weder im Glossar
+noch in der bestehenden Dokumentation auffindbar sein.
+
+### Kompositionswörter
+
+Das im Deutschen übliche Aneinanderreihen von Wörtern (Komposition) wird
+im Englischen durch das Hintereinandersetzen von Wörtern mit
+Leerzeichen erreicht. Bei sehr langen Wortfolgen ergeben sich dabei
+logische Untergruppen aus dem Zusammenhang, auch wenn das in Extremfällen
+manchmal wenig intuitiv erscheint:
+
+> Default Font Multichannel Signed Distance Field
+
+Im Deutschen sollte dagegen vermieden werden, lange Kompositionen zu bilden,
+da die Lesbarkeit extrem leidet, wenn die Wörter sehr lang werden. Eine
+einfache Lösung ist hier, mithilfe von Bindestrichen Klarheit zu schaffen.
+Allerdings ist es im Allgemeinen besser, die grammatikalische Struktur des
+Begriffs
+aufzubrechen und ihn klar zu beschreiben. Dabei ist es notwendig,
+nachzulesen, was dieser Begriff im Kontext von Godot eigentlich genau bedeutet:
+
+> :arrow_forward: Medium Quality Probe Ray Count
+>
+> :x: Mittelqualitätsprobestrahlenanzahl
+>
+> :heavy_check_mark: Strahlenzahl für Probes bei mittlerer Qualität
+
+Es sollte bei der Übersetzung generell vermieden werden, überlange Komposita zu
+erzeugen. Als Richtschnur sollten mehr als zwei Wörter nur in Ausnahmefällen zu
+Komposita verbunden werden, mehr als drei Wörter hingegen am besten gar nicht.
+Sollte sich keine brauchbare Übersetzung eines Kompositums finden, dann
+sollten zumindest Bindestriche eingesetzt werden, um die Teilbegriffe klarer
+voneinander zu trennen.
+
+Beispiele:
+
+> :arrow_forward: Interaction Profile Path
+>
+> :x: Interaktionsprofilpfad
+>
+> :heavy_check_mark: Interaktionsprofil-Pfad
+>
+> :heavy_check_mark: Pfad zum Interaktionsprofil
+
+
+
+> :arrow_forward: Render Target Size Multiplier
+>
+> :x: Renderzielgrößenfaktor
+>
+> :heavy_check_mark: Render-Zielgrößen-Faktor
+>
+> :heavy_check_mark: Faktor für Render-Zielgröße
+
+### Schachtelsätze und „die die”-Wiederholungen
+
+Beim direkten Übersetzen eines englischen Satzes kommt man leicht in
+Versuchung, Schachtelsätze oder allgemein sehr lange Sätze zu bilden. Auch hier
+ist eine KI-Vorübersetzung von Nutzen, die dies oft recht gut vermeidet.
+Im Allgemeinen ist es allerdings einfach so, dass deutsche Wörter und Sätze im Mittel länger
+als ihre englischen Pendants sind. Daher sollte darauf geachtet werden,
+die deutsche Übersetzung nicht zu komplex oder zu lang werden zu lassen. Es
+kann durchaus guter Stil sein, einen Satz in zwei Sätze aufzuteilen, auch wenn
+dabei die grammatikalische Form des Originals nicht erhalten bleibt.
+
+Ein weiterer verwandter Aspekt ist hier die Verwendung der Wortwiederholung
+„die die”, die ebenfalls vermieden werden sollte. Eine Ersetzung durch „welche
+die” scheint oft naheliegend, klingt aber umständlich und ist keine gute Lösung.
+Stattdessen ist eine Umformulierung des Satzes oft die bessere Wahl.
+
+Beispiele:
+
+> :arrow_forward: Min SDK cannot be lower than %d, which is the version
+> needed by the Godot library.
+>
+> :x: Min SDK kann nicht niedriger als %d sein, der Version, die die
+> Godot-Bibliothek benötigt.
+>
+> :heavy_check_mark: Min SDK kann nicht niedriger als %d sein (die
+> Version, die von der Godot-Bibliothek benötigt wird).
+
+
+
+> :arrow_forward: In addition, one will need a primary GUI for their game that
+> manages the various menus and widgets the project needs.
+>
+> :x: Außerdem benötigt man für sein Spiel eine primäre GUI, die die
+> verschiedenen Menüs und Widgets verwaltet, die das Projekt benötigt.
+>
+> :heavy_check_mark: Außerdem benötigt man für sein Spiel eine primäre GUI,
+> um die verschiedenen Menüs und Widgets des Projekts zu verwalten.
+>
+> :heavy_check_mark: Außerdem benötigt man für sein Spiel eine primäre GUI.
+> Diese GUI verwaltet die verschiedenen Menüs und Widgets des Projekts.
+
+### Eigene Ergänzungen
+
+Achte bei der Übersetzung der Anleitung darauf, nur den Originaltext zu
+übersetzen, ohne eigene Ergänzungen oder Erläuterungen vorzunehmen. Sollte
+der Originaltext unvollständig oder erklärungswürdig sein, so beantrage zuerst
+eine Änderung am Original oder stelle selbst einen Pull-Request in
+[godot-docs](https://github.com/godotengine/godot-docs).
+Wir sollten uns auf Weblate ausschließlich als Übersetzer und nicht als
+Autoren verstehen.
+
+> :arrow_forward:: Computes the arctan of x
+>
+> :x: Berechnet den Arcustangens von x. Der Arcustangens ist die Umkehrfunktion
+> des Tangens.
+>
+> :heavy_check_mark: Berechnet den Arcustangens von x
+
+## Konsistenz zwischen Editor/Properties und Anleitung
+
+Wenn Du einen Begriff aus dem Editor oder den Properties änderst, solltest Du
+die Weblate-Seite der Anleitung nach diesen Begriffen durchsuchen und sie
+entsprechend anpassen, damit die Übersetzungen konsistent bleiben.
+
+Beachte auch, dass ein Editor/Properties-Begriff meist an mehreren Stellen im Editor
+oder den Properties vorkommt, sodass nach Möglichkeit alle dieser Stellen
+mit übersetzt werden sollten.
+
+## Testen der Übersetzung
+
+Für Übersetzungen des Editors und der Properties ist es ratsam, diese
+auch selbst zu testen, indem
+man [die aktuelle Übersetzung herunterlädt](https://docs.godotengine.org/de/4.x/contributing/documentation/editor_and_docs_localization.html#offline-translation-and-testing)
+und Godot mit den Änderungen [selbst kompiliert](https://docs.godotengine.org/de/4.x/contributing/development/compiling/compiling_for_windows.html).
+
+Gerade bei der Anleitung kommt es oft auf den Kontext zwischen benachbarten
+Textblöcken an, sodass das Lesen eines ganzen Artikels Fehler sichtbar
+macht, die in Weblate leicht überlesen werden können.
+
+## Recherchetipps
+
+Grundsätzlich sollte man sich bei
+der Übersetzung eines Begriffs gut überlegen, ob man eine korrekte
+Übersetzung aus der eigenen Spracherfahrung vornehmen kann, oder besser erst
+einmal etwas näher recherchieren sollte.
+
+Die erste Quelle bei der Übersetzung feststehender Begriffe
+sollte das Glossar und die bestehenden Übersetzungen sein.
+Die Suchfunktion von Weblate leistet hier gute Dienste.
+
+Wenn ein Begriff in diesen Quellen nicht gefunden werden kann oder Zweifel an
+ihrer Korrektheit bestehen, gibt es einige weitere hilfreiche Quellen:
+
+Grundbegriffe aus der
+Wissenschaft kann man auf der englischen [Wikipedia](https://www.wikipedia.org)
+nachschlagen.
+Von dort aus lässt sich über das Sprachmenü der deutsche
+Schwesterartikel aufrufen, wo man oft eine korrekte deutsche Übersetzung des
+Begriffs findet. Achte allerdings darauf, ob der deutsche Artikel auch
+dieselbe Bedeutung des Wortes beschreibt, wie der englische Artikel.
+
+Bei weiteren allgemeinen technischen Begriffen kann
+man auf Webseiten wie www.linguee.com zurückgreifen, um zu schauen, wie
+ein Begriff von anderen, oft professionellen, Übersetzern in unterschiedlichen
+Kontexten bereits übersetzt wurde.
+
+Zuletzt gibt es Fachbegriffe, die direkt aus dem Gaming oder Game-Design
+stammen, und es ist sicherlich nicht verkehrt, bei der Übersetzung einmal
+nachzuschauen, wie andere Tools aus dem Bereich diese Begriffe übersetzen
+(Unity, Unreal). Da diese Tools über das Budget für professionelle
+Übersetzer verfügen, ist dies eine besonders hilfreiche Quelle für sehr
+spezifische Fachbegriffe.
+
+Zuletzt kann es sinnvoll sein, sich an erfahrene Entwickler zu wenden, um
+die Übersetzung eines Begriffs zu klären, entweder im [Chat](https://chat.godotengine.org/channel/translation-de) oder im
+[deutschen Godot-Discord](https://discord.com/channels/553242711109533729/)
+
+
+## Glossar-Regeln
+
+Dieser Abschnitt befasst sich mit dem Glossar. Wenn Du einfach nur übersetzen
+möchtest, kannst Du hier aufhören zu lesen. Falls Du aber Glossar-Einträge pflegen
+möchtest, solltest Du weiterlesen.
+
+Das Weblate-Glossar folgt bestimmten eigenen Regeln, die beachtet werden
+sollten:
+
+### Was kommt überhaupt ins Glossar?
+
+Das Glossar hat seinen praktischen Nutzen dort, wo man ein Wort an
+verschiedenen Stellen gleich übersetzen möchte. Immer, wenn das
+gewährleistet werden soll, lohnt sich auch ein Glossar-Eintrag. Beachte
+allerdings auch, dass ein sehr großes Glossar Pflegeaufwand bedeutet. Nicht
+jedes Wort muss also unbedingt einen Eintrag bekommen.
+
+> :x: color -> Farbe
+
+Das Wort „color” ist ziemlich eindeutig und bedarf vermutlich keiner
+expliziten Klärung in einem Glossar.
+
+> :heavy_check_mark: ctrl -> Strg
+
+Hier haben wir einen Fachbegriff, der über ein eindeutiges
+deutsches Äquivalent verfügt. Dafür kann man durch eine „Forbidden
+Translation” (s.u.) darauf hinweisen, dass eine Übersetzung als das
+vielleicht naheliegende „Ctrl” nicht zulässig ist.
+
+
+> :heavy_check_mark: aligned -> bündig/ausgerichet
+
+In diesem Fall kann das Glossar dabei helfen, die verschiedenen
+Übersetzungen des Wortes „aligned” zu definieren, das in der Form
+*left-aligned* als *linksbündig* und in der Form *axis-aligned* als *an den
+Achsen ausgerichtet* übersetzt werden sollte.
+
+> :heavy_check_mark: blitting -> Blitting
+
+Hier verweist das Glossar darauf, dass ein Begriff ein
+feststehender Fachbegriff ist, der im keine gute deutsche Entsprechung
+hat und daher englisch bleibt.
+
+### Ein Wort, ein Eintrag
+
+Da Weblate seine Glossar-Einträge bei der Übersetzung automatisch anbietet,
+sobald im Originaltext ein bestimmter Begriff vorkommt, sollte
+sichergestellt werden, dass Einträge auch gefunden werden. Das kann nur
+gelingen, wenn ein Eintrag in der englischen Form genau so auch in einem
+Text vorkommen kann.
+
+> :x: float, floats -> float
+>
+> :heavy_check_mark: float -> float
+
+Im vorigen Beispiel könnte Weblate für einen Text, der den *Float*-Datentyp
+erklärt, den Glossareintrag nicht finden, da der Begriff *float, floats* so
+im Originaltext nicht vorkommt.
+
+### Ein Wort, mehrere Bedeutungen
+
+Sollte ein englisches Wort auf mehrere Arten übersetzt werden können, dann
+sollte für jede Übersetzung ein eigener Glossar-Eintrag angelegt werden.
+Dies hilft bei der Lesbarkeit und macht es später leichter, weitere Bedeutungen
+hinzuzufügen.
+
+> :x: volume -> Volumen, Lautstärke
+>
+> :heavy_check_mark: volume -> Volumen (*Translation Explanation:* im Sinne von „Rauminhalt”)
+>
+> :heavy_check_mark: volume -> Lautstärke (*Translation Explanation:* im Audio-Kontext)
+
+Es bietet sich an, über das jeweilige „Translation Explanation”-Feld
+zu beschreiben, wie sich
+die verschiedenen Übersetzungen unterscheiden und in welchen Fällen man sie
+verwenden sollte.
+
+**Achtung:** Es gibt auch das Feld
+„Explanation”, das für die Erklärung des Originaltextes gedacht
+ist. Dieses Feld sollte nicht verwendet werden, da es in der Seitenleiste
+zu unschönen Doppeleinträgen führen kann.
+
+### Grundformen verwenden
+
+Ein englisches Wort sollte grundsätzlich in seiner einfachsten Form ins
+Glossar eingetragen werden, damit es in möglichst vielen Fällen automatisch
+zugeordnet werden kann. Das bedeutet bei Verben die Grundform (**wichtig:** ohne *to*)
+und bei Substantiven der Singular.
+
+Beispiele:
+
+> :x: to hide -> verbergen
+>
+> :heavy_check_mark: hide -> verbergen
+
+
+
+> :x: constants -> Konstanten
+>
+> :heavy_check_mark: constant -> Konstante
+
+Leider unterstützt die aktuelle Version von Weblate keine
+morphologischen Varianten. Wenn also ein Wort im Glossar als Singular angegeben wird, dann
+wird es beim Übersetzen nur angeboten, wenn auch im Übersetzungstext der Singular
+verwendet wird. Es gibt bereits ein [Ticket](https://github.com/WeblateOrg/weblate/issues/3023)
+dazu im Weblate-Github. Bis zur Lösung dieses Problems sollten wir vermeiden,
+als Workaround Singular *und* Plural-Einträge im Glossar zu erzeugen, da das
+schlecht zu warten ist.
+
+### Terminology
+
+Ein als „Terminology” markierter Eintrag wird automatisch in allen
+anderen Sprachen in die Glossare eingetragen und führt dort zu offenen
+Arbeitspaketen.
+
+Das kann dazu führen, dass neue Glossareinträge in der deutschen
+Übersetzung erscheinen, weil eine andere Sprache sie eingefügt hat. In diesem
+Fall ist es legitim, das Terminology-Flag zu entfernen und den Eintrag zu löschen,
+wenn er aus unserer Sicht nicht sinnvoll ist. Dieser Vorgang lässt den Eintrag
+in allen anderen Sprachen unverändert.
+
+Wir sollten das Terminology-Flag grundsätzlich nicht setzen, da es potentiell
+die Glossare anderer Sprachen zumüllt, insbesondere, wenn diese andere Definitionen
+davon haben, welche Art von Begriffen als „Terminologie” zu bewerten sind.
+
+
+### Untranslatable
+
+Ein als „Untranslatable” markierter Eintrag ist ein Begriff, der bewusst nicht
+übersetzt werden soll, z.B. feststehende Begriffe wie `Android` oder `OpenGL`.
+Allerdings haben viele dieser Begriffe eigentlich nichts im Glossar verloren,
+sodass dieses Flag nicht allzu häufig vorkommen sollte.
+Man kann einen als „Untranslatable” markierten Begriff daran
+erkennen, dass er bei der Glossar-Einblendung in der Seitenleiste gelb hinterlegt ist.
+
+### Forbidden Translation
+
+Ein als „Forbidden Translation” markierter Eintrag kann dazu verwendet
+werden, um eine Übersetzung aufzuzeigen, die nicht verwendet werden soll, zum
+Beispiel weil sie einen fehleranfälligen
+[Falschen Freund](https://de.wikipedia.org/wiki/Falscher_Freund) darstellt
+oder um bestimmte deutsche Begriffe zu sperren. Zum Beispiel könnte man sich
+darauf einigen, den Begriff *enemy* durchgängig als *Gegner* und nicht als das
+extremere *Feind* zu übersetzen. In dem Fall würden beide Begriffe ins Glossar
+eingetragen, wobei der zweite als „Forbidden Translation” markiert wird.
+
+## Änderungen an diesem Dokument
+
+Änderungen an diesem Dokument sollten im [Chat](https://chat.godotengine.org/channel/translation-de) diskutiert und nach
+Klärung per Pull-Request ins Github-Repo committet werden.
diff --git a/_templates/layout.html b/_templates/layout.html
index 268c4ca381a..2afebc33468 100644
--- a/_templates/layout.html
+++ b/_templates/layout.html
@@ -6,12 +6,13 @@
{% endblock -%}
{% block extrahead -%}
-
-
+
+
+
{% endblock -%}
{% block linktags -%}
-
+
{% if godot_inject_language_links -%}
{% for alternate_lang in godot_docs_supported_languages -%}
{# Convert to ISO 639-1 format, e.g. zh_CN -> zh-cn -#}
@@ -66,7 +67,17 @@
{% endif %}
{% block body %}{% endblock %}
+
+{% if (not meta or meta.get('allow_comments') != 'False') and godot_show_article_comments %}
+
+{% endif %}
+
{%- if self.comments()|trim %}
{%- block comments %}{% endblock %}
diff --git a/_tools/redirects/redirects.csv b/_tools/redirects/redirects.csv
index f85a7179eba..a003118c3b0 100644
--- a/_tools/redirects/redirects.csv
+++ b/_tools/redirects/redirects.csv
@@ -1,5 +1,6 @@
source,destination
/about/index.html,/index.html
+/about/troubleshooting.html,/tutorials/troubleshooting.html
/classes/_classes.html,/classes/
/community/contributing/best_practices_for_engine_contributors.html,/contributing/development/best_practices_for_engine_contributors.html
/community/contributing/bisecting_regressions.html,/contributing/workflow/bisecting_regressions.html
@@ -419,3 +420,5 @@ source,destination
/tutorials/viewports/multiple_resolutions.html,/tutorials/rendering/multiple_resolutions.html
/tutorials/viewports/using_viewport_as_texture.html,/tutorials/shaders/using_viewport_as_texture.html
/tutorials/viewports/viewports.html,/tutorials/rendering/viewports.html
+/contributing/development/compiling/compiling_for_uwp.html,/about/faq.html#which-platforms-are-supported-by-godot
+/tutorials/export/exporting_for_uwp.html,/about/faq.html#which-platforms-are-supported-by-godot
diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst
index 0a013277f66..a3a51350ef8 100644
--- a/about/complying_with_licenses.rst
+++ b/about/complying_with_licenses.rst
@@ -1,14 +1,21 @@
+:allow_comments: False
+
.. _doc_complying_with_licenses:
Complying with licenses
=======================
+.. warning::
+
+ The recommendations in this page **are not legal advice.** They are provided
+ in good faith to help users navigate license attribution requirements.
+
What are licenses?
------------------
Godot is created and distributed under the `MIT License `_.
-It doesn't have a sole owner either, as every contributor that submits code to
-the project does it under this same license and keeps ownership of the
+It doesn't have a sole owner, as every contributor that submits code to
+the project does it under this same license and keeps ownership of their
contribution.
The license is the legal requirement for you (or your company) to use and
@@ -22,13 +29,12 @@ with the original one.
If you are interested in licence compliance as a contributor, you can find
guidelines :ref:`here `.
-.. warning::
+.. tip::
- In your project's credits screen, remember to also list third-party notices
+ Alongside the Godot license text, remember to also list third-party notices
for assets you're using, such as textures, models, sounds, music and fonts.
-
- Free assets in particular often come with licenses that require attribution.
- Double-check their license before using those assets in a project.
+ This includes free assets, which often come with licenses that require
+ attribution.
Requirements
------------
@@ -36,18 +42,33 @@ Requirements
In the case of the MIT license, the only requirement is to include the license
text somewhere in your game or derivative project.
-This text reads as follows:
+This text reads as follows::
This game uses Godot Engine, available under the following license:
Copyright (c) 2014-present Godot Engine contributors.
Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.
- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Beside its own MIT license, Godot includes code from a number of third-party
+libraries. See :ref:`doc_complying_with_licenses_thirdparty` for details.
.. note::
@@ -58,31 +79,9 @@ This text reads as follows:
Inclusion
---------
-The license does not specify how it has to be included, so anything is valid as
-long as it can be displayed under some condition. These are the most common
-approaches (only need to implement one of them, not all).
-
-.. tip::
-
- Godot provides several methods to get license information in the Engine
- singleton. This allows you to source the license information directly from
- the engine binary, which prevents the information from becoming outdated if
- you update engine versions.
-
- For the engine itself:
-
- - :ref:`Engine.get_license_text`
-
- For third-party components used by the engine:
-
- - :ref:`Engine.get_license_info`
- - :ref:`Engine.get_copyright_info`
-
- For miscellaneous engine contributor information. You don't have to include
- these ones in your project, but they're listed here for reference:
-
- - :ref:`Engine.get_author_info`
- - :ref:`Engine.get_donor_info`
+The license text must be made available to the user. The license doesn't specify
+how the text has to be included, but here are the most common approaches (you
+only need to implement one of them, not all).
Credits screen
^^^^^^^^^^^^^^
@@ -101,20 +100,20 @@ or **Open Source Licenses**.
Output log
^^^^^^^^^^
-Printing the licensing text using the :ref:`print() `
+Printing the license text using the :ref:`print() `
function may be enough on platforms where a global output log is readable.
-This is the case on desktop platforms, Android and HTML5 (but not iOS and UWP).
+This is the case on desktop platforms, Android and HTML5 (but not iOS).
Accompanying file
^^^^^^^^^^^^^^^^^
If the game is distributed on desktop platforms, a file containing the license
-can be added to the software that is installed to the user PC.
+text can be added to the software that is installed to the user PC.
Printed manual
^^^^^^^^^^^^^^
-If the game includes printed manuals, license text can be included there.
+If the game includes a printed manual, the license text can be included there.
Link to the license
^^^^^^^^^^^^^^^^^^^
@@ -123,71 +122,40 @@ The Godot Engine developers consider that a link to ``godotengine.org/license``
in your game documentation or credits would be an acceptable way to satisfy
the license terms.
-Third-party licenses
---------------------
-
-Godot itself contains software written by
-`third parties `_.
-Most of it does not require license inclusion, but some do.
-Make sure to do it if these are compiled in your Godot export template. If
-you're using the official export templates, all libraries are enabled. This
-means you need to provide attribution for all the libraries listed below.
-
-Here's a list of libraries requiring attribution:
-
-FreeType
-^^^^^^^^
-
-Godot uses `FreeType `_ to render fonts. Its license
-requires attribution, so the following text must be included together with the
-Godot license:
-
- Portions of this software are copyright © The FreeType Project (www.freetype.org). All rights reserved.
-
-.. note::
-
- should correspond to the value from the FreeType version used
- in your build. This information can be found in the editor by opening
- the **Help > About** dialog and going to the **Third-party Licenses**
- tab.
-
-ENet
-^^^^
-
-Godot includes the `ENet `_ library to handle
-high-level multiplayer. ENet has similar licensing terms as Godot:
-
-
- Copyright (c) 2002-2020 Lee Salzman
+.. tip::
- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ Godot provides several methods to get license information in the
+ :ref:`Engine ` singleton. This allows you to source the
+ license information directly from the engine binary, which prevents the
+ information from becoming outdated if you update engine versions.
- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ For the engine itself:
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ - :ref:`Engine.get_license_text`
-mbed TLS
-^^^^^^^^
+ For third-party components used by the engine:
-If the project is exported with Godot 3.1 or later, it includes `mbed TLS `_.
-The Apache license needs to be complied to by including the following text:
+ - :ref:`Engine.get_license_info`
+ - :ref:`Engine.get_copyright_info`
- Copyright The Mbed TLS Contributors
+.. _doc_complying_with_licenses_thirdparty:
- Licensed under the Apache License, Version 2.0 (the "License"); you may
- not use this file except in compliance with the License.
- You may obtain a copy of the License at
+Third-party licenses
+--------------------
- http://www.apache.org/licenses/LICENSE-2.0
+Godot itself contains software written by
+`third parties `_,
+which is compatible with, but not covered by Godot's MIT license.
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
+Many of these dependencies are distributed under permissive open source licenses
+which require attribution by explicitly citing their copyright statement and
+license text in the final product's documentation.
-.. note::
+Given the scope of the Godot project, this is fairly difficult to do thoroughly.
+For the Godot editor, the full documentation of third-party copyrights and
+licenses is provided in the `COPYRIGHT.txt `_
+file.
- If you exported your project using a
- :ref:`custom build with specific modules disabled `,
- you don't need to list the disabled modules' licenses in your exported project.
+A good option for end users to document third-party licenses is to include this
+file in your project's distribution, which you can e.g. rename to
+``GODOT_COPYRIGHT.txt`` to prevent any confusion with your own code and assets.
diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst
index 65bc1c44652..6c432a56ab4 100644
--- a/about/docs_changelog.rst
+++ b/about/docs_changelog.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
.. _doc_docs_changelog:
Documentation changelog
@@ -11,6 +13,34 @@ added since version 3.0.
.. note:: This document only contains new pages so not all changes are reflected,
many pages have been substantially updated but are not reflected in this document.
+New pages since version 4.1
+---------------------------
+
+C#
+^^
+
+- :ref:`doc_c_sharp_diagnostics`
+
+Development
+^^^^^^^^^^^
+
+- :ref:`doc_2d_coordinate_systems`
+
+Migrating
+^^^^^^^^^
+
+- :ref:`doc_upgrading_to_godot_4.2`
+
+I/O
+^^^
+
+- :ref:`doc_runtime_loading_and_saving`
+
+Platform-specific
+^^^^^^^^^^^^^^^^^
+
+- :ref:`doc_android_library`
+
New pages since version 4.0
---------------------------
diff --git a/about/faq.rst b/about/faq.rst
index ee5dd1a060a..58da3c68f40 100644
--- a/about/faq.rst
+++ b/about/faq.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
.. meta::
:keywords: FAQ
@@ -47,7 +49,7 @@ Which platforms are supported by Godot?
**For exporting your games:**
-* Windows (and UWP)
+* Windows
* macOS
* Linux, \*BSD
* Android
@@ -68,6 +70,13 @@ about :ref:`doc_consoles`.
For more on this, see the sections on :ref:`exporting `
and :ref:`compiling Godot yourself `.
+.. note::
+
+ Godot 3 also had support for Universal Windows Platform (UWP). This platform
+ port was removed in Godot 4 due to lack of maintenance, and it being
+ deprecated by Microsoft. It is still available in the current stable release
+ of Godot 3 for interested users.
+
Which programming languages are supported in Godot?
---------------------------------------------------
@@ -509,7 +518,7 @@ reasons why we have chosen SCons over other alternatives. For example:
customization (:ref:`modules `). This requires
complex logic which is easier to write in an actual programming language (like Python)
rather than using a mostly macro-based language only meant for building.
-- Godot build process makes heavy use of cross-compiling tools. Each
+- Godot's build process makes heavy use of cross-compiling tools. Each
platform has a specific detection process, and all these must be
handled as specific cases with special code written for each.
diff --git a/about/introduction.rst b/about/introduction.rst
index 5ef95b44a50..c3314f475bf 100644
--- a/about/introduction.rst
+++ b/about/introduction.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
.. _doc_about_intro:
Introduction
@@ -28,7 +30,7 @@ is a great starting point.
In case you have trouble with one of the tutorials or your project,
you can find help on the various :ref:`Community channels `,
especially the Godot `Discord`_ community and
-`Q&A `_.
+`Forum `_.
About Godot Engine
------------------
diff --git a/about/list_of_features.rst b/about/list_of_features.rst
index 17c8bf2d772..82f9a8edd57 100644
--- a/about/list_of_features.rst
+++ b/about/list_of_features.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
.. _doc_list_of_features:
List of features
@@ -14,24 +16,30 @@ This page aims to list **all** features currently supported by Godot.
Platforms
---------
+.. seealso::
+
+ See :ref:`doc_system_requirements` for hardware and software version requirements.
+
**Can run both the editor and exported projects:**
-- Windows 7 and later (64-bit and 32-bit).
-- macOS 10.12 and later (64-bit, x86 and ARM).
-- Linux (64-bit, x86 and ARM).
+- Windows (x86, 64-bit and 32-bit).
+- macOS (x86 and ARM, 64-bit only).
+- Linux (x86 and ARM, 64-bit and 32-bit).
- Binaries are statically linked and can run on any distribution if compiled
on an old enough base distribution.
- - Official binaries are compiled on Ubuntu 14.04.
- - 32-bit binaries can be compiled from source.
+ - Official binaries are compiled using the
+ `Godot Engine buildroot `__,
+ allowing for binaries that work across common Linux distributions
+ (including LTS variants).
-- Android 6.0 and later (editor support is experimental).
+- Android (editor support is experimental).
- :ref:`Web browsers `. Experimental in 4.0,
using Godot 3.x is recommended instead when targeting HTML5.
**Runs exported projects:**
-- iOS 11.0 and later.
+- iOS.
- :ref:`Consoles `.
Godot aims to be as platform-independent as possible and can be
@@ -55,7 +63,7 @@ Editor
Visual Studio Code or Vim.
- GDScript :ref:`debugger `.
- - No support for debugging in threads yet.
+ - Support for debugging in threads is available since 4.2.
- Visual profiler with CPU and GPU time indications for each step of the
rendering pipeline.
- Performance monitoring tools, including
@@ -362,6 +370,8 @@ Rendering
**Anti-aliasing:**
- Temporal :ref:`antialiasing ` (TAA).
+- AMD FidelityFX Super Resolution 2.2 :ref:`antialiasing ` (FSR2),
+ which can be used at native resolution as a form of high-quality temporal antialiasing.
- Multi-sample antialiasing (MSAA), for both :ref:`doc_2d_antialiasing` and :ref:`doc_3d_antialiasing`.
- Fast approximate antialiasing (FXAA).
- Super-sample antialiasing (SSAA) using bilinear 3D scaling and a 3D resolution scale above 1.0.
@@ -372,8 +382,8 @@ Rendering
- Support for :ref:`rendering 3D at a lower resolution `
while keeping 2D rendering at the original scale. This can be used to improve
performance on low-end systems or improve visuals on high-end systems.
-- Resolution scaling uses bilinear filtering or AMD FidelityFX Super Resolution
- 1.0 (FSR).
+- Resolution scaling uses bilinear filtering, AMD FidelityFX Super Resolution
+ 1.0 (FSR1) or AMD FidelityFX Super Resolution 2.2 (FSR2).
- Texture mipmap LOD bias is adjusted automatically to improve quality at lower
resolution scales. It can also be modified with a manual offset.
@@ -639,10 +649,14 @@ XR support (AR and VR)
- Out of the box :ref:`support for OpenXR `.
- - Including support for popular headsets like the Meta Quest and the Valve Index.
+ - Including support for popular desktop headsets like the Valve Index, WMR headsets, and Quest over Link.
+
+- Support for :ref:`Android based headsets ` using OpenXR through a plugin.
+
+ - Including support for popular stand alone headsets like the Meta Quest 1/2/3 and Pro, Pico 4, Magic Leap 2, and Lynx R1.
-- Support for ARKit on iOS out of the box.
-- Support for the OpenVR APIs.
+- Other devices supported through an XR plugin structure.
+- Various advanced toolkits are available that implement common features required by XR applications.
GUI system
----------
diff --git a/about/release_policy.rst b/about/release_policy.rst
index ee0ae7f4a61..777381eb922 100644
--- a/about/release_policy.rst
+++ b/about/release_policy.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
.. _doc_release_policy:
Godot release policy
@@ -80,26 +82,26 @@ on GitHub.
+--------------+----------------------+--------------------------------------------------------------------------+
| **Version** | **Release date** | **Support level** |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 4.2 | November 2023 | |unstable| *Development.* Receives new features, usability and |
+| Godot 4.3 | April 2024 | |unstable| *Development.* Receives new features, usability and |
| (`master`) | (estimate) | performance improvements, as well as bug fixes, while under development. |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 4.1 | July 2023 | |supported| Receives fixes for bugs and security issues, as well as |
+| Godot 4.2 | November 2023 | |supported| Receives fixes for bugs and security issues, as well as |
| | | patches that enable platform support. |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 4.0 | March 2023 | |supported| Receives fixes for bugs and security issues, as well as |
+| Godot 4.1 | July 2023 | |supported| Receives fixes for bugs and security issues, as well as |
| | | patches that enable platform support. |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 3.6 | Q3 2023 (estimate) | |supported| *Beta.* Receives new features, usability and performance |
+| Godot 4.0 | March 2023 | |eol| No longer supported (last update: 4.0.4). |
++--------------+----------------------+--------------------------------------------------------------------------+
+| Godot 3.6 | Q1 2024 (estimate) | |supported| *Beta.* Receives new features, usability and performance |
| (`3.x`, LTS) | | improvements, as well as bug fixes, while under development. |
+--------------+----------------------+--------------------------------------------------------------------------+
| Godot 3.5 | August 2022 | |supported| Receives fixes for bugs and security issues, as well as |
| | | patches that enable platform support. |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 3.4 | November 2021 | |eol| No longer supported, as fully superseded by the compatible 3.5 |
-| | | release (last update: 3.4.5). |
+| Godot 3.4 | November 2021 | |eol| No longer supported (last update: 3.4.5). |
+--------------+----------------------+--------------------------------------------------------------------------+
-| Godot 3.3 | April 2021 | |eol| No longer supported, as fully superseded by the compatible 3.4 |
-| | | release (last update: 3.3.4). |
+| Godot 3.3 | April 2021 | |eol| No longer supported (last update: 3.3.4). |
+--------------+----------------------+--------------------------------------------------------------------------+
| Godot 3.2 | January 2020 | |eol| No longer supported (last update: 3.2.3). |
+--------------+----------------------+--------------------------------------------------------------------------+
diff --git a/about/system_requirements.rst b/about/system_requirements.rst
new file mode 100644
index 00000000000..f90134f6e42
--- /dev/null
+++ b/about/system_requirements.rst
@@ -0,0 +1,371 @@
+:allow_comments: False
+
+.. _doc_system_requirements:
+
+System requirements
+===================
+
+This page contains system requirements for the editor and exported projects.
+These specifications are given for informative purposes only, but they can be
+referred to if you're looking to build or upgrade a system to use Godot on.
+
+Godot editor
+------------
+
+These are the **minimum** specifications required to run the Godot editor and work
+on a simple 2D or 3D project:
+
+Desktop or laptop PC - Minimum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. When adjusting specifications, make sure to only mention hardware that can run the required OS version.
+.. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model),
+.. which can run up to macOS 10.13.
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, or any x86_64 CPU |
+| | |
+| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300* |
+| | |
+| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
+| | |
+| | - *Example: Intel Core 2 Duo SU9400, Apple M1* |
+| | |
+| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
+| | |
+| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** Integrated graphics with full Vulkan 1.0 support |
+| | |
+| | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* |
+| | |
+| | - **Mobile rendering method:** Integrated graphics with full Vulkan 1.0 support |
+| | |
+| | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* |
+| | |
+| | - **Compatibility rendering method:** Integrated graphics with full OpenGL 3.3 support |
+| | |
+| | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **Native editor:** 4 GB |
+| | - **Web editor:** 8 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 200 MB (used for the executable, project files and cache). |
+| | Exporting projects requires downloading export templates separately |
+| | (1.3 GB after installation). |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **Native editor:** Windows 7, macOS 10.13 (Compatibility) or |
+| | macOS 10.15 (Forward+/Mobile), Linux distribution released after 2016 |
+| | - **Web editor:** Firefox 79, Chrome 68, Edge 79, Safari 15.2, Opera 64 |
++----------------------+-----------------------------------------------------------------------------------------+
+
+.. note::
+
+ Windows 7/8/8.1 are supported on a best-effort basis. These versions are not
+ regularly tested and some features may be missing (such as colored
+ :ref:`print_rich ` console output).
+ Support for Windows 7/8/8.1 may be removed in a
+ :ref:`future Godot 4.x release `.
+
+ Vulkan drivers for these Windows versions are known to have issues with
+ memory leaks. As a result, it's recommended to stick to the Compatibility
+ rendering method when running Godot on an Windows version older than 10.
+
+Mobile device (smartphone/tablet) - Minimum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU |
+| | |
+| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* |
+| | |
+| | - **iOS:** *Cannot run the editor* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* |
+| | |
+| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2* |
+| | |
+| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 306, Mali-T628 MP6* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **Native editor:** 3 GB |
+| | - **Web editor:** 6 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 200 MB (used for the executable, project files and cache). |
+| | Exporting projects requires downloading export templates separately |
+| | (1.3 GB after installation). |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **Native editor:** Android 6.0 (Compatibility) or Android 9.0 (Forward+/Mobile), |
+| | iOS 11.0 |
+| | - **Web editor:** Firefox 79, Chrome 88, Edge 79, Safari 15.2, Opera 64, |
+| | Samsung Internet 15 |
++----------------------+-----------------------------------------------------------------------------------------+
+
+These are the **recommended** specifications to get a smooth experience with the
+Godot editor on a simple 2D or 3D project:
+
+Desktop or laptop PC - Recommended
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more |
+| | |
+| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600* |
+| | |
+| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
+| | |
+| | - *Example: Intel Core i5-8500, Apple M1* |
+| | |
+| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
+| | |
+| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* |
+| | |
+| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* |
+| | |
+| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **Native editor:** 8 GB |
+| | - **Web editor:** 12 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **Native editor:** Windows 10, macOS 10.15, |
+| | Linux distribution released after 2020 |
+| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera |
++----------------------+-----------------------------------------------------------------------------------------+
+
+Mobile device (smartphone/tablet) - Recommended
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more |
+| | |
+| | - *Example: Qualcomm Snapdragon 845, Samsung Exynos 9810* |
+| | |
+| | - **iOS:** *Cannot run the editor* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* |
+| | |
+| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* |
+| | |
+| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **Native editor:** 6 GB |
+| | - **Web editor:** 8 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 1.5 GB (used for the executable, project files, all export templates and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **Native editor:** Android 9.0 or iOS 11.0 |
+| | - **Web editor:** Latest version of Firefox, Chrome, Edge, Safari, Opera, |
+| | Samsung Internet |
++----------------------+-----------------------------------------------------------------------------------------+
+
+Exported Godot project
+----------------------
+
+.. warning::
+
+ The requirements below are a baseline for a **simple** 2D or 3D project,
+ with basic scripting and few visual flourishes. CPU, GPU, RAM and
+ storage requirements will heavily vary depending on your project's scope,
+ its rendering method, viewport resolution and graphics settings chosen.
+ Other programs running on the system while the project is running
+ will also compete for resources, including RAM and video RAM.
+
+ It is strongly recommended to do your own testing on low-end hardware to
+ make sure your project runs at the desired speed. To provide scalability for
+ low-end hardware, you will also need to introduce a
+ `graphics options menu `__
+ to your project.
+
+These are the **minimum** specifications required to run a simple 2D or 3D
+project exported with Godot:
+
+Desktop or laptop PC - Minimum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. When adjusting specifications, make sure to only mention hardware that can run the required OS version.
+.. For example, the x86 CPU requirement for macOS is set after the MacBook Air 11" (late 2010 model),
+.. which can run up to macOS 10.13.
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Windows:** x86_32 CPU with SSE2 instructions, or any x86_64 CPU |
+| | |
+| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300* |
+| | |
+| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
+| | |
+| | - *Example: Intel Core 2 Duo SU9400, Apple M1* |
+| | |
+| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
+| | |
+| | - *Example: Intel Core 2 Duo E8200, AMD Athlon XE BE-2300, Raspberry Pi 4* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** Integrated graphics with full Vulkan 1.0 support |
+| | |
+| | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* |
+| | |
+| | - **Mobile rendering method:** Integrated graphics with full Vulkan 1.0 support |
+| | |
+| | - *Example: Intel HD Graphics 5500 (Broadwell), AMD Radeon R5 Graphics (Kaveri)* |
+| | |
+| | - **Compatibility rendering method:** Integrated graphics with full OpenGL 3.3 support |
+| | |
+| | - *Example: Intel HD Graphics 2500 (Ivy Bridge), AMD Radeon R5 Graphics (Kaveri)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **For native exports:** 2 GB |
+| | - **For web exports:** 4 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 150 MB (used for the executable, project files and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **For native exports:** Windows 7, macOS 10.13 (Compatibility) or |
+| | macOS 10.15 (Forward+/Mobile), Linux distribution released after 2016 |
+| | - **For web exports:** Firefox 79, Chrome 68, Edge 79, Safari 15.2, Opera 64 |
++----------------------+-----------------------------------------------------------------------------------------+
+
+.. note::
+
+ Windows 7/8/8.1 are supported on a best-effort basis. These versions are not
+ regularly tested and some features may be missing (such as colored
+ :ref:`print_rich ` console output).
+ Support for Windows 7/8/8.1 may be removed in a
+ :ref:`future Godot 4.x release `.
+
+ Vulkan drivers for these Windows versions are known to have issues with
+ memory leaks. As a result, it's recommended to stick to the Compatibility
+ rendering method when running Godot on an Windows version older than 10.
+
+Mobile device (smartphone/tablet) - Minimum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Android:** SoC with any 32-bit or 64-bit ARM or x86 CPU |
+| | |
+| | - *Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430* |
+| | |
+| | - **iOS:** SoC with any 64-bit ARM CPU |
+| | |
+| | - *Example: Apple A7 (iPhone 5S)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2, PowerVR G6430 (iPhone 6S/iPhone SE 1)* |
+| | |
+| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 505, Mali-G71 MP2, PowerVR G6430 (iPhone 6S/iPhone SE 1)* |
+| | |
+| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.0 support |
+| | |
+| | - *Example: Qualcomm Adreno 306, Mali-T628 MP6, PowerVR G6430 (iPhone 5S)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **For native exports:** 1 GB |
+| | - **For web exports:** 2 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 150 MB (used for the executable, project files and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **For native exports:** Android 6.0 (Compatibility) or Android 9.0 (Forward+/Mobile), |
+| | iOS 11.0 |
+| | - **For web exports:** Firefox 79, Chrome 88, Edge 79, Safari 15.2, Opera 64, |
+| | Samsung Internet 15 |
++----------------------+-----------------------------------------------------------------------------------------+
+
+These are the **recommended** specifications to get a smooth experience with a
+simple 2D or 3D project exported with Godot:
+
+Desktop or laptop PC - Recommended
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Windows:** x86_64 CPU with SSE4.2 instructions, with 4 physical cores or more |
+| | |
+| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600* |
+| | |
+| | - **macOS:** x86_64 or ARM CPU (Apple Silicon) |
+| | |
+| | - *Example: Intel Core i5-8500, Apple M1* |
+| | |
+| | - **Linux:** x86_32 CPU with SSE2 instructions, x86_64 CPU, ARMv7 or ARMv8 CPU |
+| | |
+| | - *Example: Intel Core i5-6600K, AMD Ryzen 5 1600, Raspberry Pi 5 with overclocking* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** Dedicated graphics with full Vulkan 1.2 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* |
+| | |
+| | - **Mobile rendering method:** Dedicated graphics with full Vulkan 1.2 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 1050 (Pascal), AMD Radeon RX 460 (GCN 4.0)* |
+| | |
+| | - **Compatibility rendering method:** Dedicated graphics with full OpenGL 4.6 support |
+| | |
+| | - *Example: NVIDIA GeForce GTX 650 (Kepler), AMD Radeon HD 7750 (GCN 1.0)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **For native exports:** 4 GB |
+| | - **For web exports:** 8 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 150 MB (used for the executable, project files and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **For native exports:** Windows 10, macOS 10.15, |
+| | Linux distribution released after 2020 |
+| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera |
++----------------------+-----------------------------------------------------------------------------------------+
+
+Mobile device (smartphone/tablet) - Recommended
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++----------------------+-----------------------------------------------------------------------------------------+
+| **CPU** | - **Android:** SoC with 64-bit ARM or x86 CPU, with 3 "performance" cores or more |
+| | |
+| | - *Example: Qualcomm Snapdragon 845, Samsung Exynos 9810* |
+| | |
+| | - **iOS:** SoC with 64-bit ARM CPU |
+| | |
+| | - *Example: Apple A11 (iPhone XS/XR)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **GPU** | - **Forward+ rendering method:** SoC featuring GPU with full Vulkan 1.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple G11P (iPhone XR/XS)* |
+| | |
+| | - **Mobile rendering method:** SoC featuring GPU with full Vulkan 1.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple G11P (iPhone XR/XS)* |
+| | |
+| | - **Compatibility rendering method:** SoC featuring GPU with full OpenGL ES 3.2 support |
+| | |
+| | - *Example: Qualcomm Adreno 630, Mali-G72 MP18, Apple G11P (iPhone XR/XS)* |
++----------------------+-----------------------------------------------------------------------------------------+
+| **RAM** | - **For native exports:** 2 GB |
+| | - **For web exports:** 4 GB |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Storage** | 150 MB (used for the executable, project files and cache) |
++----------------------+-----------------------------------------------------------------------------------------+
+| **Operating system** | - **For native exports:** Android 9.0 or iOS 11.0 |
+| | - **For web exports:** Latest version of Firefox, Chrome, Edge, Safari, Opera, |
+| | Samsung Internet |
++----------------------+-----------------------------------------------------------------------------------------+
+
+.. note::
+
+ Godot doesn't use OpenGL/OpenGL ES extensions introduced after OpenGL
+ 3.3/OpenGL ES 3.0, but GPUs supporting newer OpenGL/OpenGL ES versions
+ generally have fewer driver issues.
diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst
index 1bbf88cc1f9..abd49a0367f 100644
--- a/classes/class_@gdscript.rst
+++ b/classes/class_@gdscript.rst
@@ -972,7 +972,7 @@ See also :ref:`@GlobalScope.typeof`, :ref:`typ
:ref:`int` **len** **(** :ref:`Variant` var **)**
-Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String`, the element count of any array type or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped.
+Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String` or :ref:`StringName`, the element count of any array type, or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped.
::
@@ -992,7 +992,7 @@ Returns the length of the given Variant ``var``. The length can be the character
:ref:`Resource` **load** **(** :ref:`String` path **)**
-Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload`.
+Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload`. This method is equivalent of using :ref:`ResourceLoader.load` with :ref:`ResourceLoader.CACHE_MODE_REUSE`.
\ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst
index ebb7762634a..6696e60a7ea 100644
--- a/classes/class_@globalscope.rst
+++ b/classes/class_@globalscope.rst
@@ -2393,6 +2393,42 @@ Group Switch key mask.
----
+.. _enum_@GlobalScope_KeyLocation:
+
+.. rst-class:: classref-enumeration
+
+enum **KeyLocation**:
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation` **KEY_LOCATION_UNSPECIFIED** = ``0``
+
+Used for keys which only appear once, or when a comparison doesn't need to differentiate the ``LEFT`` and ``RIGHT`` versions.
+
+For example, when using :ref:`InputEvent.is_match`, an event which has :ref:`KEY_LOCATION_UNSPECIFIED` will match any :ref:`KeyLocation` on the passed event.
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_LEFT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation` **KEY_LOCATION_LEFT** = ``1``
+
+A key which is to the left of its twin.
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_RIGHT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation` **KEY_LOCATION_RIGHT** = ``2``
+
+A key which is to the right of its twin.
+
+.. rst-class:: classref-item-separator
+
+----
+
.. _enum_@GlobalScope_MouseButton:
.. rst-class:: classref-enumeration
@@ -2835,7 +2871,7 @@ enum **MIDIMessage**:
:ref:`MIDIMessage` **MIDI_MESSAGE_NONE** = ``0``
-Enum value which doesn't correspond to any MIDI message. This is used to initialize :ref:`MIDIMessage` properties with a generic state.
+Does not correspond to any MIDI message. This is the default value of :ref:`InputEventMIDI.message`.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_OFF:
@@ -2843,7 +2879,9 @@ Enum value which doesn't correspond to any MIDI message. This is used to initial
:ref:`MIDIMessage` **MIDI_MESSAGE_NOTE_OFF** = ``8``
-MIDI note OFF message. Not all MIDI devices send this event; some send :ref:`MIDI_MESSAGE_NOTE_ON` with zero velocity instead. See the documentation of :ref:`InputEventMIDI` for information of how to use MIDI inputs.
+MIDI message sent when a note is released.
+
+\ **Note:** Not all MIDI devices send this message; some may send :ref:`MIDI_MESSAGE_NOTE_ON` with :ref:`InputEventMIDI.velocity` set to ``0``.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON:
@@ -2851,7 +2889,7 @@ MIDI note OFF message. Not all MIDI devices send this event; some send :ref:`MID
:ref:`MIDIMessage` **MIDI_MESSAGE_NOTE_ON** = ``9``
-MIDI note ON message. Some MIDI devices send this event with velocity zero instead of :ref:`MIDI_MESSAGE_NOTE_OFF`, but implementations vary. See the documentation of :ref:`InputEventMIDI` for information of how to use MIDI inputs.
+MIDI message sent when a note is pressed.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH:
@@ -2859,7 +2897,7 @@ MIDI note ON message. Some MIDI devices send this event with velocity zero inste
:ref:`MIDIMessage` **MIDI_MESSAGE_AFTERTOUCH** = ``10``
-MIDI aftertouch message. This message is most often sent by pressing down on the key after it "bottoms out".
+MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTROL_CHANGE:
@@ -2867,7 +2905,7 @@ MIDI aftertouch message. This message is most often sent by pressing down on the
:ref:`MIDIMessage` **MIDI_MESSAGE_CONTROL_CHANGE** = ``11``
-MIDI control change message. This message is sent when a controller value changes. Controllers include devices such as pedals and levers.
+MIDI message sent when a controller value changes. In a MIDI device, a controller is any input that doesn't play notes. These may include sliders for volume, balance, and panning, as well as switches and pedals. See the `General MIDI specification `__ for a small list.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_PROGRAM_CHANGE:
@@ -2875,7 +2913,7 @@ MIDI control change message. This message is sent when a controller value change
:ref:`MIDIMessage` **MIDI_MESSAGE_PROGRAM_CHANGE** = ``12``
-MIDI program change message. This message sent when the program patch number changes.
+MIDI message sent when the MIDI device changes its current instrument (also called *program* or *preset*).
.. _class_@GlobalScope_constant_MIDI_MESSAGE_CHANNEL_PRESSURE:
@@ -2883,7 +2921,7 @@ MIDI program change message. This message sent when the program patch number cha
:ref:`MIDIMessage` **MIDI_MESSAGE_CHANNEL_PRESSURE** = ``13``
-MIDI channel pressure message. This message is most often sent by pressing down on the key after it "bottoms out". This message is different from polyphonic after-touch as it indicates the highest pressure across all keys.
+MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of :ref:`MIDI_MESSAGE_AFTERTOUCH`.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_PITCH_BEND:
@@ -2891,7 +2929,7 @@ MIDI channel pressure message. This message is most often sent by pressing down
:ref:`MIDIMessage` **MIDI_MESSAGE_PITCH_BEND** = ``14``
-MIDI pitch bend message. This message is sent to indicate a change in the pitch bender (wheel or lever, typically).
+MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_EXCLUSIVE:
@@ -2899,7 +2937,9 @@ MIDI pitch bend message. This message is sent to indicate a change in the pitch
:ref:`MIDIMessage` **MIDI_MESSAGE_SYSTEM_EXCLUSIVE** = ``240``
-MIDI system exclusive message. This has behavior exclusive to the device you're receiving input from. Getting this data is not implemented in Godot.
+MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_QUARTER_FRAME:
@@ -2907,7 +2947,9 @@ MIDI system exclusive message. This has behavior exclusive to the device you're
:ref:`MIDIMessage` **MIDI_MESSAGE_QUARTER_FRAME** = ``241``
-MIDI quarter frame message. Contains timing information that is used to synchronize MIDI devices. Getting this data is not implemented in Godot.
+MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to :ref:`MIDI_MESSAGE_TIMING_CLOCK`.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_POSITION_POINTER:
@@ -2915,7 +2957,9 @@ MIDI quarter frame message. Contains timing information that is used to synchron
:ref:`MIDIMessage` **MIDI_MESSAGE_SONG_POSITION_POINTER** = ``242``
-MIDI song position pointer message. Gives the number of 16th notes since the start of the song. Getting this data is not implemented in Godot.
+MIDI message sent to jump onto a new position in the current sequence or song.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_SELECT:
@@ -2923,7 +2967,9 @@ MIDI song position pointer message. Gives the number of 16th notes since the sta
:ref:`MIDIMessage` **MIDI_MESSAGE_SONG_SELECT** = ``243``
-MIDI song select message. Specifies which sequence or song is to be played. Getting this data is not implemented in Godot.
+MIDI message sent to select a sequence or song to play.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI` is not implemented.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_TUNE_REQUEST:
@@ -2931,7 +2977,7 @@ MIDI song select message. Specifies which sequence or song is to be played. Gett
:ref:`MIDIMessage` **MIDI_MESSAGE_TUNE_REQUEST** = ``246``
-MIDI tune request message. Upon receiving a tune request, all analog synthesizers should tune their oscillators.
+MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_TIMING_CLOCK:
@@ -2939,7 +2985,7 @@ MIDI tune request message. Upon receiving a tune request, all analog synthesizer
:ref:`MIDIMessage` **MIDI_MESSAGE_TIMING_CLOCK** = ``248``
-MIDI timing clock message. Sent 24 times per quarter note when synchronization is required.
+MIDI message sent 24 times after :ref:`MIDI_MESSAGE_QUARTER_FRAME`, to keep connected MIDI devices synchronized.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_START:
@@ -2947,7 +2993,7 @@ MIDI timing clock message. Sent 24 times per quarter note when synchronization i
:ref:`MIDIMessage` **MIDI_MESSAGE_START** = ``250``
-MIDI start message. Start the current sequence playing. This message will be followed with Timing Clocks.
+MIDI message sent to start the current sequence or song from the beginning.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTINUE:
@@ -2955,7 +3001,7 @@ MIDI start message. Start the current sequence playing. This message will be fol
:ref:`MIDIMessage` **MIDI_MESSAGE_CONTINUE** = ``251``
-MIDI continue message. Continue at the point the sequence was stopped.
+MIDI message sent to resume from the point the current sequence or song was paused.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_STOP:
@@ -2963,7 +3009,7 @@ MIDI continue message. Continue at the point the sequence was stopped.
:ref:`MIDIMessage` **MIDI_MESSAGE_STOP** = ``252``
-MIDI stop message. Stop the current sequence.
+MIDI message sent to pause the current sequence or song.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_ACTIVE_SENSING:
@@ -2971,7 +3017,7 @@ MIDI stop message. Stop the current sequence.
:ref:`MIDIMessage` **MIDI_MESSAGE_ACTIVE_SENSING** = ``254``
-MIDI active sensing message. This message is intended to be sent repeatedly to tell the receiver that a connection is alive.
+MIDI message sent repeatedly while the MIDI device is idle, to tell the receiver that the connection is alive. Most MIDI devices do not send this message.
.. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_RESET:
@@ -2979,7 +3025,7 @@ MIDI active sensing message. This message is intended to be sent repeatedly to t
:ref:`MIDIMessage` **MIDI_MESSAGE_SYSTEM_RESET** = ``255``
-MIDI system reset message. Reset all receivers in the system to power-up status. It should not be sent on power-up itself.
+MIDI message sent to reset a MIDI device to its default state, as if it was just turned on. It should not be sent when the MIDI device is being turned on.
.. rst-class:: classref-item-separator
@@ -3615,7 +3661,7 @@ Hints that a :ref:`Color` property should be edited without affecti
:ref:`PropertyHint` **PROPERTY_HINT_OBJECT_ID** = ``22``
-
+Hints that the property's value is an object encoded as object ID, with its type specified in the hint string. Used by the debugger.
.. _class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING:
@@ -3698,7 +3744,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = ``24``
-
+*Deprecated.* This hint is not used anywhere and will be removed in the future.
.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_TOO_BIG:
@@ -3706,7 +3752,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_OBJECT_TOO_BIG** = ``25``
-
+Hints that an object is too big to be sent via the debugger.
.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES:
@@ -3714,7 +3760,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_NODE_PATH_VALID_TYPES** = ``26``
-
+Hints that the hint string specifies valid node types for property of type :ref:`NodePath`.
.. _class_@GlobalScope_constant_PROPERTY_HINT_SAVE_FILE:
@@ -3722,7 +3768,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_SAVE_FILE** = ``27``
-
+Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the project's directory. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also :ref:`FileDialog.filters`.
.. _class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_SAVE_FILE:
@@ -3730,7 +3776,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_GLOBAL_SAVE_FILE** = ``28``
-
+Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also :ref:`FileDialog.filters`.
.. _class_@GlobalScope_constant_PROPERTY_HINT_INT_IS_OBJECTID:
@@ -3738,7 +3784,9 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_INT_IS_OBJECTID** = ``29``
+Hints that an :ref:`int` property is an object ID.
+\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
.. _class_@GlobalScope_constant_PROPERTY_HINT_INT_IS_POINTER:
@@ -3746,7 +3794,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_INT_IS_POINTER** = ``30``
-
+Hints that an :ref:`int` property is a pointer. Used by GDExtension.
.. _class_@GlobalScope_constant_PROPERTY_HINT_ARRAY_TYPE:
@@ -3754,7 +3802,7 @@ Examples:
:ref:`PropertyHint` **PROPERTY_HINT_ARRAY_TYPE** = ``31``
-
+Hints that a property is an :ref:`Array` with the stored type specified in the hint string.
.. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALE_ID:
@@ -3778,7 +3826,7 @@ Hints that a dictionary property is string translation map. Dictionary keys are
:ref:`PropertyHint` **PROPERTY_HINT_NODE_TYPE** = ``34``
-
+Hints that a property is an instance of a :ref:`Node`-derived type, optionally specified via the hint string (e.g. ``"Node2D"``). Editing it will show a dialog for picking a node from the scene.
.. _class_@GlobalScope_constant_PROPERTY_HINT_HIDE_QUATERNION_EDIT:
@@ -3892,7 +3940,7 @@ Used to group properties together in the editor in a subgroup (under a group). S
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_BITFIELD** = ``512``
-
+The property is a bitfield, i.e. it contains multiple flags represented as bits.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_NO_INSTANCE_STATE:
@@ -3924,7 +3972,7 @@ The property is a script variable which should be serialized and saved in the sc
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_STORE_IF_NULL** = ``8192``
-
+The property value of type :ref:`Object` will be stored even if its value is ``null``.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED:
@@ -3932,7 +3980,7 @@ The property is a script variable which should be serialized and saved in the sc
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED** = ``16384``
-
+If this property is modified, all inspector fields will be refreshed.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE:
@@ -3940,7 +3988,9 @@ The property is a script variable which should be serialized and saved in the sc
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE** = ``32768``
+Signifies a default value from a placeholder script instance.
+\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_CLASS_IS_ENUM:
@@ -3948,7 +3998,7 @@ The property is a script variable which should be serialized and saved in the sc
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_ENUM** = ``65536``
-
+The property is an enum, i.e. it only takes named integer constants from its associated enumeration.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_NIL_IS_VARIANT:
@@ -3956,7 +4006,7 @@ The property is a script variable which should be serialized and saved in the sc
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NIL_IS_VARIANT** = ``131072``
-
+If property has ``nil`` as default value, its type will be :ref:`Variant`.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_ARRAY:
@@ -3996,7 +4046,7 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT** = ``4194304``
-
+The :ref:`NodePath` property will always be relative to the scene's root. Mostly useful for local resources.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT:
@@ -4004,7 +4054,7 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT** = ``8388608``
-
+Use when a resource is created on the fly, i.e. the getter will always return a different instance. :ref:`ResourceSaver` needs this information to properly save such resources.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_KEYING_INCREMENTS:
@@ -4012,7 +4062,7 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_KEYING_INCREMENTS** = ``16777216``
-
+Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFERRED_SET_RESOURCE:
@@ -4020,7 +4070,9 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_DEFERRED_SET_RESOURCE** = ``33554432``
+When loading, the resource for this property can be set at the end of loading.
+\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT:
@@ -4028,7 +4080,7 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT** = ``67108864``
-
+When this property is a :ref:`Resource` and base object is a :ref:`Node`, a resource instance will be automatically created whenever the node is created in the editor.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_BASIC_SETTING:
@@ -4036,7 +4088,7 @@ The property is only shown in the editor if modern renderers are supported (the
:ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR_BASIC_SETTING** = ``134217728``
-
+The property is considered a basic setting and will appear even when advanced mode is disabled. Used for project settings.
.. _class_@GlobalScope_constant_PROPERTY_USAGE_READ_ONLY:
@@ -5474,20 +5526,10 @@ Clamps the ``value``, returning a :ref:`Variant` not less than ``
var b = clamp(8.1, 0.9, 5.5)
# b is 5.5
-
- var c = clamp(Vector2(-3.5, -4), Vector2(-3.2, -2), Vector2(2, 6.5))
- # c is (-3.2, -2)
-
- var d = clamp(Vector2i(7, 8), Vector2i(-3, -2), Vector2i(2, 6))
- # d is (2, 6)
-
- var e = clamp(Vector3(-7, 8.5, -3.8), Vector3(-3, -2, 5.4), Vector3(-2, 6, -4.1))
- # e is (-3, -2, 5.4)
-
- var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6))
- # f is (-4, -5, -6)
-\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, :ref:`Vector4i.clamp`, or :ref:`Color.clamp`.
+\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, :ref:`Vector4i.clamp`, or :ref:`Color.clamp` (not currently supported by this method).
+
+\ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick ``min`` if ``value < min`` or ``max`` if ``value > max``. To perform component-wise clamping use the methods listed above.
.. rst-class:: classref-item-separator
@@ -6412,6 +6454,8 @@ When printing to standard output, the supported subset of BBCode is converted to
\ **Note:** On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output.
+\ **Note:** Output displayed in the editor supports clickable ``[url=address]text[/url]`` tags. The ``[url]`` tag's ``address`` value is handled by :ref:`OS.shell_open` when clicked.
+
.. rst-class:: classref-item-separator
----
@@ -7219,7 +7263,7 @@ Converts the given ``variant`` to the given ``type``, using the :ref:`Variant.Ty
If the type conversion cannot be done, this method will return the default value for that type, for example converting :ref:`Rect2` to :ref:`Vector2` will always return :ref:`Vector2.ZERO`. This method will never show error messages as long as ``type`` is a valid Variant type.
-The returned value is a :ref:`Variant`, but the data inside and the :ref:`Variant.Type` will be the same as the requested type.
+The returned value is a :ref:`Variant`, but the data inside and its type will be the same as the requested type.
::
@@ -7287,6 +7331,8 @@ Encodes a :ref:`Variant` value to a byte array, without encoding
\ **Note:** If you need object serialization, see :ref:`var_to_bytes_with_objects`.
+\ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data.
+
.. rst-class:: classref-item-separator
----
@@ -7299,6 +7345,8 @@ Encodes a :ref:`Variant` value to a byte array, without encoding
Encodes a :ref:`Variant` value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with :ref:`bytes_to_var_with_objects`.
+\ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data.
+
.. rst-class:: classref-item-separator
----
@@ -7347,7 +7395,7 @@ Prints:
:ref:`Variant` **weakref** **(** :ref:`Variant` obj **)**
-Returns a weak reference to an object, or ``null`` if ``obj`` is invalid.
+Returns a :ref:`WeakRef` instance holding a weak reference to ``obj``. Returns an empty :ref:`WeakRef` instance if ``obj`` is ``null``. Prints an error and returns ``null`` if ``obj`` is neither :ref:`Object`-derived nor ``null``.
A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it.
diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst
index 113d74bdf4e..cdca47511ea 100644
--- a/classes/class_aabb.rst
+++ b/classes/class_aabb.rst
@@ -17,13 +17,13 @@ A 3D axis-aligned bounding box.
Description
-----------
-**AABB** consists of a position, a size, and several utility functions. It is typically used for fast overlap tests.
+The **AABB** built-in :ref:`Variant` type represents an axis-aligned bounding box in a 3D space. It is defined by its :ref:`position` and :ref:`size`, which are :ref:`Vector3`. It is frequently used for fast overlap tests (see :ref:`intersects`). Although **AABB** itself is axis-aligned, it can be combined with :ref:`Transform3D` to represent a rotated or skewed bounding box.
-It uses floating-point coordinates. The 2D counterpart to **AABB** is :ref:`Rect2`.
+It uses floating-point coordinates. The 2D counterpart to **AABB** is :ref:`Rect2`. There is no version of **AABB** that uses integer coordinates.
-Negative values for :ref:`size` are not supported and will not work for most methods. Use :ref:`abs` to get an AABB with a positive size.
+\ **Note:** Negative values for :ref:`size` are not supported. With negative size, most **AABB** methods do not work correctly. Use :ref:`abs` to get an equivalent **AABB** with a non-negative size.
-\ **Note:** Unlike :ref:`Rect2`, **AABB** does not have a variant that uses integer coordinates.
+\ **Note:** In a boolean context, a **AABB** evaluates to ``false`` if both :ref:`position` and :ref:`size` are zero (equal to :ref:`Vector3.ZERO`). Otherwise, it always evaluates to ``true``.
.. note::
@@ -163,7 +163,7 @@ Property Descriptions
:ref:`Vector3` **end** = ``Vector3(0, 0, 0)``
-Ending corner. This is calculated as ``position + size``. Setting this value will change the size.
+The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`.
.. rst-class:: classref-item-separator
@@ -175,7 +175,7 @@ Ending corner. This is calculated as ``position + size``. Setting this value wil
:ref:`Vector3` **position** = ``Vector3(0, 0, 0)``
-Beginning corner. Typically has values lower than :ref:`end`.
+The origin point. This is usually the corner on the bottom-left and back of the bounding box.
.. rst-class:: classref-item-separator
@@ -187,9 +187,9 @@ Beginning corner. Typically has values lower than :ref:`end` **size** = ``Vector3(0, 0, 0)``
-Size from :ref:`position` to :ref:`end`. Typically, all components are positive.
+The bounding box's width, height, and depth starting from :ref:`position`. Setting this value also affects the :ref:`end` point.
-If the size is negative, you can use :ref:`abs` to fix it.
+\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-back corner, and the :ref:`end` is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use :ref:`abs`.
.. rst-class:: classref-section-separator
@@ -206,7 +206,7 @@ Constructor Descriptions
:ref:`AABB` **AABB** **(** **)**
-Constructs a default-initialized **AABB** with default (zero) values of :ref:`position` and :ref:`size`.
+Constructs an **AABB** with its :ref:`position` and :ref:`size` set to :ref:`Vector3.ZERO`.
.. rst-class:: classref-item-separator
@@ -226,7 +226,7 @@ Constructs an **AABB** as a copy of the given **AABB**.
:ref:`AABB` **AABB** **(** :ref:`Vector3` position, :ref:`Vector3` size **)**
-Constructs an **AABB** from a position and size.
+Constructs an **AABB** by ``position`` and ``size``.
.. rst-class:: classref-section-separator
@@ -243,7 +243,28 @@ Method Descriptions
:ref:`AABB` **abs** **(** **)** |const|
-Returns an AABB with equivalent position and size, modified so that the most-negative corner is the origin and the size is positive.
+Returns an **AABB** equivalent to this bounding box, with its width, height, and depth modified to be non-negative values.
+
+
+.. tabs::
+
+ .. code-tab:: gdscript
+
+ var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
+ var absolute = box.abs()
+ print(absolute.position) # Prints (-15, -10, 0)
+ print(absolute.size) # Prints (20, 10, 5)
+
+ .. code-tab:: csharp
+
+ var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5));
+ var absolute = box.Abs();
+ GD.Print(absolute.Position); // Prints (-15, -10, 0)
+ GD.Print(absolute.Size); // Prints (20, 10, 5)
+
+
+
+\ **Note:** It's recommended to use this method when :ref:`size` is negative, as most other methods in Godot assume that the :ref:`size`'s components are greater than ``0``.
.. rst-class:: classref-item-separator
@@ -255,7 +276,32 @@ Returns an AABB with equivalent position and size, modified so that the most-neg
:ref:`bool` **encloses** **(** :ref:`AABB` with **)** |const|
-Returns ``true`` if this **AABB** completely encloses another one.
+Returns ``true`` if this bounding box *completely* encloses the ``with`` box. The edges of both boxes are included.
+
+
+.. tabs::
+
+ .. code-tab:: gdscript
+
+ var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4))
+ var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3))
+ var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8))
+
+ print(a.encloses(a)) # Prints true
+ print(a.encloses(b)) # Prints true
+ print(a.encloses(c)) # Prints false
+
+ .. code-tab:: csharp
+
+ var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4));
+ var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3));
+ var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8));
+
+ GD.Print(a.Encloses(a)); // Prints True
+ GD.Print(a.Encloses(b)); // Prints True
+ GD.Print(a.Encloses(c)); // Prints False
+
+
.. rst-class:: classref-item-separator
@@ -267,26 +313,34 @@ Returns ``true`` if this **AABB** completely encloses another one.
:ref:`AABB` **expand** **(** :ref:`Vector3` to_point **)** |const|
-Returns a copy of this **AABB** expanded to include a given point.
-
-\ **Example:**\
+Returns a copy of this bounding box expanded to align the edges with the given ``to_point``, if necessary.
.. tabs::
.. code-tab:: gdscript
- # position (-3, 2, 0), size (1, 1, 1)
- var box = AABB(Vector3(-3, 2, 0), Vector3(1, 1, 1))
- # position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2)
- var box2 = box.expand(Vector3(0, -1, 2))
+ var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))
+
+ box = box.expand(Vector3(10, 0, 0))
+ print(box.position) # Prints (0, 0, 0)
+ print(box.size) # Prints (10, 2, 5)
+
+ box = box.expand(Vector3(-5, 0, 5))
+ print(box.position) # Prints (-5, 0, 0)
+ print(box.size) # Prints (15, 2, 5)
.. code-tab:: csharp
- // position (-3, 2, 0), size (1, 1, 1)
- var box = new Aabb(new Vector3(-3, 2, 0), new Vector3(1, 1, 1));
- // position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2)
- var box2 = box.Expand(new Vector3(0, -1, 2));
+ var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5));
+
+ box = box.Expand(new Vector3(10, 0, 0));
+ GD.Print(box.Position); // Prints (0, 0, 0)
+ GD.Print(box.Size); // Prints (10, 2, 5)
+
+ box = box.Expand(new Vector3(-5, 0, 5));
+ GD.Print(box.Position); // Prints (-5, 0, 0)
+ GD.Print(box.Size); // Prints (15, 2, 5)
@@ -300,7 +354,7 @@ Returns a copy of this **AABB** expanded to include a given point.
:ref:`Vector3` **get_center** **(** **)** |const|
-Returns the center of the **AABB**, which is equal to :ref:`position` + (:ref:`size` / 2).
+Returns the center point of the bounding box. This is the same as ``position + (size / 2.0)``.
.. rst-class:: classref-item-separator
@@ -312,7 +366,7 @@ Returns the center of the **AABB**, which is equal to :ref:`position` **get_endpoint** **(** :ref:`int` idx **)** |const|
-Gets the position of the 8 endpoints of the **AABB** in space.
+Returns the position of one of the 8 vertices that compose this bounding box. With a ``idx`` of ``0`` this is the same as :ref:`position`, and a ``idx`` of ``7`` is the same as :ref:`end`.
.. rst-class:: classref-item-separator
@@ -324,7 +378,30 @@ Gets the position of the 8 endpoints of the **AABB** in space.
:ref:`Vector3` **get_longest_axis** **(** **)** |const|
-Returns the normalized longest axis of the **AABB**.
+Returns the longest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`).
+
+
+.. tabs::
+
+ .. code-tab:: gdscript
+
+ var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
+
+ print(box.get_longest_axis()) # Prints (0, 0, 1)
+ print(box.get_longest_axis_index()) # Prints 2
+ print(box.get_longest_axis_size()) # Prints 8
+
+ .. code-tab:: csharp
+
+ var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
+
+ GD.Print(box.GetLongestAxis()); // Prints (0, 0, 1)
+ GD.Print(box.GetLongestAxisIndex()); // Prints 2
+ GD.Print(box.GetLongestAxisSize()); // Prints 8
+
+
+
+See also :ref:`get_longest_axis_index` and :ref:`get_longest_axis_size`.
.. rst-class:: classref-item-separator
@@ -336,7 +413,9 @@ Returns the normalized longest axis of the **AABB**.
:ref:`int` **get_longest_axis_index** **(** **)** |const|
-Returns the index of the longest axis of the **AABB** (according to :ref:`Vector3`'s ``AXIS_*`` constants).
+Returns the index to the longest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X`, :ref:`Vector3.AXIS_Y`, and :ref:`Vector3.AXIS_Z`).
+
+For an example, see :ref:`get_longest_axis`.
.. rst-class:: classref-item-separator
@@ -348,7 +427,9 @@ Returns the index of the longest axis of the **AABB** (according to :ref:`Vector
:ref:`float` **get_longest_axis_size** **(** **)** |const|
-Returns the scalar length of the longest axis of the **AABB**.
+Returns the longest dimension of this bounding box's :ref:`size`.
+
+For an example, see :ref:`get_longest_axis`.
.. rst-class:: classref-item-separator
@@ -360,7 +441,30 @@ Returns the scalar length of the longest axis of the **AABB**.
:ref:`Vector3` **get_shortest_axis** **(** **)** |const|
-Returns the normalized shortest axis of the **AABB**.
+Returns the shortest normaalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`).
+
+
+.. tabs::
+
+ .. code-tab:: gdscript
+
+ var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
+
+ print(box.get_shortest_axis()) # Prints (1, 0, 0)
+ print(box.get_shortest_axis_index()) # Prints 0
+ print(box.get_shortest_axis_size()) # Prints 2
+
+ .. code-tab:: csharp
+
+ var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
+
+ GD.Print(box.GetShortestAxis()); // Prints (1, 0, 0)
+ GD.Print(box.GetShortestAxisIndex()); // Prints 0
+ GD.Print(box.GetShortestAxisSize()); // Prints 2
+
+
+
+See also :ref:`get_shortest_axis_index` and :ref:`get_shortest_axis_size`.
.. rst-class:: classref-item-separator
@@ -372,7 +476,9 @@ Returns the normalized shortest axis of the **AABB**.
:ref:`int` **get_shortest_axis_index** **(** **)** |const|
-Returns the index of the shortest axis of the **AABB** (according to :ref:`Vector3`::AXIS\* enum).
+Returns the index to the shortest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X