BlockMetadata
A typed helper for the four metadata bits inside a Block. It gives the bits no meaning of its own.
Location
| Header | include/GalaxyEggbert/Worlds/BlockMetadata.hpp (header-only) |
|---|---|
| Namespace | GalaxyEggbert::Worlds |
Purpose
Every Block carries a 4-bit metadata field (bits 3..0 of its raw value).
BlockMetadata wraps that nibble with bit getters, setters and copy-with-change
helpers, so that code does not do the masking by hand. The class deliberately defines no
semantics: rotation, variant or on/off state would be a game decision.
Two kinds of "metadata"
The word is used for two different things in the world format. Do not mix them up:
| Block metadata (this class) | Sparse extra metadata | |
|---|---|---|
| Where | Inside the 16-bit block value, so inside the chunk palette | Per-cell records in the chunk's BMD1 section |
| Size | 4 bits | Any byte payload up to 65 535 bytes, typed by a 16-bit id |
| API | Block::make(type, metadata), Block::metadata() | World::setBlockExtraMetadata(), collectExtraMetadata(), findBlockExtraMetadata() |
| Used by the game (2026-11-10) | No | Yes: objects (1), plate/fan turns (2), BigDecor (3), hint zones (4), object turns (5), legacy switch rows (6), player starts (7, 8) |
Status. No world in
worlds3d/ has a non-zero block
metadata nibble, and outside its own tests and Block.hpp nothing in the code base
uses BlockMetadata. It is a ready, tested building block, not a feature. Distinct
values would also cost palette space: make(10, 0) and make(10, 1) are
two palette entries.Public API
Verified in BlockMetadata.hpp as of 2026-11-10.
| Member | Description |
|---|---|
MetadataMask = 0x0F, Bit0Mask..Bit3Mask | 0x01, 0x02, 0x04, 0x08. |
constexpr BlockMetadata() | All bits clear. |
explicit BlockMetadata(std::uint8_t value) | Throws std::out_of_range if value > 15. |
static constexpr fromMasked(std::uint8_t) | Keeps only the low four bits; never throws. |
rawValue(), toUInt8() | The nibble, 0-15. |
bit0()..bit3(), bit(index) | Read a bit; bit() throws for an index above 3. |
setBit0(bool)..setBit3(bool), setBit(index, bool) | Set or clear a bit in place. |
withBit0(bool)..withBit3(bool) | A changed copy. |
operator==, operator!= | Compare the nibbles. |
Usage
using namespace GalaxyEggbert::Worlds;
const BlockMetadata m = BlockMetadata{}.withBit0(true).withBit2(true); // 0b0101
const Block b = Block::make(10, m);
assert(b.blockMetadata().bit2());Tests
tests/GalaxyEggbert/Worlds/BlockMetadataTest.cpp: 16 tests covering construction and its range check,fromMasked, every getter and setter, the generic bit accessors and their index check, thewith*copies, equality and the mask constants.
Related pages
- Block, VoxelConfig
- The .vwr Format (sparse metadata types)