使用 BepInEx 在 Valheim 1.0-1.0.16 上恢复 Steam 成就进度。保留原版作弊和官方绕过逻辑，同时忽略 Game.isModded。

《英灵神殿》1.0-1.0.16 :: 模组检测与成就系统架构

《英灵神殿》1.0.x Steam成就进度的技术分析、运行时解耦与验证套件

---

📌 概述

支持的遊戲版本：Valheim 1.0.0 至 1.0.16。最新執行階段驗證：1.0.16，於 2026-09-26。 构建、Harmony目标审计、隔离启动日志、包验证和程序集哈希均记录在 舰队兼容性证明.

在《英灵神殿》1.0版本（深层北境/灰烬之地）发布期间，官方社区更新提到：

我们了解到，在游玩模组时无法获得成就。

1.0.5版本运行铁门的完整 成就是否作弊过() 仅在临时屏蔽时实施 已安装模组。这样可以在不将这些规则复制到模组中的情况下，保留1.0.16的物品、世界、开发者命令、缓存和官方绕过规则。

对于使用客户端便利性插件（如物品栏管理、制作界面、视角调整或管理工具）的玩家和服务器社区而言，该政策意外导致了Steam成就进度的抑制。

该仓库提供了开源的技术解析与解决方案：

1. 字节码根因分析：检查反编译后的C# IL，以查明原因 游戏是否已安装模组 导致成就无法解锁。
2. 交互式建筑模型：一个结构化系统流程，经由 档案化 展示确切的引擎评估路径。
3. 轻量级运行时插件（IsModded.dll)： 一个11.8 KB的Harmony补丁，用于解耦 是否有模组 在保持真正的作弊防护措施有效的同时，脱离作弊验证。
4. 模组作者的嵌入代码片段：一个15行的即插即用Harmony补丁，作者可直接将其整合到现有模组中，无需单独的插件。
5. 自动验证套件：独立命令行界面可执行文件（验证是否已安装模组.exe）、PowerShell 验证脚本，以及游戏内实时控制台命令（已修改) 检查引擎字节码并验证运行时状态。

---

🗺️ 系统架构

下面的交互流程直接根据正式规范编译而成，使用 档案化:

