TABS隐藏兵种MOD实战：Unity资源打包、单位注册与数值平衡

最近在整理一份 TABS（Totally Accurate Battle Simulator，全面战争模拟器）隐藏兵种 MOD 的大版本更新，把之前只存在于草稿里的几个新单位推到"可玩、可展示、可发布"的状态。整个过程比想象中琐碎：资源打包、单位注册、图鉴可见性、数值平衡、版本兼容，每一环都有坑。本篇就把这次更新的完整流程整理成一份可复现的实操笔记，从概念讲到环境、从配置讲到代码、从打包讲到排错。无论你是刚接触 Unity 模组的新手，还是已经能改数值但卡在"兵种不出现在菜单里"的进阶玩家，都可以顺着这篇文章一步步走完。

1. TABS 隐藏兵种 MOD 的核心概念

1.1 什么是"隐藏兵种"

在 TABS 这款游戏里，"隐藏兵种"通常指两类内容。第一类是官方内置但未在常规兵种菜单中直接展示的单位，它们往往需要通过特定条件触发、特定关卡出现，或者干脆只存在于资源包里，玩家能通过存档、控制台或模组手段把它们调出来。第二类是模组作者基于游戏原有单位体系新增的自定义单位，作者可以选择把它们设为"隐藏"，即不在默认选人界面出现，只有满足解锁条件才显示。

这两类内容在技术上的实现路径并不相同，但对玩家来说体验是一致的：正常玩看不到，满足某种条件后突然出现。理解这个区别很重要，因为它决定了你后面要写的是"解锁逻辑"还是"注册逻辑"。本文主要围绕第二类展开，也就是如何从零做一个自己的隐藏兵种，同时会兼顾第一类的调取思路。

1.2 MOD 与官方内容的边界

做模组之前必须先明确一件事：MOD 是对游戏本地资源的扩展，不是对游戏的破解。所有操作都应该在你合法拥有的游戏副本上进行，遵守游戏的最终用户许可协议，不传播游戏本体文件，不修改联机相关逻辑，不用于任何商业用途。这个边界看起来很基础，但确实有不少人栽在这里。

从工程角度看，MOD 与官方内容的关系可以理解为"追加"而非"覆盖"。追加意味着你新增的单位有自己的唯一标识、自己的资源包、自己的配置数据，游戏本体不感知它的存在，直到你的加载器把它注册进去。这种设计的好处是兼容性好、卸载干净，坏处是你必须自己处理好生命周期，比如场景切换后重新注册、版本更新后重新打包。

1.3 为什么值得自己动手做一个

很多人第一次接触 TABS 模组是从"改数值"开始的，把血量调成一百万，玩十分钟就腻了。真正有意思的是做一个有设计感的单位：它有自己的模型、自己的攻击节奏、自己的定位，在战场上能打出独特的效果。这个过程需要你同时处理资源、配置、代码、平衡四件事，本质上是一次小型的游戏开发练习。

而且隐藏兵种这个切入点特别好。因为"隐藏"意味着你可以在不破坏原有平衡的前提下做实验，把这些单位当作彩蛋、当作挑战奖励、当作版本更新的惊喜。玩家社区对隐藏内容的热情往往高于常规内容，这也是这次大更新把重点放在隐藏兵种上的原因。

2. 开发环境与工具链准备

2.1 环境清单与版本策略

TABS 基于 Unity 引擎开发，所以模组开发的核心工具链就是 Unity 那一套。需要准备的东西包括：Unity 编辑器（版本需要与你目标游戏版本使用的 Unity 大版本匹配，具体版本号请在游戏安装目录下的*_Data/globalgamemanagers或游戏日志中确认，不要凭印象选版本）、一个 C# 代码编辑器（Rider 或 Visual Studio 均可）、一个模组加载框架（社区常用的是 BepInEx，用于在游戏启动时注入我们的程序集）、以及一个资源打包工具（Unity 自带的 AssetBundle 构建流程即可）。

