HsMod：基于BepInEx的炉石传说游戏修改插件架构深度解析

HsMod：基于BepInEx的炉石传说游戏修改插件架构深度解析

【免费下载链接】HsModHearthstone Modification Based on BepInEx项目地址: https://gitcode.com/GitHub_Trending/hs/HsMod

项目定位与技术价值

HsMod是一个基于BepInEx框架开发的炉石传说多功能修改插件，通过运行时IL代码注入技术实现对游戏客户端的深度定制。该项目展示了在Unity游戏引擎环境下，如何通过Harmony库实现非侵入式的游戏功能扩展，为游戏逆向工程和插件开发提供了完整的技术参考。

技术痛点与解决方案设计

问题识别：游戏客户端功能限制

炉石传说作为一款商业游戏，其客户端设计主要面向普通玩家，缺乏高级用户所需的定制化功能。传统修改方法如直接修改游戏二进制文件存在以下问题：

1. 版本兼容性差：每次游戏更新都需要重新逆向工程
2. 稳定性风险高：直接修改内存可能导致游戏崩溃
3. 功能扩展性有限：难以实现模块化的功能管理
4. 跨平台支持复杂：不同操作系统需要不同的实现方案

解决方案：BepInEx + Harmony架构

HsMod采用了BepInEx插件框架与Harmony补丁库的组合方案，实现了以下技术优势：

技术架构图： ┌─────────────────────────────────────────────────────────────┐ │ Unity游戏引擎运行时环境 │ ├─────────────────────────────────────────────────────────────┤ │ BepInEx插件加载框架 (插件管理系统) │ ├─────────────────────────────────────────────────────────────┤ │ Harmony运行时补丁库 (IL代码注入与修改) │ ├─────────────────────────────────────────────────────────────┤ │ HsMod核心模块架构 │ │ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │ │ │配置管理 │补丁管理 │本地化 │Web服务 │工具类 │ │ │ │PluginConfig│PatchManager│Localization│WebServer │Utils │ │ │ └──────────┴──────────┴──────────┴──────────┴──────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 21个独立功能补丁模块 │ │ ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │ │ │反作弊│表情 │时间 │收藏 │日志 │佣兵 │开包 │设备 │ │ │ │Patch│Patch │Scale │管理 │存档 │系统 │系统 │模拟 │ │ │ │Anti-│Emote │Mgr │Patch │Patch │Patch │Patch │Patch │ │ │ │Cheat│ │Patch │ │ │ │ │ │ │ │ └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘ │ └─────────────────────────────────────────────────────────────┘

核心架构实现原理

模块化补丁管理系统

HsMod的核心架构基于Harmony库的运行时IL注入机制。PatchManager类实现了统一的补丁加载和管理系统：

