iDevelopThings/bdo-data-extractor
GitHub: iDevelopThings/bdo-data-extractor
一款纯 Go 编写的零依赖命令行工具，用于将《黑色沙漠 Online》客户端的私有二进制格式逆向解码为结构化 JSON 与图标资源。
Stars: 1 | Forks: 1
# bdo-data-extractor
一个单一、快速、只读的 Go CLI，用于解码 **Black Desert Online** 的客户端
data 文件 —— 包括 `PAZ` 档案、`.bss`/`.dbss` 二进制表、每个物品的
配方 XML 以及 `.loc` 本地化文件 —— 将它们转换为整洁缓存的 JSON（`items.json`、
`recipes.json`）以及物品图标（PNG）。
它还能解码 NPC、刷怪点、地区/节点、钓鱼点以及完整的
**知识/生态**树。
所有数据均来自**您自己安装的游戏文件**。无需爬取数据，也不依赖
第三方数据网站 —— 这个项目的核心在于数据*就在您的客户端中*，
您不应该被别人的网站所限制而无法获取数据。
**唯一的例外**是实时的**中央集市价格**：市场经济是
服务器端且实时的，因此它确实不在客户端中。提取的参考
数据保持 100% 来自客户端，且提取器根本不会进行任何网络调用。
```
// one entry from items.json
{
"id": 9359,
"name": "Balacs Lunchbox",
"icon": "New_Icon/03_ETC/07_ProductMaterial/00009359.dds",
"grade": "yellow",
"category": "Cook",
"marketCategory": "Consumables",
"marketSubCategory": "Food",
"weight": 0.1,
"buyPrice": 38775,
"sellPrice": 1551,
"effects": {
"cooldownMs": 1800000,
"durationMs": 5400000,
"stats": [
{ "stat": "Fishing EXP", "op": "+", "value": 10, "unit": "%", "buff": 55948 },
{ "stat": "Auto-fishing Time", "op": "-", "value": 7, "unit": "%", "buff": 55942 },
{ "stat": "Fishing", "op": "+", "value": 2, "buff": 50675 }
],
"hidden": [ { "stat": "Health EXP", "op": "+", "value": 100, "buff": 50562 } ]
}
}
```
## 制作过程
这里解码的二进制格式**没有任何公开文档** —— 社区网站
只提供处理好的数据，却不告诉你如何自己读取这些文件。整个项目，
包括逆向工程，几乎完全由 **Claude**
（Anthropic 的 AI）在一系列会话中完成，然后**由维护者进行了验证**：
它可以构建、可以运行，并且解码后的数值已经与实时
游戏和社区参考资料进行了交叉比对，以确保正确性。
格式说明特意记录在 **[FORMATS.md](FORMATS.md)** 中 ——
这样下个需要它的人就不必从零开始了。你可以拿去使用、
学习并扩展它。
## 免责声明
## 要求
- **Go 1.26+**（该项目跟进最新的 Go 版本）。该 CLI 是**纯标准库** —— 没有
外部依赖。
- 一份**合法安装的 Black Desert Online 副本**。默认情况下，该工具会查找
标准的 Steam 路径
（`C:\Program Files (x86)\Steam\steamapps\common\Black Desert Online`）；请使用
`--game ` 进行覆盖。默认路径适用于 Windows；在其他平台上请传递 `--game`。
- **Windows** 是受支持的目标平台（这是 BDO 运行的平台）；其他平台可通过
源码构建 —— 欢迎提交 PR 以支持它们。
## 构建与运行
```
go install github.com/idevelopthings/bdo-data-extractor@latest # or, from source: go build -o bdo-data-extractor .
# 解码所有内容 -> ./data/items.json + ./data/recipes.json
bdo-data-extractor build
# 其他命令
bdo-data-extractor icons # decode item icons (DXT .dds) -> ./data/icons/.png (+ zone-category icons -> ./data/icons/zonecategories/)
bdo-data-extractor knowledge-icons # decode knowledge card images -> ./data/knowledge_icons/.png
bdo-data-extractor regionmaps # decode the region masks -> ./data/regionmaps/*.png
bdo-data-extractor loc # dump the entire localization -> ./data/loc_.json
bdo-data-extractor meta # parse the archive index, print a summary
bdo-data-extractor extract # extract decoded archive files whose path contains substr
bdo-data-extractor table # decode one schema-known table -> JSON (stdout)
```
Flags（位置不限）：`--game ` `--out ` `--lang `
`--pretty`（缩进 JSON）。
一次完整的 `build` 会读取每个源表一次，处理约 72,000 个
物品只需几秒钟即可完成。输出是紧凑且确定性的（按 id 排序）。
## 输出
| 文件 | 内容 |
|---|---|
| `data/items.json` | 每个物品：名称、描述、图标路径、等级、类别、**集市类别/子类别**（在上市交易时为真实值，否则针对不可交易装备进行*推导* —— 见 `tradeable`）、**`equipInfo`**（插槽 / 种类 / 类型，加上多插槽时装的 `slots`；`type` = 集市风格的物品类型，即使是像 Tuvala 这样的不可交易物品也会存在）、重量、购买/出售/修理价格、**最大耐久度**、**职业限制**（`classes` —— 缺失 = 所有职业）、**`crystalGroup`**（用于插槽水晶的转换组 + 最大数量）、**`expirationMinutes`**（定时物品）、**`requiredLevel`**、**`maxStack`**、**`dyeParts`**、最大强化、强化曲线、消耗品效果以及获取方式（出售它的 `vendors`、`gatheredFrom`/`gatherNodes`） |
| `data/recipes.json` | 制作配方 `{output, type, station, inputs:[{item,count}]}` —— 烹饪/炼金/加工 **以及房屋制造**（`station` = 工坊，例如 "Jeweler"）；从本地化和基础的每个物品 XML 中合并而来 |
| `data/marketcategories.json` | 中央集市类别树 `[{id, name, subCategories:[{id, name}]}]`，采用游戏的显示顺序（主类别按 id，子类别按子 id）；`id`/子 `id` 与物品作为 `marketCategory`/`marketSubCategory` 携带的值相同 |
| `data/knowledge.json` | 完整的知识/生态数据集 —— `themes`（类别树，`{key,name,parent,item}`）+ `entries`（卡片，`{key,theme,name,description,image,minFavor,maxFavor,interest,item,character}`）；通过名称链接到物品和 NPC |
| `data/mastery.json` | 生活技能**精通产出/产量曲线**，以精通值为键 —— `cooking`/`alchemy`（比率列）+ `processing`（`procRate`，批量处理的 `batch`）。这些是游戏在基础输出 1 之上应用的客户端产出率；每个配方的产量范围本身是服务器端的 |
| `data/manufacture.json` | 来自 `manufacture.bss` 的制造/加工配方 —— `{group, type, success, inputs}`（成功率 + 动作类型；输出是 `group`/ResultDropGroup，在服务器端解析，因此未列出） |
| `data/npcs.json` | NPC `{id, name, title, spawns:[{region, regionName, pos}]}` —— **英文**名称（loc 表 6），包含每个出生点的城镇/区域名称（loc 表 17） |
| `data/regions.json` | 地区/节点 `{key, bounds:{min,max}, spawns:[{key, pos, dialogIndex}]}` —— 每个 NPC/怪物的放置位置 + 世界坐标，以及可用时的地区世界边界 |
| `data/fishingspots.json` | 悬浮钓鱼点的世界位置（客户端；每个地点的鱼类表在服务器端），归属于各个地区 |
| `data/worldmap.json` | 区域地图基础图像 + 世界坐标→图像坐标的转换，以便任何世界坐标数据都可以放置在地图上 |
| `data/zones.json` | 所有 **105** 个怪物区域信息区域，完全独立 —— `name`、`node:{key,name,pos}`、`mainCategory:{id,name,icon}`（区域）+ `subCategories:[{id,name,icon}]`（内容过滤器）、推荐的 `sheet`/`total` AP/DP + `effectiveLimit`/`apApplyPercent`，以及内联解析的列表：`titles[{id,name,desc}]`、`recurringQuests`/`regionQuests[{id,name}]`、`ecology[{id,name}]`（生物知识）、`topography[{id,name}]`（地点知识）、`tags[{key,name,desc,color,fontColor}]`，以及作为物品 id 的战利品 `loot`（→ items.json） |
| `data/icons/.png` | 物品图标，从客户端 DXT 压缩的 `.dds` 解码（通过 `bdo-data-extractor icons`） |
| `data/knowledge_icons/.png` | 知识卡片图像，从 `.dds` 解码（通过 `bdo-data-extractor knowledge-icons`）；每个条目的 `image` 字段是相对路径 |
| `data/regionmaps/*.png` | 解码的区域/领地遮罩图像（通过 `bdo-data-extractor regionmaps`） |
| `data/icons/zonecategories/.png` | 怪物区域信息主/子类别图标，从它们的 UI 图集中裁剪出来（`zones.json` 中的 `icon` id），包含所有三种 UI 状态：`.png`（正常）、`_Over.png`、`_Click.png`；由 `bdo-data-extractor icons` 生成 |
| `data/loc_.json` | 完整的本地化转储，分组为 `table → id → field → text`（通过 `bdo-data-extractor loc`） |
图标以**物品 id** 命名（客户端将它们存储在不相关的图标 id 下），
因此它们可以直接映射回 `items.json`。
## 架构
```
main.go CLI entry point + subcommands (build, icons, loc, meta, table, …)
pipeline/ icon / region-map / knowledge-icon / loc-dump pipelines
internal/
config/ flag parsing + global config
paz/ archive layer: ICE cipher, BDO-LZ, meta index, read-only access
bss/ .bss/.dbss record reader + schema + offset-index + PABR helpers
loc/ languagedata_.loc decoder
tables/ the leaf parsers: items, enchant curves, buffs/skills, recipe XML, npcs,
regions, zones, fishing, region maps, knowledge (mentalcard/mentaltheme)
build/ the assembler: Builder reads sources, joins across tables, writes JSON
(items, recipes, market, world, zones, fishing, knowledge, mastery, caphras)
schema/ declarative table schemas (used by `table`)
jsonio/ buffered + parallel JSON file writer
tex/ DXT1/DXT5/uncompressed DDS -> RGBA
progress/ pipeline progress sink
src/
model/ the unified output structs
models/ base/ref helpers for the output types
recipe/ recipe-classification helpers (extraction / byproduct / imperial)
urn/ stable urn identifiers for output records
utils/ small generic helpers (timing, slices, strings)
```
有关逆向工程的文件格式和
表布局，请参见 **[FORMATS.md](FORMATS.md)**。
## 许可证
[非商业许可证](LICENSE.md) —— 出于任何**非商业**目的，可自由使用、学习、修改和分享；
您不得出售它或利用它赚钱。它仅涵盖本项目的源代码，
不对 Black Desert Online 或 Pearl Abyss 的数据/资产提出任何权利主张，并且按“原样”提供，
**不提供任何保证**。
标签：EVTX分析, Go, Homebrew安装, Ruby工具, 云资产清单, 数据提取, 文件解析, 文档结构分析, 日志审计, 游戏, 逆向工程