Chickensoft.GodotNodeInterfaces 1.7.0-godot4.2.0-beta.1

GodotNodeInterfaces

Godot node interfaces and adapters.

<p align="center"> <img alt="Chickensoft.GodotNodeInterfaces" src="Chickensoft.GodotNodeInterfaces/icon.png" width="200"> </p>

🤔 What...why?

In a perfect world, there are cases where mocking Godot nodes for testing makes a lot of sense:

• You are a TDD cultist.
• You want to unit-test a Godot node script.
• You don't want to instantiate the corresponding scene for a node script. Why? Because instantiating a scene also instantiates any children and their scripts, and so on. Just instantiating scripts and adding them to the scene causes test coverage to be collected, and it ends up covering far more of the app than the actual system-under-test (the node script you were trying to test), which makes it hard to tell which scripts are still un-tested.

GodotSharp doesn't expose interfaces for Godot nodes, making it very expensive or difficult to mock them.

If you're still confused, this probably isn't for you. It's one of those "you'll know if you ever want/need this" type of things. This is really just for those completionists who like writing tests and getting 100% code coverage.

🧐 I don't see anything here

That's because the interfaces and adapters are generated at build-time based on the version of the GodotSharp API being referenced.

Here's a sample of a generated interface:

/// <summary>
/// <para>Casts light in a 2D environment. A light is defined as a color, an energy value, a mode (see constants), and various other parameters (range and shadows-related).</para>
/// </summary>
public interface ILight2D : INode2D {
    /// <summary>
    /// <para>The Light2D's blend mode. See <see cref="Light2D.BlendModeEnum" /> constants for values.</para>
    /// </summary>
    Light2D.BlendModeEnum BlendMode { get; set; }
    /// <summary>
    /// <para>The Light2D's <see cref="Color" />.</para>
    /// </summary>
    Color Color { get; set; }
    /// <summary>
    /// <para>If <c>true</c>, Light2D will only appear when editing the scene.</para>
    /// </summary>
    bool EditorOnly { get; set; }

    ...

And here's the corresponding adapter:

/// <summary>
/// <para>Casts light in a 2D environment. A light is defined as a color, an energy value, a mode (see constants), and various other parameters (range and shadows-related).</para>
/// </summary>
public class Light2DAdapter : Node2DAdapter, ILight2D {
  private readonly Light2D _node;

  /// <summary>Creates a new Light2DAdapter for Light2D.</summary>
  /// <param name="node">Godot node.</param>
  public Light2DAdapter(Node node) : base(node) {
    if (node is not Light2D typedNode) {
      throw new System.InvalidCastException(
        $"{node.GetType().Name} is not a Light2D"
      );
    }
    _node = typedNode;
  }

    /// <summary>
    /// <para>The Light2D's blend mode. See <see cref="Light2D.BlendModeEnum" /> constants for values.</para>
    /// </summary>
    public Light2D.BlendModeEnum BlendMode { get => _node.BlendMode; set => _node.BlendMode = value; }

    ...

And here's what the adapter factory looks like:

public static class GodotNodes {
  private static readonly Dictionary<Type, Func<Node, IGodotNodeAdapter>> _adapters = new() {
      [typeof(INode)] = node => new NodeAdapter(node),
      [typeof(IAnimationPlayer)] = node => new AnimationPlayerAdapter(node),
      [typeof(IAnimationTree)] = node => new AnimationTreeAdapter(node),
      [typeof(ICodeEdit)] = node => new CodeEditAdapter(node),
      [typeof(IGraphEdit)] = node => new GraphEditAdapter(node),

      ...

📦 Installation

Just install the package from nuget!

dotnet add package Chickensoft.GodotNodeInterfaces 

📖 Usage

All you have to do is implement your own extension method and use it in in place of GetNode<T>(string) that actually gets the godot node by the path and creates an adapter for it (or looks up the path in a cache of mocked nodes).

public static class FakeSceneTree {
  public static T GetNodeEx<T>(this Node node, string path) where T : class, INode {
    var child = node.GetNode(path);
    if (child == null) {
      // TODO: lookup a mock node in your fake scene tree or something
      return (T)FakeSceneTree.Mocks[path];
    }

    return GodotNodes.Adapt<T>(child);
  }

  // When running tests, put your fake scene tree stuff here
  // (or come up with your own system for storing mock nodes temporarily)
  public static Dictionary<string, INode> Mocks = new();
}

Or you can use the [AutoNode] functionality from PowerUps with SuperNodes.

Once you have that setup, you can use it in your node scripts.

public partial class MyNode : Node2D {
  public ISprite2D Sprite { get; set; } = default!;

  public override void _Ready() {
    Sprite = this.GetNodeEx<ISprite2D>("Sprite");
  }
}

💁 Getting Help

Is this package broken? Encountering obscure C# build problems? We'll be happy to help you in the Chickensoft Discord server.

💪 Contributing

This project contains a very hastily written console generator program that uses reflection (yep!) to find all the types in GodotSharp that are or extend the Godot Node class, and then generates interfaces, adapters, and an adapter factory.

The actual package is left empty — we generate the project in CI/CD so that we can keep this package up-to-date with renovatebot and automatically release a new version whenever a new GodotSharp package drops.

🐞 Debugging

A VSCode launch profile is provided that allows you to debug the generator program. This can be great when trying to figure out why it's generating invalid code.

Important: You must setup a GODOT environment variable for the launch configurations above. If you haven't done so already, please see the Chickensoft Setup Docs.

🏚 Renovatebot

This repository includes a renovate.json configuration for use with Renovatebot to help keep it up-to-date.

Unlike Dependabot, Renovatebot is able to combine all dependency updates into a single pull request — a must-have for Godot C# repositories where each sub-project needs the same Godot.NET.Sdk versions. If dependency version bumps were split across multiple repositories, the builds would fail in CI.

The easiest way to add Renovatebot to your repository is to install it from the GitHub Marketplace. Note that you have to grant it access to each organization and repository you want it to monitor.

The included renovate.json includes a few configuration options to limit how often Renovatebot can open pull requests as well as regex's to filter out some poorly versioned dependencies to prevent invalid dependency version updates.

If your project is setup to require approvals before pull requests can be merged and you wish to take advantage of Renovatebot's auto-merge feature, you can install the Renovate Approve bot to automatically approve the Renovate dependency PR's. If you need two approvals, you can install the identical Renovate Approve 2 bot. See this for more information.

🐣 Package generated from a 🐤 Chickensoft Template — https://chickensoft.games