交互式查看器：开启 docs/valheim-ismodded.html (实时网页预览在任意浏览器中打开以查看完整交互模型：

• 引导视图: 端到端解锁流程, 原版模组锁定, 模组前缀解耦，和 零开销验证.
• 导航： 动态平移、缩放、组件元数据检查，以及深色/浅色主题切换。
• 源文件与矢量图导出：规格说明： docs/valheim-ismodded.architecture.json 以及独立向量 资源/建筑-美化.svg.

---

📥 安装（玩家版）

在运行BepInEx时恢复Steam成就进度：

1. 下载 Modded.dll （11.8 KB）来自仓库 dist/ 目录、GitHub Releases 或 Thunderstore。
2. 将文件放入你的 Valheim BepInEx 插件文件夹：

   <Valheim-Directory>/BepInEx/plugins/IsModded.dll
   

3. 正常启动游戏。达成里程碑时，Steam 成就将自动记录。

---

🔬 技术分析：英灵神殿 1.0 中的根本原因

在模组环境下成就被抑制，并非由反作弊引擎或文件完整性扫描所驱动，而是源于一个遗留的遥测标志与1.0成就判定逻辑的耦合。

1. 该 是否已安装模组 遥测字段

在《英灵神殿》的早期版本中，Iron Gate引入了一个静态布尔字段，位于 游戏.cs 旨在协助客户支持分流：

// Valheim assembly_valheim.dll :: Game.cs public static bool isModded = false; // 代码库中的注释： // “虽然我们目前并不正式支持 Valheim 的模组， // 但我们请求您在自己的模组中将以下 isModded 值设为 true。 // 这将在菜单中显示一小段文字，告知玩家其游戏已安装模组， // 并帮助我们解决支持问题。感谢您的协助！”

2. BepInEx 自动标记

为配合开发者支持指南，BepInEx加载器实现了一个自动反射辅助工具（将模组加载状态设为已修改设置 Game.isModded = true 每当 BepInEx 初始化时。

3. 英灵神殿1.0成就评价

随着《英灵神殿》1.0版本引入Steam成就系统，一种内部方法 成就是否作弊过？ 被添加用于评估会话资格。除了测试控制台作弊标志、世界修改器和生成物品外，回退条件还会评估 游戏是否已安装模组:

// Valheim 1.0 assembly_valheim.dll :: Achievements.cs public static bool IsCheatedAtAll() { if (Time.frameCount == Achievements.m_cheatCheckFrame) return Achievements.m_cheatCheckCache; Achievements.m_cheatCheckFrame = Time.frameCount; // 检查玩家是否使用了控制台开发者指令 bool profileCheated = (Game.instance != null) && Game.instance.GetPlayerProfile().m_usedCheats; // 检查服务器世界是否有作弊修正（被动敌人等） bool worldCheated = Achievements.IsWorldCheated(); // 检查玩家背包中是否生成了物品 bool itemCheated = (Player.m_localPlayer != null) && Player.m_localPlayer.GetInventory().AnyCheatedItem(); if (profileCheated || worldCheated || itemCheated) { Achievements.m_cheatCheckCache = true; } else { // 直接将 Game.isModded 作为作弊条件进行评估： Achievements.m_cheatCheckCache = Game.isModded; } return Achievements.m_cheatCheckCache; }

4. 对进程的下游影响

每当达成进度里程碑时（例如击败首领、制作、采集）， 玩家档案.增加统计数据() 评估资格门槛：

如果（！成就.可以获取成就（假））返回；

因为 是否安装模组 是 真, 是否作弊过() 返回 真，造成 无法获取成就（） 返回 假属性增量被静默丢弃，阻止了对 Steamworks.SteamUserStats.设置成就().

---

🛠️ 实现：作用域遥测掩码

模组 在以下对象上安装轻量级 Harmony 前缀、后缀和终结器： 成就.是否作弊过()。该前缀仅屏蔽加载器遥测标志，原始游戏方法仍会评估每个原版规则，而后缀/终结器即使方法抛出异常也会恢复该标志：

[HarmonyPatch(typeof(Achievements), nameof(Achievements.IsCheatedAtAll))] static class Achievements_IsCheatedAtAll_Patch { private struct State { internal bool Applied; internal bool Original; } [HarmonyPrefix] static void Prefix(out State __state) { __state = new State { Applied = true, Original = Game.isModded }; Game.isModded = false; } [HarmonyPostfix] static void Postfix(State __state) => Game.isModded = __state.Original; }

对于加载了便利性模组的正常玩家， 是否作弊() 计算结果为 假，允许 无法获取成就（） 返回 真 并启用标准Steam成就触发功能。

---

🧪 验证协议

提供三种独立验证方式，用于审查并确认成就获取资格：

---

方法一：独立字节码验证器（验证-是否为模组版.exe)

一个零依赖的命令行工具，基于 Mono.Cecil。奔跑 dist/Verify-IsModded.exe 或 工具/Verify-IsModded.ps1:

它实时反编译本地游戏程序集，检测针对 是否已安装模组，并提供了一个执行矩阵：

