GodotSharp.SourceGenerators 2.3.4

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 project input actions
• 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 Content

• GodotSharp.SourceGenerators
  • Table of Content
  • Installation
  • Attributes
    • SceneTree
    • GodotOverride
    • Notify
    • InputMap
    • CodeComments
    • OnInstantiate
    • OnImport

Installation

Install from NuGet

Attributes

SceneTree

• Class attribute
• Generates class property for uniquely named nodes
• Provides strongly typed access to the scene hierarchy (via _ operator)

// 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 SceneA : Node2D 
{
    public override void _Ready() 
    {
        // You can access the node via '_' object.
        GD.Print(_.Node1.Node11.Node12.Node121);
        GD.Print(_.Node4.Node41.Node412);
    }
}

GodotOverride

• Method attribute
• Allows use of On*, instead of virtual _* overrides
• (Requires partial method declaration for use with Godot 4.0)

public partial class MyNode : Node2D 
{
    // Requires partial method declaration for use with Godot 4.0
    public override partial void _Ready(); 
    
    [GodotOverride]
    protected virtual void OnReady() 
    {
        GD.Print("Ready");   
    }
}

Equivalent with

public override void _Ready() 
{
    GD.Print("Ready");
}

Notify

• Property attribute
• Generates boiler plate code, triggering only when values differ
• (Automagically triggers nested changes for Resource and Resource[])

public partial class NotifyTest : Node {
    // [Notify] attribute is used to generate a private field _value1, a public event Action Value1Changing, and Value1Changed.
    [Notify]
    public float Value1 
    {
        get => _value1.Get();
        set => _value1.Set(value);
    }

    public override void _Ready() 
    {
        Value1Changing += () => GD.Print("Value1Changing raised before changing the value.");
        Value1Changed += () => GD.Print("Value1Changed raised after changing the value.");

        Value1 = 1; // Raise Value1Changing and Value1Changed
        Value1 = 2; // Raise Value1Changing and Value1Changed
        Value1 = 2;// Not raise any events because the value is the same.
    }
}

InputMap

• Class attribute
• Provides strongly typed access to project input actions Declare a class with [InputMap] attribute.

/// <summary>
/// This class is used to define the input actions in the project.
/// </summary>
[InputMap]
public static partial class InputMapConst { }

The following code will be auto-generated by Source Genreator. The actions are declared in the project.godot.

partial class InputMapConsts
{
    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";
}

The generated code does not include built-in actions such as ui_accept.

You may want to manually add built-in actions to your class. If so, check this: BuiltinInputActions.cs

CodeComments

• Class attribute
• Provides a nested static class to access property comments from code (useful for in-game tooltips, etc)

[CodeComments]
public partial class CodeCommentsTest : Node 
{
    // This a comment for Value1.
    // [CodeComments] only works with Property.
    [Export] public float Value1 { get; set; }

    // Value 2 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: ""
    }
}

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)

// [OnInstantiate] is used to instantiate the PackedScene from resource. 
// You have to create a C# script with the same name as the scene file, and attach it to the root node of the scene.
// Additionally, the script must be in the same folder as the scene file.
public partial class InstantiateTest : Node {
    // The method with the [OnInstantiate] attribute will be called when the scene is instantiated via the Instantiate(), which is auto-generated as well.
    [OnInstantiate]
    private void Init() {
        GD.Print("Init called when the node is instantiated.");
    }
}

public partial class InstantiateTestCaller : Node {
    public override void _Ready() {
        // Instantiate the scene and add it as a child.
        InstantiateTest node = InstantiateTest.Instantiate();
        AddChild(node);
    }
}

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