企业官网建设流程全解析

最近在折腾 TABS（Totally Accurate Battle Simulator）的自定义内容时，踩了不少坑：明明单位文件已经放到目录里，游戏里就是不显示；派系更新一次，旧存档里的单位全部变成「缺失」；隐藏单位更是找不到入口，只能在资源里干瞪眼。本文把这一整套流程整理成一份可复现的实战笔记，从概念、目录结构、配置文件字段，到可直接复制的插件骨架、批量校验脚本和排错清单，全部拆开讲。无论你是第一次接触 TABS mod，还是正在给自己的蒸汽朋克派系做版本更新，都可以按顺序抄下来用。

1. TABS mod、隐藏单位与派系的核心概念

1.1 TABS 的内容加载机制

TABS 是 Landfall 开发的一款基于物理模拟的沙盒对战游戏，底层跑在 Unity 引擎上。它和大多数 Unity 游戏一样，把单位模型、骨骼、动画、武器参数打包进游戏安装目录的资源里。玩家能直接操作的部分，则是游戏额外开放的一层「自定义内容」入口。

理解 mod 的本质，先要理解它的三层加载顺序：

第一层是游戏自带的资源包，里面的单位由开发者在构建时注册进单位索引。第二层是用户自定义内容目录，游戏启动时会扫描这个目录，把玩家通过 Unit Creator 保存的单位、Faction Creator 保存的派系读进来。第三层是代码型 mod，通常通过 BepInEx 这类通用 Unity 插件框架加载，可以在运行时修改游戏逻辑、往索引里塞额外条目。

这三层是叠加关系而不是替换关系。你放在用户目录里的单位，不会覆盖游戏原版单位，只是在原版索引后面追加；而 BepInEx 插件则可以做到更强的事情，比如把一个原本没被注册进索引的单位强行注册进去。这也是「隐藏单位」能够被找回来的技术前提。

需要强调的是，不同游戏版本的目录命名、文件扩展名、索引结构都可能有差异。本文给出的路径和字段名以常见情况为例，实际请以你本机导出的真实文件为准，不要照抄路径里的每一个字符。

1.2 什么是「隐藏单位」

隐藏单位（Hidden Unit）并不是一个官方术语，而是社区里对一类单位的统称。它们的共同特征是：数据存在于游戏资源中，但在正常的兵种选择界面里看不到、点不到。

粗略分类，隐藏单位通常来自这几种情况：

• 开发者调试用的单位，参数被调得极不平衡，不适合放进正式玩法。
• 未完成的实验性单位，模型和武器有，但动画或平衡没做完，于是从索引里摘掉。
• 特殊活动、彩蛋性质的单位，只在特定条件下出现。
• 被后续版本下架的单位，资源还留着，索引里已经删了。

它们的资源其实都在，缺的只是「注册」这一步。所以做一个隐藏单位 mod，核心工作是两件事：第一，确认目标单位在资源里的唯一标识；第二，把这个标识重新挂到玩家可访问的单位索引上。

1.3 派系在 mod 里的定位

派系（Faction）在 TABS 里是单位的分组容器。原版游戏里你看到的「部落」「农夫」「古代」这些，都是派系。玩家自定义派系时，游戏会生成一个派系描述文件，里面记录派系名称、图标、以及一个单位引用列表。

这里有个容易混淆的点：派系文件本身不存单位数据，它只存「指向单位的引用」。单位数据仍然在单位文件里。这意味着如果你更新了某个单位的 ID，但派系文件里还写着旧 ID，游戏就会认为这个单位不存在，界面上表现为一个空槽或者直接报错。

所以派系 mod 的更新，本质上是一次「引用重建」：单位改了，引用也要跟着改；单位删了，引用必须同步删掉。

1.4 为什么「更新」比「新建」更容易出问题

新建一个派系，你面对的是一张白纸，写完就是写完。更新则不同，你要同时兼容三类历史包袱：

一是旧存档。玩家在旧版本里保存的对战配置、自定义阵容，里面记录的是旧 ID。你换了 ID，旧存档就废了。