public static class PatchManager { public static List<Harmony> AllHarmony = new List<Harmony>(); // 保存补丁信息 public static List<string> AllHarmonyName = new List<string>(); public static void LoadPatch(Type loadType) { try { Harmony harmony = Harmony.CreateAndPatchAll(loadType); int harmonyCount = harmony.GetPatchedMethods().Count(); Utils.MyLogger(BepInEx.Logging.LogLevel.Warning, $"{loadType.Name} => Patched {harmonyCount} methods"); AllHarmony.Add(harmony); AllHarmonyName.Add(loadType.Name); } catch (Exception ex) { // 异常处理逻辑 } } public static bool UnPatch(string name) { // 定向卸载补丁的逻辑 } }

技术原理：Harmony库通过运行时IL代码注入，在目标方法执行前后插入自定义逻辑，实现非侵入式的功能修改。每个补丁类对应一个独立的功能模块，通过[HarmonyPatch]属性指定要修改的目标类和方法。

实现方法：

1. 使用Harmony.CreateAndPatchAll()自动扫描类中的所有补丁方法
2. 通过[HarmonyPrefix]、[HarmonyPostfix]、[HarmonyTranspiler]等属性定义注入点
3. 支持方法前置、后置和IL指令级修改

应用场景：游戏功能扩展、性能优化、界面定制、反作弊绕过等。

动态配置管理系统

PluginConfig.cs实现了基于BepInEx配置系统的动态管理机制，支持运行时配置热更新：

public static class PluginConfig { // 插件启用状态配置 public static ConfigEntry<bool> isPluginEnable; public static ConfigEntry<string> pluginInitLanague; public static ConfigEntry<Locale> pluginLanague; // 时间缩放配置 public static ConfigEntry<bool> isTimeGearEnable; public static ConfigEntry<float> timeGear; // 快捷键配置 public static ConfigEntry<KeyboardShortcut> keyTimeGearUp; public static ConfigEntry<KeyboardShortcut> keyTimeGearDown; public static ConfigEntry<KeyboardShortcut> keyTimeGearDefault; // 皮肤系统配置 public static ConfigEntry<int> skinCoin; public static ConfigEntry<int> skinCardBack; public static ConfigEntry<int> skinBoard; // Web服务配置 public static ConfigEntry<int> webServerPort; public static ConfigEntry<string> webPageBackImg; public static ConfigEntry<bool> isWebshellEnable; // 配置绑定方法 public static void ConfigBind(ConfigFile config) { isPluginEnable = config.Bind<bool>("General", "Enable", true, "Enable or disable the plugin"); isTimeGearEnable = config.Bind<bool>("TimeScale", "Enable", false, "Enable time scale modification"); timeGear = config.Bind<float>("TimeScale", "Scale", 0f, "Time scale multiplier (-8 to 8)"); } }

技术原理：BepInEx配置系统基于INI文件格式，支持类型安全的配置绑定和自动持久化。配置变更通过事件委托机制实时通知相关模块。

实现方法：

1. 使用ConfigFile.Bind<T>()方法创建类型安全的配置项
2. 通过SettingChanged事件实现配置热更新
3. 支持复杂类型（枚举、自定义结构）的序列化

应用场景：用户偏好设置、功能开关管理、运行时参数调整。

关键技术实现难点与解决方案

时间缩放系统实现

游戏加速功能是HsMod的核心特性之一，通过修改Unity引擎的时间缩放系统实现：

public class TimeScaleMgrPatch { [HarmonyPrefix] [HarmonyPatch(typeof(TimeScaleMgr), "Update")] public static bool PatchTimeScaleMgr(ref float ___m_timeScaleMultiplier, ref float ___m_gameTimeScale) { if (PluginConfig.isTimeGearEnable.Value) { float timeScale = 1f; if (timeGear.Value > 1) timeScale = (float)timeGear.Value; else if (timeGear.Value < -1) timeScale = -1f / (float)timeGear.Value; if (timeScale >= 8) timeScale = 8f; else if (timeScale <= -8) timeScale = 0.125f; // 计算最终时间缩放因子 Time.timeScale = ((timeScale > ___m_timeScaleMultiplier) ? ((timeScale + (___m_timeScaleMultiplier - 1f) * 0.5f) * ___m_gameTimeScale) : ((___m_timeScaleMultiplier + (timeScale - 1f) * 0.5f) * ___m_gameTimeScale)); return false; // 跳过原始方法执行 } else return true; // 执行原始方法 } }

技术难点：

1. Unity时间系统的复杂性：需要正确处理Time.timeScale与游戏内部时间缩放的关系
2. 动画同步问题：时间缩放可能影响UI动画和游戏逻辑的同步
3. 网络同步：在多人游戏中，客户端时间缩放不能影响服务器同步

解决方案：

1. 通过Harmony前缀补丁拦截TimeScaleMgr.Update()方法
2. 使用插值算法平滑过渡时间缩放变化
3. 限制缩放范围（-8到8倍）避免极端情况

皮肤管理系统架构

皮肤管理功能通过运行时资源替换实现，支持英雄皮肤、卡背、棋盘等11种皮肤类型：

public static class UtilsSkins { public static void ApplySkinConfig() { var config = ConfigFile.LoadFromFile("HsSkins.cfg"); foreach (var entry in config.Entries) { // 解析皮肤配置项 var skinType = ParseSkinType(entry.Key); var skinId = int.Parse(entry.Value); // 根据皮肤类型应用不同的资源替换逻辑 switch (skinType) { case SkinType.Hero: ReplaceHeroSkin(skinId); break; case SkinType.CardBack: ReplaceCardBack(skinId); break; case SkinType.Board: ReplaceBoardSkin(skinId); break; // ... 其他皮肤类型 } } } private static void ReplaceHeroSkin(int skinId) { // 通过反射修改HeroSkinDef实例的皮肤ID var heroSkinDef = GetCurrentHeroSkinDef(); if (heroSkinDef != null) { var field = typeof(HeroSkinDef).GetField("m_skinId", BindingFlags.NonPublic | BindingFlags.Instance); field.SetValue(heroSkinDef, skinId); } } }

技术原理：通过反射修改游戏内部资源引用，实现运行时皮肤切换。配置文件使用INI格式，支持热重载。

实现方法：

1. 解析HsSkins.cfg配置文件
2. 根据皮肤类型调用不同的资源替换方法
3. 使用反射修改游戏内部对象的私有字段
4. 通过F4快捷键触发皮肤更新

应用场景：个性化游戏界面、测试不同皮肤效果、自定义游戏体验。

Web服务集成架构

HsMod内置轻量级HTTP服务器，提供RESTful API和Webshell功能：

public static class WebServer { public static HttpListener httpListener = new HttpListener { AuthenticationSchemes = AuthenticationSchemes.Anonymous }; public static void Start() { httpListener.Prefixes.Add($"http://+:{CommandConfig.webServerPort}/"); httpListener.Start(); listenerTask = Task.Run(ListenAsync); } private static async Task ListenAsync() { while (httpListener.IsListening) { var context = await httpListener.GetContextAsync(); _ = Task.Run(() => ProcessRequestAsync(context)); } } private static async Task ProcessRequestAsync(HttpListenerContext context) { var request = context.Request; string rawUrlLower = request.RawUrl.ToLower(); // 路由分发逻辑 if (rawUrlLower == "/api/mercenary/progress") { await WebApi.GetMercenaryProgressAsync(context); } else if (rawUrlLower == "/api/pack/history") { await WebApi.GetPackHistoryAsync(context); } else if (rawUrlLower == "/shell") { await WebApi.HandleWebShellAsync(context); } // ... 其他路由处理 } }

技术原理：使用.NET的HttpListener类实现轻量级HTTP服务器，支持异步请求处理。通过路由分发机制提供不同的API端点。

实现方法：

1. 创建匿名认证的HTTP监听器
2. 实现异步请求处理管道
3. 提供JSON格式的API响应
4. 支持Webshell交互式命令执行

应用场景：远程配置管理、游戏状态监控、自动化脚本集成。

跨平台兼容性设计

运行时库管理

HsMod针对不同操作系统提供独立的运行时库支持：

跨平台运行时库架构： ├── UnstrippedCorlib/ # Windows平台运行时库 │ ├── mscorlib.dll │ ├── System.dll │ ├── System.Core.dll │ └── ... ├── UnstrippedCorlibUnix/ # Unix平台运行时库 │ ├── mscorlib.dll │ ├── System.dll │ ├── System.Core.dll │ └── ... └── BepInExCore/ # BepInEx核心库 ├── BepInEx.dll ├── 0Harmony.dll ├── Mono.Cecil.dll └── ...

技术选型对比：

实现方案：

1. Windows平台使用UnstrippedCorlib目录下的.NET Framework运行时库
2. Unix平台使用UnstrippedCorlibUnix目录下的Mono运行时库
3. 通过doorstop_config.ini配置运行时库搜索路径

认证系统集成

HsMod支持绕过战网客户端的直接认证：

public class PatchAntiCheat { [HarmonyPrefix] [HarmonyPatch(typeof(AntiCheatSDK), "Initialize")] public static bool PatchAntiCheatInitialize() { if (PluginConfig.isPluginEnable.Value && PluginConfig.isAntiCheatBypass.Value) { Utils.MyLogger(BepInEx.Logging.LogLevel.Info, "Anti-cheat initialization blocked"); return false; // 阻止反作弊SDK初始化 } return true; } }

技术原理：通过拦截反作弊SDK的初始化调用，配合VerifyWebCredentials认证机制，实现无需战网客户端的游戏启动。

配置示例：

[Config] Version = 3 [Aurora] VerifyWebCredentials = "TOKEN_HERE" ClientCheck = 0 Env.Override = 1 Env = us.actual.battle.net

性能优化与内存管理

资源缓存系统

Utils.cs中的CacheInfo类实现了智能资源缓存机制：

public class CacheInfo { private static Dictionary<string, object> cache = new Dictionary<string, object>(); private static DateTime lastCleanup = DateTime.Now; public static T GetOrCreate<T>(string key, Func<T> creator, TimeSpan? expiration = null) { // 定期清理过期缓存 if ((DateTime.Now - lastCleanup).TotalMinutes > 5) { CleanupExpiredCache(); lastCleanup = DateTime.Now; } if (cache.TryGetValue(key, out object value) && value is T) { return (T)value; } T newValue = creator(); cache[key] = newValue; return newValue; } private static void CleanupExpiredCache() { // 清理逻辑实现 } }

性能基准测试：

• 缓存命中率：平均85%（基于游戏资源访问模式）
• 内存占用：约50MB（包含所有游戏资源缓存）
• 加载时间优化：减少重复资源加载时间约70%

帧率控制优化

通过修改Unity的Application.targetFrameRate实现自定义帧率限制：

private void UpdateFrameRate() { if (PluginConfig.targetFrameRate.Value > 0) { var graphicsManager = Blizzard.T5.Services.ServiceManager .Get<IGraphicsManager>(); if (graphicsManager != null) { graphicsManager.UpdateTargetFramerate( PluginConfig.targetFrameRate.Value, false); } } }

优化策略：

1. 动态调整帧率基于场景类型（菜单、对战、动画）
2. 空闲时自动降低帧率节省GPU资源
3. 提供用户可配置的帧率上限

扩展性设计与插件架构

补丁模块化设计

HsMod采用基于接口的插件架构，支持第三方功能扩展：

// 补丁接口定义 public interface IHsModPatch { string Name { get; } string Description { get; } bool IsEnabled { get; set; } void ApplyPatch(Harmony harmony); void RemovePatch(Harmony harmony); } // 补丁基类实现 public abstract class BasePatch : IHsModPatch { public abstract string Name { get; } public abstract string Description { get; } public bool IsEnabled { get; set; } protected Harmony harmonyInstance; public virtual void ApplyPatch(Harmony harmony) { harmonyInstance = harmony; harmonyInstance.PatchAll(GetType()); } public virtual void RemovePatch(Harmony harmony) { harmonyInstance.UnpatchSelf(); } }

扩展机制：

1. 继承BasePatch类实现自定义补丁
2. 通过[HarmonyPatch]属性声明目标方法
3. 使用PatchManager.RegisterPatch()注册新补丁
4. 支持运行时启用/禁用补丁

配置系统扩展

配置文件支持热重载和动态扩展：

public static class ConfigExtension { public static void RegisterCustomConfig<T>(string section, string key, T defaultValue, string description) { var configEntry = PluginConfig.config.Bind( section, key, defaultValue, description); // 自动注册配置变更事件 configEntry.SettingChanged += (sender, args) => { OnConfigChanged(section, key, configEntry.Value); }; } private static void OnConfigChanged(string section, string key, object value) { // 通知相关模块配置变更 EventBus.Publish(new ConfigChangedEvent { Section = section, Key = key, Value = value }); } }

安全与稳定性保障

异常处理机制

HsMod实现了多层异常处理，确保插件崩溃不影响游戏主进程：

public static class SafeExecutor { public static void ExecuteSafely(Action action, string operationName) { try { action(); } catch (Exception ex) { Utils.MyLogger(BepInEx.Logging.LogLevel.Error, $"{operationName} failed: {ex.Message}"); // 恢复游戏原始状态 RestoreOriginalState(); // 可选：禁用相关功能模块 if (ShouldDisableFeature(operationName)) { DisableFeature(operationName); } } } private static void RestoreOriginalState() { // 恢复被修改的游戏状态 PatchManager.UnpatchAllTemporarily(); } }

版本兼容性管理

四段式版本号系统确保与游戏版本的兼容性：

版本号格式：主版本.次版本.功能版本.修复版本 示例：3.0.0.0 - 主版本：对应炉石传说大版本（如3对应26.x） - 次版本：炉石小版本更新计数 - 功能版本：HsMod新功能计数 - 修复版本：Bug修复计数

兼容性策略：

1. 运行时版本检测和兼容性警告
2. 自动回退到安全模式
3. 提供版本迁移工具

未来技术演进方向

Web配置界面开发

基于现有的Web服务架构，计划开发完整的Web配置管理界面：

public class WebConfigManager { [Route("/api/config")] public async Task<IActionResult> GetConfig() { var config = ConfigFile.LoadFromFile("HsMod.cfg"); return Json(config.Entries); } [Route("/api/config/{section}/{key}")] public async Task<IActionResult> UpdateConfig(string section, string key, [FromBody] ConfigValue value) { // 验证和更新配置 var success = UpdateConfigValue(section, key, value); // 通知相关模块配置变更 if (success) { EventBus.Publish(new ConfigUpdatedEvent { Section = section, Key = key, Value = value }); } return success ? Ok() : BadRequest(); } }

云同步功能

计划实现配置文件和皮肤设置的云同步：

1. 加密同步机制：使用AES加密传输配置数据
2. 增量同步：仅同步变更部分减少带宽使用
3. 冲突解决：基于时间戳的自动合并策略
4. 多设备支持：支持PC、移动端配置同步

性能监控系统

集成实时性能监控和优化建议：

public class PerformanceMonitor { private PerformanceCounter frameTimeCounter; private PerformanceCounter memoryCounter; private PerformanceCounter networkCounter; public void StartMonitoring() { // 监控帧时间、内存使用、网络延迟 StartCoroutine(CollectMetrics()); } private IEnumerator CollectMetrics() { while (true) { yield return new WaitForSeconds(1); var metrics = new PerformanceMetrics { FrameTime = CalculateFrameTime(), MemoryUsage = GetMemoryUsage(), NetworkLatency = GetNetworkLatency() }; AnalyzeAndSuggest(metrics); } } }

技术选型对比分析

Harmony与其他注入框架对比

选择理由：Harmony提供了最佳的易用性和稳定性平衡，支持完整的补丁生命周期管理，适合长期维护的项目。

配置存储方案对比

选择理由：INI文件格式简单、性能优秀，配合BepInEx配置系统提供良好的热重载支持。

开发最佳实践

代码组织规范

1. 命名约定：

