Noodloft.Components 0.0.1-alpha3

Noodloft.Components

Engine-agnostic gameplay components for .NET games, with save/load built in and a Godot 4 addon on top.

The gameplay rules — how armor and resistances combine, when a level-up fires, where an item stacks — live in plain C# classes that can be unit-tested without an engine running. The engine layer is a thin shell over them.

Projects

The component families

The shape every component takes

Model            mutable state, with internal setters
DTO              a readonly struct describing one operation
Evaluator        a pure static function: (DTO, Model) -> result
Component        wires them together and raises events

An operation returns one of three outcomes, and the difference matters:

var result = cooldown.SetModel(CooldownOperation.Tick(delta));

result.Outcome switch
{
    ReactiveOutcome.Applied   => // the model changed; OnModelSet fired
    ReactiveOutcome.Unchanged => // legal, but a no-op. Silent: this is the per-frame path
    ReactiveOutcome.Rejected  => // the caller asked for something impossible. Logged, with a reason
};

Input, specifically

The two halves are split because only one of them is save state.

// Timing. Never saved: restoring a half-held button leaves it stuck down forever.
if (buffer.TryConsume("jump"))   // pressed up to BufferDuration ago, and not yet claimed
    Jump();

buffer.HoldRatio("charge");      // 0..1, for a charge meter

// Bindings. Saved — but only the actions the player actually rebound, so retuning a
// default control scheme still reaches everyone who left that action alone.
bindings.SetModel(BindingOperation.Rebind("jump", new InputBinding(InputDeviceKind.Keyboard, "Enter")));

A rebind onto a button another action owns is refused and names the clash, which is what a controls menu needs in order to say "Space is already Jump". InputBindingsNode is the only thing that turns a stored binding into a real InputEvent, so a save survives an engine upgrade renumbering its keycodes.

Unchanged exists so that ticking sixty idle cooldowns a frame raises no events and logs nothing. Every reason string on that path is a constant, because an interpolated one would allocate on every tick of every component — measured at 128 B per tick before it was fixed.

Three words, no overlap

Configuration is never written to a save file. That is what lets a designer rebalance a curve or widen a chest and have it take effect on saves that already exist, instead of being overwritten by them.

Persistence

var session = new SaveSession(new FileSystemSaveStore("saves"), gameVersion: "1.0.0");

session.Register(SaveParticipants.ForDamageable("player", damageable));
session.Register(SaveParticipants.ForInventory("player.bag", bag));

session.Save("slot1");
session.Load("slot1");

Save merges over what is already in the slot rather than replacing it, so saving while only one scene is loaded does not wipe every other scene's state. Restoring writes models directly and fires no domain events: loading a dead boss raises no OnDied, loading level 12 raises no eleven level-ups.

The full contract — the JSON shape, the type-id table, the version-mismatch rules and the config-drift table — is in docs/save-format.md.

Godot

Add addons/noodloft.components/ to your project and enable the plugin. That registers the SaveManager autoload; the nodes and resources appear in Create New Node and Create New Resource as soon as the project builds.

Drop a node in, point it at a .tres, give it a Save Id, and it is saved:

GetNode<SaveManager>("/root/SaveManager").Save("slot1");

Nodes are gated hard on processing. SetProcess(false) is the normal state — a ready cooldown, a damageable out of invulnerability frames, an idle interactable — so a level full of components costs nothing. At 64 actors an idle frame measures 4.8 µs and 0 B allocated.

Why the addon ships as source

Godot registers C# types as scripts keyed by a res:// path, stamped at compile time by Godot.SourceGenerators. A [GlobalClass] compiled into a referenced DLL has no such path in the consuming project, so it cannot be attached to a node in the editor and a .tres cannot name it. The node and resource types therefore ship as source; the engine-independent logic they call stays in the compiled libraries.

Shipping source also removes GodotSharp version skew: the consumer compiles against their own engine's bindings.

Build

dotnet build Noodloft.Components.slnx -c Release   # must stay at zero warnings
dotnet test  Noodloft.Components.slnx
dotnet run -c Release --project benchmarks/Noodloft.Components.Benchmarks -- --filter '*FrameLoop*' --job short

Analyzers run at latest-recommended with EnforceCodeStyleInBuild, so the IDE and the command line agree on what counts as a warning. Nothing is suppressed in src/; the few suppressions that exist are scoped to a test or benchmark csproj with a written reason.

Releases

Tagging is what publishes. A vX.Y.Z tag is the version — the workflow refuses a tag that is not a semantic version, and refuses one with no matching section in CHANGELOG.md. That section becomes both the package's release notes and the body of the Gitea release, so the three can never disagree.

Below 0.1.0 every tag carries -alpha and the API is explicitly unstable.