二是旧引用。派系文件、收藏列表、快捷栏，都可能各自缓存了一份引用。

三是游戏版本。游戏本体更新后，单位的数据结构字段可能增减，老文件读进来会缺字段或者多字段。

这三点决定了更新策略的核心原则：能不改 ID 就不改 ID，能只追加字段就不删字段。后文的实战部分会围绕这条原则展开。

2. 环境准备与版本说明

2.1 运行环境与游戏版本

本文的操作在 Windows 桌面环境下完成。TABS 的 PC 版本分发渠道不同，版本号差异较大，社区里流传的单位文件格式也随版本演进过，因此本文不写死具体版本号，只强调一件事：做 mod 之前先确认自己的游戏版本，并在整个开发周期内保持版本一致。

原因是这样的：如果你在 A 版本导出的单位文件，拿到 B 版本的游戏里加载，字段对不上是小事，严重的时候游戏会直接读失败、把整个自定义目录判为损坏。所以建议在动手前做一次完整备份，具体目录见下一节。

2.2 关键目录速览

TABS 在 Windows 上的用户数据目录，通常位于当前用户的本地低权限应用数据区，路径形如：

C:\Users\<你的用户名>\AppData\LocalLow\<发行商目录>\<游戏目录>\

这个目录下面通常会有几类内容：

<游戏用户数据目录>/ ├── CustomUnits/ # 玩家通过 Unit Creator 保存的单位 ├── CustomFactions/ # 玩家保存的自定义派系 ├── Player.log # 游戏运行日志，排错必看 └── ... # 其他存档与配置

游戏安装目录则是另一套结构，代码型 mod 的插件一般放在安装目录下的插件文件夹里：

<游戏安装目录>/ ├── <游戏可执行文件>.exe ├── BepInEx/ │ ├── core/ # 框架本体 │ ├── plugins/ # 你自己写的插件放这里 │ └── config/ # 插件生成的配置文件 └── ... # 游戏自身资源

这里要特别提醒：Player.log是你排查问题时最有价值的文件。单位加载失败、字段解析异常、插件抛异常，基本都会在这里留下痕迹。养成「改完先看日志」的习惯，能省掉大量盲猜时间。

2.3 工具清单

按用途分，一套完整的 mod 开发环境大致需要下面这些工具：

需要说明的是，BepInEx 和 .NET SDK 只在你打算写代码型 mod 时才需要。如果你的需求只是「把现成的单位文件塞进自定义派系」，那么文本编辑器加游戏本体就够了。

2.4 动手前的备份流程

这一步很多人会跳过，但它决定了你出问题时是「五分钟恢复」还是「重装游戏」。建议按下面的顺序操作：

# 1. 先关闭游戏，确保没有进程占用文件 # 2. 把整个用户数据目录复制一份带日期的备份 # Windows 上可以在资源管理器里手动复制，也可以用 robocopy robocopy "%USERPROFILE%\AppData\LocalLow\<发行商目录>\<游戏目录>" "%USERPROFILE%\Desktop\tabs_backup_20240101" /E

命令里的/E表示包含空目录一起复制。备份完成后，再开始你的修改。后续每次发布新版本前，也应该保留一份上一版的文件快照，方便对比差异。

3. 工程结构与配置文件拆解

3.1 单位文件的结构组成

TABS 的用户自定义单位文件，本质上是一份结构化的数据描述，记录了单位的外观、属性、武器挂载信息。不同版本可能使用 JSON 或游戏自有的键值结构，下面用 JSON 作为示意，重点看字段的职责划分，而不是具体字段名的拼写。

一份单位描述通常包含这几块内容：

{ "unitId": "steampunk_gear_knight", "displayName": "齿轮骑士", "category": "steampunk", "stats": { "health": 320, "moveSpeed": 6.5, "attackSpeed": 1.1, "damage": 45 }, "weapon": { "type": "melee", "range": 2.2, "arc": 90 }, "appearance": { "rig": "humanoid_basic", "parts": [ { "slot": "head", "asset": "steampunk_helmet" }, { "slot": "body", "asset": "steampunk_armor" }, { "slot": "weapon", "asset": "steam_hammer" } ] }, "flags": { "hidden": true, "experimental": false } }

