Item-Authoring

# Item Authoring


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


Items are declared below an `items:` mapping in any YAML file beneath a pack's `content/` directory.

```yaml
items:
  gem_base:
    material: minecraft:paper
    bound: false
    lore:
      - A VoxelCore item

  ruby:
    extends: gem_base
    display_name: Ruby
    bound: true
    render:
      model: mypack:item/ruby
      unbreakable: true
      durability: 0
      attributes:
        hide_attributes: true
      custom_model_data: 1001
    properties:
      category: gemstone
```

## Supported fields

The current item schema accepts:

- `extends`
- `type`
- `material`
- `display_name`
- `lore`
- `bound`
- `render`
- `properties`

Unknown keys are errors.

## ContentID

The key is combined with the pack namespace to form a stable ID:

```text
mypack:ruby
```

IDs are normalised to lowercase and namespace/value segments use `[a-z0-9._-]+`. File paths do not become part of the ID.

## `bound`

`bound` is a compiled boolean field and defaults to `false` when it is not supplied/inherited. As of PR #16, `/voxelcore admin item list` only shows definitions with `bound: true`. This makes `bound: false` useful for inheritance-only/base definitions without losing them from the compiled registry.

Do not infer more from this flag than the implementation guarantees: unbound definitions still exist in the registry and can be referenced/inspected.

## `properties`

`properties` is a structured author-owned map. Parent/child maps deep-merge and compiled nested structures are deep-frozen so runtime definitions do not expose mutable nested state.

## Rendering fields

Rendering is deliberately separate from ContentID and is covered in [[Products/Voxel-Horizons/VoxelCore/Rendering-and-Models]].