CMZToMCWorldConverter

Tools for exporting CastleMiner Z worlds into Minecraft Java Anvil worlds.

This repository contains two related tools:

Tool	Type	Purpose
CMZToMCWorldConverter	C# console app	Converts CastleMiner Z chunk .dat files into a Minecraft Java world.
CMZFullChunkExporter	CastleForge mod	Exports full hydrated CMZ chunk files from inside the game so the converter can capture generated terrain, not just edited block deltas.

CMZToMCWorldConverter is the main offline converter. CMZFullChunkExporter is an optional companion mod that is useful for normal CastleMiner Z survival worlds.

---

Why two tools are needed

CastleMiner Z does not always save every block in a chunk to disk.

In normal gameplay, CMZ chunk .dat files usually store only edited block deltas. That means the save file records blocks that changed from the original generated terrain, such as mined blocks, placed blocks, or other saved modifications.

The rest of the chunk is not necessarily stored block-by-block in the .dat file. Instead, CastleMiner Z recreates the untouched terrain locally from the world seed when the world is loaded. The game generates the base terrain, caves, ores, trees, and other terrain features, then applies the saved block edits over that generated terrain.

Because of that, a normal CMZ save folder may contain chunk files that only describe the changed parts of the world. If the converter reads those files directly, it can only convert the saved edits it can see. Untouched generated terrain that was never explicitly saved into the chunk files may appear as air in Minecraft.

The companion CastleForge mod solves that problem by letting the game do what it already does best:

CMZ world seed
    ↓
CMZ generates the chunk in-game
    ↓
CMZ applies saved block edits
    ↓
CMZFullChunkExporter reads the final block state
    ↓
Full raw chunk files are exported
    ↓
CMZToMCWorldConverter converts those chunks to Minecraft

In other words:

CMZToMCWorldConverter converts chunk files.
CMZFullChunkExporter creates better full chunk files from real in-game terrain.

---

Tool 1: CMZToMCWorldConverter

CMZToMCWorldConverter is a C# console tool for converting CastleMiner Z native chunk .dat files into a Minecraft Java Anvil world using a customizable JSON reverse block map.

It can map CastleMiner Z blocks back to Minecraft block states, such as:

Log          -> minecraft:oak_log[axis=y]
Leaves       -> minecraft:oak_leaves[persistent=true]
Rock         -> minecraft:stone
IronWall     -> minecraft:iron_block
Crate        -> minecraft:chest[facing=north,type=single,waterlogged=false]

Converter features

• Converts CastleMiner Z chunk files named like X0Y-64Z0.dat into Minecraft Java region files.
• Reads CMZ chunk delta payloads using the known native chunk format.
• Supports RTSD SaveDevice-wrapped CMZ chunk files.
• Supports Steam SaveDevice key inference from paths like:

AppData/Local/CastleMinerZ/<SteamID>/Worlds/<WorldGuid>

• Supports legacy gamertag SaveDevice keys for old or copied saves.
• Supports raw unwrapped CMZ chunk files for test, staging, and CMZFullChunkExporter workflows.
• Maps CMZ block IDs to Minecraft Java block states through reverse-block-map.json.
• Includes a full default CMZ block map to basic Minecraft equivalents.
• Writes a Minecraft Java world folder with:

level.dat
session.lock
region/r.x.z.mca

• Supports clear vertical mapping, for example:

CMZ Y -64..63 -> Minecraft Y 0..127

• Writes an unmapped report if a CMZ block is missing from the reverse block map.
• Streams queued Minecraft chunks during large conversions to reduce memory usage.

---

Tool 2: CMZFullChunkExporter

CMZFullChunkExporter is a CastleForge mod that exports full hydrated CastleMiner Z chunk files for CMZToMCWorldConverter.

It runs inside CastleMiner Z, allows the game to generate terrain normally, waits for chunks to load, reads the final generated-plus-edited block state, and writes full raw CMZ-style chunk payloads to a separate export folder.

This is most useful for normal CMZ survival worlds where the original save folder only contains edited block deltas.

Exporter commands