这里要特别强调版本匹配问题。Unity 的 AssetBundle 有版本兼容性要求，用 2021 版本打出来的包，2022 版本的游戏大概率读不了，反过来也一样。所以第一步永远是确认游戏用的是哪个 Unity 版本，然后装一个完全一致的编辑器。如果你不确定，可以先看游戏日志里的引擎版本信息，或者看社区模组文档里标注的兼容版本。

本文示例以 Windows 平台的常见环境为例，其他平台思路一致，只是在打包目标和路径上不同。具体版本号请按你自己的游戏实际版本调整，本文重点演示配置思路和代码结构，不写死具体版本。

2.2 目录结构与工程约定

一个清晰的目录结构能省掉后面 80% 的混乱。建议把"资源工程"和"代码工程"分开，资源工程负责模型、材质、动画、预制体，代码工程负责加载器和配置解析。打包产物统一输出到一个dist目录，最终发布的模组目录结构大致如下：

TabsHiddenUnits/ ├── BepInEx/ │ └── plugins/ │ └── TabsHiddenUnits/ │ ├── TabsHiddenUnits.dll # 加载器程序集 │ ├── units.json # 单位配置数据 │ ├── localization.json # 文本本地化 │ └── bundles/ │ ├── hidden_units_win # Windows 平台资源包 │ └── hidden_units_linux # Linux 平台资源包 └── README.md

这个结构的关键点在于：程序集、配置、资源三者分离。程序集只做一件事——读配置、加载资源、注册单位，不写死任何单位数据。配置用纯文本 JSON，改数值不用重新编译。资源按平台分包，避免一个包在多个平台互相干扰。这种约定在你只有三五个单位时显得多余，等到单位数量上去、需要多人协作时，它就是救命的东西。

2.3 一个最小可加载的 MOD 骨架

在动手做单位之前，先做一个"什么都不做"的空壳，确认它能被游戏加载、能打印日志。这一步非常关键，因为它把"环境问题"和"业务问题"隔离开了。下面是一个基于 BepInEx 的最小插件模板：

// 文件路径：src/TabsHiddenUnits/Plugin.cs using BepInEx; using BepInEx.Logging; using UnityEngine; namespace TabsHiddenUnits { [BepInPlugin(PluginGuid, PluginName, PluginVersion)] public class Plugin : BaseUnityPlugin { public const string PluginGuid = "com.example.tabs.hiddenunits"; public const string PluginName = "Tabs Hidden Units"; public const string PluginVersion = "1.0.0"; internal static ManualLogSource Log; private void Awake() { Log = Logger; Log.LogInfo($"{PluginName} v{PluginVersion} 已加载"); // 注册场景加载完成回调，等游戏场景就绪后再做业务逻辑 UnityEngine.SceneManagement.SceneManager.sceneLoaded += OnSceneLoaded; } private void OnDestroy() { UnityEngine.SceneManagement.SceneManager.sceneLoaded -= OnSceneLoaded; } private void OnSceneLoaded(UnityEngine.SceneManagement.Scene scene, UnityEngine.SceneManagement.LoadSceneMode mode) { Log.LogInfo($"场景加载完成: {scene.name}, mode={mode}"); // 后续在这里调用单位注册流程 } } }

这段代码做了什么？BepInPlugin特性告诉 BepInEx 这个程序集是一个插件，并声明唯一标识、显示名和版本号。Awake是插件被注入后最早的生命周期点，此时游戏主体对象还没完全就绪，所以不适合做重活。真正适合做注册的时机是场景加载完成，因此我们挂了sceneLoaded事件。OnDestroy里反注册事件是良好习惯，避免热重载时重复挂载导致回调执行多次。

编译后把 DLL 放进BepInEx/plugins/TabsHiddenUnits/目录，启动游戏，看BepInEx/LogOutput.log里有没有输出那行"已加载"。如果看到了，说明整条链路是通的，可以进入下一步。如果没看到，先别急着写业务代码，去第 6 节看排查清单。

3. 单位数据的三层结构拆解

