BedrockMap

# 使用子模块克隆
git clone --recursive https://github.com/bedrock-dev/BedrockMap.git

# 构建 BedrockMap
.\scripts\build.ps1 -buildBL

# 1. 克隆仓库
git clone --recursive https://github.com/bedrock-dev/BedrockMap.git

# 2. 编译 bedrock-level 静态库
cd bedrock-level
.\build.ps1

# 3. 编译 BedrockMap 主程序
cd ..
.\scripts\build.ps1

# 4. 编译并运行（含翻译更新）
.\scripts\build_run.ps1

BedrockMap/
├── CMakeLists.txt              # 顶层 CMake 构建文件
├── config.ini                  # 运行时配置文件
├── icon.rc                     # Windows 应用程序图标
├── res.qrc                     # 动态生成的 Qt 资源文件
├── README.md
├── TODO.md
│
├── bedrock-level/              # Bedrock 存档数据层（静态库）
│   ├── CMakeLists.txt
│   ├── build.ps1               # 编译脚本
│   ├── libs/                   # 预编译第三方库 (leveldb, zstd)
│   ├── third/                  # 第三方头文件
│   ├── app/                    # 辅助工具
│   │   ├── biome_png.cpp       # 群系颜色导出工具
│   │   ├── level_stater.cpp    # 存档统计工具
│   │   └── missing_color_finder.cpp  # 缺失颜色查找工具
│   ├── src/
│   │   ├── include/            # 头文件
│   │   ├── bedrock_level.cpp   # 存档管理器
│   │   ├── bedrock_key.cpp     # LevelDB Key 编解码
│   │   ├── chunk.cpp           # 区块数据
│   │   ├── sub_chunk.cpp       # 子区块数据
│   │   ├── nbt.cpp            # NBT 标签库
│   │   ├── color.cpp           # 颜色表与颜色计算
│   │   ├── data_3d.cpp         # 3D 数据（群系/高度图）
│   │   ├── actor.cpp           # 实体解析
│   │   ├── player.cpp          # 玩家数据（框架）
│   │   ├── global.cpp          # 全局数据（村庄等）
│   │   ├── level_dat.cpp       # level.dat 解析
│   │   ├── scoreboard.cpp      # 计分板
│   │   └── utils.cpp           # 工具函数
│   ├── tests/                  # Google Test 单元测试
│   │   ├── actor_test.cpp
│   │   ├── bedrock_level_test.cpp
│   │   ├── bit_tools_test.cpp
│   │   ├── chunk_test.cpp
│   │   ├── color_test.cpp
│   │   ├── data3d_test.cpp
│   │   ├── data_dump_test.cpp
│   │   ├── key_test.cpp
│   │   ├── level_dat_test.cpp
│   │   ├── palette_test.cpp
│   │   ├── sub_chunk_test.cpp
│   │   └── utils_test.cpp
│   └── data/colors/            # 方块和群系颜色数据文件
│
├── src/                        # GUI 应用程序
│   ├── include/                # 头文件
│   ├── main.cpp                # 入口
│   ├── mainwindow.cpp/h       # 主窗口
│   ├── leveltabwidget.cpp/h   # 多存档标签页管理
│   ├── levelpagewidget.cpp/h  # 单存档页面
│   ├── maphost.cpp/h          # 地图共享状态 + 编辑操作（非 widget）
│   ├── cpumapwidget.cpp/h     # 地图渲染器：QPainter 后端
│   ├── gpumapwidget.cpp/h     # 地图渲染器：OpenGL 后端
│   ├── toolbar.cpp            # 工具栏（几乎未使用）
│   ├── floatingtoolbar.cpp/h  # 浮动工具栏
│   ├── selectionregion.h      # 选区管理
│   ├── asynclevelloader.cpp/h # 异步存档加载器
│   ├── chunk_task.cpp/h       # 区块加载任务
│   ├── chunkeditorwidget.cpp/h# 区块编辑器
│   ├── chunksectionwidget.cpp/h # 子区块截面视图
│   ├── voxelwidget.cpp/h      # 3D 体素渲染器
│   ├── mapitemeditor.cpp/h    # 地图物品编辑器
│   ├── nbtwidget.cpp/h        # NBT 树形编辑器
│   ├── nbtmodifydialog.cpp/h  # NBT 值修改对话框
│   ├── renderfilterdialog.cpp/h # 渲染过滤器
│   ├── gotopositiondialog.cpp/h # 坐标跳转对话框
│   ├── aboutdialog.cpp/h      # 关于对话框
│   ├── config.cpp/h           # 配置管理
│   ├── resourcemanager.cpp/h  # 资源管理与翻译
│   ├── maptile.cpp/h          # 地图瓦片数据
│   └── msg.cpp                # 消息/字符串常量
│
├── res/                       # 资源文件（图标、纹理、着色器、字体）
│   ├── ui/                    # UI 图标
│   ├── shaders/               # OpenGL 着色器
│   ├── fonts/                 # 字体文件
│   ├── block_actor/           # 方块实体图标
│   ├── entity/                # 实体图标
│   ├── nbt/                   # NBT 图标
│   └── village/               # 村庄图标
│
├── translations/              # 翻译文件
│   ├── en.ts                  # 英文
│   └── zh_CN.ts               # 简体中文
│
├── scripts/                   # 构建/部署脚本
│   ├── build.ps1
│   ├── build_run.ps1
│   ├── deploy.ps1
│   └── scale_icon.py
│
├── docs/                      # 文档
│   └── complie_guide.md
│
├── build/                     # 构建输出目录
└── build_rls/                 # Release 构建输出目录

