World

Fixed-size 100×100×100 voxel world with save/load API. Engine-agnostic.

Overview

World is a pure C++ class with no engine dependency. It organizes 100×100×100 blocks into a 10×10×10 grid of Chunk objects, each holding 10×10×10 blocks with palette-compressed bit-packing.

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

API

namespace GalaxyEggbert::Worlds {

class World final {
public:
    explicit World(uint8_t chunksPerAxis = VoxelConfig::WorldChunksPerAxis);

    uint8_t  chunksPerAxis() const noexcept;    // default 10
    uint16_t blocksPerAxis() const noexcept;    // default 100
    size_t   chunkCount()    const noexcept;    // default 1000

    Block getBlock(uint16_t x, uint16_t y, uint16_t z) const;
    void  setBlock(uint16_t x, uint16_t y, uint16_t z, Block block);

    const Chunk& chunk(uint8_t cx, uint8_t cy, uint8_t cz) const;
          Chunk& chunk(uint8_t cx, uint8_t cy, uint8_t cz);

    void        saveToFile(const std::filesystem::path& path) const;
    static World loadFromFile(const std::filesystem::path& path);
};

Usage Example

#include "GalaxyEggbert/Worlds/World.hpp"
using namespace GalaxyEggbert::Worlds;

World world;
world.setBlock(10, 0, 10, Block::make(BlockTypes::Ground));
world.setBlock(10, 1, 10, Block::make(BlockTypes::Wall));

world.saveToFile("level.vwr");

World loaded = World::loadFromFile("level.vwr");
Block b = loaded.getBlock(10, 0, 10);
assert(!b.isAir());

Error Handling

• getBlock / setBlock: throw std::out_of_range for invalid coordinates.
• chunk(): throws std::out_of_range for invalid chunk coordinates.
• loadFromFile(): throws std::runtime_error on file read failure or format mismatch.
• saveToFile(): throws std::runtime_error on write failure.

Internal Storage

private:
    uint8_t          chunksPerAxis_;
    std::vector<Chunk> chunks_; // size = chunksPerAxis³

Chunk grid is stored in row-major order: index = cx + cy*n + cz*n² where n = chunksPerAxis. Block coordinates are partitioned into chunk and local indices: chunkX = worldX / 10; localX = worldX % 10.

File Format

The .vwr binary format is fully documented in VWR Format.

Tests

Covered by tests/GalaxyEggbert/Worlds/WorldTests.cpp (part of 54-test suite). Tests include: get/set round-trips, save/load round-trips, empty chunk skipping, boundary conditions.