3.1 静态定义、运行时实例与表现层

理解单位数据的组织方式，是做好隐藏兵种的前提。在 Unity 类游戏里，一个单位通常可以拆成三层：静态定义层、运行时实例层、表现层。

静态定义层是"模板"，描述这个单位本来是什么——叫什么名字、属于哪个阵营、基础血量多少、攻击间隔多少、用什么武器、模型是哪个预制体。这一层在游戏启动时就该确定，一般不随对局变化。运行时实例层是"个体"，描述战场上这一个具体的单位——当前血量、当前状态机、当前目标、当前冷却。每个实例都从静态定义复制一份初始值，然后独立演化。表现层则是"看得见的部分"——模型、材质、动画控制器、音效、粒子特效。

你的 MOD 主要工作在静态定义层：新增一个模板，让游戏知道有这么个单位。运行时实例层通常交给游戏原有逻辑处理，除非你要做特殊机制。表现层则完全由你提供资源。把这三层想清楚，你就不会在"为什么我改了血量但没生效"这类问题上浪费时间——因为很可能你改的是模板，而场上那个单位早就从模板复制完初始值了。

3.2 资源打包与运行时加载

TABS 的资源以 AssetBundle 形式组织。你要做的事情是：在 Unity 编辑器里把模型、材质、动画、预制体组织好，标记 AssetBundle 名称，通过构建脚本打包，然后在运行时用AssetBundle.LoadFromFile读回来。

打包环节有两个高频坑。第一个是 Shader 丢失。如果你的材质用了自定义 Shader 或者游戏本体没有的内置 Shader，打包时必须把 Shader 一起打进包，否则运行时模型会显示成一片粉色或纯黑。第二个是依赖缺失。预制体引用了另一个包里的资源，构建时没有正确声明依赖，加载时就会报"资源找不到"。解决办法是统一把相关资源放在同一个 Bundle 里，或者用 Unity 的依赖分析工具把依赖关系理清楚。

下面是一个 Unity 编辑器侧的打包脚本示例，放在Assets/Editor/BuildBundles.cs：

// 文件路径：Assets/Editor/BuildBundles.cs using UnityEditor; using UnityEngine; using System.IO; public static class BuildBundles { [MenuItem("TABS/Build Hidden Units Bundles")] public static void BuildWindows() { Build(BuildTarget.StandaloneWindows64, "hidden_units_win"); } [MenuItem("TABS/Build Hidden Units Bundles (Linux)")] public static void BuildLinux() { Build(BuildTarget.StandaloneLinux64, "hidden_units_linux"); } private static void Build(BuildTarget target, string bundleName) { string outDir = Path.Combine(Directory.GetCurrentDirectory(), "dist/bundles"); Directory.CreateDirectory(outDir); var options = BuildAssetBundleOptions.ChunkBasedCompression | BuildAssetBundleOptions.StrictMode; BuildPipeline.BuildAssetBundles( outDir, options, target); Debug.Log($"打包完成，目标平台={target}，输出目录={outDir}"); } }

ChunkBasedCompression对应 LZ4 压缩，特点是加载快、支持随机读取，适合游戏内资源；StrictMode会让构建在发现依赖问题时直接失败而不是静默通过，能把问题提前暴露。构建产物的文件名取决于你在资源上标记的 AssetBundle 名称，建议统一加平台后缀，避免跨平台覆盖。

3.3 隐藏兵种的可见性控制

"隐藏"这个需求在技术上可以拆成三个层面，很多人只做了第一层，结果发现单位还是能被找到。

第一层是菜单过滤。游戏的选人界面会读取一个单位列表，你的注册逻辑要么不把这个单位加进列表，要么给它打一个"未解锁"标记，让 UI 层自己过滤掉。第二层是图鉴过滤。如果游戏有兵种图鉴或资料库，同样要处理，否则玩家在图鉴里翻到了，隐藏就名存实亡。第三层是生成逻辑过滤。有些模式会随机生成单位，如果随机池里包含你的隐藏单位，它就会莫名其妙出现在战场上。