逐块解释一下：

unitId是全局唯一标识，派系文件、存档、快捷栏都靠它来定位单位。这是整个文件里最不能随意改的字段，前面说过，改它等于让所有历史引用失效。

displayName是界面上显示的名字。改这个是安全的，因为它只是展示层字段。

category决定这个单位归到哪一类，在自定义派系里主要用于分组和排序。

stats是数值块，血、速度、攻速、伤害这些。调数值是 mod 里最安全也最常做的操作，因为它不影响引用关系。

weapon描述武器行为，近战还是远程、攻击距离、攻击弧角。这里要注意，远程武器的投射物逻辑通常不在单位文件里，而是在游戏资源里，所以你只能引用已有的投射物类型，不能凭空定义一个。

appearance是外观挂载，指定用哪套骨骼、每个槽位挂哪个资源。这部分最容易出错，因为资源名拼错不会报错，只会导致模型缺件。

flags是标记位。hidden: true在示意结构里表示这是一个隐藏单位，需要额外逻辑才会显示。实际游戏里这个标记的名字和语义需要以真实文件为准。

3.2 派系文件的结构

派系文件比单位文件简单，它只负责「组织」：

{ "factionId": "steampunk_faction", "displayName": "蒸汽朋克", "description": "以齿轮与蒸汽为核心的自定义派系", "units": [ "steampunk_gear_knight", "steampunk_boiler_gunner", "steampunk_clockwork_drone", "steampunk_pressure_tank" ] }

units数组里存的全是单位 ID，顺序决定了界面上单位的排列顺序。这个数组是「强引用」：如果里面某个 ID 在单位目录里找不到对应文件，游戏在加载派系时就会出问题，轻则跳过，重则整个派系加载失败。

所以维护派系文件时，最稳妥的做法是先扫描单位目录，拿到所有真实存在的 ID，再生成派系文件，而不是手工敲。后文的校验脚本就是干这件事的。

3.3 隐藏单位的启用思路

隐藏单位的启用，取决于它「隐藏」在哪一层。常见的三种情况：

第一种，单位数据在，但没被注册进单位索引。这种最简单的解法是在自定义内容里重建一份单位描述，用一个新的 ID 指向同一套资源，相当于在玩家侧复制了一个副本。这种方式不改游戏本体，风险最低，适合大多数玩家。

第二种，单位被索引注册了，但带了一个「不显示」的标记。这种情况需要用代码型 mod 在运行时修改这个标记，或者修改控制显示逻辑的方法。这就涉及 Harmony 之类的运行时打补丁技术。

第三种，单位资源根本没打包进当前版本的游戏资源里。这种情况下无论怎么改配置都找不回来，只能等游戏更新或者找社区资源包。做 mod 的第一件事其实是确认目标单位到底属于哪一种。

3.4 字段改动的兼容性判断

在动手改任何字段之前，先问自己一个问题：这个字段会不会被外部引用？判断标准如下表：

把这张表贴在开发流程里，每次改动前过一遍，能避免掉一大半的兼容性问题。

4. 完整实战：蒸汽朋克派系隐藏单位 mod

下面走一遍完整流程。目标是做一个「蒸汽朋克」自定义派系，里面包含若干自定义单位，其中一个是从隐藏单位「复活」出来的。

4.1 建立工程目录

先在游戏用户数据目录旁边建一个独立的工程目录，不要直接在游戏的目录里改，这样出问题可以随时整体替换。

steampunk-mod/ ├── src/ │ ├── units/ # 单位描述文件 │ │ ├── steampunk_gear_knight.json │ │ ├── steampunk_boiler_gunner.json │ │ ├── steampunk_clockwork_drone.json │ │ └── steampunk_pressure_tank.json │ └── factions/ │ └── steampunk_faction.json ├── tools/ │ └── build_faction.py # 生成与校验脚本 ├── plugin/ │ ├── SteampunkFaction.csproj │ └── Plugin.cs └── dist/ # 打包输出目录