================================================================================ Valheim 1.0 :: isModded 与成就完整性验证器 ================================================================================ [+] Valheim 目录 : C:\Program Files (x86)\Steam\steamapps\common\Valheim [+] Valheim 版本 : 1.0.15 (最新验证构建) --- [步骤 1: 检查 VALHEIM 1.0.15 字节码] -------------------------------- [通过] 找到方法: Achievements.IsCheatedAtAll() 正在扫描指令流以查找 Game.isModded 访问... -> IL_005B: ldsfld Game::isModded [已确认] Valheim 1.0.15 在评估作弊时直接检查 Game.isModded！ 如果 Game.isModded 为 True，引擎将会话评估为已作弊，这会强制 CanGetAchievements() 返回 FALSE。 --- [步骤 2: 检查 BEPINEX 链式加载器] ---------------------------------- [通过] 找到 BepInEx 方法: Chainloader.SetIsModdedTrue() -> BepInEx 在启动时自动将 Game.isModded 设置为 True。 --- [步骤 3: 检查 ISMODDED 插件状态] -------------------------------- [通过] 检测到成就绕过插件: IsModded.dll 位置: C:\Program Files (x86)\Steam\steamapps\common\Valheim\BepInEx\plugins\IsModded.dll [通过] 已验证针对 Achievements.IsCheatedAtAll 的 Harmony 前缀钩子 --- [步骤 4: 日志文件检查] --------------------------------------------- [通过] 在 LogOutput.log 中找到: [Info : BepInEx] Loading [IsModded 1.0.4] ================================================================================ 最终判定 ================================================================================ 模拟游戏内成就评估（使用模组的合法玩家）: 条件 | 无 IsModded | 有 IsModded -----------------------------+---------------------------+----------------------- BepInEx 运行中 | 是 (Game.isModded=True) | 是 (Game.isModded=True) 角色 Devcommands | 否 | 否 世界作弊修改器 | 否 | 否 物品栏作弊物品 | 否 | 否 -----------------------------+---------------------------+----------------------- Achievements.IsCheatedAtAll | TRUE（将模组视为作弊） | FALSE（忽略 isModded！） Achievements.CanGet | FALSE [已阻止] | TRUE [已恢复！] Steamworks.Unlock() | 从未调用 | 在进度达成时调用 -----------------------------+---------------------------+----------------------- >>> 状态: 就绪！您的配置已设置为可在使用模组的情况下获得 Steam 成就。

---

方法二：游戏内实时运行审核（已安装模组)

1. 游戏内，按 F5 打开英灵神殿控制台。
2. 输入审计命令：

   是否已安装模组
   

3. 引擎输出实时诊断报告，显示：
   • 状态 是否安装模组.
   • 预计原版评估（已阻止）。
   • 使用补丁进行活动运行时评估（符合条件且处于活动状态）。

---

方法三：游戏内进度测试

1. 在全新的本地世界中创建一个临时角色。
2. 收集第一块石头或木树枝（E）。
3. 初始进度统计将触发，同时激活 Steam 成就通知。

---

👨💻 整合指南（面向模组作者）

希望将此解耦逻辑直接捆绑到现有插件中的模组开发者，应使用相同的限定作用域掩码模式。参见 src/Patches/AchievementsPatch.cs; 生产版本包含配置处理和 Harmony 终结器，因此 已安装模组 如果原版评估抛出异常，则恢复。

使用HarmonyLib；[HarmonyPatch(typeof(Achievements), nameof(Achievements.IsCheatedAtAll))] public static class DecoupleModdedAchievementsPatch { public struct State { public bool Applied; public bool Original; } [HarmonyPrefix] public static void Prefix(out State __state) { __state = new State { Applied = true, Original = Game.isModded }; Game.isModded = false; } [HarmonyPostfix] public static void Postfix(State __state) => Game.isModded = __state.Original; [HarmonyFinalizer] public static Exception Finalizer(Exception error, State __state) { Game.isModded = __state.Original; return error; } }

---

⚙️ 配置

配置通过以下方式管理 Valheim/BepInEx/config/djc.valheim.ismodded.cfg:

[General] ## 启用在使用 BepInEx / 加载模组游玩时获得成就。 # 设置类型：Boolean # 默认值：true AllowWhileModded = true ## 可选：即使在此角色或世界上使用过 devcommands / 作弊，也启用在获得成就。 # 设置类型：Boolean # 默认值：false AllowWithDevcommands = false [Visual] ## 可选：隐藏主菜单上的“Modded”水印。 # 设置类型：Boolean # 默认值：false HideModdedWatermark = false

---

❓ 技术常见问题

这与Valve反作弊系统（VAC）有交互吗？

不。 《英灵神殿》未使用 Valve 反作弊系统。成就同步通过标准的客户端 Steamworks API 处理（SteamUserStats.设置成就）。

这会禁用devcommands的作弊检测吗？

不。 默认情况下（允许使用开发者命令 = false）、使用开发者控制台作弊的角色或世界（开发命令, 神, 生成) 根据原版规则仍无法获得成就。此补丁仅将 游戏已安装模组 旗帜。

这个功能在专用服务器上能用吗？

是。 成就由客户端评估，并直接从本地客户端同步至 Steamworks。

---

📜 许可协议

本项目遵循以下许可协议发布： MIT 许可证允许的用途包括再分发、修改以及直接嵌入第三方插件。