比较稳妥的做法是给每个隐藏单位定义一个解锁条件字段，加载时统一判断：

{ "id": "hidden_void_monk", "displayNameKey": "unit.void_monk.name", "hidden": true, "unlockCondition": { "type": "achievement", "key": "clear_campaign_chapter_3", "fallbackVisible": false }, "faction": "spooky", "stats": { "health": 420, "attackInterval": 1.6, "damage": 35, "moveSpeed": 1.2, "mass": 1.4 }, "bundleName": "hidden_units_win", "prefabPath": "Assets/HiddenUnits/VoidMonk/VoidMonk.prefab", "iconPath": "Assets/HiddenUnits/VoidMonk/icon.png" }

hidden字段决定它是否属于隐藏集合，unlockCondition描述解锁方式，fallbackVisible是兜底开关——当解锁条件判断失败（比如成就系统接口异常）时，是否退化为可见。默认建议设为false，让隐藏单位在异常情况下保持隐藏，避免提前暴露影响体验。

4. 实战：从零添加一个隐藏兵种

4.1 需求拆解与单位设定

动手前先把设计写清楚，这一步比写代码重要。我们要做的这个单位，定位是"第三章通关后的彩蛋"，属于幽灵阵营，特点是血厚、攻速慢、单次伤害高，移动速度偏慢，视觉上是一个飘浮的僧侣。这个设定决定了几个关键参数：血量给到 400 以上（明显高于常规步兵），攻击间隔 1.5 秒以上（体现"慢"），单次伤害 30 到 40（体现"重"），移动速度低于同阵营平均水平。

为什么先写设计再写配置？因为单位的手感来自参数之间的比例关系，而不是单个数值。一个血量 400、攻速 0.3 秒的单位是坦克，一个血量 400、攻速 2 秒的单位是重锤，两者体验完全不同。先在纸面上把这个关系定下来，配置写起来会快很多，后面调平衡也有依据。

4.2 定义单位配置数据

配置采用纯 JSON，一个文件放所有单位，方便统一校验。下面是这次大更新中三个新单位的完整配置示例：

{ "schemaVersion": 2, "units": [ { "id": "hidden_void_monk", "displayNameKey": "unit.void_monk.name", "descKey": "unit.void_monk.desc", "hidden": true, "unlockCondition": { "type": "achievement", "key": "clear_campaign_chapter_3" }, "faction": "spooky", "stats": { "health": 420, "attackInterval": 1.6, "damage": 35, "moveSpeed": 1.2, "mass": 1.4, "attackRange": 1.8 }, "bundleName": "hidden_units_win", "prefabPath": "Assets/HiddenUnits/VoidMonk/VoidMonk.prefab", "iconPath": "Assets/HiddenUnits/VoidMonk/icon.png" }, { "id": "hidden_iron_chorus", "displayNameKey": "unit.iron_chorus.name", "descKey": "unit.iron_chorus.desc", "hidden": true, "unlockCondition": { "type": "achievement", "key": "clear_campaign_chapter_4" }, "faction": "medieval", "stats": { "health": 260, "attackInterval": 0.9, "damage": 18, "moveSpeed": 1.6, "mass": 1.1, "attackRange": 2.4 }, "bundleName": "hidden_units_win", "prefabPath": "Assets/HiddenUnits/IronChorus/IronChorus.prefab", "iconPath": "Assets/HiddenUnits/IronChorus/icon.png" }, { "id": "hidden_tide_herald", "displayNameKey": "unit.tide_herald.name", "descKey": "unit.tide_herald.desc", "hidden": true, "unlockCondition": { "type": "achievement", "key": "win_50_battles" }, "faction": "pirate", "stats": { "health": 180, "attackInterval": 0.6, "damage": 12, "moveSpeed": 2.1, "mass": 0.9, "attackRange": 1.2 }, "bundleName": "hidden_units_win", "prefabPath": "Assets/HiddenUnits/TideHerald/TideHerald.prefab", "iconPath": "Assets/HiddenUnits/TideHerald/icon.png" } ] }

