CiCi's Trinket & Binding Framework

A library mod for White Knuckle. Provides a public API that other mods can call to register custom Trinkets (run-start modifiers, optional) and Bindings (run-start modifiers with stronger effects, optional) so they show up in the trinket/binding picker on Fresh Game start.

This mod does nothing by itself. It's a dependency for other mods.

For players

Just install it. You'll only need it if a mod you use lists this as a dependency — Thunderstore Mod Manager will install it automatically in that case.

For modders

using TrinketAndBindingFramework;

[BepInDependency(TrinketAndBindingFramework.Plugin.GUID)]
public class MyMod : BaseUnityPlugin
{
    private void Awake()
    {
        TrinketRegistry.Register(
            id: "yourmod_my_trinket",
            displayName: "My Trinket",
            description: "...",
            icon: yourSprite,
            isBinding: false,
            itemsToGrantFactory: () => new List<Item_Object> { yourItemTemplate }
        );
    }
}

See the source of CiCi's Climbing Axes or CiCi's Pioneer's Shotgun for working examples.

Compatibility

• White Knuckle (current build)
• BepInEx 5.x

Changelog

1.2.2

Added

• Centralized leaderboard disable. The framework now holds disableLeaderboards = true for any run while it's loaded, replacing the per-mod copy-paste call in dependent mods. Polls and re-asserts so other systems clearing the flag can't slip a leaderboard submission through.

For mod authors

• Drop your CL_Leaderboard.WK_Leaderboard_Core.disableLeaderboards = true line. The framework owns it now.

1.2.1

Added

• Holiday Piton, Holiday Rebar, and Holiday Rope Rebar start-of-run trinkets — Christmas/Chimney variants of the existing climbing-item starters. Cryo-blue titles, route into the Chimney bucket in the picker.

1.2.0

Vanilla picker is now content-rich out of the box: every vanilla perk shows up as a Trinket or Binding, and most vanilla items show up as start-of-run grants.

Added

• Every vanilla Perk is now mirrored into the picker as either a Trinket (beneficial) or Binding (gameplay change), with category-tinted title colors.
• Vanilla tools as one-pick Trinkets (Cryo-Gun, Flare Gun, Flashlight, Wrench, Scanner) — mutex-locked so only one tool starts the run.
• Vanilla artifacts as one-pick Trinkets (Glove, Remote, Spear, Timepiece, Translocator) — mutex-locked.
• Vanilla consumables as stackable Trinkets, max 12 each (Blink Eye, Canned Food, Delta-0052, Food Bar, Grub, Injector, Inoculator, Lemon Roach, Milk, Pills, Hot Cocoa, Cookie, Candy Cauldron).
• Vanilla climbing items as stackable Trinkets, max 12 each (Rope Rebar, Explosive Rebar, Rope, Auto Piton, Brick, Piton, Rebar).
• Vanilla misc / Other items as stackable Trinkets, max 12 each (Flare, Gold/Platinum/Ruby Roach, Floppy Disks T1–T3).
• New No Hammer binding: bans the starting hammer + any world-spawned hammer for the run.
• Stack-count overlay on stackable trinkets — left-click adds a stack, right-click removes one.
• Picker scroll on the trinket and binding grids so the bigger entry list still fits.
• Picker ordering is now bucketed: vanilla originals first, external mods next, framework-added entries last (sub-sorted by Vanilla → Halloween/Parasite → Christmas/Chimney update, then category, then grey-then-colored, then tier).

API

• Public TrinketRegistry.Bucket and Category enums for mods that want to slot themselves into the framework's ordering.

1.1.0

Picker now appears in every gamemode — Challenge, Parasite, and any future modes — and every vanilla trinket / binding shows up too.

1.0.0

Initial release.

Added

• Public TrinketRegistry API for mods to register custom Trinkets (run-start modifiers) and Bindings (run-start modifiers with stronger gameplay effects).
• Trinkets and Bindings registered via this framework appear in the run-start picker on Fresh Game.
• Per-trinket itemsToGrantFactory callback runs at gamemode start to hand the player starter items.
• Custom icons, custom display names, custom descriptions, and custom title-color tags are all supported.

Notes

• This mod is a library. It does nothing on its own.