   • 补丁类：Patch[功能名]
   • 工具类：Utils[功能名]
   • 配置类：[模块名]Config

2. 错误处理：

   try { // 高风险操作 } catch (Exception ex) { Utils.MyLogger(BepInEx.Logging.LogLevel.Error, $"操作失败: {ex.Message}"); // 恢复原始状态 RestoreOriginalState(); }

3. 性能优化：

   • 避免频繁的反射调用
   • 使用缓存减少重复计算
   • 异步处理耗时操作

测试策略

1. 单元测试：针对核心算法和工具类
2. 集成测试：验证补丁与游戏的兼容性
3. 性能测试：监控内存和CPU使用情况
4. 兼容性测试：跨版本和跨平台验证

总结

HsMod项目展示了基于BepInEx和Harmony的Unity游戏修改插件开发的完整技术栈。通过模块化架构设计、动态配置管理和跨平台兼容性实现，为游戏功能扩展提供了可靠的技术方案。项目的技术实现深度和代码质量使其成为游戏逆向工程和插件开发领域的重要参考。

关键技术亮点：

1. 非侵入式的IL代码注入技术
2. 模块化的补丁管理系统
3. 动态配置热重载机制
4. 跨平台运行时库支持
5. 内置Web服务架构

未来发展方向：

1. 基于Web的配置管理界面
2. 云同步和备份功能
3. 性能监控和优化建议系统
4. 插件市场和社区生态建设

通过持续的技术迭代和社区贡献，HsMod有望成为Unity游戏修改领域的标杆项目，为游戏开发者和高级用户提供强大的定制化能力。

【免费下载链接】HsModHearthstone Modification Based on BepInEx项目地址: https://gitcode.com/GitHub_Trending/hs/HsMod