几个字段的设计意图值得说明。schemaVersion是配置格式版本，将来字段结构变化时可以用来做兼容处理，避免老配置在新加载器里报错。displayNameKey用键而不是直接用文本，是为了本地化——文本放在localization.json里，改文案不用动配置。id必须全局唯一，建议加作者前缀或模组前缀，比如yourname_hidden_void_monk，因为多个 MOD 同时加载时，ID 撞车的后果是后加载的覆盖先加载的，症状非常隐蔽。

4.3 编写加载与注册代码

加载器的职责是：读配置 → 校验 → 加载资源包 → 从包里取出预制体 → 生成单位定义 → 注册进游戏。下面是一个结构化的实现示例，其中UnitRegistry和UnitDefinition是本文的示意类名，实际项目中你需要替换成游戏自身的单位模板类型，具体类型名请以你查阅的游戏程序集为准：

// 文件路径：src/TabsHiddenUnits/UnitLoader.cs using System; using System.Collections.Generic; using System.IO; using BepInEx; using Newtonsoft.Json; using UnityEngine; namespace TabsHiddenUnits { [Serializable] public class UnitStats { public float health; public float attackInterval; public float damage; public float moveSpeed; public float mass; public float attackRange; } [Serializable] public class UnlockCondition { public string type; public string key; public bool fallbackVisible = false; } [Serializable] public class UnitConfig { public string id; public string displayNameKey; public string descKey; public bool hidden; public UnlockCondition unlockCondition; public string faction; public UnitStats stats; public string bundleName; public string prefabPath; public string iconPath; } [Serializable] public class UnitConfigRoot { public int schemaVersion; public List<UnitConfig> units; } public static class UnitLoader { private static readonly Dictionary<string, AssetBundle> LoadedBundles = new Dictionary<string, AssetBundle>(); public static List<UnitConfig> LoadConfig(string modDir) { string path = Path.Combine(modDir, "units.json"); if (!File.Exists(path)) { Plugin.Log.LogError($"配置文件不存在: {path}"); return new List<UnitConfig>(); } string json = File.ReadAllText(path); UnitConfigRoot root = JsonConvert.DeserializeObject<UnitConfigRoot>(json); if (root == null || root.units == null) { Plugin.Log.LogError("配置解析失败或 units 为空"); return new List<UnitConfig>(); } if (root.schemaVersion != 2) { Plugin.Log.LogWarning($"配置 schemaVersion={root.schemaVersion}，当前加载器期望 2，可能出现字段缺失"); } return root.units; } public static bool Validate(UnitConfig cfg, out string error) { if (string.IsNullOrEmpty(cfg.id)) { error = "id 为空"; return false; } if (cfg.stats == null) { error = $"{cfg.id}: stats 为空"; return false; } if (cfg.stats.health <= 0) { error = $"{cfg.id}: health 必须大于 0"; return false; } if (cfg.stats.attackInterval <= 0) { error = $"{cfg.id}: attackInterval 必须大于 0"; return false; } if (string.IsNullOrEmpty(cfg.bundleName)) { error = $"{cfg.id}: bundleName 为空"; return false; } error = null; return true; } public static AssetBundle GetBundle(string modDir, string bundleName) { if (LoadedBundles.TryGetValue(bundleName, out AssetBundle cached) && cached != null) { return cached; } string path = Path.Combine(modDir, "bundles", bundleName); if (!File.Exists(path)) { Plugin.Log.LogError($"资源包不存在: {path}"); return null; } AssetBundle bundle = AssetBundle.LoadFromFile(path); if (bundle == null) { Plugin.Log.LogError($"资源包加载失败: {path}，请检查平台与 Unity 版本是否匹配"); return null; } LoadedBundles[bundleName] = bundle; return bundle; } public static void LoadAll(string modDir) { var configs = LoadConfig(modDir); int ok = 0, fail = 0; foreach (var cfg in configs) { if (!Validate(cfg, out string error)) { Plugin.Log.LogError($"配置校验失败: {error}"); fail++; continue; } AssetBundle bundle = GetBundle(modDir, cfg.bundleName); if (bundle == null) { fail++; continue; } // 注意：不同版本 Unity 中 LoadAsset 的泛型参数不同 // 这里用非泛型重载按路径取资源，再转成目标类型 UnityEngine.Object asset = bundle.LoadAsset(cfg.prefabPath); if (asset == null) { Plugin.Log.LogError($"{cfg.id}: 资源包中找不到 {cfg.prefabPath}"); fail++; continue; } Plugin.Log.LogInfo($"{cfg.id}: 资源加载成功 -> {asset.name}"); ok++; // 此处调用游戏自身的单位注册接口，把 cfg 与 asset 组装成单位模板 } Plugin.Log.LogInfo($"单位加载完成: 成功 {ok} 个，失败 {fail} 个"); } } }