Command	Description
/exportchunks existing	Reads the active world's existing X...Y-64Z....dat chunk list, teleports through those coordinates, and exports hydrated full chunks.
/exportchunks loaded	Exports only the currently loaded 24×24 chunk terrain window. Useful for quick testing.
/exportchunks around <value>	Exports a square centered on the player's current chunk. 1 = current chunk only, 2 = current chunk + 1 ring, 3 = current chunk + 2 rings.
/exportchunks status	Shows active export progress.
/exportchunks cancel	Stops the export and teleports back to the original position.
/exportchunks help	Shows in-game help.

Aliases:

/hydratechunks
/exportchunk
/hydrate
/export

Around-player export sizing

/exportchunks around <value> uses the value as a center-inclusive ring count:

/exportchunks around 1 = 1×1 = current chunk only
/exportchunks around 2 = 3×3 = current chunk plus 1 ring
/exportchunks around 3 = 5×5 = current chunk plus 2 rings

The exported target count is:

(2 × (value - 1) + 1)²

Source-world expansion protection

Teleporting through terrain can cause CMZ to save newly generated source chunk files.

For teleport-based exports, the mod snapshots the source chunk list before starting and removes newly-created source chunk .dat files after finish or cancel. The exported hydrated chunks remain in the export folder.

Back up important worlds before large exports.

---

Recommended workflows

Workflow A: Converting a world that already has full chunk data

Use this when the CMZ chunk files already contain full saved block data, such as worlds generated by MCToCMZWorldConverter or exported by another full-chunk tool.

CMZ world folder
    ↓
CMZToMCWorldConverter
    ↓
Minecraft Java world

Steps:

1. Back up your CMZ world folder.
2. Open config.json.
3. Set InputCmzWorldFolder to the CMZ world folder.
4. Set OutputMinecraftWorld to a new Minecraft saves folder.
5. Run CMZToMCWorldConverter.exe config.json.
6. Open the converted world in Minecraft Java.

Workflow B: Converting a normal CastleMiner Z survival world

Use this when the original CMZ world only saves edited chunks/deltas.

CMZ world loaded in-game
    ↓
CMZFullChunkExporter
    ↓
Full raw hydrated chunk export folder
    ↓
CMZToMCWorldConverter
    ↓
Minecraft Java world

Steps:

1. Back up your CMZ world folder.
2. Load the CMZ world in single-player or a private host session.
3. Run one of these commands:

/exportchunks existing
/exportchunks around 2
/exportchunks loaded

4. Wait for the export job to finish.
5. Open CMZToMCWorldConverter/config.json.
6. Set InputCmzWorldFolder to the generated exporter output folder.
7. Make sure raw chunk files are allowed:

"AllowRawChunkFiles": true

8. Run the converter.
9. Open the converted world in Minecraft Java.

---

CMZFullChunkExporter output

Exports are written to:

<CastleMiner Z folder>/!Mods/CMZFullChunkExporter/Exports/<WorldName>_<Mode>_<Timestamp>/

Each exported chunk is a raw, unwrapped CMZ-style payload:

uint magic = 3203334144
int count
int packedEntry[count]

The file names match the normal CMZ chunk naming style:

X0Y-64Z0.dat
X16Y-64Z0.dat
X0Y-64Z16.dat

Use the export folder as CMZToMCWorldConverter's InputCmzWorldFolder with:

"AllowRawChunkFiles": true

Raw chunks exported by CMZFullChunkExporter do not need SaveDevice decoding.

---

Converter usage

Run:

CMZToMCWorldConverter.exe config.json

Example config paths:

{
  "InputCmzWorldFolder": "C:/Users/John/AppData/Local/CastleMinerZ/76561198296842857/Worlds/<WorldGuid>",
  "OutputMinecraftWorld": "C:/Users/John/AppData/Roaming/.minecraft/saves/Converted-CMZ-World",
  "ReverseBlockMap": "reverse-block-map.json"
}

When using CMZFullChunkExporter, set InputCmzWorldFolder to the generated export folder instead of the original CMZ save folder.

---

Converter config

The main runtime settings are in:

config.json

Important fields:

{
  "InputCmzWorldFolder": "C:/Users/John/AppData/Local/CastleMinerZ/76561198296842857/Worlds/<WorldGuid>",
  "OutputMinecraftWorld": "C:/Users/John/AppData/Roaming/.minecraft/saves/Converted-CMZ-World",
  "ReverseBlockMap": "reverse-block-map.json"
}

