[MD]
# Petra
>把 Minecraft 基岩版的世界存档,渲染成一张能在浏览器里缩放浏览的俯视地图——类似 Java 版的 BlueMap,但是给基岩版用的。
单个原生程序,不依赖 Java、Node 或任何运行时。渲染一次,产出一堆瓦片图和一个纯静态的网页,双击打开就能看。
---
## 为什么是它
- **不用装官方 LevelDB**——存档读取是自己实现的只读解析器(SST 表、WAL 日志、MANIFEST),不链接 Google 的 C++ LevelDB 库,不用为了编译它去折腾额外的工具链
- **纯原生二进制**——Rust 编译,跑起来不需要 JVM、不需要 Node、不需要任何解释器
- **多线程渲染**——区块渲染按线程数并行,核心越多渲得越快
- **产出的网页零依赖**——纯 HTML/CSS/JS,双击打开就能看,不需要联网、不需要起服务器、不用装任何东西
---
## 能做什么
- 支持新旧两种子区块格式:1.18+ 的调色板格式和更早的旧版格式,老存档也能渲
- 主世界 / 下界 / 末地三个维度都能渲,自己选渲哪几个
- 方块颜色支持内置颜色表,也可以指向官方资源包(目录、`.zip`、`.mcpack` 都行)取更准的颜色
- 出生点标记(可选,默认关闭)
- 渲染出的地图带缩放金字塔、坐标网格、比例尺,水体有深浅渐变、地形有阴影起伏
- **可扩展**:网页里留了一个事件钩子,不改这个项目一行代码,就能往地图上叠加你自己的标记(玩家位置、自定义地点之类)
---
## 用法
```bash
bedrock-map-renderer --world "存档/Bedrock level" --out ./my-map
```
`--world` 指向存档文件夹(里面能看到 `db/`、`level.dat` 的那一层),`--out` 是输出目录。跑完打开 `my-map/index.html` 就能看地图。
**常用参数**
```
--dimension <列表> 要渲染的维度,逗号分隔,默认只渲主世界
可用值: overworld / nether / end(或 0 / 1 / 2)
--resource-pack <路径> 官方资源包(目录、.zip 或 .mcpack),用于取色
--spawn 从存档读取世界出生点并显示在地图上(默认不读)
--threads <N> 渲染线程数,默认用满 CPU 核心数
--template <目录> 自定义查看器页面(见下面"自定义/扩展")
-h, --help 查看全部参数
--web 启动内置的web服务用于预览渲染后的html
--port 修改预览服务的端口(默认8080)
```
**示例**
```bash
# 三个维度全渲,用官方资源包取色,开启预览服务
bedrock-map-renderer --world "存档/Bedrock level" --out ./my-map \
--dimension overworld,nether,end \
--resource-pack ./bedrock-samples/resource_pack \
--spawn \
--web
```
---
## 自定义 / 扩展
输出的网页由两部分组成:`map-viewer.js`(引擎,负责画瓦片、网格、缩放、维度切换)和 `index.html`(外壳,负责页面布局和按钮)。想要自己的样式,用 `--template` 指向一个你自己写的、带 `<canvas id="map">` 并引入 `map-viewer.js` 的 HTML 文件即可,其余控件(维度按钮、网格开关等)引擎会自动识别、接线。
想在地图上叠加自己的标记(比如玩家实时位置),不需要碰这个项目的代码——引擎每次重绘时会派发一个事件,监听它就能拿到坐标换算工具,往 canvas 上画任何东西:
```js
window.bedrockMap.onRedraw(function (d) {
var p = d.worldToScreen(100, 200); // 世界坐标 (x=100, z=200) → 屏幕像素
d.ctx.fillStyle = "red";
d.ctx.fillRect(p[0] - 4, p[1] - 4, 8, 8);
});
```
这套机制原本是给 [LumaPanel](https://www.minebbs.com/resources/lumapanel.17076/) 用的——它在这上面叠了在线玩家和死亡地点两个图层,渲染器本身完全不知道"玩家""死亡"这些概念的存在。
---
## 常见问题
**渲出来一片空白?**
确认 `--world` 指向的是存档文件夹本身(能看到 `db/` 子目录的那一层),不是它的上一级或者 `db/` 里面。
**指定了多个维度，但是渲染的维度对不上?**
对于未被存档保存的区块都不会渲染，维度也一样，需要玩家进入对应维度进行加载，才能被程序读取到。
**颜色跟游戏里看到的不太一样?**
默认用的是内置颜色表,不是从材质取的。加 `--resource-pack` 指向官方资源包(在 Mojang/bedrock-samples 能下到),配色会准很多。
**很大的存档渲染很慢?**
调大 `--threads`(默认已经是 CPU 核心数,但可以手动设更高试试),或者用 `--dimension` 只渲你需要的维度。
---
## 反馈
用着有问题,或者想扩展点什么,欢迎通过以下方式联系:
- 邮箱:**maskviva@qq.com**
- 或在**讨论区**留言反馈
[/MD]
