SBGItemFramework

Shared backbone for Super Battle Golf custom-item mods. Each consumer mod hands the framework a RegisteredItem description and an IItemHandler that owns the gameplay; the framework deals with everything that would otherwise force every item mod to write the same ~300 lines of ItemCollection / PlayerInventory / LocalizedString / HotkeyUi plumbing and to coordinate that plumbing pairwise with every other custom-item mod the user has installed.

Not a gameplay mod. It does nothing on its own — install it because something else lists it as a dependency.

Consumer flow

public sealed class MyItemPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        ItemKit.Register(RegisteredItem.Define((ItemType)1234, "My Item")
            .WithHandler(new MyItemHandler())
            .WithIconFromVanillaItem(ItemType.OrbitalLaser)
            .WithIconTint(new Color(0.65f, 0.85f, 1.0f))
            .WithMaxUses(2)
            .WithTooltip("One-line description shown in the pause-menu probability grid.")
            .WithConfigBindings(Config, bindMaxUses: true, bindSpawnWeights: true)
            .Done());
    }
}

public sealed class MyItemHandler : ItemHandlerBase
{
    public override void OnUse(PlayerInventory inventory)
    {
        // Server-authoritative work goes through a Mirror Cmd; client-only fizz can run here.
    }
}

The framework picks a non-conflicting integer for the ItemType is the consumer's responsibility. Use anything >= 1000 to stay clear of the vanilla enum range; the framework rejects ids <= 0 and warns when two mods claim the same id (second registration loses).

What the framework owns

What the framework deliberately does not own (yet)

• Held-model prefab in the right hand. If a future item needs a custom mesh visible while equipped, that landed in v0.2.x of the framework.
• Animator pose mapping for the upper body. Same v0.2 scope.
• Custom drop visuals — vanilla pickup mesh works for sprite-based items.
• Network helpers for cross-client gameplay events. Consumer mods register their own Mirror message handlers.

Build / deploy / release

dotnet build -c Release
pwsh tools/package.ps1
gh release create vX.Y.Z artifacts/Cray-SBGItemFramework-<ver>.zip --notes-file CHANGELOG.md