Norvinsk Stalker知识库

切换主题

EFT 现实主义数值生成器使用指南（v3.15） ​

<NolebasePageProperties />

本文档说明当前生成器的输入格式、处理流程、规则入口、输出策略，以及审计与回归测试的配套用法。

1. 工具作用 ​

generate_realism_patch.py 会读取 input/ 中的物品数据，结合 现实主义物品模板/ 重建 Realism 补丁对象，并把结果输出到 output/。

当前版本具备以下特征：

  • 支持 CURRENT_PATCH、STANDARD、CLONE、ITEMTOCLONE、VIR、TEMPLATE_ID 六类输入。
  • 输出只按源文件导出，并保留 input/ 相对目录结构。
  • 每次运行前自动清空 output/，避免旧结果混入。
  • 武器、附件、弹药规则分别由独立规则文件维护。
  • 静态映射与默认模板已拆分到 generator_static_data.py。
  • 审计脚本与名称回归测试已纳入正式工作流。

2. 环境要求 ​

  • Python 3.8 及以上
  • 建议使用项目内 .venv
  • Windows 可直接双击 现实主义数值生成器.bat

命令行推荐写法：

powershell
.\.venv\Scripts\python.exe generate_realism_patch.py

3. 当前目录职责 ​

  • generate_realism_patch.py：主流程，负责识别、构建、规则应用、导出
  • generator_static_data.py：静态映射、默认模板、特殊字段配置
  • weapon_rule_ranges.py：武器一级基础区间
  • weapon_refinement_rules.py：武器口径与枪托二级修正
  • attachment_rule_ranges.py：附件档位规则
  • ammo_rule_ranges.py：弹药三层规则
  • audit_output_rule_violations.py：输出审计
  • tests/test_name_extraction.py：名称回填回归测试
  • input/：输入数据
  • output/：生成结果
  • audit_reports/：审计报告输出目录

4. 快速开始 ​

方式 A：双击批处理 ​

  1. 将待处理 JSON 放入 input/
  2. 双击 现实主义数值生成器.bat
  3. 在 output/ 查看结果

方式 B：命令行运行 ​

powershell
.\.venv\Scripts\python.exe generate_realism_patch.py

5. 输入格式 ​

脚本会自动识别以下格式：

5.1 CURRENT_PATCH ​

  • 特征：包含 $type 与 ItemID
  • 处理方式：直接以输入对象为基线重算与校验

5.2 STANDARD ​

  • 特征：包含 parentId 或 itemTplToClone
  • 处理方式：解析 parentId，再按模板或默认模板构建

5.3 CLONE ​

  • 特征：包含 clone
  • 处理方式：优先按模板查找，必要时递归解析同文件引用链

5.4 ITEMTOCLONE ​

  • 特征：包含 ItemToClone
  • 处理方式：通过常量或映射推断类型，再按模板重建

5.5 VIR ​

  • 特征：包含 item._id 与 item._parent
  • 处理方式：提取 item 节点，统一归一化后走主流程

5.6 TEMPLATE_ID ​

  • 特征：包含 TemplateID 或模板直接引用
  • 处理方式：直接按模板构建基线对象

6. 输出规则 ​

  • 输出根目录固定为 output/
  • 目录结构与 input/ 保持一致
  • 每次运行前会清空 output/

输出文件命名：

  • 默认：原文件名_realism_patch.json
  • 若某源文件中 CURRENT_PATCH 占比大于 50%：保持原文件名输出

7. 核心处理流程 ​

当前生成器遵循“识别 -> 构建 -> 合并 -> 校验 -> 导出”的流水线：

  1. 递归扫描 input/ 下所有 JSON
  2. 逐文件逐条目识别格式
  3. 提取统一 item_info
  4. 依据模板、默认模板和静态映射构建基线补丁
  5. 合并输入属性
  6. 进入 apply_realism_sanity_check() 做规则校验
  7. 按物品类型统计，并按源文件聚合
  8. 清空 output/ 后导出

