CiCi's Trinket & Binding Framework

A library mod for White Knuckle. Lets other mods register custom Trinkets (run-start picks) and Bindings (run-start picks with stronger gameplay effects) so they appear in the picker on Fresh Game.

v1.4.0 also bundles 13 mutator modes from Nebulaetrix's MoreMutators — Devil Daggers, Marathon Mode, Markiplier%, Zen, Glass Knuckle, and more, available as toggles on the Campaign settings panel.

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.

For modders

1. Add a dependency

Reference the framework's DLL in your .csproj, then mark your plugin so BepInEx loads us first:

using BepInEx;
using TrinketAndBindingFramework;
using UnityEngine;
using System.Collections.Generic;

[BepInPlugin("com.yourmod.example", "Example Mod", "1.0.0")]
[BepInDependency(TrinketAndBindingFramework.Plugin.GUID)]
public class ExampleMod : BaseUnityPlugin
{
    private void Awake()
    {
        // Register here.
    }
}

2. Register a Trinket

A Trinket is a small starter pick — usually a starter item or perk. Examples: Wall Runner (climbing axes), Sawed-Off (shotgun + shells).

TrinketRegistry.RegisterTrinket(
    id:                   "yourmod_my_trinket",        // unique string
    title:                "My Trinket",                 // shown in picker
    description:          "What it does in one line.",
    flavorText:           "Optional italic tagline under the description.",
    cost:                 1,                            // picker slot cost
    icon:                 myIconSprite,                 // 32x32-ish Sprite
    itemsToGrantFactory:  () => new List<Item_Object> { myItemTemplate });

All parameters except id, title, description are optional.

3. Register a Binding

A Binding is a run-modifier — usually changes gameplay rules and increases score. Examples: Alpine Purist (climbing tools banned, axes red & breakable), Infestation (more enemies).

TrinketRegistry.RegisterBinding(
    id:                    "yourmod_my_binding",
    title:                 "My Binding",
    description:           "Makes the run harder in some way.",
    flavorText:            "Optional flavor.",
    cost:                  1,
    scoreMultiplierBonus:  0.5f,                       // +0.5x run score
    scoreBonus:            0f,                         // flat bonus
    icon:                  myIconSprite);

Same signature as RegisterTrinket — under the hood the framework just flags isBinding=true and tints the picker title differently.

4. Grant starter items

itemsToGrantFactory runs at run start (not at registration), so you can lazy-build your item templates without worrying about asset-manager readiness at Awake:

itemsToGrantFactory: () =>
{
    try { EnsureMyItemTemplate(); } catch { }
    if (MyItemTemplate == null) return new List<Item_Object>();
    return new List<Item_Object> { MyItemTemplate, MyItemTemplate };  // 2 copies
}

The returned Item_Object instances are template prefabs — vanilla clones them for the player's bag.

5. Mutex groups (mutually-exclusive picks)

When two of your trinkets shouldn't both be selected (e.g. different starter weapon variants), wire them into a mutex group:

TrinketRegistry.RegisterTrinket(id: "yourmod_sword", title: "Sword", ...);
TrinketRegistry.RegisterTrinket(id: "yourmod_axe",   title: "Axe",   ...);
TrinketRegistry.RegisterTrinket(id: "yourmod_bow",   title: "Bow",   ...);

TrinketRegistry.RegisterMutexGroup(
    groupId: "yourmod_starting_weapon",
    "yourmod_sword", "yourmod_axe", "yourmod_bow");

The picker auto-deselects the others when one is chosen.

6. Lookup a registered runtime trinket

If you need the live Trinket ScriptableObject for an id you registered (e.g. to check selection state):

var rt = TrinketRegistry.GetRuntimeTrinket("yourmod_my_trinket");
if (rt != null) { /* ... */ }

Working examples in the wild

• CiCi's Climbing Axes — Wall Runner (trinket), Alpine Purist (binding), Free Climber (trinket), all in [Plugin.cs lines 200-250](also on Thunderstore).
• CiCi's Pioneer's Shotgun — Sawed-Off (trinket), Infestation (binding).

Compatibility

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

Changelog

2.1.3

Added

• Subtle "CiCi's Trinkets & Bindings Framework Menu — Made & Designed by: Li-0" credit line below the gamemode picker panel. Grey and unobtrusive.

2.1.2

Fixed

• Mass Damper now disables leaderboards when selected in endless modes.

2.1.1

Fixed

• Picker description scroll now uses a constant pixels/second rate (12 px/s) instead of a fixed total-time. Long descriptions no longer accelerate and stay readable at the same pace as short ones. Floor at 3s so very short overflows don't snap past.
• Top/bottom pauses bumped (1.5s / 1.0s) so there's more time to start reading before the scroll kicks in.

2.1.0

Added — Collapsible sections in the picker and gamemode-settings UI

Both pickers and the gamemode-settings panel are now organized into nested, collapsible sections. Click a section header to fold/unfold it; right-click any group header to force-expand it and everything beneath. Open/closed state persists per-section across runs (saved to BepInEx/config/cici_framework_sections.json).

Trinket & Binding pickers auto-classify each entry by source:

