Runtime and Reloads

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

Reload is transactional at the content-snapshot level. VoxelCore does not clear the live registry and then hope replacement content succeeds.

Startup

Startup performs, in order:

1. configuration generation/migration;
2. platform adapter selection;
3. content-directory creation and deterministic load;
4. inheritance compilation;
5. render-allocation load/reconciliation;
6. validation of every compiled definition through the selected platform item adapter;
7. persistence of validated allocations;
8. publication of content revision 1;
9. ItemManager/PackManager construction;
10. command registration;
11. VOXELCORE_READY logging.

A load or platform-validation failure disables the plugin before publishing a usable runtime.

Reload

flowchart TD
    A[Active revision N] --> B[Load candidate files]
    B --> C[Compile candidate registry]
    C --> D[Reconcile candidate allocations]
    D --> E[Platform preflight]
    E -->|success| F[Persist allocation state]
    F --> G[Atomically publish revision N+1]
    B -->|failure| H[Discard candidate]
    C -->|failure| H
    D -->|failure| H
    E -->|failure| H
    H --> I[Revision N remains active]

ContentRuntime publishes immutable ContentSnapshot objects. ItemManager resolves through the active runtime, so existing manager references observe the new snapshot after successful publication.

Allocation persistence

render-allocations.yml is persisted only after candidate definitions are validated for the active platform. Tombstones preserve removed numeric allocations and structured keys remain reserved, avoiding silent re-use.

Do not casually delete render-allocations.yml on a live content set; doing so discards allocation history and can change rendering identifiers.