8. 规则应用顺序 ​

在 apply_realism_sanity_check() 中，当前顺序为：

  1. 补齐必填字段
  2. 应用材质、尺寸、枪管长度等启发式预处理
  3. 做全局基础夹紧
  4. 按物品类型进入专项规则：
    • Gun：weapon_rule_ranges.py -> weapon_refinement_rules.py
    • WeaponMod：attachment_rule_ranges.py
    • Ammo：ammo_rule_ranges.py
    • Gear：仅应用当前 Gear 夹紧规则
  5. 做最终安全兜底

9. 调参入口 ​

9.1 武器 ​

改 weapon_rule_ranges.py：调整一级基础档位。

改 weapon_refinement_rules.py：调整口径修正、枪托修正和关键词映射。

9.2 附件 ​

改 attachment_rule_ranges.py：调整附件档位区间。

补充说明：附件规则应用启用了 ensure_fields=True，缺失字段会先补种子值再采样。

9.3 弹药 ​

改 ammo_rule_ranges.py：

  • AMMO_PROFILE_RANGES：第一层口径基础区间
  • AMMO_PENETRATION_TIERS / AMMO_PENETRATION_MODIFIERS：第二层穿深修正
  • AMMO_SPECIAL_KEYWORDS / AMMO_SPECIAL_MODIFIERS：第三层弹种型号修正

9.4 静态映射 ​

改 generator_static_data.py：

  • PARENT_ID_TO_TEMPLATE：parentId 到模板文件映射
  • ITEM_TYPE_NAME_TO_ID：字符串类型名到标准 ID 的映射
  • DEFAULT_*_TEMPLATE：默认模板
  • MOD_TYPE_SPECIFIC_ATTRS：特殊 ModType 补字段

10. 审计与回归测试 ​

审计输出 ​

powershell
.\.venv\Scripts\python.exe audit_output_rule_violations.py

默认会：

  • 扫描 output/ 下全部结果
  • 输出 audit_reports/output_rule_audit.json
  • 在终端打印违规与警告摘要

当前审计策略补充：

  • consumable/cosmetic 不作为规则审计重点
  • mod_profile_unresolved 不计入附件未命中警告

名称回归测试 ​

powershell

.\.venv\Scripts\python.exe -m unittest tests.test_name_extraction

覆盖范围：

  • CLONE 的 locales 名称回填
  • STANDARD 的 locales 名称回填
  • VIR 优先使用 item._name
  • ITEMTOCLONE 的 LocalePush 回填
  • CURRENT_PATCH 的 Name / locales 优先级
  • 审计器回读源名称逻辑

11. 常见问题 ​

输出为空 ​

  • 检查 input/ 是否包含合法 JSON
  • 检查输入是否满足支持格式之一

部分物品被跳过 ​

  • 先查看终端中的跳过原因
  • 常见原因是 parentId 缺失、模板找不到、格式不可识别

瞄具分类不稳定 ​

  • 优先检查 Name 关键词是否足够明确
  • 当前 sight 规则是“名称关键词优先，未命中时再回退模板/parent，ScopeTemplates 默认 red dot”

弹匣档位异常 ​

  • 检查是否有 Capacity 或 CartridgeMaxCount
  • 缺少容量字段时会回退到 magazine 标准兼容档

为什么 README 说优先改配置文件，不建议改主脚本 ​

  • 因为大多数调参都已经外置
  • 主脚本现在主要负责流程编排，直接改它更容易引入回归

12. 推荐维护顺序 ​

  1. 先小样本跑通生成
  2. 调整规则文件
  3. 重新生成并查看 output/
  4. 跑审计脚本
  5. 必要时跑名称回归测试
  6. 最后再处理全量输入

贡献者 ​

<NolebaseGitContributors />

文件历史 ​

<NolebaseGitChangelog />

用 ♥ 撰写

CC BY-SA 4.0 © 2022-PRESENT Nólëbase 的创作者们