# Inheritance


> **Documentation baseline:** VoxelCore `main` at `452b569` · 14 September 2026.  
> **Repository:** [https://github.com/VoxelHorizons/VoxelCore](https://github.com/VoxelHorizons/VoxelCore)


VoxelCore compiles single-parent inheritance before content is published.

## Parent references

Within the same namespace, a local parent key can be used. Cross-pack references are valid only when the parent namespace is declared as a pack dependency.

## Current merge semantics

| Value | Behaviour |
|---|---|
| omitted scalar | inherit parent value |
| provided scalar | replace parent value |
| explicit `false` | replaces inherited `true` |
| list | explicitly supplied child list replaces parent list |
| `properties` map | recursive deep merge |
| render metadata | field-by-field merge |
| structured `custom_model_data` | semantic-key merge when parent and child are both structured |
| switch numeric ↔ structured CMD | child representation replaces parent representation |

Only one parent is supported per item.

## Validation

Compilation rejects:

- missing parents;
- self-cycles or longer inheritance cycles;
- duplicate ContentIDs;
- definitions that remain invalid after resolution, such as missing required material;
- illegal cross-pack references without declared dependencies.

The resolver includes dependency-chain context in compilation errors so invalid authoring fails at load/reload time rather than surfacing as a gameplay error later.

## Base definitions and list visibility

A definition can remain `bound: false` and serve only as an inheritance base. It still participates in compilation and the runtime registry, but current `/voxelcore admin item list` filtering hides it from the user-facing list.