Raw chunk files

Raw unwrapped chunk files are useful for generated exports, test files, and CMZFullChunkExporter output.

"AllowRawChunkFiles": true

Large world conversions

Large hydrated exports can contain hundreds of thousands of chunk files. To avoid holding too many Minecraft chunks in memory at once, the converter can flush queued chunks during conversion.

Default example:

"MaxQueuedMinecraftChunks": 256

For very large conversions or low-memory systems, lower it:

"MaxQueuedMinecraftChunks": 128

or:

"MaxQueuedMinecraftChunks": 64

Lower values use less memory but may write to disk more often.

---

SaveDevice key settings

Steam CastleMiner Z saves use this key pattern:

MD5(SteamID + "CMZ778")

If your input folder looks like this:

C:/Users/<you>/AppData/Local/CastleMinerZ/76561198296842857/Worlds/<WorldGuid>

leave this enabled:

"InferSaveDeviceSteamIdFromInputPath": true

If the converter cannot infer it, set the numeric SteamID manually:

"SaveDeviceSteamId": "76561198296842857"

Older saves, copied saves, or saves that were not migrated may still use the old gamertag key:

MD5(Gamertag + "CMZ778")

If every chunk fails with a message like:

Could not unwrap CMZ SaveDevice file with any resolved key

set this in config.json to the exact CMZ/Steam display name that originally created the save:

"SaveDeviceGamerTag": "YourOldNameHere"

The converter also tries the current Windows username as a legacy gamertag key when:

"TryCurrentWindowsUserAsLegacyGamerTag": true

The converter may also try a CommonKey fallback for old/non-Steam or mixed SaveDevice files.

---

Vertical mapping

CMZ chunks store Y values from:

-64 through 63

The default config maps that into Minecraft as:

"VerticalMapping": {
  "CmzY": -64,
  "MinecraftY": 0
}

That means:

CMZ Y -64 -> Minecraft Y 0
CMZ Y   0 -> Minecraft Y 64
CMZ Y  63 -> Minecraft Y 127

So the full slice is:

CMZ Y -64..63 -> Minecraft Y 0..127

---

Reverse block map

The reverse-block-map.json file controls how CMZ blocks become Minecraft blocks.

Example:

{
  "DefaultBlock": "minecraft:air",
  "Mappings": {
    "Empty": "minecraft:air",
    "Dirt": "minecraft:dirt",
    "Grass": "minecraft:grass_block",
    "Rock": "minecraft:stone",
    "Log": "minecraft:oak_log[axis=y]",
    "Leaves": "minecraft:oak_leaves[persistent=true]",
    "Wood": "minecraft:oak_planks"
  }
}

The included default map covers the full known CastleMiner Z block enum with basic Minecraft equivalents.

Default block examples

CMZ block              Minecraft block
---------------------------------------------------------
Empty                  minecraft:air
Dirt                   minecraft:dirt
Grass                  minecraft:grass_block
Rock                   minecraft:stone
GoldOre                minecraft:gold_ore
IronOre                minecraft:iron_ore
CopperOre              minecraft:copper_ore
CoalOre                minecraft:coal_ore
DiamondOre             minecraft:diamond_ore
Log                    minecraft:oak_log[axis=y]
Leaves                 minecraft:oak_leaves[persistent=true]
Wood                   minecraft:oak_planks
BloodStone             minecraft:netherrack
SpaceRock              minecraft:end_stone
IronWall               minecraft:iron_block
CopperWall             minecraft:copper_block
GoldenWall             minecraft:gold_block
DiamondWall            minecraft:diamond_block
Crate                  minecraft:chest
Torch                  minecraft:torch
TNT / C4 / BombBlock   minecraft:tnt
Slime                  minecraft:slime_block
Spawner blocks         minecraft:spawner
CraftingStation        minecraft:crafting_table
HellForge              minecraft:furnace

---

Unmapped block report

If a CMZ block is not found in reverse-block-map.json, the converter uses:

"DefaultBlock": "minecraft:air"

and writes a report to the output world folder:

cmz-to-mc-world.unmapped.txt

---

