{"url":"https://levimc.org/mods/github.com/CodeOfCraft/WorldDL/","id":"github.com/CodeOfCraft/WorldDL","name":"WorldDL","description":"Save received Minecraft Bedrock client chunks as a local world","owner":"CodeOfCraft","logo":"https://raw.githubusercontent.com/CodeOfCraft/WorldDL/main/logo.png","repository":"https://github.com/CodeOfCraft/WorldDL","issues":"https://github.com/CodeOfCraft/WorldDL/issues","releases":"https://github.com/CodeOfCraft/WorldDL/releases","stars":3,"downloads":35,"updated":"2026-10-17T18:12:28Z","published":"2026-10-17T18:12:28Z","created":"2026-10-01T20:31:28Z","license":"CC0-1.0","side":["client"],"platform":["win-x64"],"gameVersions":["1.26.51"],"tags":["platform:levilamina","type:mod"],"latest":{"variant":"client","version":"0.1.0","install":"lip install github.com/CodeOfCraft/WorldDL#client@0.1.0"},"readmes":[{"file":"README.md","lang":"en","text":"<p align=\"center\"><img src=\"logo.png\" alt=\"WorldDL\" width=\"160\"></p>\n\n# WorldDL\n\nEnglish | [简体中文](README.zh-CN.md)\n\nAuthor: [CodeOfCraft](https://github.com/CodeOfCraft) · Discord: [join](https://discord.gg/NyjNnuG2Rc)\n\nA Windows x64 Minecraft Bedrock client mod that saves received chunks as a local world. Built with [LeviLamina](https://github.com/LiteLDev/LeviLamina) on its [official mod template](https://github.com/LiteLDev/levilamina-mod-template).\n\n## Compatibility\n\n| Component | Supported version |\n| --- | --- |\n| Platform | Windows x64, Bedrock client |\n| Minecraft Bedrock | 1.26.51 |\n| LeviLamina | 26.51.6, client |\n| Engine data | `bedrockdata 26.51.1-client.7` |\n| WorldDL | 0.1.0 |\n\nJava Edition, mobile clients, and Bedrock Dedicated Server (BDS) are unsupported. A Minecraft update needs matching LeviLamina dependencies and a review of the engine interfaces; changing the manifest alone is not enough.\n\n## Install and use\n\n1. Install the matching LeviLamina version with the [client installation guide](https://lamina.levimc.org/user_guides/install_on_client/).\n2. Build the mod, or download a package from [Releases](https://github.com/CodeOfCraft/WorldDL/releases) and extract it. Copy the whole `WorldDL` directory into the game's `mods` directory, so that `mods/WorldDL/manifest.json` and `mods/WorldDL/WorldDL.dll` exist.\n3. Join a world or server, run `/wdl start \"World name\"` in chat, and explore the areas to save.\n4. Run `/wdl stop` and wait for the success message before copying or packaging the world.\n\nCommands run locally on the client. The server does not need the mod, and server operator permissions are not required.\n\n| Command | Action |\n| --- | --- |\n| `/wdl` or `/wdl status` | Show session state, written chunk count, queue, and output path |\n| `/wdl start` | Start a new session with the default world name |\n| `/wdl start \"Name\"` | Start a new session with a custom display name |\n| `/wdl save` | Recapture loaded chunks and wait for writes, keeping the session open |\n| `/wdl stop` | Perform the final capture, drain the queue, and close the database |\n\nEach session creates its own directory at `mods/WorldDL/data/worlds/wdl_<timestamp>/`, containing `level.dat`, `level.dat_old`, `levelname.txt`, and `db/`.\n\nAfter stopping, copy the whole world directory into the game's `minecraftWorlds` directory, or export a `.mcworld` archive with PowerShell 7:\n\n```powershell\npwsh -File scripts/Export-World.ps1 -WorldPath \"C:\\path\\to\\wdl_<timestamp>\"\n# Optional destination; an existing file is never overwritten.\npwsh -File scripts/Export-World.ps1 -WorldPath \"C:\\path\\to\\wdl_<timestamp>\" -OutputPath \"C:\\exports\\world.mcworld\"\n```\n\nThe script checks the database lock and puts the world files at the archive root. Open the `.mcworld` file with Minecraft to import it. Stop downloading before exporting or opening the saved world.\n\n## Saved data and limits\n\n### Saved data\n\n- Received subchunk blocks, extra block layers, biomes, heightmaps, and block entity NBT.\n- Separate keys for the Overworld, Nether, and End, including negative coordinates and negative subchunk heights.\n- The game's `SubChunk::serialize(..., false)` disk format instead of connection-specific block runtime IDs.\n- Missing subchunks are skipped; a partial update keeps the subchunks saved before it.\n\n### Capture and storage\n\n- Subchunk loading notifications are coalesced and captured on client ticks, with a final capture before chunk destruction and a periodic scan every 20 ticks. Loaded notifications take priority.\n- Normal capture handles up to 4 chunks per tick and checks a 2 ms budget between chunks; a single chunk can exceed that budget. The writer queue holds up to 256 pending snapshots.\n- Owned byte buffers go to a background writer that uses uncompressed LevelDB and synchronous atomic batches. A 2 ms coalescing window combines up to 32 snapshots per commit, with a roughly 4 MiB batch target.\n- Stopping, leaving the world, or disabling the mod closes the session.\n\n### Limits\n\nOnly data received by the client can be saved; unexplored areas are not downloaded. Exported Overworld generation is configured as air-only, so missing Overworld terrain stays empty while saved chunks are preserved. Nether and End generation is independent of that setting. Exports use Creative mode with commands enabled.\n\nEntities, player inventories, scoreboards, map data, scheduled ticks, server plugin data, and resource/behavior packs are not exported. Container contents may not be sent to the client and cannot be guaranteed. Custom blocks need their corresponding packs.\n\n`/wdl save`, `/wdl stop`, and leaving the world wait for disk writes and may briefly pause the game. They drain pending writes when the queue fills and after capture completes; normal tick capture pauses while the writer queue is full. A queue rejection means the queue was full, and loaded chunks are retried during later scans. Before a chunk is destroyed, a rejected capture waits for pending writes and retries once. `/wdl status` reports snapshot write and batch counts.\n\n## Build\n\nRequirements: Windows x64, Visual Studio C++ build tools and Windows SDK, LLVM/clang-cl 22, xmake 3.0+, Git, and PowerShell 7 for the scripts. Dependencies are fetched from the official LeviMC xmake repository.\n\n```powershell\npwsh -File scripts/Build.ps1\n# Debug build\npwsh -File scripts/Build.ps1 -Mode debug\n```\n\nThe helper uses xmake and LLVM from `PATH`, with optional portable tools under `.tools/`. It enables Git long paths only for the build process. A normal toolchain installation is enough; `.tools/` is not part of the repository.\n\nAlternatively:\n\n```powershell\nxmake f -y -p windows -a x64 -m release --target_type=client\nxmake -y\n```\n\nOutput: `bin/WorldDL/`, a complete mod directory ready to copy or archive.\n\n## Verification\n\nStorage, format, and export tests do not need Minecraft. Install CMake 3.24+ and Visual Studio C++ build tools; the first configuration fetches LevelDB and nlohmann/json.\n\n```powershell\ncmake -S tests -B build/tests -A x64\ncmake --build build/tests --config Release --parallel\nctest --test-dir build/tests -C Release --output-on-failure\npwsh -File tests/ExportWorldTests.ps1\n```\n\nTests cover coordinate and dimension keys, negative heights, `level.dat` headers, void generation settings, database reopening, partial updates, concurrent batch updates, queue pressure, draining on stop, capture notification coalescing and chunk lifetimes, refusing existing world directories, and archive packaging. GitHub Actions builds the client and runs these checks.\n\nIn-game validation is still required: connect to a server, start a capture, explore, change blocks, switch dimensions, stop or disconnect, import the world, and inspect blocks and biomes. Automated tests do not establish runtime hook behavior or world-loading compatibility.\n\n## Project layout\n\n| Path | Responsibility |\n| --- | --- |\n| `src/mod/` | Mod lifecycle, event wiring, and session state |\n| `src/hooks/` | Chunk load, chunk destruction, and world-leave hooks |\n| `src/command/` | `/wdl` command overloads |\n| `src/world/ChunkCapture.*` | Engine serialization and metadata capture |\n| `src/world/WorldGeneration.*` | Air-only Overworld configuration |\n| `src/world/WorldWriter.*` | Background LevelDB writes |\n| `src/world/BedrockFormat.h` | World keys and file headers |\n| `scripts/` | Build helper and offline export |\n| `tests/` | Standalone storage, format, and export checks |\n\nThe build target and its packaging list live in [xmake.lua](xmake.lua); package metadata is in [tooth.json](tooth.json); `manifest.json` is the template that the packer expands into the built mod.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development and release instructions, and [CHANGELOG.md](CHANGELOG.md) for changes.\n\n## License\n\nProject code retains the template's [CC0-1.0 license](LICENSE). Dependencies retain their own licenses; see [NOTICE.md](NOTICE.md) and [LICENSES/](LICENSES/).\n"},{"file":"README.zh-CN.md","lang":"zh-Hans","text":"<p align=\"center\"><img src=\"logo.png\" alt=\"WorldDL\" width=\"160\"></p>\n\n# WorldDL\n\n[English](README.md) | 简体中文\n\n作者：[CodeOfCraft](https://github.com/CodeOfCraft) · Discord：[加入](https://discord.gg/NyjNnuG2Rc)\n\n将客户端收到的区块保存为本地世界的 Windows x64 Minecraft 基岩版模组。基于 [LeviLamina](https://github.com/LiteLDev/LeviLamina) 及其[官方模组模板](https://github.com/LiteLDev/levilamina-mod-template)构建。\n\n## 兼容性\n\n| 组件 | 支持版本 |\n| --- | --- |\n| 平台 | Windows x64，基岩版客户端 |\n| Minecraft 基岩版 | 1.26.51 |\n| LeviLamina | 26.51.6，client |\n| 引擎数据 | `bedrockdata 26.51.1-client.7` |\n| WorldDL | 0.1.0 |\n\n不支持 Java 版、移动端或基岩版专用服务器（BDS）。升级 Minecraft 时，需要同步升级 LeviLamina 依赖并核对引擎接口，只修改 manifest 的版本号是不够的。\n\n## 安装与使用\n\n1. 按[客户端安装文档](https://lamina.levimc.org/user_guides/install_on_client/)安装对应版本的 LeviLamina。\n2. 编译模组，或从 [Releases](https://github.com/CodeOfCraft/WorldDL/releases) 下载发布包并解压。将整个 `WorldDL` 目录放入游戏的 `mods` 目录，确保存在 `mods/WorldDL/manifest.json` 和 `mods/WorldDL/WorldDL.dll`。\n3. 进入世界或服务器，在聊天栏执行 `/wdl start \"世界名称\"`，然后探索需要保存的区域。\n4. 执行 `/wdl stop`，等待成功消息后再复制或打包存档。\n\n命令都在客户端本地执行。服务器不需要安装模组，也不需要服务器 OP 权限。\n\n| 命令 | 作用 |\n| --- | --- |\n| `/wdl` 或 `/wdl status` | 显示会话状态、已写入区块数、队列与输出路径 |\n| `/wdl start` | 开始新会话，使用默认世界名称 |\n| `/wdl start \"名称\"` | 开始新会话，指定游戏中显示的名称 |\n| `/wdl save` | 重新捕获已加载区块并等待写入，保持会话 |\n| `/wdl stop` | 最后捕获、排空队列并关闭数据库 |\n\n每次会话创建独立目录 `mods/WorldDL/data/worlds/wdl_<时间戳>/`，包含 `level.dat`、`level.dat_old`、`levelname.txt` 和 `db/`。\n\n停止后，可以将整个存档目录复制到游戏的 `minecraftWorlds` 目录，也可以用 PowerShell 7 导出 `.mcworld`：\n\n```powershell\npwsh -File scripts/Export-World.ps1 -WorldPath \"C:\\path\\to\\wdl_<时间戳>\"\n# 可指定输出位置；不会覆盖已有文件。\npwsh -File scripts/Export-World.ps1 -WorldPath \"C:\\path\\to\\wdl_<时间戳>\" -OutputPath \"C:\\exports\\world.mcworld\"\n```\n\n脚本会检查数据库锁，并把存档文件放在压缩包根目录。用 Minecraft 打开 `.mcworld` 即可导入。导出或打开存档前，请先停止下载。\n\n## 保存范围与限制\n\n### 保存内容\n\n- 已收到的子区块方块、附加方块层、生物群系、高度图和方块实体 NBT。\n- 主世界、下界、末地使用独立坐标键，支持负坐标和负高度子区块。\n- 使用游戏自身 `SubChunk::serialize(..., false)` 的磁盘格式，而不是仅在当前连接有效的方块 runtime ID。\n- 跳过未收到的子区块；部分更新会保留此前已保存的子区块。\n\n### 捕获与写入\n\n- 合并重复的子区块加载通知，在客户端 tick 中捕获，并在区块销毁前及每 20 tick 的周期扫描中补充捕获。加载通知优先处理。\n- 常规捕获每 tick 最多处理 4 个区块，并在区块之间检查 2 毫秒时间预算；单个区块可能超出该预算。写入队列最多容纳 256 个待处理快照。\n- 独立内存的字节串交给后台写入线程，使用无压缩 LevelDB 和同步原子批量写入。2 毫秒合并窗口内每次提交最多 32 个快照，批次目标大小约 4 MiB。\n- 停止下载、退出世界或禁用模组时关闭会话。\n\n### 限制\n\n客户端只能保存实际收到的数据，未探索区域不会下载。导出世界的主世界生成器配置为纯空气，未下载区域保持空白，已保存区块保持原样；下界和末地的生成器独立，不受此设置影响。导出世界使用创造模式并开启命令。\n\n实体、玩家背包、计分板、地图数据、计划刻、服务器插件数据和资源/行为包不会导出。容器物品可能未由服务器发送给客户端，无法保证完整恢复。自定义方块需要另外安装对应的资源/行为包。\n\n`/wdl save`、`/wdl stop` 和退出世界会等待磁盘写入，可能造成短暂停顿；队列满时以及捕获结束后会排空待处理写入，队列满期间常规 tick 捕获暂停。出现 queue rejection 表示队列已满，仍在加载的区块会在后续扫描中重试；区块销毁前若捕获被拒绝，会等待写入并重试一次。`/wdl status` 会显示快照写入次数和批次次数。\n\n## 编译\n\n需要 Windows x64、Visual Studio C++ 构建工具及 Windows SDK、LLVM/clang-cl 22、xmake 3.0+、Git，以及运行脚本所需的 PowerShell 7。依赖从官方 LeviMC xmake 仓库下载。\n\n```powershell\npwsh -File scripts/Build.ps1\n# 调试构建\npwsh -File scripts/Build.ps1 -Mode debug\n```\n\n脚本优先使用 `PATH` 中的 xmake 和 LLVM，也支持 `.tools/` 下的便携工具，并且只为构建进程启用 Git 长路径支持。常规安装的工具链即可构建，`.tools/` 不属于仓库内容。\n\n也可以直接使用 xmake：\n\n```powershell\nxmake f -y -p windows -a x64 -m release --target_type=client\nxmake -y\n```\n\n输出目录为 `bin/WorldDL/`，是可直接复制或打包的完整模组目录。\n\n## 验证\n\n存储、格式及导出测试不需要 Minecraft。请安装 CMake 3.24+ 和 Visual Studio C++ 构建工具，首次配置时会下载 LevelDB 与 nlohmann/json。\n\n```powershell\ncmake -S tests -B build/tests -A x64\ncmake --build build/tests --config Release --parallel\nctest --test-dir build/tests -C Release --output-on-failure\npwsh -File tests/ExportWorldTests.ps1\n```\n\n测试覆盖坐标与维度键、负高度、`level.dat` 文件头、虚空生成配置、数据库重开、部分更新、并发批量更新、队列压力、停止时排空、捕获通知去重与区块生命周期、拒绝覆盖已有存档，以及存档打包。GitHub Actions 会构建客户端并运行这些检查。\n\n仍需游戏内验证：连接服务器、开始下载、探索区块、修改方块、切换维度、停止或断开连接、导入存档并检查方块与生物群系。自动化测试不能证明 hook 的运行时行为或客户端实际加载存档的兼容性。\n\n## 项目结构\n\n| 路径 | 职责 |\n| --- | --- |\n| `src/mod/` | 模组生命周期、事件注册与会话状态 |\n| `src/hooks/` | 区块加载、区块销毁、退出世界的 hook |\n| `src/command/` | `/wdl` 命令的各个重载 |\n| `src/world/ChunkCapture.*` | 引擎序列化与元数据捕获 |\n| `src/world/WorldGeneration.*` | 纯空气主世界配置 |\n| `src/world/WorldWriter.*` | 后台 LevelDB 写入 |\n| `src/world/BedrockFormat.h` | 存档键和文件头 |\n| `scripts/` | 构建脚本与离线导出 |\n| `tests/` | 独立存储、格式及导出测试 |\n\n构建目标与打包清单在 [xmake.lua](xmake.lua)；包元数据在 [tooth.json](tooth.json)；`manifest.json` 是打包器展开后写入模组目录的模板。\n\n开发及发布流程见 [CONTRIBUTING.md](CONTRIBUTING.md)，版本变化见 [CHANGELOG.md](CHANGELOG.md)。\n\n## 许可证\n\n项目代码沿用模板的 [CC0-1.0 许可证](LICENSE)。依赖保留各自许可证，见 [NOTICE.md](NOTICE.md) 和 [LICENSES/](LICENSES/)。\n"}],"gallery":[],"versions":[{"version":"0.1.0","prerelease":false,"released":"2026-10-17T18:12:28Z","releaseUrl":"https://github.com/CodeOfCraft/WorldDL/releases/tag/v0.1.0","manifestUrl":"https://github.com/CodeOfCraft/WorldDL/blob/v0.1.0/tooth.json","info":{"name":"WorldDL","description":"Save received Minecraft Bedrock client chunks as a local world","tags":["platform:levilamina","type:mod"],"logo":"https://raw.githubusercontent.com/CodeOfCraft/WorldDL/main/logo.png"},"variants":{"client":[{"side":"client","platform":"win-x64","deps":{"github.com/LiteLDev/LeviLamina#client":"26.51.6"}}]}}],"dependencies":{"github.com/liteldev/levilamina":{"id":"github.com/LiteLDev/LeviLamina","name":"LeviLamina","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LeviLamina/"}},"requiredBy":[]}