AnanLa's Quenching Guarantee

一个 Vintage Story 模组，为金属淬火增加保底机制，降低反复烧铁搓工具的精神损耗。

A Vintage Story mod that adds a pity/quarantee system to metal quenching, reducing the frustration of repeated tool crafting.

该模组使用 AI（Claude）辅助开发 / This mod was developed with AI (Claude) assistance.

• 每次淬火失败时计数器 +1

• 每次淬火成功时计数器归零

• 当计数器 ≥ 保底次数时，下一次淬火必定成功

• Counter +1 on each failed quench

• Counter reset to 0 on each successful quench

• When counter ≥ guarantee count, next quench is guaranteed to succeed

模组启动后自动生成两个配置文件：

Two config files are auto-generated after first launch:

服务端配置（控制保底逻辑） — ModConfig/ananlaquenchingguarantee_server_config.json
Server config (controls guarantee logic):

{
    "GuaranteeCount": 3,
    // 保底基数 / Base guarantee count
    "Mode": "Fixed",
    // 动态保底模式 / Dynamic mode:
    //   Fixed       = 固定模式，GuaranteeCount 恒定不变（默认 / default）
    //   Phased      = 阶段禁用，淬火次数达 Param 后禁用保底 / Disable guarantee after Param total quenches
    //   Progressive = 递增模式，保底阈值随淬火次数递增 / Threshold increases with total quenches
    //   BreakChance = 破损概率，破碎概率达 Param 后禁用保底 / Disable when shatter chance ≥ Param
    "Param": 20.0
    // 模式参数 / Mode parameter
    //   Phased:      淬火次数上限（示例 20） / Max total quenches (e.g. 20)
    //   Progressive: 递增步长（示例 1） / Increment step (e.g. 1)
    //   BreakChance: 破碎概率阈值（示例 1.0 = 100%） / Shatter chance threshold (e.g. 1.0 = 100%)
}

客户端配置（控制消息显示） — ModConfig/ananlaquenchingguarantee_client_config.json
Client config (controls message display):

{
    "GuaranteePrompt": true,
    // 是否显示提示消息 / Show prompt messages
    "DisplayMode": "BottomError"
    // 显示风格 / Display style:
    // BottomError = 底部提示栏（默认）/ bottom error bar (default)
    // Chat = 聊天栏 / chat bar
    // Discovery = 中央发现动画 / center discovery animation
}

// 固定模式：连续失败 3 次后保底 / Fixed: guaranteed after 3 consecutive failures
{ "GuaranteeCount": 3, "Mode": "Fixed" }

// 阶段禁用：淬火 20 次后不再保底 / Phased: disable guarantee after 20 total quenches
{ "GuaranteeCount": 2, "Mode": "Phased", "Param": 20 }

// 递增模式：保底阈值 = 3 + 1 × 淬火数，越淬越难 / Progressive: threshold = 3 + 1 × quenches
{ "GuaranteeCount": 3, "Mode": "Progressive", "Param": 1 }

// 破损概率：破碎概率 100% 后不再保底 / BreakChance: disable when shatter chance reaches 100%
{ "GuaranteeCount": 3, "Mode": "BreakChance", "Param": 1.0 }

开启 GuaranteePrompt 后显示：

When GuaranteePrompt is enabled:

消息可通过 DisplayMode 切换显示风格（BottomError 底部提示栏 / Chat 聊天栏 / Discovery 中央发现动画）。

Message display style can be toggled via DisplayMode (BottomError / Chat / Discovery).

• 每个玩家独立计数，存储在玩家实体数据中

• 随玩家存档自动保存，不会丢失

• Each player has an independent counter stored in their entity attributes

• Saved with the player's save data, persists across sessions

使用 Harmony 补丁拦截 CollectibleBehaviorQuenchable 的淬火流程：

Uses Harmony patches to intercept the quench logic in CollectibleBehaviorQuenchable:

1. 破碎决策前（Prefix）：根据模式计算有效保底次数，比较当前失败数。触发则设 willbreak=false 跳过碎裂；动态禁用（Phased/BreakChance 达阈值）则不干预

2. 碎裂发生时（Postfix）：失败计数 +1，根据模式发送不同格式的失败通知

3. 淬火完成时（trySettleWorkItem Postfix）：淬火成功时计数归零，清理临时标记

4. Before break check (Prefix): Calculate effective guarantee by mode, compare failures. On trigger: set willbreak=false to prevent shatter; on dynamic disable (Phased/BreakChance threshold): no intervention

5. On break (Postfix): Increment failure counter, send mode-specific fail notification

6. On success (trySettleWorkItem Postfix): Reset counter to 0, clean temp attributes

• 保底机制仅对主动桶淬（手持热金属右键水桶）生效

• 将物品丢入水中自然冷却不会触发保底（也无法刷淬火次数）

• 这是有意设计：避免玩家批量丢入水中刷失败计数，保持机制简洁

• Only affects active bucket quenching (right-clicking a water bucket with hot metal)

• Dropping items into water to cool naturally does NOT trigger the guarantee (and cannot be used to farm successes)

• This is intentional: prevents players from farming failures by batch-dropping items into water, keeping the mechanic simple

同时安装 AnanLa的淬火预测 时，若同一帧触发保底通知与预测预警，两条消息将合并为两行显示（伪同屏），不再互相覆盖。

When installed alongside AnanLa's Quenching Prediction, if a guarantee notification and a prediction warning fire in the same frame, the two messages merge into two lines (pseudo same-screen) instead of overwriting each other.

• 零依赖：两个模组互不引用，可独立安装或同时安装 / Zero dependency: both mods work independently or together
• 合并条件：双方客户端使用相同的显示风格（DisplayMode）/ Merge condition: both clients use the same DisplayMode