RA2 INI Data Exporter

这是一个强大且灵活的数据提取工具，专为《红色警戒2：尤里的复仇》及其模组（Mod）设计。它能够深度解析游戏复杂的 INI 文件结构，并将其转换为结构化的 JSON 数据，可用于自动化生成和更新 Mod Wiki（百科网站）的内容。

核心功能

• 深度 INI 解析: 基于专为 RA2 设计的 ra2ini 库，能够健壮地处理非标准格式，包括：
  • [#include] 注册表指令的自动、递归展开。
  • [Derived]:[Base] 形式的节继承。
  • +=Value 形式的注册表键。
• 智能 CSF 集成: 内置 ra2csf 库，可自动解析 .csf 语言文件，将 UIName 等标签直接转换为人类可读的文本。
• 强大的关系追溯: 能够理解并自动追溯 INI 中复杂的数据引用关系，例如 单位 -> 武器 -> 弹头，并将它们构建为嵌套的 JSON 对象。
• 配置驱动: 整个提取过程由易于理解的 YAML 配置文件驱动，无需修改 Python 代码即可轻松调整提取目标、字段和规则。
• 灵活的过滤机制: 通过独立的过滤文件，可以精确地使用白名单/黑名单控制需要提取的单位、建筑或武器。
• 数据转换与美化: 支持将 INI 中的原始字符串转换为数字、布尔值，或通过映射文件将其替换为更友好的名称（例如，将 armor: heavy 转换为 armor: "重型装甲"）。

它是如何工作的？

graph LR
    subgraph "输入 (User Inputs)"
        direction LR
        A["config.yaml<br/>(核心配置)"]
        B["filters.yaml<br/>(过滤规则)"]
        C["mappings.yaml<br/>(名称映射)"]
        D["游戏 INI 文件<br/>(数据源)"]
        E["游戏 CSF 文件<br/>(文本源)"]
    end

    subgraph "输出 (Output)"
        G["wiki_data.json<br/>(结构化数据)"]
    end

    subgraph "处理引擎 (Processing Engine)"
        F["<b>wikiextractor.py</b><br/><br/>- 解析 INI & CSF<br/>- 追溯数据关系<br/>- 应用过滤器和映射"]
    end

    A --> F
    B --> F
    C --> F
    D --> F
    E --> F
    F --> G

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#f9f,stroke:#333,stroke-width:2px
    style D fill:#ccf,stroke:#333,stroke-width:2px
    style E fill:#ccf,stroke:#333,stroke-width:2px
    style F fill:#fff,stroke:#333,stroke-width:2px
    style G fill:#9f9,stroke:#333,stroke-width:4px

Loading

1. 加载配置: 程序读取 config.yaml，了解您的 Mod 路径、提取目标等信息。
2. 解析 INI: 使用 ra2ini 库，从入口 INI 文件开始，完整加载您 Mod 的所有相关规则。
3. 解析 CSF: 使用 ra2csf 库，加载语言文件，准备进行文本替换。
4. 遍历目标: 程序根据 config.yaml 中的 targets 定义，逐一处理（如“步兵”、“载具”）。
5. 过滤与提取: 对每个目标，程序使用 filters.yaml 筛选出您关心的单位，然后根据字段定义，逐一提取数据。
6. 追溯与转换: 在提取过程中，程序会自动追溯数据关系（如查找武器的弹头），并使用 mappings.yaml 和 CSF 数据进行美化和转换。
7. 生成 JSON: 最后，将所有提取并结构化的数据写入一个格式优美的 JSON 文件中。

快速上手

1. 准备环境

• 确保您已安装 Python 3.8 或更高版本。

• 安装必要的依赖库：

  pip install pyyaml

2. 下载项目

将本项目克隆或下载到您的本地计算机。

3. 配置项目

这是最关键的一步。您需要根据您的 Mod 情况修改以下 YAML 文件：

• config.yaml:

  • global.ini_root: 必须修改为您的 Mod 或游戏所在的根目录的绝对路径。
  • global.main_ini_file: 修改为您的主规则文件名 (例如 rulesmd.ini, rules.ini)。
  • global.csf_path: 修改为您的主要语言文件名 (例如 ra2md.csf) 或包含所有语言文件的目录。
  • 根据需要调整 targets 中的提取规则。

• filters.yaml:

  • 在 whitelist 下添加您希望在 Wiki 上展示的单位、建筑等的 INI ID。

• mappings.yaml:

  • 添加或修改键值对，用于将 INI 中的代码（如 heavy）映射为您希望在 Wiki 上显示的文本（如 重型装甲）。

4. 运行提取器

打开终端或命令提示符，进入项目根目录，然后执行：

python wikiextractor.py

执行成功后，您将在项目目录下找到一个名为 wiki_data.json 的文件。这个文件就是您可以直接用于驱动您的 Wiki 网站的结构化数据源。

配置文件详解

config.yaml - 主控制器

• global: 定义全局路径和文件名。
• targets: 一个列表，每一项定义了一类要提取的数据（如步兵）。
  • name: 在最终 JSON 中顶层的键名。
  • from_sections: 定义从哪里获取要处理的节列表。
    • registry: INI 中包含ID列表的注册表节名（如 [InfantryTypes]）。
    • filter_key: 对应 filters.yaml 中的一个键，用于过滤。
  • fields: 定义要为每个单位提取哪些字段。
    • 简单字段: { key: "Cost", type: "integer" }
      • key: INI 中的键名。
      • type: 数据类型，支持 string, integer, float, boolean, string_array, float_array, map, csf。
    • 关系字段: { type: "relation", ... }
      • multiple: false (单关系) 或 true (多关系列表)。
      • key / keys: INI 中包含关系ID的键名（或键名列表）。
      • follow: 定义如何处理追溯到的新节，其内部结构与 fields 相同。

filters.yaml - 过滤器

用于定义白名单和黑名单，保持主配置文件的整洁。结构简单直观：

infantry_units:
  whitelist:
    - E1
    - GHOST
  blacklist:
    - CIV1

mappings.yaml - 美化器

用于将代码化的值转换为人类可读的文本。

armor_types:
  heavy: "重型装甲"
  light: "轻型护甲"

贡献

欢迎提交 Issue 或 Pull Request 来改进此工具。

许可证

本项目采用 MIT 许可证。