Example console output

CMZ to Minecraft world conversion
Input CMZ world:        C:\Users\John\AppData\Local\CastleMinerZ\76561198296842857\Worlds\...
Output Minecraft world: C:\Users\John\AppData\Roaming\.minecraft\saves\Converted-CMZ-World
Reverse block map:      reverse-block-map.json
CMZ chunk files:        128
SaveDevice keys:        SteamID(path): 76561198296842857 | GamerTag(Windows): John | CommonKey
Y mapping:              CMZ Y -64 -> Minecraft Y 0
Skip air blocks:        True

Progress: 25/128 CMZ chunks, MC chunks written 0, queued 25, blocks converted 182,420

Conversion complete.
Elapsed:               00:00:12.3456789
CMZ chunks converted:  128
Read-error chunks:     0
Blocks converted:      931,552
Air blocks skipped:    1,162,304
Unknown blocks:        0
MC chunks written:     128

---

Current limitations

The converter focuses on block terrain.

The following data is not currently converted:

• player inventory .inv files
• CMZ entities/enemies
• crate/container contents
• door pairing correctness beyond basic block-state mapping
• torch placement perfection for every orientation edge case
• lighting data
• biome variety
• Minecraft block entities for chests, furnaces, spawners, and barrels

When converting directly from original CMZ save files, untouched procedural terrain may be missing because CMZ usually stores edited block deltas instead of full chunks.

When converting from CMZFullChunkExporter output, generated terrain is included because the mod exports the final in-game block state.

---

Requirements

• Windows
• CastleMiner Z
• CastleForge ModLoader
• ModLoaderExtensions for CMZFullChunkExporter
• .NET Framework 4.8.1 for CMZToMCWorldConverter
• Visual Studio 2022 or MSBuild for building from source

---

Repository structure

CMZToMCWorldConverter/
├── README.md
├── LICENSE
│
├── CMZToMCWorldConverter/
│   ├── CMZToMCWorldConverter.sln
│   ├── BuildRelease.bat
│   └── CMZToMCWorldConverter/
│       ├── config.json
│       ├── reverse-block-map.json
│       ├── ConvertCMZToMinecraft.bat
│       ├── CMZToMCWorldConverter.csproj
│       ├── Program.cs
│       ├── CastleMinerZ/
│       ├── Configuration/
│       ├── Mapping/
│       ├── Minecraft/
│       ├── Properties/
│       └── ReferenceAssemblies/
│
└── CMZFullChunkExporter/
    ├── CMZFullChunkExporter.csproj
    ├── CMZFullChunkExporter.cs
    └── README.md

The root README describes the full conversion workflow. Each project folder may also contain project-specific notes.

---

Build notes

Both tools target Windows.

CMZToMCWorldConverter targets:

.NET Framework 4.8.1

Recommended converter build settings:

Platform: x86
Configuration: Release

Build with Visual Studio or run:

BuildRelease.bat

The following runtime files should be copied next to the final .exe:

config.json
reverse-block-map.json
System.Text.Json.dll
System.Text.Encodings.Web.dll
System.Memory.dll
System.Buffers.dll
System.Runtime.CompilerServices.Unsafe.dll
System.Threading.Tasks.Extensions.dll
Microsoft.Bcl.AsyncInterfaces.dll
System.Numerics.Vectors.dll

CMZFullChunkExporter is a CastleForge mod and should be built against the CastleForge / CastleMiner Z modding environment.

---

Safety notes

Back up important CMZ worlds before large exports or conversions.

CMZFullChunkExporter exports to a separate folder and does not overwrite the original CMZ save. Teleport-based exports may still cause CMZ to create temporary source chunk files while terrain loads, so the exporter snapshots the original chunk list and removes newly-created source chunk files after finish or cancel.

Use teleport-based exports in a single-player world or private host session.

---

License

This project is licensed under the GPL-3.0-or-later license.

See LICENSE for details.

---

Credits

Created by RussDev7 for CastleMiner Z / CastleForge tooling.

CMZToMCWorldConverter is a reverse companion to MCToCMZWorldConverter.

CMZFullChunkExporter is the companion CastleForge exporter used to create full hydrated raw chunk files for normal CastleMiner Z worlds.