• White Knuckle — vanilla content, further split into Vanilla / Parasite / Chimney / Misc buckets, with Vanilla and Chimney further split into Trinkets / Items / Perks by category. Section headers are tinted to match each bucket's in-game color (pink/red for Vanilla matching the scrollbar pulse, dark green for Parasite, cryo-blue for Chimney).
• CiCi's Trinkets / Bindings — gold header. Sub-leaves per CiCi mod (Trinket & Binding Framework, Climbing Axes, Shotgun, Lidar Vision, Fake Wand, …) detected automatically from any com.cicismods.* plugin GUID.
• Modded — non-CiCi external mods, one sub-leaf per mod, labeled with the mod's BepInPlugin display name.

Gamemode settings panel uses the same shape: Vanilla / CiCi's Modes / Modded.

Each header pulses with a soft brightness oscillation, hover-scales slightly, and plays the vanilla UI hover/click sounds. Auto-detection happens at registration time by stack-walking inside RegisterTrinket / RegisterBinding / CustomModeRegistry.Register — consumer mods don't need to do anything.

Other

• Picker description panel pauses (1.5s → 0.75s) shortened so descriptions scroll into motion sooner.
• Bindings picker now reflows to a max of 4 columns and gracefully drops to fewer when the panel is narrow.

2.0.0

Breaking: mutators are no longer bundled. They now live in a separate mod, NebulaetrixMutators, maintained directly by Nebulaetrix. Install that mod to keep all 13 modes (Devil Daggers, Marathon, Zen, etc.) available on Campaign's settings panel.

Added — Public CustomModeRegistry API

Other mods can now register their own custom gamemode modes through a public API, the same way they already register trinkets and bindings.

using TrinketAndBindingFramework;

// In your Plugin's Awake:
CustomModeRegistry.Register(
    id: "MyMode",
    displayName: "My Custom Mode",
    description: "What this mode does",
    difficulty: CustomModeRegistry.Difficulty.Hard,
    onToggle: enabled => { MyMode.Enabled = enabled; },
    exclusiveSettingIds: null,
    disablesLeaderboards: true,
    hoverCreditText: "Mode by YourName"
);
CustomModeRegistry.RegisterCombo(new[] { "MyMode", "OtherMode" }, "<color=#ff9500>Combo Name</color>");
CustomModeRegistry.RegisterDisabledLock("WIPMode", "WIP");
CustomModeRegistry.RegisterMutualLink("ModeA", "ModeB");
CustomModeRegistry.RegisterGamemodeAlias("GM_Level_Tester", "Campaign");
CustomModeRegistry.InjectIntoGamemode("Campaign");

The framework handles the picker UI (toggle visual, mutex enforcement, difficulty-colored title, hover-credit text), leaderboard gating, combo display in the green pill list, and save-data persistence. Mode logic stays entirely in your mod.

Removed

• All 13 mutator mode classes and their Harmony patches moved to NebulaetrixMutators.
• more_mutators_assets AssetBundle moved to NebulaetrixMutators.
• Removed MutatorRegistry, MutatorPickerIntegration, MutatorCredit, MarathonBackwardLink, and related types — replaced by the generic CustomModeRegistry / CustomModePickerIntegration / CustomModeCredit / CustomModeLinks infrastructure.

1.4.0

13 Mutator Modes from Nebulaetrix's MoreMutators (v1.1.2) are now live on Campaign's settings panel. Marathon assembles a custom ~110-level Campaign chain end-to-end, mutator combos get fun custom names, and the trinket picker auto-scrolls long descriptions.

Huge thanks to Nebulaetrix for letting me bring MoreMutators content into this framework.

Added — Mutator Modes (on Campaign's settings panel)

• Devil Daggers (Easy) — shoot rebar from your hands. Hold the fire button (~0.1s) to launch. Combine with Volatile for explosive rebar.
• Zen Mode (Easy) — no mass, bloodbugs, teeth, turrets, vent things. HP capped low.
• Zero-G (Easy) — gravity off, drag reduced.
• Volatile (Medium) — random explosions trigger around you.
• Markiplier% (Medium) — bag inventory disabled.
• Amputated (Hard) — right hand locked, upgrade consoles destroyed.
• Baby Knuckle (Hard) — 50% scale, tweaked hold/jump/speed, weapon recoil.
• Disoriented (Hard) — camera flipped 180°.
• Glass Knuckle (Hard) — 0.1 max HP, one-shot to anything.
• Paraplegic (Hard) — jump disabled.
• Marathon Mode (Extreme) — full ~110-level Campaign chain end-to-end, silos → pipeworks → habitation → abyss (no Chimney / LadderWarp / Foundations clutter). Within-family chunks reshuffle per run.
• Wind Tunnel (Extreme) — constant downward blizzard.
• Backward (elkcunK etihW) — staged as WIP, locked in the picker for now.

Added — Picker UX

• Auto-scrolling description box. Long trinket / binding descriptions now bob top → bottom → top with pauses inside a masked viewport. Short descriptions (e.g. Carabiner) skip the wrapper entirely so the text shows exactly like vanilla.
• Per-mutator credit hover. Hovering any of the 13 ported mutators shows "Custom mode originally made by Nebulaetrix (MoreMutators Mod)" under the settings panel.

Removed

• Helping Hand mutator (player can already give themselves perks through the picker).

1.3.1

Fixed

• Linux install: archive was packed with backslash path separators, which Linux extractors treated as part of the filename instead of as folders. Repackaged with spec-compliant forward slashes so the mod installs cleanly without manual file moves.

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.