这段代码有几个刻意的设计。第一，LoadedBundles做了缓存，同一个包只加载一次，因为 AssetBundle 重复加载会抛异常。第二，Validate把校验和加载分开，校验失败不会中断整个流程，只跳过当前单位，这样即使某个单位配错了，其他单位还能正常进游戏。第三，用LoadAsset的非泛型重载按路径取资源，避免因为泛型类型写错而导致编译期就崩掉——当然前提是你清楚prefabPath必须和打包时的资源路径完全一致，这类路径区分大小写，写错一个字母就是"找不到资源"。

4.4 图标与图鉴条目制作

单位能被生成出来，不代表玩家能"看到"它。图鉴和菜单里的图标是体验的一部分，处理不好会显得很糙。

图标建议统一尺寸，导出为带透明通道的 PNG，宽高比与游戏原有图标保持一致。如果你不确定游戏用的是什么尺寸，可以反编译或者从游戏资源包里取一张原有图标量一下，照着做。更稳妥的方式是在 Unity 里把图标做成 Sprite，随资源包一起打包，避免运行时因为格式不支持而加载失败。

图鉴条目需要三样东西：标题、描述、图标。标题和描述走本地化键，图标走资源路径。描述文案建议写清楚"怎么解锁"和"怎么用"，因为隐藏兵种本身就带一点探索性质，玩家不知道用法的话，解锁了也不会用。

4.5 构建打包与运行验证

打包流程走一遍：在 Unity 里执行前面写的构建脚本，产物输出到dist/bundles/；把units.json、localization.json、DLL、bundles 按第 2.2 节的目录结构摆好；启动游戏，观察日志。

验证要分层做。第一层看日志，确认插件加载成功、配置解析成功、每个单位都打印了"资源加载成功"。第二层看菜单，确认隐藏单位在未解锁状态下不出现。第三层做解锁验证，把解锁条件临时改成"总是成立"，重启游戏，看单位是否出现在列表里。第四层进对局，生成这个单位，观察模型、动画、攻击行为是否正常。

这个分层验证的顺序不能乱。如果一上来就进对局看效果，出问题时你根本分不清是注册失败、资源缺失还是数值异常。按层排查，问题范围会小很多。

5. 数值调参与平衡性验证

5.1 关键字段的量纲统一

调数值踩过最多的坑，是量纲不统一。attackInterval到底是秒还是帧？moveSpeed是米每秒还是格每秒？mass是绝对质量还是相对倍率？这些问题的答案只有一个：看你参照的原有单位用的是什么。最可靠的做法是拿一个官方单位做基准，把它的各项数值和你的单位放在一起比，比例关系对了，绝对值就不会离谱。

举个具体例子。假设官方一个标准步兵的攻击间隔是 1.0，你的新单位设为 1.6，感官上就是"比标准步兵慢 60%"。如果你的单位设成 16，那不是慢，那是永远打不出第二下。同理，mass如果是相对倍率，1.0 是标准，0.9 是略轻，1.4 是明显更重；如果某个引擎里 mass 是绝对数值且单位是千克，那 1.4 就轻得离谱了。先确认量纲，再写数值，能省下大量反复改配置的时间。

