# dump.txt 结构化索引 — 使用文档

`dump.txt` 是 Unispect v0.2.4.0 生成的 IL2CPP 类布局 dump（15.8 万行 / 7MB）。
本工具将其解析为 SQLite 数据库 `dump_index.db`，提供毫秒级类型 / 字段 / 偏移检索，
替代对原始文本的暴力搜索。

---

## 1. 快速开始

```powershell
# 构建索引（默认输入 F:\desktop\Release\dump.txt，输出 dump_index.db）
python build_index.py

# 自定义路径
python build_index.py D:\other\dump.txt D:\other\dump_index.db

# 查询统计
python query_index.py stats
```

构建耗时约 1.5 秒，输出：

```
types   = 15137          # class 11118 / interface 1118 / struct 1998 / enum 903
fields  = 143599         # static 12350 / const 17693
anomaly = 0              # 无法解析的行数（应为 0）
```

---

## 2. 数据库结构（schema）

```sql
CREATE TABLE types (
    id        INTEGER PRIMARY KEY,   -- 类型 ID，查询时可直接用
    kind      TEXT,                  -- class / interface / enum / struct
    name      TEXT,                  -- 原始名（含 -. 前缀与泛型参数，如 -.Player.FirearmController）
    short     TEXT,                  -- 可读短名（去掉 -. 前缀与泛型尾巴，如 Player.FirearmController）
    base_type TEXT,                  -- 基类（接口无基类时为空串）
    line_no   INTEGER,               -- 在 dump.txt 中的行号
    src_order INTEGER                -- 原始顺序
);

CREATE TABLE fields (
    id         INTEGER PRIMARY KEY,
    type_id    INTEGER REFERENCES types(id),  -- 所属类型
    offset_hex TEXT,                           -- 十六进制偏移，如 "1D8"
    offset_dec INTEGER,                        -- 十进制偏移（排序用）
    is_static  INTEGER,                        -- 1 = 静态字段 [S]
    is_const   INTEGER,                        -- 1 = 常量 [C]
    name       TEXT,                           -- 字段名
    field_type TEXT,                           -- 字段类型
    line_no    INTEGER
);

-- FTS5 全文索引（按 rowid 关联）
CREATE VIRTUAL TABLE types_fts  USING fts5(name, short, base_type, ...);
CREATE VIRTUAL TABLE fields_fts USING fts5(name, field_type, ...);
```

字段行格式还原（与 dump.txt 一致）：

```
    [偏移][S|C] 字段名 : 字段类型
    [1D8] CoverStruct : -.GStruct13       ← 普通字段
    [00][S] staticVar : Int32             ← 静态字段
    [00][C] TooLittle : System.Int32      ← 枚举常量 / const
```

---

## 3. 查询命令手册

所有命令：`python query_index.py <命令> [关键词] [--limit N]`

### 3.1 统计总览

```powershell
python query_index.py stats
```

输出类型总数、各类别数量、字段最多的 TOP10 类型（可直接拿 ID 去展开）。

### 3.2 按类型名搜索

```powershell
python query_index.py type Player
python query_index.py type "GClass" --limit 50
```

模糊匹配 `name` 与 `short`，按字段数降序排列，便于快速定位"大头"类。

### 3.3 按基类搜索（继承关系）

```powershell
python query_index.py base MonoBehaviour
python query_index.py base "GClass429"
```

找出所有直接继承自某基类的类型。

### 3.4 全局搜字段名

```powershell
python query_index.py field Health
python query_index.py field "k__BackingField" --limit 100
```

跨所有类型搜索字段名，输出含所属类型、偏移、类型。

### 3.5 按字段类型搜索

```powershell
python query_index.py ftype "List<"
python query_index.py ftype "System.Action"
```

找出所有声明为该类型的字段（如所有 `List<Int32>` 字段）。

### 3.6 展开一个类型的全部字段

