WK_huoyan1231COMLib

White Knuckle BepInEx Common Library — Shared utilities for huoyan1231's White Knuckle mods
White Knuckle BepInEx 公共组件库 — huoyan1231 系列 White Knuckle Mod 的共享工具库

---

English

What is this?

WK_huoyan1231COMLib is a shared BepInEx library (plugin) used by huoyan1231's White Knuckle mods.
It provides common utilities that multiple mods can share, avoiding code duplication.

Features

Leaderboard Management

Ported and extended from WKUnlimitedTrinkets:

• Automatic leaderboard disabling: When any dependent mod requests it (e.g. when the Trinket budget is exceeded), the library sets CL_Leaderboard.WK_Leaderboard_Core.disableLeaderboards = true
• Multi-mod coordination: Multiple mods can register/unregister disable requests independently. Leaderboards are only restored when all requesters have cleared their requests.
• Auto-reset on run end: Leaderboard state is fully reset after each run (M_Gamemode.Finish) to prevent state leaking into subsequent runs.

Achievement Management (Steam)

Intercepts the game's single Steam-achievement upload entry point — CL_AchievementManager.GameAchievement.GetSteamAchievement() (which calls new Achievement(id).Trigger(true)) — via a Harmony prefix:

• Disable Steam achievement uploads without losing progress: When disabled, the Steam Trigger call is skipped, so your real Steam achievement profile is never polluted. In-game flagged state and XP are kept intact.
• Multi-mod coordination: Multiple mods can register/unregister disable requests independently. Steam uploads stay blocked until all requesters have cleared.
• Global hard switch: A separate SetSteamAchievementsDisabled(bool) flag for an unconditional, run-independent block.
• Auto-reset on run end: Per-run disable requests are cleared after each run (M_Gamemode.Finish); the global hard switch persists.

Why intercept GetSteamAchievement instead of SetAchievementValue?
SetAchievementValue also drives in-game progression (flags, XP, unlock animations). Blocking there would break the game. GetSteamAchievement is the only method that touches Steam, so intercepting it disables uploads while leaving gameplay untouched.

Public API for Mod Developers

Other mods can use the LeaderboardManager and AchievementManager static classes:

// Leaderboards — disable for this run (call from your StartFreshGamemode patch)
LeaderboardManager.DisableForThisRun("your.mod.guid");
LeaderboardManager.TryRestore("your.mod.guid");                 // re-enable your request
bool exceeded = LeaderboardManager.IsTrinketBudgetExceeded(trinketNamesList);

// Steam achievements — disable uploads for this run (keeps in-game progress)
AchievementManager.DisableForThisRun("your.mod.guid");
AchievementManager.TryRestore("your.mod.guid");                 // clear your request
AchievementManager.SetSteamAchievementsDisabled(true);          // unconditional global block
bool blocked = AchievementManager.IsSteamAchievementsDisabled(); // query current state

Installation

1. Ensure BepInEx 5.x is installed (via Gale, R2MM, or manual)
2. Place WK_huoyan1231COMLib.dll in:

   <Game Root>/BepInEx/plugins/
   

3. Install any dependent mods that require this library

Configuration

A config file will be generated in BepInEx/config/ after first run:

huoyan1231.whiteknuckle.comlib.cfg

Setting	Default	Description
EnableLeaderboardManagement	true	Set to false to disable all leaderboard management patches
EnableAchievementManagement	true	Set to false to disable the Steam achievement interception patches

Dependencies

Mod	Purpose
WKUnlimitedTrinkets	Leaderboard logic was ported from here

---

中文

这是什么？

WK_huoyan1231COMLib 是一个 BepInEx 共享库插件，供 huoyan1231 的 White Knuckle 系列 Mod 使用。
它提供多个 Mod 可复用的公共工具，避免重复实现相同逻辑。

功能

排行榜管理

从 WKUnlimitedTrinkets 移植并扩展：

• 自动禁用排行榜：当任意依赖本库的 Mod 发起请求时（例如 Trinket 预算超限），库会将 CL_Leaderboard.WK_Leaderboard_Core.disableLeaderboards 设为 true
• 多 Mod 协调：多个 Mod 可独立注册/撤销禁用请求；只有所有请求者都撤销后，排行榜才会恢复
• 局结束自动重置：每局结束（M_Gamemode.Finish）后完全重置排行榜状态，防止污染后续局

