A collection of helpful utilities related to the zvcr file format and the Minecraft Anvil file format, in the form of a C++ library and a command line program.

The zvcr CLI accepts parameters in sequence, denoted by a - prefix:
zvcr -flag -arg1=value1 -arg2=value2

Basic parameter syntax:
-parameter=value
-parameter='string value with spaces'
-flag

You can choose from the following modes to do operations on zvcr / mca files, Minecraft worlds, etc.

Some commands require the use of Minecraft registries (-reg='/path/to/registries'), which you can download here. You may also optionally set the ZVCR_CLI_MINECRAFT_REGISTRIES_PATH environment variable to avoid passing in the -reg parameter every time.

In the help page,
optional parameters are denoted with []: [-optional=value],
variadic parameters are denoted with [...]: -parameters=values[...] (example: zvcr -parameters=value1 value2 value3).

• -help: Shows all commands and their usages. Use zvcr -help <command> to see the usage of that command.
• -merge: Merges distinct zvcr directories together, preserving their histories and combining their timelines
• -import: Imports Minecraft anvil (mca) files to zvcr
• -export: Exports zvcr files to Minecraft anvil (mca)
• -level-dat: Creates a level.dat file with custom parameters in a Minecraft world folder

• -merge: Merges distinct zvcr directories together, preserving their histories and combining their timelines
  • -dim={overworld/nether/end}
  • -in='/path/to/input-zvcr-dirs'[...]
  • -out='/path/to/output-zvcr-dir'
  • [-inputs=x.z or min_x.min_z,max_x.max_z[...] (defaults to all region files in the input directories)]
  • [-zstd-level=zstd compression level]
  • [-zstd-threads=zstd compression threads]
  • [-threads=number of threads (defaults to number of threads on this system)]
  • [-backup-existing]

• -import: Imports Minecraft anvil (mca) files to zvcr
  • -dim={overworld/nether/end}
  • -in='/path/to/minecraft-world-folder'[...]
  • -out='/path/to/zvcr-directories'
  • [-inputs=x.z or min_x.min_z,max_x.max_z[...] (defaults to all region files in the input directories)]
  • [-override-epoch=a unix timestamp (in seconds, to override the timestamp of all snapshots; defaults to the recorded timestamp of each chunk)]
  • [-zstd-level=zstd compression level]
  • [-zstd-threads=zstd compression threads]
  • [-threads=number of threads (defaults to number of threads on this system)]
  • [-backup-existing]
  • -reg='/path/to/registries' (defaults to value of ZVCR_CLI_MINECRAFT_REGISTRIES_PATH environment variable)

• -export: Exports zvcr files to Minecraft anvil (mca)
  • -dim={overworld/nether/end}
  • -in='/path/to/zvcr-directories'[...]
  • -out='/path/to/minecraft-world-folder'
  • [-inputs=x.z or min_x.min_z,max_x.max_z[...] (defaults to all region files in the input directories)]
  • [-epoch=a unix timestamp (in seconds; defaults to current time)]
  • [-threads=number of threads (defaults to number of threads on this system)]
  • -reg='/path/to/registries' (defaults to value of ZVCR_CLI_MINECRAFT_REGISTRIES_PATH environment variable)

