# Architecture


> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.  
> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](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.

```mermaid
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.