这个结构的好处是源文件和产物分离。src里是你要手工维护的内容，dist是打包出来给玩家用的，中间用脚本衔接。

4.2 编写单位描述文件

先写一个普通单位，把结构跑通：

{ "unitId": "steampunk_gear_knight", "displayName": "齿轮骑士", "category": "steampunk", "stats": { "health": 320, "moveSpeed": 6.5, "attackSpeed": 1.1, "damage": 45 }, "weapon": { "type": "melee", "range": 2.2, "arc": 90 }, "appearance": { "rig": "humanoid_basic", "parts": [ { "slot": "head", "asset": "steampunk_helmet" }, { "slot": "body", "asset": "steampunk_armor" }, { "slot": "weapon", "asset": "steam_hammer" } ] }, "flags": { "hidden": false, "experimental": false } }

再写一个远程单位，把武器类型换掉：

{ "unitId": "steampunk_boiler_gunner", "displayName": "锅炉炮手", "category": "steampunk", "stats": { "health": 180, "moveSpeed": 4.8, "attackSpeed": 1.6, "damage": 30 }, "weapon": { "type": "ranged", "range": 14.0, "projectile": "steam_cannonball" }, "appearance": { "rig": "humanoid_basic", "parts": [ { "slot": "head", "asset": "steampunk_goggles" }, { "slot": "body", "asset": "steampunk_coat" }, { "slot": "weapon", "asset": "steam_cannon" } ] }, "flags": { "hidden": false, "experimental": false } }

注意这里的projectile字段。它引用的是游戏里已有的投射物类型，不是你自己定义的。如果你写了一个游戏里不存在的名字，运行时可能表现为单位不开火，或者直接抛异常。这就是上一节说的「远程武器只能引用已有类型」。

第三个单位就是隐藏单位复活出来的副本。做法是复制原单位的资源引用，换一个新的可读 ID：

{ "unitId": "steampunk_pressure_tank", "displayName": "压力战车", "category": "steampunk", "stats": { "health": 1200, "moveSpeed": 2.2, "attackSpeed": 0.8, "damage": 80 }, "weapon": { "type": "melee", "range": 3.5, "arc": 180 }, "appearance": { "rig": "vehicle_large", "parts": [ { "slot": "body", "asset": "steampunk_tank_hull" }, { "slot": "weapon", "asset": "steam_piston_ram" } ] }, "flags": { "hidden": false, "experimental": false } }

关键点在于：外观资源引用的还是原本那套隐藏单位的资源，但unitId是新起的可读名字，flags.hidden设为 false。这样在玩家侧就是一个正常可选的单位，而资源层面复用的还是原本那份。

4.3 用脚本自动生成派系文件

派系文件不要手工敲，容易漏、容易写错 ID。写一个 Python 脚本扫描units目录，自动生成派系文件并做校验：

# 文件路径：tools/build_faction.py import json import os import sys UNITS_DIR = os.path.join(os.path.dirname(__file__), "..", "src", "units") FACTION_OUT = os.path.join(os.path.dirname(__file__), "..", "src", "factions", "steampunk_faction.json") REQUIRED_UNIT_FIELDS = ["unitId", "displayName", "stats", "appearance"] def load_all_units(): """读取所有单位文件，返回 (成功列表, 错误列表)""" units = [] errors = [] if not os.path.isdir(UNITS_DIR): errors.append("单位目录不存在: %s" % UNITS_DIR) return units, errors for filename in sorted(os.listdir(UNITS_DIR)): if not filename.endswith(".json"): continue path = os.path.join(UNITS_DIR, filename) try: with open(path, "r", encoding="utf-8") as f: data = json.load(f) except json.JSONDecodeError as e: errors.append("%s 解析失败: %s" % (filename, e)) continue missing = [f for f in REQUIRED_UNIT_FIELDS if f not in data] if missing: errors.append("%s 缺少必需字段: %s" % (filename, ", ".join(missing))) continue units.append(data) return units, errors def check_duplicate_ids(units): """检查 unitId 是否重复""" seen = {} errors = [] for u in units: uid = u["unitId"] if uid in seen: errors.append("unitId 重复: %s（%s 与 %s）" % (uid, seen[uid], uid)) else: seen[uid] = uid return errors def build_faction(units): """根据单位列表生成派系描述""" return { "factionId": "steampunk_faction", "displayName": "蒸汽朋克", "description": "以齿轮与蒸汽为核心的自定义派系", "units": [u["unitId"] for u in units], } def main(): units, errors = load_all_units() errors += check_duplicate_ids(units) if errors: print("发现 %d 个问题：" % len(errors)) for e in errors: print(" - " + e) sys.exit(1) faction = build_faction(units) os.makedirs(os.path.dirname(FACTION_OUT), exist_ok=True) with open(FACTION_OUT, "w", encoding="utf-8") as f: json.dump(faction, f, ensure_ascii=False, indent=2) print("已生成派系文件: %s" % FACTION_OUT) print("共包含 %d 个单位" % len(faction["units"])) for uid in faction["units"]: print(" - " + uid) if __name__ == "__main__": main()