┌──────────────────────────────────────────────────────────┐
│                     GUI 应用层 (src/)                      │
│  MainWindow → LevelTabWidget → LevelPageWidget            │
│     ├── MapHost (共享状态: MapView/MapOverlays/编辑操作)   │
│     ├── CpuMapWidget 或 GpuMapWidget (二选一的渲染器)      │
│     ├── FloatingToolBar (维度/图层/覆盖控制)              │
│     ├── NbtWidget (NBT 编辑器)                            │
│     ├── ChunkEditorWidget (区块编辑)                      │
│     └── VoxelWidget (3D 体素渲染)                         │
└──────────────────────┬────────────────────────────────────┘
                       │ AsyncLevelLoader
                       ▼
┌──────────────────────────────────────────────────────────┐
│                  数据加载层 (src/)                         │
│  AsyncLevelLoader                                         │
│     ├── LoadRegionTask/ChunkRegion (异步渲染任务)         │
│     ├── 多级缓存 (region_cache, ...)                       │
│     └── MapFilter (渲染过滤控制)                          │
└──────────────────────┬────────────────────────────────────┘
                       │ bl::bedrock_level
                       ▼
┌──────────────────────────────────────────────────────────┐
│               Bedrock 数据层 (bedrock-level/)              │
│  bl::bedrock_level                                        │
│     ├── LevelDB 接口                                      │
│     ├── bl::chunk / bl::sub_chunk                         │
│     ├── bl::actor / bl::village_data                      │
│     ├── bl::nbt (NBT 编解码)                          │
│     └── bl::level_dat                                     │
└──────────────────────┬────────────────────────────────────┘
                       │ LevelDB C API
                       ▼
┌──────────────────────────────────────────────────────────┐
│                   存储层                                    │
│        LevelDB (Minecraft Bedrock 格式)                   │
└──────────────────────────────────────────────────────────┘

MainWindow
  └── LevelTabWidget (QTabWidget)
       ├── [Welcome Tab]
       └── LevelPageWidget × N
            ├── AsyncLevelLoader ─── bl::bedrock_level ─── LevelDB
            ├── MapHost (共享 MapView / MapOverlays / ImportOverlay / 编辑操作)
            │    └── 选择 CpuMapWidget 或 GpuMapWidget 之一作为渲染器
            │         ├── FloatingToolBar (维度/图层/覆盖)
            │         ├── FloatingToolBar (选区模式)
            │         ├── RenderFilterDialog
            │         ├── GoToPositionDialog
            │         ├── VoxelWidget (3D渲染)
            │         └── ChunkEditorWidget
            │         ├── ChunkSectionWidget
            │         ├── NbtWidget (方块实体)
            │         ├── NbtWidget (实体)
            │         ├── NbtWidget (PendingTicks)
            │         └── VoxelWidget (3D预览)
            ├── LevelStatusBar
            └── QTabWidget (NBT数据)
                 ├── NbtWidget (level.dat)
                 ├── NbtWidget (players)
                 ├── NbtWidget (villages)
                 ├── NbtWidget (other)
                 └── NbtWidget (Map)

路径: bedrock-level/src/bedrock_level.cpp / include/bedrock_level.h

路径: bedrock-level/src/chunk.cpp / include/chunk.h

路径: bedrock-level/src/sub_chunk.cpp / include/sub_chunk.h

sub_chunk
├── version_: uint8_t
├── y_index_: int8_t          // 子区块 Y 索引
└── layers_: vector<layer*>
     └── layer
          ├── bits: uint8_t           // 每个方块的位数
          ├── type: uint8_t           // 调色板类型
          ├── palette_len: uint32_t   // 调色板长度
          ├── blocks: vector<uint16_t> // 方块索引数组 (4096)
          └── palettes: vector<compound_tag*> // 方块调色板

路径: bedrock-level/src/nbt.cpp / include/nbt.h