5.2 用脚本批量校验配置

单位数量上去之后，人工检查配置基本不现实。写一个校验脚本，每次改完配置跑一遍，把明显错误的配置挡在打包之前。下面是一个 Python 校验脚本示例：

# 文件路径：tools/validate_units.py import json import sys REQUIRED_STATS = [ "health", "attackInterval", "damage", "moveSpeed", "mass", "attackRange", ] def validate(path): with open(path, "r", encoding="utf-8") as f: data = json.load(f) units = data.get("units", []) if not units: print("[ERROR] units 为空") return 1 seen = set() errors = [] for u in units: uid = u.get("id") if not uid: errors.append("存在没有 id 的单位") continue if uid in seen: errors.append(f"{uid}: id 重复") seen.add(uid) stats = u.get("stats", {}) for key in REQUIRED_STATS: if key not in stats: errors.append(f"{uid}: 缺少字段 stats.{key}") continue if not isinstance(stats[key], (int, float)): errors.append(f"{uid}: stats.{key} 类型错误") elif stats[key] <= 0: errors.append(f"{uid}: stats.{key} 必须大于 0，当前 {stats[key]}") health = stats.get("health", 0) dmg = stats.get("damage", 0) interval = stats.get("attackInterval", 1) if interval > 0 and health > 0: dps = dmg / interval # 粗粒度合理性检查：DPS 与血量不应偏离常规区间 if dps > 200: errors.append(f"{uid}: DPS={dps:.1f} 明显偏高，请确认量纲") if health / max(dps, 0.01) > 600: errors.append(f"{uid}: 生存时间过长，可能数值不合理") if errors: for e in errors: print(f"[ERROR] {e}") return 1 print(f"[OK] 共 {len(units)} 个单位，校验通过") return 0 if __name__ == "__main__": sys.exit(validate(sys.argv[1] if len(sys.argv) > 1 else "units.json"))

这个脚本做四件事：检查必填字段是否齐全、检查类型是否正确、检查数值是否为正、用一个粗糙的 DPS 区间做合理性预警。最后那两条预警不是为了精确平衡，而是为了抓住"少写一个零"这种低级错误。跑一遍几秒钟，比进游戏打一局再发现问题快得多。

5.3 对局中的实测方法

数值脚本只能挡住明显错误，真正的平衡还得进游戏验证。建议固定几个测试场景：一对一对比测试（新单位 vs 同阵营标准单位，看胜负和剩余血量）、小规模混战（5v5，看单位在复杂环境下是否正常行动）、大规模压力测试（100v100，看帧率和是否崩溃）。

测试时记下三个数据：击杀耗时、剩余血量比例、单位存活时间。如果新单位在 1v1 中几乎无伤获胜，说明强度超标；如果 5v5 中完全打不出伤害，可能是攻击范围或索敌逻辑有问题，而不一定是数值问题。区分"数值问题"和"逻辑问题"是调平衡的关键，因为调数值很快，改逻辑很慢。

6. 常见问题与排查清单

6.1 高频故障对照表

6.2 排查顺序建议

遇到问题不要东一榔头西一棒子，按固定顺序走：先看日志有没有加载记录，再看配置有没有解析成功，再看资源有没有加载成功，再看注册有没有执行，最后看 UI 层有没有过滤。这个顺序是从底层往上层走，每一层都有明确的可观测点，能最快锁定问题范围。

如果日志里什么都没有，那问题在加载器之外，去查 BepInEx 安装和路径。如果日志里有加载记录但没到"配置解析成功"，那问题在配置文件和 JSON 语法。如果到了"资源加载成功"但游戏里看不到，那问题在注册时机或 UI 过滤。如果全都过了但对局行为异常，那才是数值或逻辑问题。

6.3 避免问题复发的做法

