通过逆向解析《深岩银河》的 GVAS 二进制存档文件，在本地 SQLite 与 Streamlit 仪表盘中追踪击杀数、Overclock 进度等统计数据随时间的变化趋势。
# 🪨 DRG Stats Tracker
一个涵盖真实数据工作全流程的项目：**提取**（对二进制存档进行逆向工程） → **转换/加载**（通过 ETL 导入 SQLite） → **可视化**（仪表盘）。游戏本身虽然存储了这些统计数据，但每次只能查看一项，没有历史记录，也没有图表。本项目解决了这个问题。
## ✨ 功能
- 🐛 **各物种击杀数** — 直接从存档中提取的 77 种图鉴生物的击杀排名。
- 📈 **随时间推移的进展** — 跨日期的击杀数、积分、等级和游戏时长。
- ⚙️ **Overclock 进度** — 每种武器已锻造的数量（例如 `100/160`）以及缺失的准确列表。
- 🆕 **“自上次快照以来”** — 从某一天到下一天的增长情况。
- 📸 **自动捕获** — 一个“监视器”在你游玩时自动拍下快照（任务开始 / 结束 / 游戏关闭），无需打开终端。
- 🗂️ **表格 + 导出 CSV** — 按物种搜索并下载数据。
The ⚙️ Overclocks tab — completion per weapon and exactly what's left to forge.
## 🧩 各部分如何协同工作
```
game save translate bytes store history show it nicely
(XXXXX_Player.sav) -> drg_save_parser.py -> snapshot.py -> dashboard.py
│ │ │ │
│ │ drg_stats.db <──────────────-┘
│ │ (SQLite database) (reads the db)
│ guids.json / ▲
│ all_drg_enemies.json │
└──────────────────────────────────── watcher.py (snapshots on its own while you play)
```
- **`drg_save_parser.py`** 读取二进制存档（无外部依赖）。
- **`snapshot.py`** 使用解析器拍下“快照”并存储（每天一次）。
- **`watcher.py`** 监视存档，并在你游玩时自动调用快照。
- **`dashboard.py`** 读取数据库（以及用于 overclock 的存档）并绘制图表。
- **`guids.json` / `all_drg_enemies.json`** 将内部代码（GUID）转换为名称。
## 🚀 入门指南（适用于任何 PC，配置简单）
**前提条件：** 已安装 [Python 3.10+](https://www.python.org/downloads/)（在 Windows 安装程序中勾选“Add Python to PATH”）。
```
# 1. Clone 仓库
git clone https://github.com/gilas-byte/drg-stats-tracker.git
cd drg-stats-tracker
# 2. 获取第一个快照（自动查找 save 并创建数据库）
python snapshot.py
# 3. 打开 dashboard
# Windows: 双击 "abrir_dashboard.bat"
# 任意 OS（手动）：
pip install streamlit
streamlit run dashboard.py
```
First run — double-click abrir_dashboard.bat and the panel opens.
只有 `dashboard.py` 需要外部库（**Streamlit**；自带 pandas 和 altair）。解析器、快照和监视程序运行在**纯 Python** 环境下。
## 🤖 自动捕获
为了让你无需手动拍摄快照，**监视器**（`watcher.py`）会通过 Steam 随游戏一起启动，并自动拍下快照（在打开时、任务结束时、关闭时）。
1. 运行 **`configurar_steam.bat`**（双击）—— 它会根据你电脑的路径构建命令行，并**将其复制到剪贴板**。
2. 在 Steam 中：**DRG → 属性 → 常规 → 启动选项** → 使用 `Ctrl+V` 粘贴。
3. 点击 **▶ 运行**。大功告成 —— 历史记录会自动填充。
Setup — run configurar_steam.bat, then paste into Steam → Launch Options.
数据库体积很小：如果没有任何变化，就不会写入数据（去重）；而且每天最多只保留**一次快照**（更新为一天结束时的状态），因此日常比较结果非常清晰。
## 🔄 保持更新
当此代码库获得新代码时，只需一步即可完成更新 —— 而且**绝不会触碰你的数据**：数据库（`drg_stats.db`）、日志和 `.sav` 文件已被 gitignored，因此你的历史记录和快照在更新后依然完好无损。
- **Windows：** 双击 **`atualizar.bat`** —— 它会为你运行 `git pull`。
- **任何操作系统（手动）：** `git pull`
仪表盘也会**自行检查**：当 GitHub 上存在更新版本时，侧边栏会出现 **🔔 更新可用** 的通知（最多每小时检查一次）。
## 🧠 逆向工程的原理
存档是一个 **GVAS** 文件（Unreal Engine 的二进制格式）：约 140 万个原始字节，没有说明文档。弄清楚每个数据块的含义完全靠手工完成。
👉 **完整的解释，从绝对的零基础（逐个字节）开始，都在
[`logica.md`](docs/logica.md) 中** —— 即使你从未编写过代码，也值得一读。
已解码部分的亮点：
- **FString**（带有长度前缀的字符串）以及如何通过**精确编码**而不是通过子字符串来查找属性（这样 `Level` 就不会在 `RetiredCharacterLevels` 中被错误匹配）。
- **`EnemiesKilled`** — 一个 `MapProperty`，包含 `GUID (16 bytes) → 计数`，共 77 个物种。
- 怪物名称是通过**根据击杀数进行 JOIN** 发现的（游戏内图鉴 × 存档）。
- **等级和晋升** 是**派生**的（根据职业区块 + XP 表计算得出），而不是存储的。
- **“已完成任务” (445) ≠ “游玩场次” (504)** — 前者位于 `MissionStatsSave` 区块中，按职业求和。
- **Overclock**（`ForgedSchematics`）与 `guids.json` 交叉引用 → 每种武器的进度。
## 📁 项目结构
```
drg_save_parser.py # reads the binary save (GVAS) -> organized data. Stdlib only.
snapshot.py # takes the "snapshot" and stores it in SQLite (1/day). Finds the save.
watcher.py # watches the save and calls the snapshot while you play.
dashboard.py # Streamlit panel: kills, progress, overclocks, table, CSV.
drg_watcher_launch.bat # Steam launcher (starts the watcher + the game).
configurar_steam.bat # generates the Launch Options line and copies it to the clipboard.
abrir_dashboard.bat # double-click opens the panel (installs Streamlit the first time).
atualizar.bat # double-click updates the project (git pull); keeps your data.
guids.json # GUID -> overclock/cosmetic (weapon, name, cost). The "catalog".
all_drg_enemies.json # GUID -> enemy name (the 77 species).
drg_stats.db # the database (generated; not under version control).
media/ # GIFs used in this README.
.streamlit/
└─ config.toml # the dark "cave" theme of the panel.
docs/
├─ logica.md # the reverse-engineering logic explained from scratch.
└─ claude_public.md # the full technical "map" of the project (decisions, gotchas, lessons).
```
## ⚠️ 已知限制
- **装饰品** 仍然是一个**估算值**：DRG 中的外观解锁有多个来源，当前的计算可能低于实际数量。不过，Overclock 是可靠的。
- 一些怪物名称是通过排除法推断出来的；并且有 4 对具有相同计数的生物存在模糊匹配（详见 `claude_public.md`）。
- **Game Pass/Microsoft Store** 版本的存档无法被自动检测（请使用 `DRG_SAVE`）。
## 🛠️ 构建技术
Python（标准库：`struct`、`sqlite3`、`pathlib`…） · **SQLite** · **Streamlit** · **Altair**
· **pandas**。读取存档不需要任何依赖 —— 纯 Python。
## 📜 免责声明
这是一个粉丝项目，**非官方**，且与 Ghost Ship Games **没有任何关联**。“Deep Rock Galactic” 及其资产归其所有者所有。本项目仅在本地**读取**你自己的存档（从不修改游戏存档）。使用风险自负。
Rock and Stone! ⛏️🍺
# 🪨 DRG Stats Tracker (PT-BR)
一个涵盖真实数据工作全流程的项目：
**提取**（对二进制存档进行逆向工程） → **转换/加载**（通过 ETL 导入 SQLite） → **可视化**（仪表盘）。游戏本身虽然存储了这些统计数据，但每次只能查看一项，没有历史记录，也没有图表。本项目解决了这个问题。
## ✨ 功能
- 🐛 **各物种击杀数** — 直接从存档中提取的 77 种图鉴生物的击杀排名。
- 📈 **随时间推移的进展** — 跨日期的击杀数、积分、等级和游戏时长。
- ⚙️ **Overclock 进度** — 每种武器已锻造的数量（例如 `100/160`）以及缺失的准确列表。
- 🆕 **“自上次快照以来”** — 从某一天到下一天的增长情况。
- 📸 **自动捕获** — 一个“监视器”在你游玩时自动拍下快照（任务开始 / 结束 / 游戏关闭），无需打开终端。
- 🗂️ **表格 + 导出 CSV** — 按物种搜索并下载数据。
A aba ⚙️ Overclocks — progresso por arma e exatamente o que falta forjar.
## 🧩 各部分如何协同工作
```
save do jogo traduz bytes guarda histórico mostra bonito
(XXXXX_Player.sav) -> drg_save_parser.py -> snapshot.py -> dashboard.py
│ │ │ │
│ │ drg_stats.db <──────────────-┘
│ │ (banco SQLite) (lê o banco)
│ guids.json / ▲
│ all_drg_enemies.json │
└──────────────────────────────────── watcher.py (tira foto sozinho ao jogar)
```
- **`drg_save_parser.py`** 知道如何读取二进制存档（无外部依赖）。
- **`snapshot.py`** 使用解析器拍下“快照”并写入数据库（每天一次）。
- **`watcher.py`** 监视存档，并在你游玩时自动调用快照。
- **`dashboard.py`** 读取数据库（以及用于 overclock 的存档）并绘制图表。
- **`guids.json` / `all_drg_enemies.json`** 将内部代码（GUID）转换为名称。
## 🚀 入门指南（适用于任何 PC，配置简单）
**前提条件：** 已安装 [Python 3.10+](https://www.python.org/downloads/)（在 Windows 安装程序中勾选“Add Python to PATH”）。
```
# 1. Clone o repositório
git clone https://github.com/gilas-byte/drg-stats-tracker.git
cd drg-stats-tracker
# 2. 拍摄第一张照片（自动找到存档并创建数据库）
python snapshot.py
# 3. 打开面板
# Windows：双击 "abrir_dashboard.bat"
# 任意 OS（手动）：
pip install streamlit
streamlit run dashboard.py
```
Primeira vez — duplo clique em abrir_dashboard.bat e o painel abre.
只有 `dashboard.py` 需要外部库（**Streamlit**；自带 pandas 和 altair）。解析器、快照和监视程序运行在**纯 Python** 环境下。
## 🤖 自动捕获（绝妙之策）
为了让你无需手动拍摄快照，**监视器**（`watcher.py`）会通过 Steam 随游戏一起启动，并自动拍下快照（在打开时、任务结束时、关闭时）。
1. 运行 **`configurar_steam.bat`**（双击）—— 它会根据你电脑的路径构建命令行，并**将其复制到剪贴板**。
2. 在 Steam 中：**DRG → 属性 → 常规 → 启动选项** → 使用 `Ctrl+V` 粘贴。
3. 点击 **▶ 运行**。大功告成 —— 历史记录会自动填充。
Setup — rode configurar_steam.bat e cole em Steam → Opções de Inicialização.
数据库不会膨胀：如果没有任何变化，就不会写入数据（去重）；而且每天最多只保留**一次快照**（更新为一天结束时的状态），因此日常比较结果非常清晰。
## 🔄 保持更新
当此代码库获得新代码时，只需一步即可完成更新 —— 而且**绝不会触碰你的数据**：数据库（`drg_stats.db`）、日志和 `.sav` 文件已被 gitignored，因此你的历史记录和快照在更新后依然完好无损。
- **Windows：** 双击 **`atualizar.bat`** —— 它会为你运行 `git pull`。
- **任何操作系统（手动）：** `git pull`
仪表盘也会**自行检查**：当 GitHub 上存在更新版本时，侧边栏会出现 **🔔 更新可用** 的通知（最多每小时检查一次）。
## 🧠 逆向工程的原理
存档是一个 **GVAS** 文件（Unreal Engine 的二进制格式）：约 140 万个原始字节，没有说明文档。弄清楚每个数据块的含义完全靠手工完成。
👉 **完整的解释，从绝对的零基础（逐个字节）开始，都在
[`logica.md`](docs/logica.md) 中** —— 即使你从未编写过代码，也值得一读。
已解码部分的亮点：
- **FString**（带有长度前缀的字符串）以及如何通过**精确编码**而不是通过子字符串来查找属性（这样 `Level` 就不会在 `RetiredCharacterLevels` 中被错误匹配）。
- **`EnemiesKilled`** — 一个 `MapProperty`，包含 `GUID (16 bytes) → 计数`，共 77 个物种。
- 怪物名称是通过**根据击杀数进行 JOIN** 发现的（游戏内图鉴 × 存档）。
- **等级和晋升** 是**派生**的（根据职业区块 + XP 表计算得出），而不是存储的。
- **“已完成任务” (445) ≠ “游玩场次” (504)** — 前者位于 `MissionStatsSave` 区块中，按职业求和。
- **Overclock**（`ForgedSchematics`）与 `guids.json` 交叉引用 → 每种武器的进度。
## 📁 项目结构
```
drg_save_parser.py # lê o save binário (GVAS) -> dados organizados. Só stdlib.
snapshot.py # tira a "foto" e grava no SQLite (1 por dia). Acha o save sozinho.
watcher.py # vigia o save e chama o snapshot sozinho enquanto você joga.
dashboard.py # painel Streamlit: kills, evolução, overclocks, tabela, CSV.
drg_watcher_launch.bat # lançador pra Steam (sobe o vigia + o jogo).
configurar_steam.bat # gera a linha das Launch Options e copia pro clipboard.
abrir_dashboard.bat # duplo clique abre o painel (instala o Streamlit na 1ª vez).
atualizar.bat # duplo clique atualiza o projeto (git pull); preserva seus dados.
guids.json # GUID -> overclock/cosmético (arma, nome, custo). O "catálogo".
all_drg_enemies.json # GUID -> nome do bicho (as 77 espécies).
drg_stats.db # o banco (gerado; fora do controle de versão).
media/ # GIFs usados neste README.
.streamlit/
└─ config.toml # tema escuro "caverna" do painel.
docs/
├─ logica.md # a lógica da engenharia reversa explicada do zero.
└─ claude_public.md # o "mapa" técnico completo do projeto (decisões, gotchas, aulas).
```
## ⚠️ 已知限制
- **装饰品** 仍然是一个**估算值**：DRG 中的外观解锁有多个来源，当前的计算可能低于实际数量。不过，Overclock 是可靠的。
- 一些怪物名称是通过排除法推断出来的；并且有 4 对具有相同计数的生物存在模糊匹配（详见 `claude_public.md`）。
- **Game Pass/Microsoft Store** 版本的存档无法被自动检测（请使用 `DRG_SAVE`）。
## 🛠️ 构建技术
Python（标准库：`struct`、`sqlite3`、`pathlib`…） · **SQLite** · **Streamlit** · **Altair**
· **pandas**。读取存档不需要任何依赖 —— 纯 Python。
## 📜 免责声明
这是一个粉丝项目，**非官方**，且与 Ghost Ship Games **没有任何关联**。“Deep Rock Galactic” 及其资产归其所有者所有。本项目仅在本地**读取**你自己的存档（从不修改游戏存档）。使用风险自负。
Rock and Stone! ⛏️🍺