Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
Základy C#¶
Úvod¶
This page provides a brief introduction to C#, both what it is and how to use it in Godot. Afterwards, you may want to look at how to use specific features, read about the differences between the C# and the GDScript API, and (re)visit the Scripting section of the step-by-step tutorial.
C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with .NET 6.0.
Výstraha
Projects written in C# using Godot 4 currently cannot be exported to the web platform. To use C# on the web platform, consider Godot 3 instead. Android and iOS platform support is available as of Godot 4.2, but is experimental and some limitations apply.
Poznámka
Toto je není plnohodnotný tutorial celého jazyka C# . Pokud ještě nejste obeznámeni s jeho syntaxí nebo funkcemi, podívejte se do Průvodce Microsoft C# nebo se poohlédněte po jiném vhodném úvodním materiálu.
Prerequisites¶
Godot bundles the parts of .NET needed to run already compiled games. However, Godot does not bundle the tools required to build and compile games, such as MSBuild and the C# compiler. These are included in the .NET SDK, and need to be installed separately.
In summary, you must have installed the .NET SDK and the .NET-enabled version of Godot.
Download and install the latest stable version of the SDK from the .NET download page.
Důležité
Pokud používáte 64bitovou verzi Godotu, nezapomeňte nainstalovat 64bitovou verzi SDK.
If you are building Godot from source, make sure to follow the steps to enable .NET support in your build as outlined in the Compiling with .NET page.
Konfigurace externího editoru¶
C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Dotnet. Under Dotnet, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:
Visual Studio 2022
Visual Studio Code
MonoDevelop
Visual Studio pro Mac
JetBrains Rider
Postup konfigurace externího editoru naleznete v následujících částech:
JetBrains Rider¶
Po přečtení části "Předpoklady" si můžete stáhnout a nainstalovat JetBrains Rider.
V nabídce Godot Editor → Nastavení editoru:
Set Dotnet -> Editor -> External Editor to JetBrains Rider.
V Rideru:
Nastavte verzi MSBuild na .NET Core.
Nainstalujte zásuvný modul Godot support.
Visual Studio Code¶
Po přečtení části "Předpoklady" si můžete stáhnout a nainstalovat Visual Studio Code (alias VS Code).
V nabídce Godot Editor → Nastavení editoru:
Set Dotnet -> Editor -> External Editor to Visual Studio Code.
V aplikaci Visual Studio Code:
Nainstalujte rozšíření C#.
Poznámka
Pokud používáte Linux, musíte si nainstalovat Mono SDK, aby zásuvný modul nástrojů C# fungoval.
To configure a project for debugging, you need a tasks.json
and launch.json
file in
the .vscode
folder with the necessary configuration. An example configuration can be
found here .
In the launch.json
file, make sure the program
parameter in the relevant configuration points to your Godot executable, either by
changing it to the path of the executable or by defining a GODOT4
environment variable that points to the
executable. Now, when you start the debugger in Visual Studio Code, your Godot project will run.
Poznámka
There is also a C# Tools for Godot Visual Studio Code extension, that is meant to make this setup easier and to provide further useful tools. But it is not yet updated to work with Godot 4.
Visual Studio (pouze pro Windows)¶
Stáhněte a nainstalujte nejnovější verzi Visual Studia. Visual Studio bude obsahovat požadované sady SDK, pokud máte vybrané správné pracovní úlohy, takže nemusíte'ručně instalovat věci uvedené v části "Předpoklady".
While installing Visual Studio, select this workload:
.NET desktop development
V nabídce Godot Editor → Nastavení editoru:
Set Dotnet -> Editor -> External Editor to Visual Studio.
Poznámka
If you see an error like "Unable to find package Godot.NET.Sdk", your NuGet configuration may be incorrect and need to be fixed.
A simple way to fix the NuGet configuration file is to regenerate it.
In a file explorer window, go to %AppData%\NuGet
. Rename or delete
the NuGet.Config
file. When you build your Godot project again,
the file will be automatically created with default values.
Vytvoření skriptu C#¶
Po úspěšném nastavení jazyka C# v Godot byste měli při výběru akce Připojit skript v kontextové nabídce uzlu vaší scény vidět následující možnost:
Note that while some specifics change, most concepts work the same when using C# for scripting. If you're new to Godot, you may want to follow the tutorials on Skriptovací jazyky at this point. While some documentation pages still lack C# examples, most notions can be transferred from GDScript.
Nastavení projektu a pracovní postup¶
When you create the first C# script, Godot initializes the C# project files
for your Godot project. This includes generating a C# solution (.sln
)
and a project file (.csproj
), as well as some utility files and folders
(.godot/mono
).
All of these but .godot/mono
are important and should be committed to your
version control system. Everything under .godot
can be safely added to the
ignore list of your VCS.
When troubleshooting, it can sometimes help to delete the .godot/mono
folder
and let it regenerate.
Example¶
Zde'je prázdný skript v jazyce C# s několika komentáři, které popisují jak funguje.
using Godot;
public partial class YourCustomClass : Node
{
// Member variables here, example:
private int _a = 2;
private string _b = "textvar";
public override void _Ready()
{
// Called every time the node is added to the scene.
// Initialization here.
GD.Print("Hello from C# to Godot :)");
}
public override void _Process(double delta)
{
// Called every frame. Delta is time since the last frame.
// Update game logic here.
}
}
As you can see, functions normally in global scope in GDScript like Godot's
print
function are available in the GD
static class which is part of
the Godot
namespace. For a full list of methods in the GD
class, see the
class reference pages for
@GDScript and @GlobalScope.
Poznámka
Keep in mind that the class you wish to attach to your node should have the same
name as the .cs
file. Otherwise, you will get the following error:
"Cannot find class XXX for script res://XXX.cs"
Obecné rozdíly mezi jazyky C# a GDScript¶
API C# používá PascalCase
místo snake_case
v jazyce GDScript/C++. Kde to bylo možné, byla pole(field) a gettery/settery převedeny na vlastnosti(property). Obecně se rozhraní C# Godot API snaží být co nejvíce idiomatické, jak je to jen rozumně možné.
Další informace naleznete na stránce C# API differences to GDScript.
Varování
You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the Build button in the top right corner of the editor.
Budete také muset znovu sestavit sestavy projektu, abyste mohli použít změny ve skriptech "tool".
Aktuální problémy a známé potíže¶
As C# support is quite new in Godot, there are some growing pains and things that need to be ironed out. Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt, also take a look over the official issue tracker for .NET issues.
Psaní zásuvných modulů editoru je možné, ale v současné době je poměrně složité.
Stav se v současné době neukládá a neobnovuje při načítání za chodu, s výjimkou exportovaných proměnných.
Připojené skripty C# by měly odkazovat na třídu, jejíž název odpovídá názvu souboru.
There are some methods such as
Get()
/Set()
,Call()
/CallDeferred()
and signal connection methodConnect()
that rely on Godot'ssnake_case
API naming conventions. So when using e.g.CallDeferred("AddChild")
,AddChild
will not work because the API is expecting the originalsnake_case
versionadd_child
. However, you can use any custom properties or methods without this limitation. Prefer using the exposedStringName
in thePropertyName
,MethodName
andSignalName
to avoid extraStringName
allocations and worrying about snake_case naming.
As of Godot 4.0, exporting .NET projects is supported for desktop platforms (Linux, Windows and macOS). Other platforms will gain support in future 4.x releases.
Common pitfalls¶
You might encounter the following error when trying to modify some values in Godot
objects, e.g. when trying to change the X coordinate of a Node2D
:
public partial class MyNode2D : Node2D
{
public override _Ready()
{
Position.X = 100.0f;
// CS1612: Cannot modify the return value of 'Node2D.Position' because
// it is not a variable.
}
}
This is perfectly normal. Structs (in this example, a Vector2
) in C# are
copied on assignment, meaning that when you retrieve such an object from a
property or an indexer, you get a copy of it, not the object itself. Modifying
said copy without reassigning it afterwards won't achieve anything.
The workaround is simple: retrieve the entire struct, modify the value you want to modify, and reassign the property.
var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;
Since C# 10, it is also possible to use with expressions on structs, allowing you to do the same thing in a single line.
Position = Position with { X = 100.0f };
You can read more about this error on the C# language reference.
Výkon C# v Godot¶
According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads.
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.
Consider assigning values of such properties into a local variable if you need to modify or read them multiple times at
a single code location:
using Godot;
public partial class YourCustomClass : Node3D
{
private void ExpensiveReposition()
{
for (var i = 0; i < 10; i++)
{
// Position is read and set 10 times which incurs native interop.
// Furthermore the object is repositioned 10 times in 3D space which
// takes additional time.
Position += new Vector3(i, i);
}
}
private void Reposition()
{
// A variable is used to avoid native interop for Position on every loop.
var newPosition = Position;
for (var i = 0; i < 10; i++)
{
newPosition += new Vector3(i, i);
}
// Setting Position only once avoids native interop and repositioning in 3D space.
Position = newPosition;
}
}
Passing raw arrays (such as byte[]
) or string
to Godot's C# API requires marshalling which is
comparatively pricey.
The implicit conversion from string
to NodePath
or StringName
incur both the native interop and marshalling
costs as the string
has to be marshalled and passed to the respective native constructor.
Používání balíčků NuGet v Godot¶
Balíčky NuGet lze instalovat a používat s Godotem stejně jako s jakýmkoli jiným projektem v jazyce C#. Mnoho IDE umí balíčky přidávat přímo. Lze je také přidat ručně vložením odkazu na balíček do souboru .csproj
umístěného v kořenovém adresáři projektu:
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
</ItemGroup>
...
</Project>
Od Godot 3.2.3 Godot automaticky stahuje a nastavuje nově přidané balíčky NuGet při následném sestavení projektu.
Profilování kódu C#¶
The following tools may be used for performance and memory profiling of your managed code:
JetBrains Rider with dotTrace/dotMemory plugin.
Standalone JetBrains dotTrace/dotMemory.
Visual Studio.
Profiling managed and unmanaged code at once is possible with both JetBrains tools and Visual Studio, but limited to Windows.