```powershell
python query_index.py show 13764          # 按 ID
python query_index.py show EFT.Player     # 按名字（唯一匹配时）
```

输出该类型所有字段：偏移、S/C 标记、字段名、类型。按偏移升序。

### 3.7 还原原始 dump 格式

```powershell
python query_index.py dump 12702
```

按 dump.txt 原样格式输出整个类型块，便于与原文对比或导出。

### 3.8 通用选项

| 选项 | 说明 | 默认 |
|---|---|---|
| `--limit N` | 搜索结果上限 | 20 |
| `--db PATH` | 指定索引库路径 | `dump_index.db` |

---

## 4. 高级用法：直接查 SQLite

不经过 CLI，直接用 Python / sqlite3 查询：

```powershell
python -c "
import sqlite3
con = sqlite3.connect(r'F:\desktop\CFramework\dump_index.db')
# 1. 找某类型所有字段
for r in con.execute('''
    SELECT offset_hex, name, field_type FROM fields
    WHERE type_id = (SELECT id FROM types WHERE name='EFT.Player')
    ORDER BY offset_dec'''):
    print(r)
"
```

常用 SQL 片段：

```sql
-- 同偏移字段（union/variant 布局分析）
SELECT f.type_id, t.name, f.offset_hex, f.name, f.field_type
FROM fields f JOIN types t ON t.id=f.type_id
WHERE f.offset_hex='00' AND f.is_static=0
GROUP BY f.type_id HAVING COUNT(*)>1;

-- 继承链：所有 EFT.Player 的派生类
SELECT id, name, base_type FROM types WHERE base_type LIKE '%Player%';

-- FTS 快速搜索（token 级，比 LIKE 快）
SELECT t.id, t.name
FROM types_fts JOIN types t ON t.id = types_fts.rowid
WHERE types_fts MATCH 'player';

-- 某类型静态字段清单
SELECT offset_hex, name, field_type FROM fields
WHERE type_id=13764 AND is_static=1 ORDER BY offset_dec;
```

---

## 5. 标记说明

| 标记 | 含义 |
|---|---|
| `[S]` | Static 静态字段（`is_static=1`） |
| `[C]` | Constant 常量 / 枚举值（`is_const=1`） |
| 无标记 | 实例字段 |
| 偏移 | 字段在对象内存布局中的偏移（十六进制），`offset_dec` 为其十进制值 |

注意：枚举类型的枚举值在 dump 中也是 `[C]` 行（偏移恒为 `00`），
展开 enum 时看到的 `[00][C] XXX : System.Int32` 就是枚举成员。

---

## 6. 已知限制

1. **dump 不含方法**：Unispect 默认只导出字段布局，索引同样只有字段。
   方法签名 / IL 不在 `dump.txt` 内，无法索引。
2. **异常字符行**：极少数字段名含控制字符（如 `` ` >j\x01 ``），解析时会被跳过，
   构建日志中 `anomaly` 计数反映数量（当前为 0）。
3. **同名类型**：不同命名空间下存在同名类型（如多个 `GClass857`），
   `show` / `dump` 用名字定位时若多匹配会列出候选，请改用 ID 精确指定。
4. **`-.` 前缀**：表示 global namespace 或嵌套类，`name` 保留原始形式，
   搜索时 `short` 列已去掉此前缀，两者都参与匹配。

---

## 7. 常见问题

**Q: 为什么我搜 `type GClass857` 出现多个结果？**
A: 同名类型在多处定义（正常现象），用 `show <id>` 精确定位。

**Q: 想重新生成索引？**
A: 直接重跑 `python build_index.py`，会自动覆盖旧库。

**Q: 查询报"索引不存在"？**
A: 先运行 `python build_index.py`，或确认 `--db` 路径正确。

**Q: 数据库能跨机器用吗？**
A: 能。`dump_index.db` 是纯 SQLite 文件，拷贝即可，无需重装依赖。