Noodloft.Components 0.2.0-beta.1

• net10.0

  • No dependencies.

• net8.0

  • No dependencies.

0.1.0 gave a game the ability to hurt things. It had no answer for why a player would want to. This
release is the loop that sits on top of the damage seam: skills that level, items that carry stats and
a rarity, loot tables that decide what falls out of a monster, and — the piece that was actually
missing — the half of damage that produces a number rather than reducing one.

Two rules run through all of it, and they are the same rule. **Derived, never accumulated**: skill
rewards and equipment stats are dropped by source and re-added from current state, because adding a
modifier per level-up passes every test that only counts upwards and then doubles a character on their
first load. And **no random number generator inside an evaluator**: attacks take the roll as a
parameter, loot takes an `IRollSource`, so both are pure functions of their inputs and a client and a
server given the same seed agree about what happened.

The networking layer from the relay work also lands here, undocumented until now.

Tagged `-beta.1` for a dependency reason rather than a confidence one. `Noodloft.Components.Games.Godot`
now exposes `GodotTokenStore : ITokenStore` and so depends publicly on `Noodloft.Identity.Client`,
which has only ever published `0.0.1-alpha1`. A stable package depending on a prerelease is NU5104,
and it hands consumers a dependency that can be unlisted out from under them. The label comes off when
that package goes stable; nothing else about this release is waiting on anything.

### Added

- **Skills.** `SkillSet` stands to `ProgressionReactiveComponent` exactly as `AttributeSet` stands to
 `AttributeReactiveComponent`: a keyed container over real progressions, one save entry for the whole
 set, and `OnSkillLevelUp(key, level)` re-raised with the key. A `SkillDefinition` carries
 `SkillReward`s — "+2 Armor per Mining level" — applied to an `AttributeSet` under the per-skill
 source `skill:{Key}`.

 Rewards are **derived, never accumulated**. `ApplyRewards` drops each skill's modifiers by source and
 re-adds them from the current level, so calling it once, three times, or after a load produces
 identical stats. Adding a modifier per level-up instead passes every test that only goes up, then
 doubles a character's stats the first time a save is loaded.

 In the addon: `SkillSetNode`, `SkillSetResource`, `SkillEntryResource`, `SkillRewardResource`.

- **The offensive half of damage.** `DefaultDamageEvaluator` starts from an amount and asks what the
 target keeps; `DefaultAttackEvaluator` produces that amount in the first place, as
 `(Power + Strength × StrengthFlatShare) × (1 + Strength / StrengthDivisor)`. `AttackerView` mirrors
 `DamageableView`, `IAttackSource` mirrors `IMitigationSource`, and `AttributeAttackSource` reads the
 stats live so a buff landing between two swings reaches the second one. `AttackOptions.StrengthFlatShare`
 defaults to 0, making Strength a clean linear multiplier; `0.2` reproduces Skyblock's quadratic
 `(base + Strength/5) × (1 + Strength/100)`.

 No random number generator anywhere in it — `Attack` takes the roll as a parameter, so a hit is a
 pure function of its inputs and resolves identically on a client and a server given the same roll.

 In the addon: `AttackerNode`, `AttackResource`.

