Noodloft.Components 0.2.0-beta.2

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.

Movement intent is the third piece — the one usually written inline in a character script and usually written slightly wrong:

movement.Set(rawX, rawY);        // straight off the device, before any dead zone
movement.Intent;                 // ramped: what the character moves along
movement.RawIntent;              // unramped: what a dodge or a dash fires along

The dead zone is a circle across the pair, not a threshold per axis. With a per-axis dead zone of 0.2, a stick pushed exactly diagonally to 0.19 on each axis reads as nothing — while its true magnitude is 0.27, well past the threshold. That is how a worn controller ends up drifting diagonally while nobody is touching it. Everything past the dead zone is rescaled from 0, so crossing it is a nudge rather than an instant fifth of full speed.

Gameplay abilities

Character classes, equipped items, installed parts, vehicles and temporary effects all grant through the same source-aware seam:

var abilities = new GameplayAbilitySystem(catalog, resourceBank, logger);

abilities.TrySetSource(
    GameplayAbilitySource.Item(bootsInstanceId),
    new GameplayAbilityGrantSet
    {
        Abilities = [new GameplayAbilityGrant { AbilityKey = "dash" }],
    },
    out _,
    out _);

var activation = abilities.TryActivate("dash"); // tags, cost and actor-level cooldown

EquipmentAbilityBinder derives item, installed-part and optional catalog-backed enchantment grants from authoritative instance ids. Enchanted copies persist only key and level; current definitions re-derive compatibility and abilities. Cooldowns survive source removal, so gear swapping cannot reset them; removing a source cancels its active abilities without touching another source's copy. The accepted activation is authority proof for game-side execution—the library does not pretend it can generically perform a dash, axe throw or vehicle boost. See gameplay-abilities.md for tags, lifetimes, persistence and the server command contract.

Camera

shake.Add(0.4f);        // trauma, 0..1 — adds rather than replacing
shake.Offset;           // where to displace the camera this frame

orbit.Look(dx, dy);     // device units; sensitivity, inversion and clamping are the component's
orbit.TargetYaw;        // what a character should face — leads the camera's own angle

Trauma, not "play a shake for 0.3 seconds". A duration-based shake restarts on every hit, so a machine gun produces one permanent small shake instead of a build-up, and two sources at once means whichever fired last wins. Trauma adds, saturates at 1, and drains from wherever it reached. The displacement is trauma squared, so the tail of a shake fades out instead of leaving the camera buzzing at low amplitude — which reads as a rendering fault rather than an impact.

Follow damping is a critically damped spring rather than the lerp(current, target, rate * delta) every tutorial reaches for. That one is frame-rate dependent: the same rate lands somewhere else at 144 fps than at 60, so a camera tuned on the developer's machine is wrong on the player's.

The camera nodes are the camera rather than driving one, so exactly one thing writes the transform per frame. Follow and shake as separate scripts is the classic way to get a camera that jitters because both assign to Position and whichever runs last wins.

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.

Item modding has its own trust boundary. Definitions author sockets and compatibility tags; saves and network commands carry only instance ids and links, while the authority re-derives every stat and ability grant. The ownership transaction API, integrity audit and server command checklist are in docs/item-authority.md.

Godot

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

The addon source references all four packages, Noodloft.Components.Games.Godot.Arch included — NetworkedEntityNode links a scene node to an Arch entity. A game that uses none of the networking still needs the reference for the addon to compile.

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

GetNode<NoodloftSaveManager>("/root/NoodloftSaveManager").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.

Nodes hold state; systems hold rules

A node answers what is this thing's health. It cannot answer may this attacker damage that target, because that is a question about a pair and neither node owns it. Answering it inside every weapon script is how a game ends up with six copies of the friendly-fire rule and five of them updated.

var result = damageSystem.Hit(bullet.Shooter, target, 25f, DamageType.Physical);

if (result.Landed)      SpawnHitNumber(result.AppliedAmount, result.WasFatal);
else if (result.WasBlocked) bullet.PassThrough();   // a teammate: do not consume the shot

Blocked is deliberately not Rejected. Your rules refusing a hit is the common case — a hitbox resting against a teammate refuses on every physics frame — and it must not read as something going wrong.

Rules ship as Resources — SelfDamageFilter, GroupDamageFilter, DeadTargetFilter — so turning friendly fire on for one arena is a .tres edit. Teams are Godot's own groups; this library ships no team component, because the engine already has a better one and two sources of truth would only disagree.

This is not an ECS and does not claim to be. An ECS is fast because components are flat structs in contiguous arrays walked linearly; these are class instances on scene-tree nodes, and systems on top change nothing about that. What the split does buy is real and is two things: rules in one editable place, and fewer engine crossings. Every _Process override is a marshalled call from C++ into managed code, per node, per frame — two hundred actors with a live cooldown are two hundred crossings, or one plus a C# loop under a TickSystem. Gating decides how much work happens; batching decides how often the engine has to cross into C# to do it.

The full contract — the node API, the filter interface, the recipes and the pitfalls — is in docs/godot-guide.md.

When you actually want an ECS

Noodloft.Components.Games.Godot.Arch is a separate package that runs the Arch ECS inside Godot: a Node that owns the World and drives ordered system stages, a two-way entity↔node map with a resolution cache, and sync systems that write results back onto the scene tree. It builds on the Godot glue package for engine integration.

That is the real thing — flat structs in contiguous chunks, walked linearly — and it is worth reaching for in one specific situation: thousands of similar things that per-node scripts can no longer afford. Bullets, particles with gameplay meaning, a crowd. Not the player, not a boss, not a chest: those are individually interesting, want editor authoring, and there are twelve of them.

If the goal is tidier code rather than ten thousand affordable things, the systems layer above is the answer and it keeps your nodes. See docs/arch.md.

The package also contains the server-authoritative ECS protocol under .Arch.Net: stable network IDs, compact codecs, spawn/despawn/input/snapshot systems, wrap-safe interpolation, and a GodotNetTransport bridge over SceneMultiplayer custom packets. The addon supplies NoodloftSessionNode, RelayClientNode, and NetworkedEntityNode; component state follows this one snapshot path and must not also be assigned to a MultiplayerSynchronizer.

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

The packages multi-target net8.0 and net10.0. net8.0 is what Godot 4.4 gives a C# project by default, and a library that only shipped net10.0 would fail to install there with NU1201 — in the very engine version the addon names as its floor. The test projects target both, so the net8.0 asset is executed rather than merely compiled; running the whole suite locally therefore needs the .NET 8 runtime installed alongside the SDK. Without it, dotnet test -f net10.0 runs the net10.0 half.

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.