SPT现实主义数值范围编辑生成器 v2.1 使用说明
字数
1478 字
阅读时间
6 分钟
本文档对应当前 C# 版项目的实际状态，覆盖 GUI、规则编辑、例外物品管理和补丁生成工作流。
1. 版本定位
- 版本号：v2.1
- 运行形态：独立的 .NET GUI 工具，可打包为完整包或轻量包
- 当前重点：规则编辑、补丁生成、例外物品覆盖全部在同一工程内完成
2. 目录约定
程序默认以仓库根目录为数据根，依赖以下目录：
- input
- RealismItemTemplates
- RealismItemRules
- output
其中：
- RealismItemRules 保存四大类规则，以及 RealismItemRules/item_exceptions.json
- output 保存生成后的补丁结果
3. GUI 工作流
启动 GUI：
powershell
dotnet run --project RealismPatchGenerator.Gui主界面结构：
- 顶部：保存全部、重新加载、生成补丁、语言切换、搜索
- 输出路径右侧：可选 Seed 输入框，留空表示每次生成重新采样，填写固定无符号整数可复现结果；支持一键清空，并可回填最近一次实际使用的 seed
- 左侧：规则分类树
- 中部：规则范围编辑表
- 底部：字段说明、例外总览、运行日志
- 额外入口：“例外物品”窗口用于处理具体 ItemID 的最终字段覆盖
常规使用顺序：
- 重新加载规则，确认当前磁盘状态。
- 在左侧选择分类，在中部调整数值范围。
- 点击保存全部，把规则写回 RealismItemRules 目录。
- 点击生成补丁，把结果输出到 output。
- 如有少数物品必须脱离规则单独处理，再进入“例外物品”窗口补充覆盖。
4. 例外物品管理
例外物品用于处理“某个具体 ItemID 必须保留或强制写入指定字段”的场景。
当前窗口流程：
- 第一步按 Name 只搜索 output 中已经生成出来的物品。
- 载入搜索结果后，右侧自动显示该物品当前顶层字段。
- 在同一编辑区中选择字段、修改字段值，或新增当前物品所属大类允许的字段。
- 点击“新增/修改字段”将当前编辑器中的字段和值写回字段列表。
- 点击“保存物品”把当前 ItemID 的例外配置写入 RealismItemRules/item_exceptions.json。
当前行为约束：
- 新增字段只允许来自当前物品所属大类的字段池
- 建议值范围来自当前最新规则数据，不是写死常量
- 数值在保存时会经过归一化和安全夹紧，避免极端越界
- 输出结构以 RealismItemTemplates 中的对应大类模板为结构标准，最终数值范围以 RealismItemRules 为唯一标准
5. 输出行为
当前生成行为：
- 结果写入 output
- 不会先清空整个输出目录
- 只覆盖本次需要写出的目标文件
- 只有 RealismStandardTemplate 且来源于 input/attatchments、input/gear、input/weapons 的输出文件保持原文件名
- 其他当前支持的输出文件统一为“源文件名 + _realism_patch.json”
- 每次生成都会在规则范围内重新采样，因此同一物品在多次生成之间可能出现不同数值
- 输出顺序会严格保留输入源文件中的条目顺序，方便用户按原始来源人工核对
- 生成器当前直接处理 RealismStandardTemplate、WttArmory_templates、Epic_templates、ConsortiumOfThings_templates、Requisitions_templates、EcoAttachment_templates、Artem_templates、WttStandalone_templates、SptBattlepass_templates、RaidOverhaul_templates、Moxo_Template、Mixed_templates
- RealismStandardTemplate 中允许使用 TemplateID 作为标准模板内部的克隆基底引用；生成时会先展开基底，再输出完整 Realism 结构
- Moxo_Template 的输出 Name 优先取 locales.Name
- Moxo_Template 支持在同一源文件内继续 clone 前面已生成的物品
- Mixed_templates 支持同文件内混合处理 clone + item/items 条目和 direct item/items 条目
- Mixed_templates 中 clone 基底不可用时，会退回 direct item/items 路径构造补丁
- 当前有效生成范围以武器、附件、弹药、装备为主，consumable 不在当前生成链路中
- item_exceptions 会在自动规则处理之后再应用，是最终覆盖层
6. 发布包
- 完整包：无需预装 .NET 运行时，适合直接分发给普通用户。
- 轻量包：不包含运行时，体积更小，目标机器需要预装匹配的 .NET Desktop Runtime。
- 打包脚本位于 scripts/build-release.ps1，可通过 FrameworkDependent 开关生成轻量包。
7. 启动方式
当前推荐入口是 GUI；CLI 保留一键生成补丁入口；artifacts 下也可能存在仅供维护或调查使用的临时 runner。
开发环境下启动 GUI：
powershell
dotnet run --project RealismPatchGenerator.Gui开发环境下使用 CLI 一键生成：
powershell
dotnet run --project .\RealismPatchGenerator.Cli\RealismPatchGenerator.Cli.csprojCLI 可选参数：
[basePath] [outputPath]（位置参数，可省略）--seed <uint>
CLI 职责边界：
- 仅负责补丁生成
- 规则编辑、例外管理、交互式检查等功能统一在 GUI 中进行
如果需要复现某一轮生成结果：
- 在 GUI 的 Seed 输入框中填写固定无符号整数
- 点击生成补丁执行固定 seed 生成
- 需要回到随机模式时清空 Seed 输入框
8. 当前边界
- GUI 仍以中文版体验优先
- GUI 交互自动化测试尚未补齐，当前以核心库与规则逻辑测试为主
- 例外物品窗口已可用，但仍应以真实 output 结果回归验证为准
贡献者
SamuelNOTCuriousMeow