运行方式：

cd steampunk-mod python tools/build_faction.py

预期输出类似：

已生成派系文件: .../src/factions/steampunk_faction.json 共包含 3 个单位 - steampunk_boiler_gunner - steampunk_clockwork_drone - steampunk_gear_knight - steampunk_pressure_tank

这个脚本的价值不只是省事。更重要的是，它把「校验」前置到了生成阶段。字段缺失、ID 重复、文件格式错误，都会在打包之前暴露出来，而不是等你进游戏才发现派系里少了一个单位。

4.4 编写 BepInEx 插件骨架

如果你的隐藏单位属于前面说的第二种情况——被索引注册了但带了不显示标记，那就需要代码型 mod。下面是 BepInEx 插件的通用骨架：

// 文件路径：plugin/Plugin.cs using BepInEx; using BepInEx.Logging; using HarmonyLib; namespace SteampunkFaction { [BepInPlugin("com.example.tabs.steampunkfaction", "Steampunk Faction Loader", "1.0.0")] public class Plugin : BaseUnityPlugin { internal static ManualLogSource Log; private void Awake() { Log = Logger; Log.LogInfo("Steampunk Faction Loader 开始加载"); // 启用 Harmony 补丁 var harmony = new Harmony("com.example.tabs.steampunkfaction"); harmony.PatchAll(); Log.LogInfo("Steampunk Faction Loader 加载完成"); } } }

对应的工程文件：

<!-- 文件路径：plugin/SteampunkFaction.csproj --> <Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>netstandard2.1</TargetFramework> <AssemblyName>SteampunkFaction</AssemblyName> <Version>1.0.0</Version> <LangVersion>latest</LangVersion> <AllowUnsafeBlocks>true</AllowUnsafeBlocks> </PropertyGroup> <ItemGroup> <!-- 下面这些引用的实际路径需要指向你本机的 BepInEx 与游戏程序集 --> <Reference Include="BepInEx"> <HintPath>..\libs\BepInEx.dll</HintPath> <Private>false</Private> </Reference> <Reference Include="0Harmony"> <HintPath>..\libs\0Harmony.dll</HintPath> <Private>false</Private> </Reference> </ItemGroup> </Project>

这里要重点提醒：HintPath里写的是相对路径，实际使用时必须指向你本机 BepInEx 目录下的真实 DLL 文件。Private=false表示不要把框架 DLL 一起复制到输出目录，避免和游戏自带的版本冲突。

至于具体要 Patch 哪个类的哪个方法，这取决于游戏版本和你要改的逻辑入口。通用的做法是先反编译游戏程序集，找到控制「单位列表构建」或「单位可见性判断」的方法，再用 Harmony 打补丁。补丁的基本形态是这样的：