- **Loot tables, Magic Find and Gathering Fortune.** A new `Loot` family — `LootTable`, `LootEntry`,
 `LootContext`, `DefaultLootEvaluator` — plus `LootTableResource` and `LootEntryResource` in the addon.
 Two table kinds: `Independent` (each entry rolls its own chance — a monster's drop list) and
 `Weighted` (N picks from a pool — a chest).

 **Magic Find is multiplicative and opt-in per entry.** Multiplicative so the stat is worth the same
 proportion at both ends of the scale; opt-in so it raises the rare drop rather than the guaranteed
 junk, which would otherwise make it mostly a way to get more junk and dilute what it was bought for.

 **Gathering Fortune's fractional part is a chance, not a truncation.** 100 Fortune is exactly one
 more of everything and 30 is a thirty percent chance of one more — truncating instead would make
 every amount below 100 worth precisely nothing. Also opt-in, because 2.4 legendary swords is not a
 thing anybody designed.

 A reforged drop is always a single copy: a stack of five that shared one reforge is the bug that
 forces it.

- **`SeededRollSource`** — the evaluator takes an `IRollSource` rather than calling `Random.Shared`, so
 loot is a pure function of table and seed. Deliberately **not** `System.Random`, whose sequence is
 documented as unstable across .NET versions: a save that recorded a seed would produce different loot
 after a runtime upgrade, and a client and server on different patch levels would disagree about what
 dropped. This is xorshift128 written out in full, seeded through SplitMix32 — seeding only the first
 word looks like it works and does not, because the early output is dominated by the untouched
 constants and seeds 1 through 20 produce the same sequence.

- **Items: base stats, rarity, reforges and skill requirements.** A new `Items` family — `ItemDefinition`,
 `ReforgeDefinition`, `ItemRequirement`, `ItemCatalog`, `ItemInstanceStore`, `EquipmentSet` — plus
 `ItemResource`, `ReforgeResource`, `ItemCatalogResource` and `EquipmentNode` in the addon.

 Stats are derived and idempotent, same rule as skills: `ApplyStats` drops each slot's modifiers by
 source and re-adds them from what is worn now. One source per slot (`equipment:weapon`), because
 `RemoveModifiersFrom` works by source and sharing one would make re-deriving the weapon wipe the
 boots.

 Rarity scales reforges and nothing else. A Legendary sword is strong because its own stats say so;
 making rarity multiply base stats too means every balance change has to be made twice.

 `ItemDefinition.Value` is the item's worth in the abstract, not a price. A vendor applies its own
 buy and sell margins to it, so an item that four shops stock is one number rather than four that
 drift apart, and the gap between the two margins is where an economy lives — close it and buying
 then selling becomes a free-money loop.

 `ItemDefinition.Validate()` rejects a reforgeable stackable, and `ItemCatalog.Validate()` rejects a
 reforge restricted to a slot no item uses. Both look entirely correct in an inspector and do nothing
 at runtime.

- **`ItemStack.InstanceId`** — **breaking**, and the thing every other item feature needed. A stack with
 an identity never merges with anything, so two Heroic swords and one plain one are three stacks
 rather than one. `InventoryOperation.AddUnique` / `RemoveUnique` name a specific copy; plain
 `Remove(itemId, n)` now **skips copies that carry an identity**, so a recipe asking for "a sword"
 cannot consume the reforged one the player is wearing.

 The identity is opaque and lives on `ItemInstanceStore`, not on the stack. A stack lives in an array
 of two hundred, most of them empty; hanging a reforge off each one turns a grid of value types into a
 graph of allocations for a property almost nothing uses.

 `InventorySlotSnapshot` gained `InstanceId`. Old saves load — the field defaults to null — but a save
 written by 0.1.0 has no identities to lose.

- **`AttackTiming`.** Attack speed is not a number a swing uses — it is a number *everything in* a
 swing uses. A melee attack has at least four durations: the animation, the wind-up before damage, the
 root, and the combo window. Scale three and the fourth desynchronises, and it never crashes — damage
 simply lands after the animation ended.

 So it is a type rather than a float. `Scale(seconds)` and `AnimationSpeed` come from one `Rate` by
 construction, which is the only way "the hitbox agrees with what is on screen" stops being something
 a caller has to remember. Durations divide, rates multiply.

 `MaximumAttackRate` (4 by default) is load-bearing rather than defensive: far enough up the curve a
 wind-up rounds below one frame, the hitbox turns on and off inside a single physics step, and the
 attack stops hitting anything. The cap makes attack speed a stat that stops helping instead of a
 weapon that stops working.

- **`DamageOperation.CriticalMultiplier`.** Crit damage belongs to whoever swung. A rogue with 250%
 crit damage hits everything for 250%; reading it off the target instead makes the same swing land
 differently depending on which monster it hit. Null keeps the existing `DamageableOptions.CriticalMultiplier`
 behaviour, so authored hits with no attacker behind them are unaffected.

- **`StatNames`.** Constants for the stat keys the library's own adapters look for. `AttributeSet` keys
 are ordinal, so `"critchance"` against a registered `"CritChance"` is not a lookup failure — it is a
 stat that reads zero forever, and zero looks plausible for most of them.

- **`PersistentComponentNode.OnRestored()`.** Restoring is deliberately silent: loading a character at
 Mining 41 raises zero level-ups. Correct, and it meant derived state had no way to hear about a load
 — the levels came back and the stats they paid for did not. Every persistent node gets the hook.

- **Cloud saves.** `SyncedSaveStore` writes locally and mirrors to a server on a background worker, so
 a save never costs a frame and a player with no connection keeps playing. Uploads coalesce per slot:
 autosaving every 45 seconds while offline queues one pending write, not forty. Reads are local only;
 call `PullAsync()` once after sign-in. `HttpRemoteSaveBackend` speaks four routes and takes a token
 callback rather than a token, so refresh is somebody else's problem.

 `SyncedSaveStore.PushAsync()` queues every local save the server has no newer copy of. This is what
 rescues a write the last session made but quit before uploading — without it that save waits on disk
 until the player happens to write the same slot again, which for a finished playthrough is never.

 `NoodloftSaveManager` carries `CloudBaseUrl` and a `CloudAccessToken` callback, and
 `NoodloftSessionNode.MirrorSavesToApi` wires the two together — the session node is the only thing
 that owns a token.

 Conflicts are last-write-wins by `SavedAtUtc`. Stated plainly because it is a real limitation: two
 devices playing offline will lose one of the two sessions.

- **Server-authoritative networking for the Arch adapter.** A binary replication protocol under
 `Noodloft.Components.Games.Godot.Arch/Net/`, sitting on the same ECS the swarm already runs on.

 `NetworkRole` is `Standalone`, `Server` or `Client`, and the systems are split along it:
 `NetSnapshotSendSystem` / `NetSnapshotApplySystem`, `NetInputSendSystem` / `NetInputApplySystem`,
 `NetSpawnSendSystem` / `NetSpawnSystem`, and `NetInterpolationSystem`, which smooths remote positions
 on the rendered-frame stage rather than the fixed one.

 The wire format is authored, not reflected. `INetComponentCodec` owns one component slice under a
 stable `TypeId` byte — `Position2DCodec`, `Velocity2DCodec`, `HealthCodec`, `FactionCodec`,
 `AnimatedCodec` — registered in a `NetComponentRegistry`, and `SnapshotMessages` fixes the payload
 ids and header sizes as constants. `NetworkWriter` and `NetworkReader` are non-throwing little-endian
 `ref struct`s over caller-owned memory: a truncated or hostile packet returns false rather than
 throwing inside a receive loop.

 `NetSpawnRegistry` maps an authored kind byte to the archetype and factory that builds it, so a
 client constructs an entity it has never seen a class for. `NetworkEntityMap` keeps remote ids
 separate from local `Entity` handles, and registering the same kind twice throws at registration
 rather than producing two readings of the same byte at runtime.

- **`RelayMultiplayerPeer`** — a `MultiplayerPeerExtension` that adapts Noodloft's WebSocket relay
 framing to Godot's own multiplayer API, so `SceneMultiplayer` and everything built on it works
 unchanged over the relay. Transfer mode and channel are accepted and retained because the Godot API
 is expected to behave normally, but WebSocket delivery is always reliable and ordered and they cannot
 loosen that; a lower-latency transport belongs behind this same contract.

 `GodotNetTransport` is the single bridge between Godot's custom-packet layer and the ECS protocol.
 Component state stays owned by the snapshot pipeline and is never also put on a
 `MultiplayerSynchronizer` — two mechanisms replicating one value is two mechanisms disagreeing about
 it.

 In the addon: `RelayClientNode` (host/join lifecycle), `NoodloftSessionNode` (sign-in, and the only
 thing that owns a token) and `NetworkedEntityNode`, which links an authored scene node to the
 networked entity driving it. `NodeCaptureSystem2D` reads an authoritative `CharacterBody2D`'s
 transform into ECS; `NodeSyncSystem2D` writes the other way for remote entities. Which direction a
 transform flows is a property of the entity, not something each system guesses.

- **`GodotTokenStore`** — encrypted token storage over `user://`, keyed on Godot's device identifier
 combined with a random per-install seed. Web exports expose no device identifier, so there the
 install seed is the whole of it. This keeps credentials off disk in plain text; it is not a
 replacement for a platform keychain, and any platform that has one should use it instead.

- **Documentation** — `docs/networking-blueprint.md` for the protocol and the role split.

### Changed

- **The supported engine range is now `[4.4.0, 5.0.0)`** rather than exactly `4.4.0`. The pin was
 meant to stop NuGet resolving a GodotSharp newer than the engine a consumer actually runs, and it
 did — along with stopping anyone on 4.5 or later from restoring at all.

- **The Godot addon now needs `Noodloft.Components.Games.Godot.Arch`.** `NetworkedEntityNode` links a
 scene node to an Arch entity, so the addon source no longer builds against the three core packages
 alone. Games that unpack `addons/` and use none of the networking still need the package reference
 for the addon to compile.

- **`Noodloft.Components.Games.Godot` takes a public dependency on `Noodloft.Identity.Client`**, which
 arrives transitively in any project referencing it. It is on nuget.org, so nothing extra is needed to
 restore it.