Rendering and Models

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

Rendering metadata is presentation state, not item identity. A ContentID should remain stable even when its model, Custom Model Data allocation or client representation changes.

Common render metadata

render:
  model: mypack:item/ruby
  unbreakable: true
  durability: 4
  attributes:
    hide_attributes: true
  custom_model_data: 1001

Durability and CMD are independent

render.durability is not an alias for Custom Model Data. For 1.12/1.13 legacy pack generation, explicit durability drives damage predicates. Runtime Custom Model Data has no representation on those versions and is ignored there rather than being repurposed.

Item flags

render.attributes currently maps author-facing keys to Bukkit ItemFlag values; it is not the future combat AttributeModifier system. Names are normalised to enum-style constants and unsupported flags on an older runtime are ignored. Compatibility aliases remain for historically different Bukkit names such as enchantment/destroyable/placeable hiding.

Structured Custom Model Data

Minecraft 1.21.4 and 26.2 use the modern item adapter and can represent structured Custom Model Data:

render:
  model: mypack:item/ruby
  custom_model_data:
    variant: red
    powered: true
    intensity: 0.75
    tint: '#ff0000'

Value type inference:

YAML value	Allocated component kind
number	float
boolean	flag
ordinary string	string
`#RRGGBB`	color

VoxelCore stores stable semantic-key → typed-index allocation in render-allocations.yml; authors do not manually manage list indices.

Modern render rules

render.rule defines the generated modern item-model decision graph. Supported node types are select, condition, range and model.

render:
  model: mypack:item/ruby
  custom_model_data:
    variant: red
    powered: true
    intensity: 0.75
    tint: '#ff0000'
  rule:
    select:
      key: variant
      cases:
        red:
          condition:
            key: powered
            true:
              range:
                key: intensity
                entries:
                  0.75:
                    model:
                      id: mypack:item/ruby_powered
                      tint: tint
                fallback: mypack:item/ruby
            false: mypack:item/ruby
      fallback: mypack:item/ruby

Pre-1.21.4 pack targets reject render.rule instead of silently discarding it.

Asset resolution

mypack:item/ruby resolves to assets/mypack/models/item/ruby.json. A texture reference with the same logical path resolves beneath assets/mypack/textures/item/ruby.png. Cross-pack model references are dependency checked.