From 6feb7b47c82a9db79e77711eb8ab3708b44f7eac Mon Sep 17 00:00:00 2001
From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com>
Date: Mon, 18 Nov 2024 18:22:30 -0800
Subject: [PATCH] Add FAQ entry "Which programming language is fastest?"

Compares the performance of C#, GDScript, and C++.

Co-Authored-By: Hugo Locurcio <hugo.locurcio@hugo.pro>
Co-Authored-By: Andre Sacilotto <66838864+andresacilotto@users.noreply.github.com>
---
 about/faq.rst                                 | 32 +++++++++++++++++++
 .../scripting/c_sharp/c_sharp_basics.rst      |  5 +++
 2 files changed, 37 insertions(+)

diff --git a/about/faq.rst b/about/faq.rst
index 3fe32cd979a..d5f0617f9ab 100644
--- a/about/faq.rst
+++ b/about/faq.rst
@@ -167,6 +167,38 @@ The main reasons for creating a custom scripting language for Godot were:
 
 GDScript was designed to curtail the issues above, and more.
 
+.. _doc_faq_which_programming_language_is_fastest:
+
+Which programming language is fastest?
+--------------------------------------
+
+In most games, the *scripting language* itself is not the cause of performance
+problems. Instead, performance is slowed by inefficient algorithms (which are
+slow in all languages), by GPU performance, or by the common C++ engine code
+like physics or navigation. All languages supported by Godot are fast enough for
+general-purpose scripting. You should choose a language based on other factors,
+like ease-of-use, familiarity, platform support, or language features.
+
+In general, the performance of C# and GDScript is within the same order of
+magnitude, and C++ is faster than both.
+
+Comparing GDScript performance to C# is tricky, since C# can be faster in some
+specific cases. The C# *language* itself tends to be faster than GDScript, which
+means that C# can be faster in situations with few calls to Godot engine code.
+However, C# can be slower than GDScript when making many Godot API calls, due
+to the cost of *marshalling*. C#'s performance can also be brought down by garbage
+collection which occurs at random and unpredictable moments. This can result in
+stuttering issues in complex projects, and is not exclusive to Godot.
+
+C++, using :ref:`GDExtension <doc_what_is_gdextension>`, will almost always be
+faster than either C# or GDScript. However, C++ is less easy to use than C# or
+GDScript, and is slower to develop with.
+
+You can also use multiple languages within a single project, with
+:ref:`cross-language scripting <doc_cross_language_scripting>`, or by using
+GDExtension and scripting languages together. Be aware that doing so comes with
+its own complications.
+
 What 3D model formats does Godot support?
 -----------------------------------------
 
diff --git a/tutorials/scripting/c_sharp/c_sharp_basics.rst b/tutorials/scripting/c_sharp/c_sharp_basics.rst
index 54047a6ff20..274a4f0aa4d 100644
--- a/tutorials/scripting/c_sharp/c_sharp_basics.rst
+++ b/tutorials/scripting/c_sharp/c_sharp_basics.rst
@@ -357,6 +357,11 @@ You can read more about this error on the `C# language reference <https://learn.
 Performance of C# in Godot
 --------------------------
 
+.. seealso:: 
+    
+    For a performance comparison of the languages Godot supports,
+    see :ref:`doc_faq_which_programming_language_is_fastest`.
+
 Most properties of Godot C# objects that are based on ``GodotObject``
 (e.g. any ``Node`` like ``Control`` or ``Node3D`` like ``Camera3D``) require native (interop) calls as they talk to
 Godot's C++ core.