游戏文本替换工具开发：基于BepInEx与Harmony实现《边狱巴士公司》汉化自定义

在实际游戏本地化或社区汉化项目中，我们常常会遇到一个痛点：官方或某个汉化组的翻译版本，其用词、句式或风格可能不完全符合部分玩家的偏好。例如，某个角色名、技能名或特定术语的译法，可能会让一部分玩家感到“出戏”或“不顺眼”。手动查找替换游戏内所有文本不仅工程浩大，而且容易出错。针对《边狱巴士公司》这款游戏，结合其社区汉化（如“零协汉化”）的现状，实现一个灵活、兼容且自动化的文本替换方案，就成为了提升个人游戏体验的有效技术手段。本文将从一个实际开发者的角度，详细讲解如何构建一个用于《边狱巴士公司》的文本自动替换工具。整个过程将涵盖原理分析、环境准备、核心代码实现、与现有汉化（零协汉化）的兼容性处理，以及常见问题的排查路径。最终，你将获得一个能够根据自定义规则表，在游戏运行时动态替换指定文本的工具，实现真正的“翻译自由”。

1. 理解游戏文本替换的基本原理与挑战

在动手之前，我们必须清楚我们要修改的对象是什么，以及可能遇到的限制。

1.1 游戏文本的存储与加载方式

现代PC游戏的文本资源通常不会硬编码在程序里，而是存放在外部的资源文件中，如.json,.xml,.txt, 或特定封包格式（如.asset,.bundle）内。游戏启动时，这些文本文件被加载到内存中，形成一张或多张“键值对”映射表。当游戏需要显示某段文字时，程序会根据一个唯一的键（Key）去表中查找对应的值（Value）——也就是我们看到的翻译文本。

《边狱巴士公司》作为一款使用Unity引擎开发的游戏，其文本很可能存储在TextAsset类型的资源中，或者通过本地化系统（如Unity自带的Localization包或第三方插件）进行管理。我们的替换操作，本质上就是在游戏读取文本“值”的这个环节进行拦截和修改。

1.2 实现替换的几种技术路径

1. 资源文件直接修改：找到存储文本的资源文件，直接编辑并替换其中的内容。这种方法最直接，但缺点明显：每次游戏更新，文件可能被覆盖，需要重新修改；且如果文件是加密或压缩的，处理起来很麻烦。
2. 内存补丁（Memory Patching）：在游戏运行时，通过注入代码（DLL注入）的方式，挂钩（Hook）游戏读取文本的函数。当函数被调用时，我们先检查其返回的文本是否在我们的替换列表中，如果是，则返回我们修改后的文本。这种方法灵活，不修改原始文件，兼容性好，但技术门槛较高。
3. 基于翻译层拦截：如果游戏使用了成熟的本地化框架，有时会提供接口或事件允许外部修改翻译结果。我们可以编写一个Mod，注册到该框架，实现文本替换。

对于《边狱巴士公司》和兼容零协汉化的场景，内存补丁是较为理想的选择。它允许我们在不破坏原有汉化文件的前提下，进行增量式的个性化修改。

1.3 主要挑战与应对思路

• 定位关键函数：我们需要逆向分析游戏程序，找到负责根据Key返回Text的那个或那几个核心函数。这需要一定的逆向工程基础或依赖社区已有的研究成果（如BepInEx插件框架下的补丁示例）。
• 兼容性：我们的替换工具必须作为一个“上层修饰层”工作，即先让游戏加载零协汉化等基础翻译，再应用我们的自定义替换规则。顺序不能错，否则可能失效。
• 性能：文本替换操作应在内存中进行，且查找逻辑要高效（如使用哈希字典），避免对游戏性能造成可感知的影响。
• 规则管理：需要设计一个方便用户维护的替换规则格式（如YAML或JSON），支持简单的正则表达式匹配，以应对批量替换的需求。

2. 环境与工具准备

我们将使用BepInEx作为Mod加载框架，它是Unity游戏Mod开发的事实标准，具有良好的兼容性和社区支持。Harmony库则用于实现函数挂钩（Hook），即内存补丁。