// 文件路径：plugin/UnitVisibilityPatch.cs using HarmonyLib; namespace SteampunkFaction { // 目标类型与方法名需要以你反编译得到的实际结果为准 // 这里演示的是 Harmony 补丁的通用写法，不能直接照抄类名 [HarmonyPatch] public static class UnitVisibilityPatch { // 示例：在某个返回布尔值的方法执行后修改结果 // [HarmonyPatch(typeof(TargetType), "TargetMethodName")] // [HarmonyPostfix] // public static void Postfix(ref bool __result) // { // if (!__result) // { // __result = true; // Plugin.Log.LogInfo("已强制开启单位可见性"); // } // } } }

上面这段是故意注释掉的。原因是 Harmony 补丁必须对应真实的类型和方法名，写错了要么不生效，要么直接抛异常导致整个插件加载失败。正确的做法是：先用反编译工具定位目标方法，确认签名之后再解除注释。

编译方式：

cd plugin dotnet build -c Release

编译完成后，把bin/Release/netstandard2.1/SteampunkFaction.dll复制到游戏安装目录下的BepInEx/plugins/里。

4.5 打包与安装

打包前先跑一遍校验脚本，确认没有错误：

python tools/build_faction.py

然后把单位文件和派系文件整理成玩家可用的形式：

dist/ └── steampunk-faction/ ├── CustomUnits/ │ ├── steampunk_gear_knight.json │ ├── steampunk_boiler_gunner.json │ ├── steampunk_clockwork_drone.json │ └── steampunk_pressure_tank.json ├── CustomFactions/ │ └── steampunk_faction.json ├── BepInEx/ │ └── plugins/ │ └── SteampunkFaction.dll └── README.txt

README.txt里写清楚三件事：安装路径、依赖项（是否需要 BepInEx）、以及版本兼容说明。这三条是玩家最容易出问题的地方。

安装步骤：

