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 — 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:

Trink