Steam 成就管理

通过 Harmony 前缀拦截游戏向 Steam 上传成就的唯一入口 —— CL_AchievementManager.GameAchievement.GetSteamAchievement()（其内部调用 new Achievement(id).Trigger(true)）：

• 禁用 Steam 成就上传但不丢失进度：禁用时跳过 Steam 的 Trigger 调用，真实 Steam 成就档案不会被污染；游戏内 flagged 状态与经验值保持不变
• 多 Mod 协调：多个 Mod 可独立注册/撤销禁用请求；只有所有请求者都撤销后，Steam 上传才会恢复
• 全局硬开关：另提供 SetSteamAchievementsDisabled(bool) 用于无条件、跨局常驻的禁用
• 局结束自动重置：每局结束（M_Gamemode.Finish）清除「按局」禁用请求；全局硬开关不受影响

为什么拦截 GetSteamAchievement 而不是 SetAchievementValue？
SetAchievementValue 同时驱动游戏内进度（flag、经验、解锁动画），拦截它会破坏游戏。GetSteamAchievement 是唯一触碰 Steam 的方法，拦截它即可在不影响游玩的前提下禁用上传。

面向 Mod 开发者的公共 API

其他 Mod 可使用 LeaderboardManager 与 AchievementManager 静态类：

// 排行榜 —— 本局禁用（在你的 StartFreshGamemode Patch 中调用）
LeaderboardManager.DisableForThisRun("your.mod.guid");
LeaderboardManager.TryRestore("your.mod.guid");                  // 撤销你的请求
bool exceeded = LeaderboardManager.IsTrinketBudgetExceeded(trinketNamesList);

// Steam 成就 —— 本局禁用上传（保留游戏内进度）
AchievementManager.DisableForThisRun("your.mod.guid");
AchievementManager.TryRestore("your.mod.guid");                  // 撤销你的请求
AchievementManager.SetSteamAchievementsDisabled(true);           // 无条件全局禁用
bool blocked = AchievementManager.IsSteamAchievementsDisabled(); // 查询当前状态

安装

1. 确保已安装 BepInEx 5.x（通过 Gale、R2MM 或手动安装）
2. 将 WK_huoyan1231COMLib.dll 放入：

   <游戏根目录>/BepInEx/plugins/
   

3. 安装依赖本库的其他 Mod

配置

首次运行后会在 BepInEx/config/ 生成配置文件：

huoyan1231.whiteknuckle.comlib.cfg

配置项	默认值	说明
EnableLeaderboardManagement	true	设为 false 可禁用所有排行榜管理补丁
EnableAchievementManagement	true	设为 false 可禁用 Steam 成就拦截补丁

---

Build / 构建

Requires .NET SDK (>= 6.0) / 需要 .NET SDK (>= 6.0)

dotnet build WK_huoyan1231COMLib.csproj -c Release

Output / 输出：bin/Release/net471/WK_huoyan1231COMLib.dll

---

Origin / 代码来源

The leaderboard management logic is ported from WKUnlimitedTrinkets and extended to support multiple mod coordination.

排行榜管理逻辑从 WKUnlimitedTrinkets 移植而来，并扩展为支持多 Mod 协调的公共接口。

---

License / 许可证

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

本项目采用 GNU 通用公共许可证第三版 (GPL-3.0) 授权。

See LICENSE file for full text. / 完整许可证文本见 LICENSE 文件。

---

AI Generated Notice / AI 生成声明

This code was generated with assistance from AI (WorkBuddy).

• Purpose / 用途: White Knuckle BepInEx common library — leaderboard management (ported from WKUnlimitedTrinkets) and Steam achievement management (Harmony-intercepted GetSteamAchievement with a multi-mod callable disable API)
• Generated Date / 生成日期: 2026-04-25 (achievement management added 2026-07-09)

本代码在 AI（WorkBuddy）辅助下生成。所有代码经项目维护者审查。