1. 关闭游戏 2. 备份原有的 CustomUnits 与 CustomFactions 目录 3. 把 dist/steampunk-faction/CustomUnits/* 复制到用户数据目录的 CustomUnits/ 4. 把 dist/steampunk-faction/CustomFactions/* 复制到用户数据目录的 CustomFactions/ 5. 如果使用了插件，把 SteampunkFaction.dll 复制到游戏安装目录的 BepInEx/plugins/ 6. 启动游戏

4.6 进入游戏验证

验证要分层次做，不要一上来就开整场对战。

第一步，进游戏后先看派系列表里有没有「蒸汽朋克」。如果没有，说明派系文件没被读到，去查路径和文件名。

第二步，点进派系看单位数量对不对。数量不对说明派系文件里的units数组和实际单位文件不一致，回去跑校验脚本。

第三步，单独拖一个单位到场上，看模型、武器、动画是否正常。模型缺件说明外观资源名写错了，不开火说明武器或投射物引用有问题。

第四步，整派系上阵做一次压力测试。单位一多，性能问题、逻辑冲突才会暴露出来。

如果哪一步失败，立刻去看Player.log。日志里一般会有加载失败的完整堆栈，比你在界面上猜要快得多。

5. 常见问题与排查思路

下面这张表覆盖了我在做这个派系过程中实际遇到的和社区里高频出现的问题：

针对其中几个最容易卡住的，展开说一下排查步骤。

关于「派系看不到」：先确认游戏是不是真的读到了你的文件。最直接的办法是把文件改成一个明显错误的格式，重启游戏，如果日志里出现了对应的解析错误，说明路径是对的，问题出在内容上；如果日志里什么都没多，说明路径就是错的。这个方法虽然笨，但定位非常准。

关于「模型缺件」：不要一次改一堆资源名。正确的做法是先做一个只有一个部件的单位，确认能显示，然后一个一个往上加。每加一个就进游戏看一次，虽然慢，但能精确定位到是哪一个资源名错了。

关于「旧存档失效」：这个基本没法事后补救，只能事前预防。原则就是前面反复强调的那条：新增单位用新 ID，老单位不要改 ID。真想「重做」某个单位，正确做法是新建一个 ID 不同的单位，把老的标记为弃用但保留文件。

关于「插件加载失败」：先看BepInEx/LogOutput.log，这是 BepInEx 自己的日志，比游戏日志更早、更详细。如果里面连你的插件名都没出现，说明 DLL 根本没被扫描到，去查路径和文件名；如果出现了但跟着一堆异常，那就是补丁目标写错了。

6. 最佳实践与工程建议

6.1 命名与版本管理

单位 ID 用「派系前缀 + 功能描述」的格式，全部小写加下划线，例如steampunk_gear_knight。这样做的好处是：在派系文件、存档、日志里看到这个 ID，一眼就知道它属于哪个派系、大概是什么。

版本号建议同时写在三个地方：派系文件的描述字段、插件程序集版本、以及 README。三处一致，玩家反馈问题时你能快速确认他装的是哪一版。

6.2 配置分离与向后兼容

把所有可能被玩家覆盖的内容（数值、外观、派系组成）和代码逻辑分开。单位数值单独一份文件，代码只负责加载逻辑。这样玩家想调平衡性，改数值文件就行，不用碰代码。

向后兼容的核心手段是「只增不删」。新增单位用新 ID；要废弃的单位保留文件但移出派系列表，并在 README 里标注；要改数值直接改，因为数值不涉及引用关系。这套策略执行下来，你的 mod 可以连续更新很多个版本而不破坏旧存档。

6.3 异常处理与日志

插件里的每一处对外部数据的读取都应该包在 try-catch 里，捕获之后用Log.LogError输出，而不是让异常冒泡到游戏主循环。原因很实际：一个未捕获的异常可能导致整个插件被卸载，玩家看到的就是「mod 完全没生效」，而且没有任何提示，排查成本极高。

日志内容要包含足够的上下文，比如「加载单位 xxx 时，字段 appearance 解析失败」，而不是干巴巴一句「加载失败」。

6.4 安全边界与生产环境意识

做 mod 有一些通用底线需要遵守：

第一，只修改自己有权修改的内容。不要打包、分发游戏本体的资源文件，只分发你自己创作的单位描述和代码。

第二，不要引导玩家删除或替换游戏原始文件。所有改动都应该发生在用户数据目录和插件目录，保证玩家随时能通过「移除你的文件」完全恢复到原版状态。

第三，涉及反编译游戏程序集时，仅用于个人学习和兼容性适配，不要分发反编译产物。

第四，发布前在自己机器上做完整的安装—运行—卸载流程验证，确认卸载后游戏能正常启动。

6.5 性能与可维护性

单位数量上去之后，性能会成为问题。几个常规优化点：避免在每帧逻辑里做字符串查找和反射调用；单位和派系数据在启动时一次性加载进内存字典，运行时只做字典查找；大量单位的外观资源尽量复用，不要为每个单位单独准备一套。

可维护性方面，建议在工程里保留一份CHANGELOG.md，每次发布记录三件事：新增了什么、修改了什么、删除了什么。这三条能帮你在三个月后回来看代码时，迅速回忆起当时为什么这么改。

7. 后续可以继续深入的方向

把上面这套流程跑通之后，你已经具备了一个派系 mod 从零到发布的基本能力。接下来如果要继续深入，可以往三个方向走：

第一个方向是逆向分析。学会用反编译工具读游戏程序集，理解单位注册、派系加载、可见性判断这些逻辑的真实实现。这一步突破之后，你能做的事情会多很多，比如自动扫描所有隐藏单位并生成一份完整清单。

第二个方向是资源制作。本文的外观部分是复用已有资源，真正原创的 mod 需要自己做模型、绑定骨骼、制作动画。这部分工作量很大，但也是让派系有辨识度的关键。

第三个方向是工程化。把校验脚本、打包脚本、版本号管理串成一条流水线，做到一条命令产出可发布的压缩包。mod 做多了之后，这套基建带来的效率提升非常明显。

最后留一个实操建议：先不要急着做十个单位。挑一个单位，把「描述文件 → 派系注册 → 进游戏验证 → 打包 → 卸载恢复」这条链路完整走一遍。链路通了，后面就是复制粘贴加微调。链路没通就堆量，只会在最后同时面对十几个问题时无从下手。