abstract_tag (基类)
├── compound_tag  (键值对容器)
├── list_tag      (有序标签列表)
├── byte_tag / short_tag / int_tag / long_tag
├── float_tag / double_tag
├── string_tag
├── byte_array_tag / int_array_tag / long_array_tag
└── end_tag

路径: bedrock-level/src/include/bedrock_key.h

路径: bedrock-level/src/include/bedrock_key.h

路径: bedrock-level/src/data_3d.cpp / include/data_3d.h

路径: bedrock-level/src/color.cpp / include/color.h

struct color {
    uint8_t r, g, b, a;  // RGBA 颜色
};

路径: bedrock-level/src/actor.cpp / include/actor.h

路径: bedrock-level/src/level_dat.cpp / include/level_dat.h

路径: src/mainwindow.cpp / include/mainwindow.h

路径: src/leveltabwidget.cpp / include/leveltabwidget.h

路径: src/levelpagewidget.cpp / include/levelpagewidget.h

LevelPageWidget (QVBoxLayout)
├── QSplitter (Vertical)
│   ├── 活跃的地图渲染器：CpuMapWidget 或 GpuMapWidget (包含浮动工具栏)
│   │   ├── FloatingToolBar (维度/图层/覆盖层) [左上角]
│   │   └── FloatingToolBar (选区模式) [顶部居中]
│   └── QTabWidget (NBT数据) [可折叠]
│       ├── level.dat
│       ├── players
│       ├── villages
│       ├── other
│       └── Map
└── LevelStatusBar (坐标+状态信息)

路径: src/cpumapwidget.cpp / include/ui/cpumapwidget.h   （CPU 渲染器）
      src/gpumapwidget.cpp / include/ui/gpumapwidget.h   （GPU 渲染器）

(parent, AsyncLevelLoader*, MapView*, MapOverlays*, ImportOverlay*, MapHost*)

struct RenderOption {
    enum LayerType { Biome, Terrain, Height };   // 图层类型
    enum DimType  { OverWorld, Nether, TheEnd }; // 维度类型
    enum OtherType { Grid, Coords, SlimeChunk, Actors, Village, HSA }; // 覆盖层
    DimType dim;
    LayerType layer;
    std::array<bool, 6> others;  // 各覆盖层开关
};

路径: src/maphost.cpp / include/ui/maphost.h

路径: src/floatingtoolbar.cpp / include/floatingtoolbar.h

路径: src/asynclevelloader.cpp / include/asynclevelloader.h

路径: src/include/chunk_task.h

struct ChunkRegion {
    BlockTipsInfo tips_info_[128][128];         // 每个方块的信息
    std::bitset<64> chunk_bit_map_;             // 区块存在性位图
    QImage terrain_bake_image_;                 // 地形渲染图像
    QImage biome_bake_image_;                   // 群系渲染图像
    QImage height_bake_image_;                  // 高度渲染图像
    bool valid;
    std::unordered_map<QImage*, vector<vec3>> actors_;          // 实体位置（图标模式）
    std::map<chunk_pos, map<QImage*, ActorCount>> actors_counts_; // 实体位置（计数模式）
    std::vector<hardcoded_spawn_area> HSAs_;
};

路径: src/include/renderfilterdialog.h

struct MapFilter {
    unordered_set<int> biomes_list_;             // 过滤的群系列表
    unordered_set<string> blocks_list_;          // 过滤的方块列表
    unordered_set<string> actors_list_;          // 过滤的实体系列
    int layer{64};                               // 固定 Y 层
    bool enable_layer_{false};                   // 是否启用固定层模式
    bool biome_black_mode_{true};                // true=黑名单，false=白名单
    bool block_black_mode_{true};                // true=黑名单，false=白名单
    bool actor_black_mode_{true};                // true=黑名单，false=白名单
};

路径: src/chunkeditorwidget.cpp / include/chunkeditorwidget.h

路径: src/voxelwidget.cpp / include/voxelwidget.h

路径: src/nbtwidget.cpp / include/nbtwidget.h

路径: src/config.cpp / include/config.h

chunk_key = prefix(1byte) + dim(4bytes) + cx(4bytes) + cz(4bytes) + tag(1byte) [+ y_index(1byte)]

Chunk (16×?×16)
├── SubChunk (-4\~19 or 0\~15)
│   ├── Version (uint8)
│   ├── Y Index (int8)
│   ├── Layers Count (uint8)
│   └── Layer
│       ├── Bits Per Block (uint8)
│       ├── Palette Type (uint8)
│       ├── Block Indices (4096 × uint16)
│       └── Palette (NBT Compound 列表)
├── Biome3D / HeightMap
├── Entities (actor 列表)
├── Block Entities (NBT Compound 列表)
├── Pending Ticks (NBT Compound 列表)
└── Hardcoded Spawn Areas