每次发布前固定跑三样东西：配置校验脚本、资源完整性检查、一次干净环境的启动测试。干净环境指的是删掉旧版本模组目录、清空缓存、重新安装一遍。很多"我这里好好的怎么到你这就不行"的问题，根源都是旧文件残留。

另外建议在日志里加一个版本横幅，加载时打印模组名、版本、配置 schemaVersion、加载了多少个单位。玩家反馈问题时，让他把日志前二十行贴出来，你立刻就知道他装的是哪个版本、配置有没有被正确读取。这个成本极低，收益极高。

7. 工程化建议与发布规范

7.1 命名规范与版本管理

单位 ID 用"作者前缀_阵营_单位名"的格式，例如example_spooky_voidmonk。这个规范看着啰嗦，但它同时解决了三个问题：避免与其他 MOD 冲突、从 ID 就能看出归属、排序和检索方便。同理，资源包名加平台后缀，配置文件名加版本语义，units_v2.json之类。

版本号用语义化格式：新增单位升次版本号，修 bug 升修订号，配置结构不兼容变更升主版本号。加载器里读取配置的schemaVersion，遇到不认识的版本给明确警告而不是静默失败。这样玩家装了新版模组配了旧版配置，能第一时间看到提示。

7.2 配置与代码分离的收益

前面反复强调配置和代码分离，这里说清楚为什么。单位数据是高频变动的东西，今天调血量明天改伤害，如果每次都要重新编译 DLL，开发效率会低得可怕，而且每次编译都引入新的出错可能。把数据放 JSON，改完重启游戏就生效，风险面小得多。

更进一步，可以把本地化文本也外置。所有显示文本走键名，文本内容放localization.json，按语言分文件。这样将来要加其他语言支持，只需要加文件，不用改代码。这个设计在你只做中文时看起来是过度设计，但成本其实很低，值得提前做。

7.3 发布前的自检清单

发布前过一遍这个清单：所有单位 ID 唯一且有前缀；配置通过校验脚本；资源包在两个以上平台验证过加载；日志里没有 ERROR 级别输出；隐藏单位在未解锁状态下确实不可见；解锁后确实可见且可用；与其他主流模组同时加载不冲突；README 里写清楚安装方式、卸载方式、已知问题。

最后一条经常被忽略。卸载方式很重要，因为玩家卸载模组后如果存档里还有引用这个单位的对局记录，可能出问题。建议在 README 里明确说明"卸载前请先删除包含自定义单位的存档，或至少不要在存档中保留这些单位"。

8. 继续深入的方向

把这一套跑通之后，你会发现真正的技术空间在"机制"而不在"数值"。同样的模型和血量，加一个"死亡时分裂成两个小单位"的被动，手感就完全不同；加一个"攻击三次后进入狂暴状态"的状态机，战斗节奏就有了层次。这些属于运行时实例层的扩展，需要你理解游戏的状态机和事件系统，难度比改配置高一个量级，但做出来的东西辨识度也高得多。

另一个方向是工具链优化。比如把"改配置 → 校验 → 打包 → 部署到游戏目录"做成一条命令，改完一键测试；比如做一个配置可视化编辑器，用表单替代手写 JSON；比如接入自动化测试，用脚本驱动游戏跑若干场对战，采集胜负数据辅助平衡。这些工具投入一次，后面每个单位都能受益。

还有一个容易被忽视的点是文档。你做的单位，三个月后自己都未必记得参数为什么这么设。给每个单位写一行设计意图，比如"血厚攻慢，定位是前排吸收伤害，用于对抗高攻速低伤害阵容"，比写十行注释有用。这次更新的三个单位，配置里都加了designNote字段，就是给未来的自己看的。

如果你也在做 TABS 的模组，建议从一个最简单的单位开始，把加载链路完整跑通，再逐步加复杂度。整条链路通了之后，剩下的就是设计和美术的活儿了。遇到加载失败、模型发粉、单位不显示这类问题，回到第 6 节按顺序排查，基本都能定位到具体环节。收藏这篇，下次改版本的时候可以直接对照着走一遍。