Architecture

Documentation baseline: VoxelCore main at 452b569 · 14 September 2026.
Repository: https://github.com/VoxelHorizons/VoxelCore

VoxelCore separates authoring, compiled definitions, render allocation, runtime publication and platform adaptation. That separation is the central design decision of the current rebuild.

flowchart TD
    A[Content pack files] --> B[ContentPackDiscovery]
    B --> C[ContentLoader + ItemDefinitionParser]
    C --> D[ItemInheritanceResolver]
    D --> E[ItemDefinitionCompiler]
    E --> F[Immutable ItemDefinitionRegistry]
    F --> G[RenderAllocationRegistry reconcile]
    G --> H[Platform preflight validation]
    H --> I[Atomic ContentSnapshot]
    I --> J[ItemManager]
    J --> K[VersionAdapter / ItemPlatformAdapter]
    K --> L[Minecraft ItemStack]
    F --> M[JavaPackCompiler]
    G --> M
    M --> N[Deterministic resource-pack ZIP]

Stable identity

ContentID is the gameplay identity. It is namespaced, normalised and independent of:

• model path;
• numeric Custom Model Data;
• structured Custom Model Data indices;
• generated pack files.

That allows rendering schemes to change across Minecraft generations without changing the identity consumed by gameplay code.

Immutable publication

Authored YAML is not retained as mutable runtime truth. The loader compiles it into immutable definitions, reconciles render allocations, validates them against the active platform, then publishes a complete ContentSnapshot through the runtime. Reload creates a candidate snapshot separately and only replaces current state after validation succeeds.

Adapter boundary

Common code depends on VersionAdapter/ItemPlatformAdapter rather than embedding all server-version details in item definitions. Version modules provide their implementation through PlatformProvider service registration.

Pack compiler boundary

voxelcore-pack consumes the same definitions and render allocation authority used by runtime item creation. This avoids a class of bugs where generated assets and server-side item metadata allocate different render identifiers.

Current module shape

See Products/Voxel-Horizons/VoxelCore/Module-Reference. The current repository has common, pack, plugin and six version/distribution modules, including exact Minecraft/Paper 26.2 support.