高级配置指南（v3.15）

<NolebasePageProperties />

本文档面向需要深度定制生成逻辑的用户，重点说明当前代码结构、推荐修改入口，以及哪些场景才应该动主脚本。

1. 优先改哪里

建议优先改独立配置文件，而不是直接改 generate_realism_patch.py：

• weapon_rule_ranges.py：武器第一层基础区间
• weapon_refinement_rules.py：武器第二层修正与口径关键词
• attachment_rule_ranges.py：附件档位区间
• ammo_rule_ranges.py：弹药三层规则
• generator_static_data.py：静态映射、默认模板、特殊补字段

多数需求都可以在这 5 个文件中完成。

2. 什么场景改 generator_static_data.py

当前这些内容已经不再放在主脚本顶部，而是集中在 generator_static_data.py：

• PARENT_ID_TO_TEMPLATE
• ITEM_TYPE_NAME_TO_ID
• DEFAULT_WEAPON_TEMPLATE / DEFAULT_MOD_TEMPLATE / DEFAULT_AMMO_TEMPLATE / DEFAULT_CONSUMABLE_TEMPLATE
• MOD_TYPE_SPECIFIC_ATTRS

以下情况优先改这里：

• 新增 parentId 到模板文件映射
• 新增字符串物品类型到标准 ID 的映射
• 调整默认模板字段
• 为特定 ModType 增补缺失属性

3. 什么场景才改主脚本

仅当下面这些行为需要变化时，才建议改 generate_realism_patch.py：

• 新增一种输入结构
• 调整格式识别优先级
• 调整输出策略或 CURRENT_PATCH 占比阈值
• 调整启发式逻辑（材质、尺寸、枪管长度等）
• 调整全局夹紧或规则应用顺序

4. 当前输出策略

当前版本只按源文件导出，并保留 input/ 目录结构：

• 默认输出：原文件名_realism_patch.json
• 当文件内 CURRENT_PATCH 占比大于 50%：输出保持原文件名

运行时会先清空 output/，再导出新结果。

5. 常见高级调参点

5.1 武器层

在 weapon_refinement_rules.py 中：

• 调 WEAPON_CALIBER_RULE_MODIFIERS 改口径差异
• 调 WEAPON_STOCK_RULE_MODIFIERS 改枪托形态差异
• 调 CALIBER_PROFILE_KEYWORDS 补充新口径识别

5.2 附件层

在 attachment_rule_ranges.py 中：

• 改 MOD_PROFILE_RANGES 的区间
• 若附件总是落到兼容档，先检查输入里的 parentId、ModType、Name
• 若是新增 parent 映射问题，再回到 generator_static_data.py 补模板映射

5.3 弹药层

在 ammo_rule_ranges.py 中：

• 第一层：AMMO_PROFILE_RANGES 决定口径基础风格
• 第二层：AMMO_PENETRATION_TIERS 与 AMMO_PENETRATION_MODIFIERS 决定穿深分层
• 第三层：AMMO_SPECIAL_KEYWORDS 与 AMMO_SPECIAL_MODIFIERS 决定型号差异

5.4 Gear 层

当前 Gear 还没有独立 profile 规则文件，主流程仅对以下字段做夹紧：

• ReloadSpeedMulti：0.85 到 1.25
• Comfort：0.6 到 1.4
• speedPenaltyPercent：-40 到 10

如果未来要给 Gear 建立更细的规则体系，建议新增独立配置文件，而不是继续把 Gear 规则堆回主脚本。

6. 调试与验证

推荐每次改完规则都做三步：

1. 先跑小样本生成
2. 再跑 audit_output_rule_violations.py
3. 如改到名称提取或格式兼容，再跑 tests/test_name_extraction.py

命令示例：

.\.venv\Scripts\python.exe generate_realism_patch.py
.\.venv\Scripts\python.exe audit_output_rule_violations.py
.\.venv\Scripts\python.exe -m unittest tests.test_name_extraction

7. 当前不建议回退的旧做法

• 不再建议恢复按 weapons_realism_patch.json 这类大类聚合输出
• 不再建议把静态映射重新塞回主脚本顶部
• 不再建议把一次性校验脚本或哈希快照文件长期留在根目录

8. 发版前最小检查

1. 规则文件是否与对应规则指南一致
2. generator_static_data.py 的映射变更是否同步到了使用文档
3. README、快速入门、详细说明是否仍与当前输出策略一致
4. CHANGELOG.md、批处理横幅、主脚本横幅是否同步了版本号

贡献者

<NolebaseGitContributors />

文件历史

<NolebaseGitChangelog />