世界坐标 (block_pos)
    ↓ ÷16
区块坐标 (chunk_pos)  ← 包含维度 (dim=0,1,2)
    ↓
子区块 (sub_chunk)   ← Y÷16 索引，16^3 区域
    ↓
局部坐标 (rx, ry, rz)  ← 子区块内的 0~15 偏移

paintEvent()
├── 计算相机范围 (camera_)
├── 设置世界-视图变换矩阵 (world_to_view_xf_)
├── 根据图层选择渲染函数
│   ├── drawTerrain()   → foreachRegionInCamera()
│   ├── drawBiome()     → foreachRegionInCamera()
│   └── drawHeight()    → foreachRegionInCamera()
├── 绘制覆盖层（按 RenderOption.others 控制）
│   ├── drawGrid()
│   ├── drawChunkPosText()
│   ├── drawSlimeChunks()
│   ├── drawActors()
│   ├── drawVillages()
│   ├── drawHSAs()
│   └── drawSelection()
├── drawMarkers() (打开区块标记)
└── drawDebugWindow() (调试信息)

tryGetRegion(region_pos)
├── 检查 invalid_cache_（空区域缓存命中 → 返回 nullptr）
├── 检查 region_cache_（渲染缓存命中 → 返回 ChunkRegion*）
├── 检查 TaskBuffer (processing_) 防止重复提交
└── 提交 LoadRegionTask 到线程池
    └── run()
        ├── 遍历 8×8 区块
        │   ├── level_->get_chunk(pos) 加载区块
        │   └── 跳过无效/空区块
        ├── MapFilter::renderImages()
        │   ├── 确定 Y 层（固定层或最高非空方块）
        │   ├── 遍历 16×16 柱状区域
        │   │   ├── get_block_with_color() 获取方块（名称+颜色）
        │   │   ├── 应用方块/群系过滤
        │   │   └── 设置像素颜色
        │   └── 生成 terrain/biome/height 三张图像
        ├── MapFilter::bakeChunkActors()
        │   ├── 遍历实体
        │   └── 记录位置到 actor 列表
        └── emit finish() 通知主线程

世界地图 (4K)
  └── Region (512×512)
        └── Chunk (64×64)
              └── Tile (单格)

┌─────────────────────────────────────────┐
│  1. 全屏 Quad（4 顶点）                  │
│  2. Fragment Shader：                    │
│     - 屏幕坐标 → 地图坐标                │
│     - 采样地表图、高度图、AO、阴影       │
│     - 高度位移 + 光照合成                │
│  3. 输出最终颜色                         │
└─────────────────────────────────────────┘

// 伪代码
vec2 mapCoord = screenToMap(fragUV);       // 屏幕 → 地图坐标
uint terrain  = sampleTerrain(mapCoord);   // 采样地表图
float height  = sampleHeight(mapCoord);    // 采样高度图
float ao      = sampleAO(mapCoord);        // 采样 AO
float shadow  = sampleShadow(mapCoord);    // 采样阴影

vec3 baseColor = lookupColor(terrain);     // 方块类型 → 颜色
vec2 offset    = heightToOffset(height);   // 高度 → 屏幕位移（2.5D 立体感）
vec3 finalColor = baseColor * ao * shadow;

mapX = (screenX - cameraOffsetX) * scale
mapY = (screenY - cameraOffsetY) * scale

float ao = 0.0;
for (each neighbor in 8 directions) {
    float diff = neighborHeight - currentHeight;
    if (diff > 0) {
        ao += clamp(diff / maxDiff, 0.0, 1.0) * weight;
    }
}
ao = 1.0 - ao * aoStrength;

1. 将高度图构建为四叉树
2. 对每个格子，沿光方向投射一条射线
3. 用四叉树快速跳过不需要检测的区域
4. 判断是否被遮挡

+----+----+----+----+
| C0 | C1 | C2 | C3 |
+----+----+----+----+
| C4 | C5 | C6 | C7 |
+----+----+----+----+
| ...                |
+----+----+----+----+

1. 检测需要加载/卸载的 Chunk
2. 生成或读取 Chunk 数据
3. 计算 AO、阴影（仅受影响的 Chunk）
4. 用 staging buffer 上传到纹理图集
5. 标记 Chunk 状态

startNextFrame():
  1. 更新 Uniform（相机偏移）
  2. 绑定管线、描述符集
  3. 绑定顶点/索引缓冲
  4. vkCmdDrawIndexed(6, 1, 0, 0, 0)
  5. frameReady()

// 创建 staging buffer
// 填充数据
// vkCmdCopyBufferToImage
// 转换 layout 为 SHADER_READ_ONLY_OPTIMAL