Realism 武器附件数值规则指南（v3.15）
<NolebasePageProperties />
本文档与 attachment_rule_ranges.py、generate_realism_patch.py 中的附件规则应用链路保持同步，描述当前附件规则如何命中、如何落地，以及调参时应该看哪些入口。
0. 同步说明
- 当前规则源文件：attachment_rule_ranges.py
- 当前全局夹紧来源：generate_realism_patch.py 中的 MOD_CLAMP_RULES
- 当前应用方式：命中附件档位后使用 ensure_fields=True 先补字段，再做区间采样和夹紧
- 当前版本默认忽略 mod_profile_unresolved 的审计噪音，不把它计入“未能校验附件范围”结果
1. 附件规则是怎么应用的
在 apply_realism_sanity_check() 中，WeaponMod 的处理顺序是：
- 先应用 MOD_CLAMP_RULES 全局夹紧
- 基于 parentId、模板文件、ModType、Name 推断 mod_profile
- 命中 attachment_rule_ranges.py 中的 MOD_PROFILE_RANGES 后，按档位补字段并采样
- 再做一次全局夹紧
- 如果是 muzzle_suppressor 且存在 CanCycleSubs，则强制置为 true
2. 当前主要附件档位
2.1 枪口装置
当前包含以下主档位：
- muzzle_suppressor
- muzzle_suppressor_compact
- muzzle_flashhider
- muzzle_brake
- muzzle_thread
- muzzle_adapter
其中：
- suppressor 类会覆盖 Loudness、Flash、DurabilityBurnModificator、AimSpeed 等字段
- brake / flashhider / thread 更偏中性或取舍型修正
2.2 弹匣
当前采用容量分档：
- magazine_compact：20 发及以下
- magazine_standard：21 到 40 发
- magazine_extended：41 到 60 发
- magazine_drum：61 发及以上
- magazine：容量识别失败时的兼容档
如果输入缺少 Capacity 或 CartridgeMaxCount，通常会回退到 magazine。
2.3 瞄具
当前主要档位：
- scope_magnified
- scope_red_dot
- iron_sight
当前识别策略：
- 名称关键词优先
- 未命中时按模板或 parent 回退
- ScopeTemplates 在无有效关键词时默认归到 scope_red_dot
2.4 枪托与支撑件
当前主要档位：
- stock_fixed
- stock_folding
- stock_ads_support
- stock_buttpad
- stock
- buffer_adapter
- stock_adapter
这些档位主要控制后坐、稳定性、AimSpeed、Handling、Ergonomics 的取舍关系。
2.5 握把、护木、枪管与支架类
当前还覆盖：
- pistol_grip
- foregrip
- barrel_short / barrel_medium / barrel_long
- handguard_short / handguard_medium / handguard_long
- gasblock
- mount
- receiver
- flashlight_laser
其中 barrel 和 handguard 档位通常同时影响 Accuracy、Velocity、HeatFactor、Handling 等组合字段。
3. 当前夹紧边界
附件全局安全边界当前为：
- VerticalRecoil：-35.0 到 35.0
- HorizontalRecoil：-35.0 到 35.0
- Dispersion：-55.0 到 55.0
- Loudness：-45 到 50
- Accuracy：-15 到 15
- LoyaltyLevel：1 到 4
说明：即使单个档位区间更激进，最终仍会被全局夹紧收口。
4. 调参建议
想改附件整体风格
直接改 attachment_rule_ranges.py 中对应 profile 的区间。
想提升命中率
先检查三件事：
- parentId 是否存在且正确
- ModType 是否合理
- Name 是否包含足够明确的关键词
如果仍然命不中，再检查 generator_static_data.py 中的模板映射是否需要补充。
想排查异常输出
推荐顺序：
- 先查看控制台是否提示无法识别 profile
- 运行 audit_output_rule_violations.py
- 确认该条目是否属于 mod_profile_unresolved 的预期忽略项
5. 当前文档策略
本指南说明规则结构与命中逻辑；完整数值区间以 attachment_rule_ranges.py 为准。若代码区间变更，优先更新代码，再回写本文档和 规则文件与文档同步对照清单.md。
贡献者
<NolebaseGitContributors />
文件历史
<NolebaseGitChangelog />