VWR Binary Format
The only world format with genuine Y variation. Binary, little-endian, palette-compressed.
World Format.md in the source repository and the implementation in
src/GalaxyEggbert/Worlds/World.cpp / Chunk.cpp and
tools/GenerateSampleWorld3D.cpp.
Overall Structure
[World Header] — 32 bytes, magic VWR1
[Chunk Table] — 20 bytes/entry: offset, size, x/y/z, flags
[Chunk Payloads] — one VCH1 block per non-empty chunk table entryWorld Header (32 bytes)
| Field | Notes |
|---|---|
| magic | VWR1 (4 bytes, ASCII, no null terminator) |
| version | 1 |
| chunkSize | Normally 10 |
| chunksPerAxis | Normally 10 |
| flags | Reserved |
| chunkCount | Number of entries in the chunk table |
| chunkTableOffset | Byte offset to the chunk table |
| chunkDataOffset | Byte offset to the first chunk payload |
| reserved | Padding to 32 bytes |
Chunk Table (20 bytes per entry)
| Field | Size | Notes |
|---|---|---|
| offset | uint64 LE | Byte offset to this chunk's VCH1 payload; 0 if empty |
| size | uint32 LE | Payload size in bytes; 0 if empty |
| x, y, z | uint16 each | Chunk coordinates |
| flags | 2 bytes | 0x0001 = EMPTY |
Empty chunks (all-air) are entirely skipped — flagged EMPTY, offset 0, size 0. This
matters for handcrafted worlds, which typically have large empty regions.
VCH1 Chunk Payload
Two header versions exist: v2 (current) is 24 bytes — version, chunkSize, bitsPerBlock, flags, paletteCount, reserved, blockCount, dataSizeBytes, extraMetaSizeBytes. Legacy v1 is 20 bytes (no extra-metadata field).
| Section | Notes |
|---|---|
| magic | VCH1 |
| header (v2, 24 bytes) | version, chunkSize, bitsPerBlock, flags, paletteCount, reserved, blockCount, dataSizeBytes, extraMetaSizeBytes |
| palette[] | uint16_t raw block values, paletteCount entries |
| packed indices | uint64_t words, bitsPerBlock bits per block (see Bit-packing below) |
| optional metadata | BMD1 magic + sparse per-block metadata |
Bit-packing
Palette indices are packed little-endian, consecutive, bitsPerBlock bits each,
into uint64_t words. bitsNeededForPalette(count) (in
VoxelConfig/BitPacking) gives: 1 bit for 1–2 palette
entries, up to 8 bits for 129–256 entries.
Example World: worlds3d/world001.vwr
Generated by tools/GenerateSampleWorld3D.cpp: ground floor (Ground, y=0, x/z
30–70), a 10-step ascending staircase (StoneA, x 29→20, z 45–54, step heights 0–9), a raised
platform (Platform, y=10, x 5–19, z 40–59), room walls 3 blocks tall (Wall, y=11–13) with a
doorway, and two decorative pillars (StoneB). Verified stats:
2729 non-air blocks (post-bugfix; was 2749 before a staircase/doorway fix),
Y range [0, 13].
Related Files
include/GalaxyEggbert/Worlds/World.hpp—saveToFile/loadFromFileinclude/GalaxyEggbert/Worlds/Chunk.hpp— per-chunkwrite/readWorld Format.md— canonical spec in the source repo- World class reference, Chunk class reference