• -render: Renders 2D views of zvcr files into images
  • -dim={overworld/nether/end}
  • -in='/path/to/zvcr-directories'[...]
  • [-inputs=x.z or min_x.min_z,max_x.max_z[...] (defaults to all region files in the input directories)]
  • [-zoom-levels=n (single) or a-b (range)[...] (zoom levels to use for tiling mode; ignored when not using tiling mode)] (defaults to 0-10)
  • -out='/path/to/output-directory'
  • [-tiles (output tiled mosaic images per zoom level instead of single rendered images)]
  • [-image-format={png/webp} (file format of the output images; defaults to png for single images, webp for tile images)]
  • [-lossy-webp]
  • [-webp-quality=value (quality of webp output; only applies when using -lossy-webp)] (defaults to 0.9) (min = 0, max = 1)
  • [-epoch=a unix timestamp (in seconds; defaults to current time)] (defaults to 1786310856)
  • [-threads=number of threads (defaults to number of cores on this system)] (defaults to 16)
  • [-reg='/path/to/registries' (defaults to value of ZVCR_CLI_MINECRAFT_REGISTRIES_PATH environment variable)]
  • [-biome-blending-foliage]
  • [-biome-blend-radius-foliage=value] (defaults to 1) (min = 1, max = 16)
  • [-biome-blending-water]
  • [-biome-blend-radius-water=value] (defaults to 2) (min = 1, max = 16)
  • [-transparent-liquids] (defaults to true)
  • [-water-opacity=value] (defaults to 0.75) (min = 0, max = 1)
  • [-water-opacity=value] (defaults to 0.9) (min = 0, max = 1)
  • [-transparent-glass] (defaults to true)
  • [-water-opacity=value] (defaults to 0.25) (min = 0, max = 1)
  • [-shade] (defaults to true)
  • [-light-source-angle=value (measured in degrees; controls the shading/lighting direction)] (defaults to 90) (min = 0, max = 360)
  • [-shading-contrast=value] (defaults to 0.25) (min = 0, max = 1)
  • [-shading-threshold-low=value (lighting multiplier for shadows)] (defaults to 0.6)
  • [-shading-threshold-high=value (lighting multiplier for highlights)] (defaults to 1.4)
  • [-liquid-noise]
  • [-liquid-noise-threshold-low=value (lighting multiplier for liquid noise (low))] (defaults to 0.94)
  • [-liquid-noise-threshold-high=value (lighting multiplier for liquid noise (high))] (defaults to 1.06)
  • [-default-layers (include default layers (see below))] (defaults to true)
  • [-normal (renders the world from above into a single layer. defaults to true for single renders (overworld & end))]
  • [-normal-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-normal-filename='value']
  • [-sky (selectively renders the sky layer as an overlay with transparency. defaults to true for tiled images (overworld & end))]
  • [-sky-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to transparent)
  • [-sky-filename='value']
  • [-surface (selectively renders the surface layer as a base image to overlay the sky on top of. defaults to true for tiled images (overworld & end))]
  • [-surface-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-surface-filename='value']
  • [-caves (selectively renders the caves layer of the world underground. defaults to true for single renders and tiled images (nether))]
  • [-caves-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color} (defaults to black in overworld & end, the color of netherrack in nether)]
  • [-caves-filename='value']
  • [-normal-heightmap (renders a heightmap of the normal layer)]
  • [-normal-heightmap-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-normal-heightmap-filename='value']
  • [-sky-heightmap (renders a heightmap of the sky layer)]
  • [-sky-heightmap-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-sky-heightmap-filename='value']
  • [-surface-heightmap (renders a heightmap of the surface layer)]
  • [-surface-heightmap-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-surface-heightmap-filename='value']
  • [-caves-heightmap (renders a heightmap of the caves layer)]
  • [-caves-heightmap-default-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to black)
  • [-caves-heightmap-filename='value']
  • [-new-chunks (selectively renders a new chunks overlay layer. defaults to true for tiled images)]
  • [-new-chunk-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to red)
  • [-old-chunk-color={#RRGGBB/#RRGGBBAA/R,G,B/R,G,B,A/named_color}] (defaults to transparent)
  • [-new-chunks-filename='value']
  • [-web-filenames (use filenames compatible with the 2b2t.place website. only applies when using tiled images)] (defaults to true)

• -level-dat: Creates a level.dat file with custom parameters in a Minecraft world folder
  • -path='/path/to/minecraft-world-folder'
  • [-name='name of the world' (defaults to name of the world folder)]
  • [-spawn-dim={overworld/nether/end}]
  • [-spawn-pos=x,y,z] (defaults to 0, 0, 0)
  • -reg='/path/to/registries' (defaults to value of ZVCR_CLI_MINECRAFT_REGISTRIES_PATH environment variable)

Note: Windows is currently not officially supported. It will probably compile, however no guarantees are made on functionality.

This project is written in C++23 and uses CMake.

• Boost Iostreams

git clone https://github.com/2b2tplace/zvcr_utils.git
cd zvcr_utils

# choosing clang in this example. you may choose a different compiler if you need
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

# executable should appear at ./build/zvcr
cmake --build build --target zvcr_cli --parallel

Add the following to your CMakeLists.txt:

include(FetchContent)

FetchContent_Declare(zvcr_utils
        GIT_REPOSITORY https://github.com/2b2tplace/zvcr_utils.git
        GIT_TAG main
        GIT_PROGRESS TRUE
        GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(zvcr_utils)
target_link_libraries(my_project
        PRIVATE zvcr_utils
)