CiCisTrinketAndBindingFramework

CiCi's Trinket & Binding Framework

A library mod for White Knuckle. Lets other mods register custom Trinkets (run-start picks), Bindings (run-start picks with stronger gameplay effects), and Custom Modes (gamemode-settings toggles like vanilla Hard Mode / Iron Knuckle) so they appear in the picker and the settings panel on Fresh Game.

Nebulaetrix's Mutators are temporarily back (with their permission), since their own mod has not been updated for the current game. You will find them in the Campaign settings panel under Modded > Nebulaetrix's Mutators. They will be removed again once Nebulaetrix's mod is back up. The framework exposes the CustomModeRegistry API so any mod can add its own modes the same way.

2.2.2 adds two modes for Parasite — Endless Parasite and SB12 Anomaly — in the Parasite settings panel, plus a Challenges window on the main menu with two challenges for them.

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

The framework exposes two independent registries:

• TrinketRegistry — register custom Trinkets and Bindings that appear in the picker on Fresh Game.
• CustomModeRegistry — register custom gamemode modes (toggles like vanilla Hard Mode / Iron Knuckle) that appear in the settings panel.

The two systems are unrelated — use one, the other, or both.

Setup (shared by both systems)

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()
    {
        // Trinket / binding / mode registration goes here.
    }
}

Trinkets & Bindings (TrinketRegistry)

The picker on Fresh Game lists every registered trinket and binding. The framework handles the UI (icon, title, description tint, mutex enforcement, pip cost), unlock bypass, item granting, and leaderboard gating. You register entries once at Awake.

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 { myItemTemplate });

All parameters except id, title, description are optional.

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.

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();
    return new List { MyItemTemplate, MyItemTemplate };  // 2 copies
}

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

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.

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) { /* ... */ }

Custom Modes (CustomModeRegistry)

The gamemode settings panel (the same one Hard Mode and Iron Knuckle live on) accepts custom toggles. Unlike trinkets they have no picker cost, no item grants, and no per-pick UI — each toggle is a checkbox that flips a static bool in your mod so your Harmony patches can branch on it. Examples: Devil Daggers, Marathon Mode, Glass Knuckle (all in NebulaetrixMutators).

The framework handles the toggle UI (difficulty color, hover credit, mutex enforcement, lock visuals), leaderboard gating, save persistence, and run-start flag sync. Mode logic stays entirely in your mod.

Register a Custom Mode

public static class MyMode
{
    public static bool Enabled;
    publi