228 lines
6.9 KiB
Markdown
228 lines
6.9 KiB
Markdown
# 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 文件，拷贝即可，无需重装依赖。
|