Equipment

SPI the game implements to give equip slots their TYPED rules — the framework only moves opaque bytes into slots. "A helmet only fits slot 1", "a weapon only fits slot 0", "a card only fits a deck slot": all live here, per (slot, item). Slot ids are opaque, game-defined ints. The default (DefaultEquipmentPolicy) is permissive — anything fits any slot — so a game with no slot typing works out of the box and the wire stays genre-agnostic. Register your own BEFORE AddCrossplayEquipment (a TryAdd seam). Decode your item header from the opaque bytes to answer; CanEquip runs on the poll thread each equip attempt, so keep it allocation-free.

sealed class SlotTyping : IEquipmentPolicy
{
    public bool CanEquip(long ownerId, int slot, ReadOnlySpan<byte> item) => slot switch
    {
        0 => IsWeapon(item),   // slot 0 = weapon only
        1 => IsHelmet(item),   // slot 1 = helmet only
        _ => true,
    };
}
// services.AddSingleton<IEquipmentPolicy, SlotTyping>(); // BEFORE AddCrossplayEquipment()

• bool CanEquip(long ownerId, int slot, ReadOnlySpan<byte> item)

  May this OWNER equip this item into this slot? The owner id lets a policy apply per-player rules (card thresholds, level gates, class restrictions) at equip time, not just per-(slot, item) typing.

The Equipment piece, client side. Two halves, mirroring the two wire channels: The OWNER'S loadout (like an inventory): request your equipped slots (RequestAsync), equip a bag slot into an equip slot (EquipAsync), unequip (UnequipAsync), and receive a fresh EquipmentContents snapshot after every server-side change — raised on LoadoutChanged. Item bytes + slot ids are your game's vocabulary; map them to your own icons/UI. OTHERS' visible gear: each wearer's EntityEquipment broadcast (on change, replayed on interest reveal) is decoded and pushed to the game's IEquipmentView (bound by IEquipmentViewFactory) AND raised on EntityLoadoutChanged — so a game can bind gear to models through the SPI or react through the event. Remove this package and equipment simply stops — nothing else breaks.

• EquipmentContents Loadout

  The latest OWNER loadout snapshot pushed by the server (null until first received).

• event Action<EquipmentContents> LoadoutChanged

  A fresh OWNER loadout snapshot arrived (in reply to a request, or after any server change).

• event Action<long, EquipmentSlotView[]> EntityLoadoutChanged

  Another wearer's VISIBLE loadout arrived (entity id + its occupied slots). Raised even when no IEquipmentView is bound, so an event-driven game can render gear without the factory.

• UniTask<EquipmentContents> RequestAsync(CancellationToken ct = default)

  Requests the owner's current loadout (the reply raises LoadoutChanged).

• UniTask<EquipResponse> EquipAsync(int slot, int fromBagSlot, CancellationToken ct = default)

  Equips the item at bag slot fromBagSlot into equip slot slot (atomic + policy-gated server-side; fresh contents arrive separately on success).

• UniTask<EquipResponse> UnequipAsync(int slot, CancellationToken ct = default)

  Unequips the item at equip slot slot back into the bag.

The presentation seam for ONE wearer's VISIBLE loadout — the game binds an entity id + its equipped slots to its own models / attachment points (or a text row, or a 2D paper-doll: the piece cannot tell). The piece receives each wearer's EntityEquipment broadcast (on change, and replayed in full when the wearer enters this client's interest) and pushes the full occupied set here; the game decides what "wearing this" looks like. Presentation-agnostic by construction: no mesh, no animator, no asset — just opaque slot ids and opaque item bytes. A view whose underlying object was destroyed should no-op (the piece tolerates it). This is the OTHERS'-gear half; the OWNER'S own loadout arrives instead through LoadoutChanged.

• void ApplyLoadout(long entityId, EquipmentSlotView[] slots)

  Renders entityId's full occupied loadout (empty array = wears nothing).

The game's factory that resolves a wearer's entity id to its IEquipmentView — the equipment analogue of IRigidBodyViewFactory / ICharacterFactory. The piece calls Resolve each time an EntityEquipment broadcast arrives for that wearer; a game that has no view for the id (not spawned locally, culled, …) returns null and the piece simply raises its EntityLoadoutChanged event without pushing to a view. Optional dependency: with no factory bound, the piece still decodes the broadcast and raises EntityLoadoutChanged — a headless / text / event-driven client is valid.

• IEquipmentView Resolve(long entityId)

  Returns the view bound to entityId, or null if the game has none.