GodotSharp.SourceGenerators
2.4.0
dotnet add package GodotSharp.SourceGenerators --version 2.4.0
NuGet\Install-Package GodotSharp.SourceGenerators -Version 2.4.0
<PackageReference Include="GodotSharp.SourceGenerators" Version="2.4.0" />
paket add GodotSharp.SourceGenerators --version 2.4.0
#r "nuget: GodotSharp.SourceGenerators, 2.4.0"
// Install GodotSharp.SourceGenerators as a Cake Addin #addin nuget:?package=GodotSharp.SourceGenerators&version=2.4.0 // Install GodotSharp.SourceGenerators as a Cake Tool #tool nuget:?package=GodotSharp.SourceGenerators&version=2.4.0
GodotSharp.SourceGenerators
C# Source Generators for use with the Godot Game Engine (supports Godot 4 and .NET 8!)
SceneTree
class attribute:- Generates class property for uniquely named nodes
- Provides strongly typed access to the scene hierarchy (via
_
operator)
GodotOverride
method attribute:- Allows use of On*, instead of virtual _* overrides
- (Requires partial method declaration for use with Godot 4.0)
Notify
property attribute:- Generates boiler plate code, triggering only when values differ
- (Automagically triggers nested changes for Resource and Resource[])
InputMap
class attribute:- Provides strongly typed access to input actions defined in godot.project
LayerNames
class attribute:- Provide strongly typed access to layer names defined in godot.project
CodeComments
class attribute:- Provides a nested static class to access property comments from code (useful for in-game tooltips, etc)
OnInstantiate
method attribute:- Generates a static Instantiate method with matching args that calls attributed method as part of the instantiation process
- (Also generates a protected constructor to ensure proper initialisation - can be deactivated via attribute)
OnImport
method attribute (GD4 only):- Generates default plugin overrides and options to make plugin class cleaner (inherit from OnImportEditorPlugin)
- Includes base classes/helpers to create project specific source generators
- Version 2.x supports Godot 4
- Version 1.x supports Godot 3
(See GodotSharp.BuildingBlocks or local tests for example usage patterns)
Table of Contents
Installation
Install via NuGet
Attributes
SceneTree
- Class attribute
- Generates class property for uniquely named nodes
- Provides strongly typed access to the scene hierarchy (via
_
operator) - Nodes are cached on first retrieval to avoid interop overhead
- Advanced options available as attribute arguments
- tscnRelativeToClassPath: (default null) Specify path to tscn relative to current class
- traverseInstancedScenes: (default false) Include instanced scenes in the generated hierarchy
// Attach a C# script on the root node of the scene with the same name.
// [SceneTree] will generate the members as the scene hierarchy.
[SceneTree]
public partial class MyScene : Node2D
{
public override void _Ready()
{
// You can access the node via '_' object.
GD.Print(_.Node1.Node11.Node12.Node121);
GD.Print(_.Node4.Node41.Node412);
// You can also directly access nodes marked as having a unique name in the editor
GD.Print(MyNodeWithUniqueName);
GD.Print(_.Path.To.MyNodeWithUniqueName); // Long equivalent
}
}
GodotOverride
- Method attribute
- Allows use of On*, instead of virtual _* overrides
- (Requires partial method declaration for use with Godot 4.0)
- Advanced options available as attribute arguments
- replace: (default false) Skip base call generation (ie, override will replace base)
public partial class MyNode : Node2D
{
[GodotOverride]
protected virtual void OnReady()
=> GD.Print("Ready");
[GodotOverride(replace: true)]
private void OnProcess(double delta)
=> GD.Print("Processing");
// Requires partial method declaration for use with Godot 4.0
public override partial void _Ready();
public override partial void _Process(double delta);
}
Generates:
public override void _Ready()
{
base._Ready();
OnReady();
}
public override _Process(double delta)
=> OnProcess(delta);
Notify
- Property attribute
- Generates public events Value1Changed & Value1Changing and a private class to manage field and event delivery
- (Automagically triggers nested changes for Resource and Resource[])
- Events are triggered only if value is different
- [NEW] Initial value can be set without triggering update (useful when using a non-nullable reference type)
public partial class NotifyTest : Node
{
[Notify]
public float Value1
{
get => _value1.Get();
set => _value1.Set(value); // You can also pass onchanged event handler here
}
public override void _Ready()
{
Value1Changing += () => GD.Print("Value1Changing raised before value is changed");
Value1Changed += () => GD.Print("Value1Changed raised after value is changed");
// You can also subscribe to private events if needed
// _value1.Changing += OnValue1Changing;
// _value1.Changed += OnValue1Changed;
// This might be useful... erm... if you need to clear the public listeners for some reason...?
Value1 = 1; // Raise Value1Changing and Value1Changed
Value1 = 2; // Raise Value1Changing and Value1Changed
Value1 = 2; // No event is raised since value is the same
}
public NotifyTest()
=> InitValue1(7); // [NEW] Set initial value without triggering events (optional)
}
InputMap
- Class attribute
- Provides strongly typed access to input actions defined in godot.project (set via editor)
- If you want access to built-in actions, see BuiltinInputActions.cs
[InputMap]
public static partial class MyInput { }
Equivalent (for defined input actions) to:
// (static optional)
// (string rather than StringName for Godot 3)
// (does not provide access to built-in actions)
partial static class MyInput
{
public static readonly StringName MoveLeft = "move_left";
public static readonly StringName MoveRight = "move_right";
public static readonly StringName MoveUp = "move_up";
public static readonly StringName MoveDown = "move_down";
}
LayerNames
- Class attribute
- Provides strongly typed access to layer names defined in godot.project (set via editor)
[LayerNames]
public static partial class MyLayers { }
Equivalent (for defined layers) to:
// (static optional)
partial static partial class MyLayers
{
public static class Render2D
{
public const int MyLayer1 = 0; // Yes, layers start at 1 in editor, but 0 in code
public const int MyLayer2 = 1;
public const int MyLayer7 = 6;
public const int _11reyaLyM = 10; // Yes, we will append an underscore if required...
public static class Mask
{
public const uint MyLayer1 = 1 << 0;
public const uint MyLayer2 = 1 << 1;
public const uint MyLayer7 = 1 << 6;
public const uint _11reyaLyM = 1 << 10;
}
}
public static class Render3D
{
public const int MyLayer1 = 0;
public static class Mask
{
public const uint MyLayer1 = 1 << 0;
}
}
// Also for Physics2D, Physics3D, Navigation2D, Navigation3D, Avoidance, etc...
}
CodeComments
- Class attribute
- Provides a nested static class to access property comments from code
- Advanced options available as attribute arguments
- strip: (default "// ") The characters to remove from the start of each line
[CodeComments]
public partial class CodeCommentsTest : Node
{
// This a comment for Value1
// [CodeComments] only works with Property
[Export] public float Value1 { get; set; }
// Value 2 is a field so no comment
[Export] public float value2;
public override void _Ready()
{
GD.Print(GetComment(nameof(Value1))); // output: "This a comment for Value1\n[CodeComments] only works with Property"
GD.Print(GetComment(nameof(value2))); // output: "" (No output for fields, but could be added if needed)
}
}
OnInstantiate
- Method attribute
- Generates a static Instantiate method with matching args that calls attributed method as part of the instantiation process
- (Also generates a protected constructor to ensure proper initialisation - can be deactivated via attribute)
- Advanced options available as attribute arguments
- ctor: (default "protected") Scope of generated constructor (null, "" or "none" to skip)
// Initialise can be public or protected if required; args also optional
// Currently assumes tscn is in same folder with same name
// Obviously only valid for root nodes
public partial class MyScene : Node
{
[OnInstantiate]
private void Initialise(string myArg1, int myArg2)
=> GD.PrintS("Init", myArg1, myArg2);
}
Generates (simplified):
private static PackedScene __scene__;
private static PackedScene __Scene__ => __scene__ ??= GD.Load<PackedScene>("res://Path/To/MyScene.tscn");
public static MyScene Instantiate(string myArg1, int myArg2)
{
var scene = __Scene__.Instantiate<MyScene>();
scene.Initialise(myArg1, myArg2);
return scene;
}
private Test3Arg() {}
Usage:
// ... in some class
private void AddSceneToWorld()
{
var myScene = MyScene.Instantiate("str", 3);
MyWorld.AddChild(myScene);
}
OnImport
- Method attribute (GD4 only)
- Generates default plugin overrides and options to make plugin class cleaner (inherit from OnImportEditorPlugin)
- Includes base classes/helpers to create project specific source generators
- (Not that useful unless writing lots of plugins - might remove in v3)
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories (2)
Showing the top 2 popular GitHub repositories that depend on GodotSharp.SourceGenerators:
Repository | Stars |
---|---|
chickensoft-games/GameDemo
The Chickensoft Game Demo — a fully tested, third-person 3D game built with Godot and C#. Now with saving and loading!
|
|
Cat-Lips/GodotSharp.SourceGenerators
C# source generators for the Godot Game Engine
|
Version | Downloads | Last updated |
---|---|---|
2.4.0 | 207 | 7/18/2024 |
2.4.0-240626-1054.Release | 45 | 6/26/2024 |
2.4.0-240429-1137.Release | 213 | 4/29/2024 |
2.3.4 | 286 | 4/27/2024 |
2.3.4-240426-1941.Release | 50 | 4/26/2024 |
2.3.3 | 134 | 4/1/2024 |
2.3.3-240115-0706.Release | 97 | 1/14/2024 |
2.3.2 | 393 | 1/6/2024 |
2.3.1 | 285 | 12/11/2023 |
2.3.1-231211-0953.Release | 77 | 12/10/2023 |
2.3.0 | 184 | 11/18/2023 |
2.2.1 | 156 | 10/21/2023 |
2.1.1 | 1,883 | 6/26/2023 |
2.1.0 | 142 | 6/23/2023 |
2.1.0-230621-1151.Release | 68 | 6/21/2023 |
2.1.0-230426-1916.Release | 86 | 4/26/2023 |
2.1.0-230420-1952.Release | 78 | 4/20/2023 |
2.1.0-230411-1909.Release | 82 | 4/11/2023 |
2.1.0-230315-1148.Release | 78 | 3/15/2023 |
2.0.0 | 294 | 3/1/2023 |
2.0.0-230219-1656.Release | 84 | 2/19/2023 |
2.0.0-221203-2249.Release | 97 | 12/3/2022 |
2.0.0-221203-2123.Release | 84 | 12/3/2022 |
2.0.0-221203-1959.Release | 92 | 12/3/2022 |
2.0.0-221112-2249.Release | 97 | 11/12/2022 |
2.0.0-221026-2257.Release | 98 | 10/26/2022 |
1.3.3 | 521 | 10/10/2022 |
1.3.3-221006-0024.Release | 80 | 10/5/2022 |
1.3.2 | 405 | 9/29/2022 |
1.3.2-220912-1711.Release | 97 | 9/12/2022 |
1.3.1 | 451 | 9/8/2022 |
1.3.1-220903-2224.Release | 87 | 9/3/2022 |
1.3.1-220826-1958.Release | 96 | 8/26/2022 |
1.3.0 | 440 | 8/21/2022 |
1.2.1-220815-1436.Release | 97 | 8/15/2022 |
1.2.1-220620-2346.Release | 117 | 6/20/2022 |
1.2.0 | 489 | 6/6/2022 |
1.1.4 | 462 | 4/14/2021 |
1.1.3 | 365 | 4/11/2021 |
1.1.2 | 344 | 3/31/2021 |
1.1.1 | 382 | 2/1/2021 |
1.1.0 | 388 | 1/30/2021 |
1.0.0 | 400 | 1/27/2021 |
v.2.4.0
- ADDED: LayerNames attribute
- ADDED: [NEW] Support for Nullable Reference Types (for `Notify` and `OnInstantiate`)
v.2.3.4
- ADDED: Support for .NET 8.0
- ADDED: Nested InputMap entries
- ADDED: OnImport attribute for editor only builds (GD4 only)
v.2.1.0
- ADDED: CodeComments attribute
- ADDED: OnInstantiate attribute (with protected constructor)
- ADDED: Inline changed action on Notify setter
- ADDED: Implicit operators as an alternative to calling .Get() on scene tree for non-leaf nodes
v.2.0.0
- ADDED: Support for Godot 4.0
-- KnownIssue: GodotOverride requires an additional partial method override declaration
- CHANGED: Notify must be used on property instead of field to access privately generated content
- ADDED: InputMap attribute
v.1.3.3
- ADDED: Support for placeholder scenes
- ADDED: Support for editable instanced scenes
- FIXED: GodotOverride in derived class now calls rather than hides base method
- FIXED: Previously, types could not share the same name. This has now been fixed.
- ADDED: Notify attribute (with support for [Export])
- ADDED: Support for uniquely named nodes (ie, Godot 3.5 - GetNode("%MyUniqueNode"))
v.1.2.0
- Replaces ISourceGenerator with IIncrementalGenerator for faster builds
- Hierarchy of inherited scenes are now fully accessible from base classes
- Hierarchy of instanced scenes can be made accessible using [SceneTree(traverseInstancedScenes=true)]
- FIXED: Modifications (overrides) of inheritance hierarchy now supported
- FIXED: Inheriting/Instancing scenes without scripts now supported
- FIXED: Consumers with implicit usings enabled now supported
v.1.1.4
- Exposed base classes/helpers to help create project specific source generators
v.1.0.0
- Initial release (SceneTree/GodotOverride)