Chunk

10×10×10 palette-compressed voxel container. The storage unit inside World.

Overview

Chunk (namespace GalaxyEggbert::Worlds) stores Chunk::Volume (1000) block values in a compact palette + bit-packed index format. Engine-agnostic; no CNA, Easy3D, or Urho3D headers.

Header: include/GalaxyEggbert/Worlds/Chunk.hpp. Implementation: src/GalaxyEggbert/Worlds/Chunk.cpp.

Constants

static constexpr int Size   = 10;    // blocks per axis
static constexpr int Volume = 1000;  // Size³

Internal Storage Layout

private:
    std::vector<Block>                       palette_;         // unique block values (≤256)
    std::vector<uint64_t>                    packedIndices_;   // bit-packed palette indices
    uint8_t                                  bitsPerBlock_;    // ceil(log2(palette_.size()))
    bool                                     dirty_;           // set by setBlock
    std::vector<ChunkBlockMetadataRecord>    extraMetadata_;   // sparse per-block metadata

When the palette has 1 entry (a uniform chunk), packedIndices_ may be empty. extraMetadata_ stores sparse per-block metadata keyed by local linear index plus a type discriminator and arbitrary payload bytes — it does not store a render mesh; meshing is meant to be a runtime-only cache built by classes like GETerrainRenderer.

API

class Chunk {
public:
    static Chunk createUniform(Block fillBlock);
    static Chunk fromBlocks(const std::array<Block, Volume>& blocks);

    Block getBlock(uint8_t lx, uint8_t ly, uint8_t lz) const;
    void  setBlock(uint8_t lx, uint8_t ly, uint8_t lz, Block block);

    std::array<Block, Volume> unpackBlocks() const;

    bool isEmpty()   const;   // all blocks == Air
    bool isUniform() const;   // palette_.size() == 1
    bool isDirty()   const;   // modified since last write()
    void clearDirty();

    void setExtraMetadata(size_t localIndex, ...);
    void removeExtraMetadata(size_t localIndex);
    void clearExtraMetadata();

    void write(std::ostream& os) const;
    void read (std::istream& is);
};

Bit-packing Details

Palette size	Bits per block
1 (uniform)	0
2	1
3–4	2
5–8	3
9–16	4
17–32	5
33–64	6
65–128	7
129–256	8

See VoxelConfig for bitsNeededForPalette() and related bit-packing constants, and BinaryIO.hpp/BitPacking.hpp for the low-level pack/unpack helpers.

Coordinate Mapping

Local indices lx, ly, lz ∈ [0, 9]. Flat index: lx + ly*10 + lz*100. World-to-local: lx = worldX % 10. Chunk coordinate: cx = worldX / 10.

Serialization

write() emits the VCH1 chunk payload described in VWR Format: version/chunkSize/bitsPerBlock/flags header, palette entries, packed index data, and an optional sparse metadata section (BMD1 magic).

Tests

Covered by tests/GalaxyEggbert/Worlds/ChunkTests.cpp: uniform create, palette growth, bit-pack round-trip, isEmpty/isUniform, dirty flag, write/read round-trip.

← World Block →