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.3.0

Polished picker UX: leaderboard handling is now per-selection, slot indicator handles stacked items, scrolling feels smooth, and each grid has its own pulsing scrollbar.

Added

• Centralized leaderboard gating. The picker now disables leaderboards only when the player has actually picked something that warrants it, and re-enables them when those selections are cleared. A red LEADERBOARDS DISABLED label appears at the top of the picker while disabling selections are active.
  • In Campaign, Chimney, and Endless modes (which natively shipped the picker): only framework-pooled entries, external mod entries, and Contortions Totem disable leaderboards. Picking only the vanilla picker entries (Carabiner, Iron Knuckle, Pitons & Beans, etc.) keeps leaderboards on.
  • In every other gamemode (Challenge, Parasite, tutorials, dev): the picker still works, but any selection disables leaderboards.
• Stack-aware slot indicator. The pip bar at the top-right of the picker now counts each stack of a stackable trinket as one slot instead of one slot per trinket type. Stack a perk three times → three pips light up.
• Slot indicator overflow. Past 5 slots the bar shows a [+N] overflow indicator instead of growing off-screen.
• Smooth wheel scrolling. The picker's icon grids glide on a smooth-damp curve instead of snapping a fixed distance per wheel notch.
• Per-grid scrollbars with pulsing handles — magenta for trinkets, red for bindings — visible whenever the grid actually has overflow.

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.