2.1 必要工具与依赖

1. BepInEx：用于加载我们编写的插件。请从BepInEx官方GitHub发布页下载适用于《边狱巴士公司》游戏版本的安装包。通常只需将压缩包内容解压到游戏根目录即可。
2. Harmony：BepInEx通常已内置Harmony。但为了开发，我们需要在Visual Studio项目中引用它。可以通过NuGet包管理器安装Lib.Harmony。
3. 开发环境：
   • IDE：Visual Studio 2022 或 JetBrains Rider，并安装.NET Framework开发工作负载（游戏通常使用.NET Framework 4.x）。
   • 目标框架：创建类库项目时，选择.NET Framework 4.7.2或与游戏运行时匹配的版本。
   • 引用：需要引用游戏主程序集（如Assembly-CSharp.dll）和BepInEx核心库（BepInEx.dll,BepInEx.Harmony.dll,0Harmony.dll）。这些DLL文件在安装BepInEx后可以在游戏目录下的BepInEx\core和游戏自己的Managed文件夹中找到。

2.2 项目初始化结构

在IDE中创建一个新的“类库(.NET Framework)”项目，命名为LimbusCompanyTextReplacer。初始的文件结构应如下所示：

LimbusCompanyTextReplacer/ ├── LimbusCompanyTextReplacer.csproj ├── Plugin.cs (主插件入口) ├── TextReplacer.cs (核心替换逻辑) ├── ReplacementRule.cs (规则数据类) ├── rules.yaml (替换规则配置文件) └── Properties/ └── AssemblyInfo.cs

接下来，通过NuGet安装Lib.Harmony，并通过“添加引用”将游戏目录下的Assembly-CSharp.dll和BepInEx核心DLL引入项目。

3. 核心代码实现：从插件入口到文本替换

3.1 插件主入口 (Plugin.cs)

这是BepInEx插件的标准入口点，负责插件的元信息定义和初始化。

