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