AutoInject for Godot C#

AutoInject resolves dependencies by inspecting nodes for the [Dependency] attribute and searching up the scene tree.

The Resolution Lifecycle:

1. Introspection: The Introspection generator creates metadata so the node can inspect its own properties without runtime reflection.
2. Trigger: When a node receives the Node.NotificationReady signal, it automatically begins resolution.
3. Search: The node searches its ancestors (starting with itself) for nodes implementing IProvideAny or IProvide<T>.
4. Synchronization: A dependent node's OnResolved is only called once all its required dependencies have been found and their providers have initialized.

The this.Provide() Convention: To ensure a predictable execution order and avoid deadlocks, providers should call this.Provide() inside their _Ready method. This guarantees the following synchronous order:

1. Dependent node _Ready (deepest nodes first).
2. Provider node _Ready (calls Provide).
3. Dependent OnResolved.
4. Frame 1 _Process.

Tip: If a provider is also a dependent, call this.Provide() from its OnResolved() to allow it to provide dependencies to its own subtree safely.

AutoInject uses the Introspection generator to add mixins to C# classes. These mixins allow nodes to gain state and handle lifecycle events without reflection.

CRITICAL REQUIREMENT: For any mixin to work, you must override _Notification in your node script and call this.Notify(what). This allows the mixins to intercept Godot notifications and invoke their handler methods.

Available Mixins:

• IAutoOn: Implements .NET-style handlers for Godot notifications (e.g., OnReady, OnProcess).
• IAutoConnect: Automatically binds properties marked with [Node] to scene tree nodes.
• IAutoInit: Adds an initialization lifecycle method called before _Ready (if IsTesting is false).
• IProvider: Allows a node to provide dependencies to descendants.
• IDependent: Allows a node to request dependencies from ancestors.
• IAutoNode: A convenience mixin that applies all the above mixins at once.

using Chickensoft.AutoInject;
using Chickensoft.Introspection;
using Godot;

// Apply all AutoInject functionality at once
[Meta(typeof(IAutoNode))]
public partial class MyNode : Node
{
  // REQUIRED for mixins to function
  public override void _Notification(int what) => this.Notify(what);
}

To avoid complex dependency hierarchies and ensure robust logic, subscribe to events emitted by the dependency values themselves rather than subscribing to a parent node's events. This ensures your logic reacts directly to the data it depends on.

Best Practices:

• Use OnResolved to set up subscriptions once dependencies are valid.
• Always clean up subscriptions in OnExitTree to prevent memory leaks.

[Meta(typeof(IAutoNode))]
public partial class MyDependent : Node
{
  public override void _Notification(int what) => this.Notify(what);

  [Dependency]
  public MyValue Value => this.DependOn<MyValue>();

  public void OnResolved()
  {
    // Setup subscriptions once dependencies are valid.
    MyValue.OnSomeEvent += ValueUpdated
  }

  public void OnExitTree()
  {
    // Clean up subscriptions here!
    MyValue.OnSomeEvent -= ValueUpdated
  }

  public void ValueUpdated()
  {
    // Do something in response to the value we depend on changing.
  }
}

AutoInject is a source-only package that requires the Introspection source generator. To install it, add the following packages to your .csproj file. Ensure you specify the correct versions from NuGet.

Required packages:

• Chickensoft.GodotNodeInterfaces
• Chickensoft.Introspection
• Chickensoft.Introspection.Generator (set as an analyzer)
• Chickensoft.AutoInject (set as an analyzer)

It is highly recommended to treat warning CS9057 as an error to catch compiler-mismatch issues with the Introspection generator.

<ItemGroup>
    <PackageReference Include="Chickensoft.GodotNodeInterfaces" Version="..." />
    <PackageReference Include="Chickensoft.Introspection" Version="..." />
    <PackageReference Include="Chickensoft.Introspection.Generator" Version="..." PrivateAssets="all" OutputItemType="analyzer" />
    <PackageReference Include="Chickensoft.AutoInject" Version="..." PrivateAssets="all" />
</ItemGroup>

<!-- Optional: Add analyzers for extra checks and code fixes -->
<ItemGroup>
    <PackageReference Include="Chickensoft.AutoInject.Analyzers" Version="..." PrivateAssets="all" OutputItemType="analyzer" />
</ItemGroup>

<!-- Recommended: Catch compiler-mismatch issues -->
<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <WarningsAsErrors>CS9057</WarningsAsErrors>
</PropertyGroup>

The IAutoInit mixin allows you to split a Godot node's initialization into two phases: Initialize() and OnReady(). This is designed to make unit testing easier by allowing you to mock dependencies before the node's logic runs.

• Initialize(): Used for late member initialization (e.g., assigning concrete implementations to dependencies). In a real game environment, this is called automatically from _Ready.
• OnReady(): Guaranteed to be called after Initialize(). This is where you use the dependencies set up in the previous step.

Testing Behavior: In a test environment, Initialize() is skipped if the IsTesting property is set to true. This prevents the node from overwriting your mocked dependencies with real ones.

using Chickensoft.AutoInject;
using Chickensoft.Introspection;
using Godot;

[Meta(typeof(IAutoInit), typeof(IAutoOn))]
public partial class MyNode : Node2D
{
  public override void _Notification(int what) => this.Notify(what);

  public IMyObject Obj { get; set; } = default!;

  public void Initialize()
  {
    // Called from _Ready if IsTesting is false.
    // Initialize values which would be mocked in a unit testing method.
    Obj = new MyObject();
  }

  public void OnReady()
  {
    // Guaranteed to be called after Initialize()
    // Uses the object setup in Initialize() (or the mock supplied by a test)
    Obj.DoSomething();
  }
}

How to use in a Unit Test:

var myNode = new MyNode()
{
  Obj = mock.Object
};

// Prevent Initialize() from overwriting the mock
(myNode as IAutoInit).IsTesting = true;

To make a value available to descendant nodes, implement the IProvider mixin and the IProvide<T> interface for each type you wish to provide.

Workflow:

1. Add [Meta(typeof(IProvider))] (or IAutoNode) to your class.
2. Implement IProvide<T>.Value() for each dependency.
3. Crucially, call this.Provide() once your dependencies are initialized (e.g., in OnReady or _Ready). This informs AutoInject that the values are ready for consumption.

Note: You can optionally implement OnProvided() to run logic immediately after this.Provide() is called.

namespace MyGameProject;

using Chickensoft.AutoInject;
using Chickensoft.Introspection;
using Godot;

[Meta(typeof(IAutoNode))]
public partial class MyProvider : Node, IProvide<string>
{
  public override void _Notification(int what) => this.Notify(what);

  // Implementation of the dependency
  string IProvide<string>.Value() => "Value";

  // Inform AutoInject that the value is ready
  public void OnReady() => this.Provide();

  public void OnProvided()
  {
    // Optional: logic after providing
  }
}