using BepInEx; using BepInEx.Logging; using HarmonyLib; using System.IO; using System.Reflection; namespace LimbusCompanyTextReplacer { [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)] public class Plugin : BaseUnityPlugin { internal static ManualLogSource Log; private static Harmony _harmony; private void Awake() { // 初始化日志 Log = Logger; Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 正在加载..."); // 1. 加载替换规则 string rulesPath = Path.Combine(Paths.ConfigPath, "LimbusCompanyTextReplacer", "rules.yaml"); if (!TextReplacer.Instance.LoadRules(rulesPath)) { Log.LogError("未能加载替换规则文件，插件功能可能受限。"); // 可以选择不启用Harmony补丁，但这里我们继续加载，规则可能为空。 } // 2. 应用Harmony补丁 _harmony = new Harmony(PluginInfo.PLUGIN_GUID); _harmony.PatchAll(Assembly.GetExecutingAssembly()); Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 加载完成！"); } private void OnDestroy() { // 游戏关闭时清理补丁 _harmony?.UnpatchSelf(); Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 已卸载。"); } } // 插件信息常量 internal static class PluginInfo { public const string PLUGIN_GUID = "com.yourname.limbuscompany.textreplacer"; public const string PLUGIN_NAME = "边狱巴士公司文本替换器"; public const string PLUGIN_VERSION = "1.0.0"; } }

关键点解释：

• [BepInPlugin]特性是必须的，用于向BepInEx注册插件。
• Paths.ConfigPath是BepInEx提供的标准配置目录路径，通常为BepInEx/config。我们将规则文件放在其子目录中，便于管理。
• _harmony.PatchAll()会自动扫描当前程序集中所有带有[HarmonyPatch]特性的类，并应用补丁。
• 日志使用ManualLogSource，输出内容可以在游戏根目录的BepInEx/LogOutput.log中查看，是排查问题的首要依据。

3.2 替换规则定义与加载 (ReplacementRule.cs, rules.yaml)

我们需要一个数据结构来保存“查找什么”和“替换成什么”。为了用户友好，我们选择YAML格式作为规则文件。

ReplacementRule.cs:

using System.Collections.Generic; namespace LimbusCompanyTextReplacer { public class ReplacementRule { // 是否启用此条规则 public bool Enabled { get; set; } = true; // 要查找的原始文本（支持简单正则） public string Find { get; set; } // 要替换成的目标文本 public string ReplaceWith { get; set; } // 可选的描述信息 public string Description { get; set; } // 可选的匹配模式（如“Exact”精确匹配，“Regex”正则匹配） public string MatchMode { get; set; } = "Exact"; } public class ReplacementConfig { public List<ReplacementRule> Rules { get; set; } = new List<ReplacementRule>(); } }

rules.yaml (示例):

# 边狱巴士公司文本替换规则 # MatchMode: Exact (精确匹配) | Regex (正则表达式匹配) Rules: - Enabled: true Find: “罪孽” ReplaceWith: “业力” Description: “将‘罪孽’统一替换为‘业力’” MatchMode: Exact - Enabled: true Find: “人格” ReplaceWith: “面具” Description: “将‘人格’替换为‘面具’” MatchMode: Exact - Enabled: true Find: “(李箱|良秀|鸿璐)” ReplaceWith: “【$1】” Description: “在某些角色名前后加方括号强调，使用正则表达式分组” MatchMode: Regex

TextReplacer.cs 中的加载逻辑:

using System.Collections.Generic; using System.IO; using System.Text.RegularExpressions; using YamlDotNet.Serialization; using YamlDotNet.Serialization.NamingConventions; namespace LimbusCompanyTextReplacer { public class TextReplacer { public static TextReplacer Instance { get; } = new TextReplacer(); private List<ReplacementRule> _rules = new List<ReplacementRule>(); private IDeserializer _yamlDeserializer; private TextReplacer() { _yamlDeserializer = new DeserializerBuilder() .WithNamingConvention(CamelCaseNamingConvention.Instance) .IgnoreUnmatchedProperties() .Build(); } public bool LoadRules(string filePath) { _rules.Clear(); if (!File.Exists(filePath)) { Plugin.Log.LogWarning($"规则文件不存在，将创建默认文件于: {filePath}"); SaveDefaultRules(filePath); return false; // 首次运行，规则为空是预期的 } try { string yamlContent = File.ReadAllText(filePath); var config = _yamlDeserializer.Deserialize<ReplacementConfig>(yamlContent); if (config?.Rules != null) { _rules = config.Rules; Plugin.Log.LogInfo($"成功加载 {_rules.Count} 条替换规则。"); return true; } } catch (System.Exception e) { Plugin.Log.LogError($"加载规则文件时出错: {e}"); } return false; } private void SaveDefaultRules(string filePath) { var defaultConfig = new ReplacementConfig { Rules = new List<ReplacementRule> { new ReplacementRule { Find = "示例文本", ReplaceWith = "替换后的文本", Description="这是一个示例规则，请修改或添加你自己的规则。" } } }; var serializer = new SerializerBuilder() .WithNamingConvention(CamelCaseNamingConvention.Instance) .ConfigureDefaultValuesHandling(DefaultValuesHandling.OmitNull) .Build(); string defaultYaml = serializer.Serialize(defaultConfig); Directory.CreateDirectory(Path.GetDirectoryName(filePath)); File.WriteAllText(filePath, defaultYaml); Plugin.Log.LogInfo($"已创建默认规则文件: {filePath}"); } // 核心替换方法 public string ApplyReplacements(string originalText) { if (string.IsNullOrEmpty(originalText) || _rules.Count == 0) return originalText; string processedText = originalText; foreach (var rule in _rules) { if (!rule.Enabled) continue; try { if (rule.MatchMode == "Regex") { processedText = Regex.Replace(processedText, rule.Find, rule.ReplaceWith); } else // 默认精确匹配 { processedText = processedText.Replace(rule.Find, rule.ReplaceWith); } } catch (System.Exception e) { Plugin.Log.LogWarning($"应用规则时出错 (Find: {rule.Find}): {e}"); } } return processedText; } } }

关键点解释：

• 我们使用YamlDotNet库来解析YAML文件，需要通过NuGet安装此包。
• ApplyReplacements方法是核心，它遍历所有启用的规则，按顺序对输入文本进行替换。注意顺序，规则顺序可能影响最终结果。
• 正则表达式功能强大但危险，用户编写时需谨慎。我们在代码中做了try-catch以防止错误的正则导致插件崩溃。

3.3 定位并挂钩游戏文本获取函数 (Harmony Patch)

这是最具技术挑战性的一步。我们需要找到游戏内获取本地化文本的函数。这通常需要通过逆向工具（如dnSpy, ILSpy）分析Assembly-CSharp.dll。

假设我们通过分析，发现游戏有一个名为LocalizationManager的类，其中有一个关键方法string GetText(string key)。我们的目标就是挂钩这个方法。

创建补丁类 LocalizationManagerPatch.cs:

using HarmonyLib; namespace LimbusCompanyTextReplacer { [HarmonyPatch] public class LocalizationManagerPatch { // 确定要修补的目标方法 [HarmonyTargetMethod] public static System.Reflection.MethodBase FindTargetMethod() { // 方法1：直接通过类型和方法名获取（如果知道的话） // var type = AccessTools.TypeByName("LocalizationManager"); // var method = AccessTools.Method(type, "GetText", new[] { typeof(string) }); // return method; // 方法2：更稳健的方式，通过方法特征（参数和返回类型）查找 // 这里我们假设游戏里有一个签名为 `string GetText(string key)` 的静态方法 var allTypes = typeof(UnityEngine.Object).Assembly.GetTypes(); // 从主程序集开始找 foreach (var type in allTypes) { var methods = type.GetMethods(System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Static | System.Reflection.BindingFlags.Instance); foreach (var method in methods) { var parameters = method.GetParameters(); if (method.ReturnType == typeof(string) && parameters.Length == 1 && parameters[0].ParameterType == typeof(string)) { // 进一步通过方法名或声明类型过滤，减少误判 if (method.Name.Contains("Get") && method.Name.Contains("Text") || type.Name.Contains("Localization")) { Plugin.Log.LogInfo($"找到疑似文本获取方法: {type.FullName}.{method.Name}"); return method; } } } } Plugin.Log.LogError("未找到符合条件的文本获取方法！"); return null; } // 后置补丁：在目标方法执行后，修改其返回值 [HarmonyPostfix] public static void Postfix_GetText(ref string __result) { if (__result != null) { // 调用我们的替换器 string newResult = TextReplacer.Instance.ApplyReplacements(__result); if (newResult != __result) { // 可选：记录哪些文本被修改了，用于调试 // Plugin.Log.LogDebug($"文本替换: '{__result}' -> '{newResult}'"); __result = newResult; } } } } }

关键点解释：

• [HarmonyPatch]特性告诉Harmony这个类包含补丁。
• FindTargetMethod是一个可选但非常强大的方法，它允许我们在运行时动态定位要挂钩的方法，而不是在编译时写死。这大大增强了插件对不同游戏版本的兼容性。
• [HarmonyPostfix]表示这是一个后置补丁，在原始方法执行完毕后运行。ref string __result参数让我们可以访问并修改原始方法的返回值。
• 补丁的逻辑很简单：拿到游戏原方法返回的文本（已经是零协汉化或其他汉化处理过的），交给我们的TextReplacer再处理一次，然后返回。

注意：实际的函数签名和类名需要根据对游戏程序集的实际分析结果进行调整。上述FindTargetMethod是一个启发式搜索示例，在生产环境中可能需要更精确的过滤条件，或者直接使用已知的确定类型和方法名。

4. 编译、部署与验证

4.1 编译与输出

在Visual Studio中生成项目（Build）。成功后在项目的bin/Debug或bin/Release目录下会生成LimbusCompanyTextReplacer.dll文件。

4.2 部署到游戏

1. 确保《边狱巴士公司》已安装并正常运行BepInEx。将编译好的LimbusCompanyTextReplacer.dll复制到游戏根目录下的BepInEx/plugins文件夹中。
2. 在BepInEx/config目录下，会自动生成一个LimbusCompanyTextReplacer文件夹，里面包含rules.yaml文件（如果第一次运行）。如果没有自动生成，可以手动创建该文件夹，并将项目中的示例rules.yaml复制进去。
3. 用文本编辑器（如VSCode、Notepad++）打开rules.yaml，根据你的喜好修改或添加替换规则。例如，将“罪孽”改为“业力”。
4. 保存rules.yaml文件。

4.3 运行验证

1. 启动游戏。在游戏启动器的控制台或日志文件（BepInEx/LogOutput.log）中，你应该能看到类似以下的日志，表明插件已加载：

   [Info :LimbusCompanyTextReplacer] 插件 边狱巴士公司文本替换器 正在加载... [Info :LimbusCompanyTextReplacer] 成功加载 3 条替换规则。 [Info :LimbusCompanyTextReplacer] 插件 边狱巴士公司文本替换器 加载完成！

2. 进入游戏，找到那些包含你设定规则中关键词的界面，例如角色技能描述、剧情对话、物品名称等。检查文本是否已按照你的规则被替换。
3. 你可以尝试在游戏运行时修改rules.yaml文件并保存。为了支持热重载，你可以在插件中增加一个简单的监听机制（如FileSystemWatcher）或提供一个游戏内命令来重新加载规则，但这属于进阶功能。最简单的验证方式是修改规则后，重启游戏。

5. 常见问题排查与调试

即使按照步骤操作，也可能遇到插件不生效的情况。请按照以下清单逐步排查。

5.1 插件未加载

5.2 插件已加载但文本未替换

5.3 游戏崩溃或报错

5.4 规则文件相关问题

6. 生产环境考量与最佳实践

将个人插件用于实际游戏时，除了功能实现，还需考虑稳定性、可维护性和用户体验。

1. 性能优化：

   • ApplyReplacements方法可能在每一帧被多次调用。确保规则列表不宜过长（如超过1000条），并且循环内的操作要轻量。
   • 考虑对处理过的文本进行简单缓存，避免对同一段文本反复应用相同的规则集。但要注意缓存失效问题（如规则动态变更）。

2. 规则管理：

   • YAML文件虽然可读性好，但用户可能编辑出错。可以在插件启动时或提供验证命令，对规则文件进行语法和有效性检查。
   • 支持将规则分组，例如按“角色名”、“技能描述”、“UI文本”分组，并允许用户启用/禁用整个组。

3. 兼容性与安全：

   • 明确声明插件与“零协汉化”等主流汉化Mod是兼容的，因为我们的操作在其之后。
   • 在补丁方法中做好空值检查和异常处理，确保即使我们的插件出错，也不会导致游戏主逻辑崩溃。
   • 避免替换游戏核心代码或资源，只做内存中的文本拦截。

4. 调试与日志：

   • 提供详细的日志级别控制（Info, Debug, Warning, Error）。在开发阶段开启Debug日志以追踪文本替换流程，发布时关闭以减少日志量。
   • 可以提供一个游戏内的调试面板（使用Unity IMGUI）来实时查看替换记录或临时修改规则，这对规则作者非常有用。

5. 用户文档：

   • 在插件发布时，应附带一个清晰的README.md，说明安装步骤、规则文件格式、常见问题解答。
   • 提供一个丰富的、注释清晰的示例rules.yaml文件。

通过以上步骤，你不仅实现了一个针对《边狱巴士公司》的文本替换工具，更掌握了一套通用的、基于Harmony的游戏Mod开发与文本修改方法论。这套方法经过适当调整，可以应用于许多其他Unity游戏，实现各种自定义需求。核心在于精准定位目标函数、设计稳健的替换逻辑，以及提供友好的用户配置界面。