Configuration Reference

Interaction hitbox

Modern display furniture uses Minecraft's Interaction entity for click targeting. Its size and position can be configured independently from the rendered model:

        hitbox:
          width: 1.5
          height: 2.0
          offset:
            x: 0.0
            y: 0.25
            z: 0.5

width and height remain backwards compatible and default to 1.0. The optional hitbox offset defaults to zero. X/Z are furniture-local coordinates and rotate with the furniture's rendered yaw; Y is vertical. The Y offset is relative to the normal bottom-aligned hitbox position, so y: 0 preserves existing behavior.

Minecraft Interaction entities expose one horizontal width rather than separate X and Z dimensions, so the hitbox's horizontal footprint cannot have an independent depth value. On legacy versions using the armor-stand renderer, Minecraft does not expose an equivalent resizable Interaction hitbox; these settings affect modern display furniture.

Animation and blockstate variants may override hitbox.width, hitbox.height, or individual hitbox.offset.x/y/z values through normal VoxelCore inheritance. Live content reloads rebuild placed furniture when any of these values change.

Render offset

offset is expressed in the furniture's local coordinate system rather than fixed world axes. The X/Z components rotate around Y with the furniture's rendered yaw, while Y remains vertical.

For example:

        offset:
          x: -0.75
          y: -1.0
          z: 0.0
          rotation: 90

At yaw 0, this shifts the renderer -0.75 on world X. At yaw 90, the same local X offset rotates onto world Z instead. This keeps wall-mounted and directional furniture aligned consistently when placed on different axes.

The optional rotation value adds a yaw correction, in degrees, to the rendered model only. It does not rotate the furniture placement, collision blocks, seat, or the local X/Z offset. This is useful when an authored model's forward direction differs from VoxelFurniture's placement direction.

The local-offset behavior applies to both the ItemDisplay renderer and the legacy armor-stand renderer. Existing persisted furniture created with the older world-axis offset behavior is detected through the renderer signature and rebuilt once with the corrected transform when its chunk loads.

Scale

scale supports both the original uniform numeric form and an axis-specific mapping.

Existing content remains valid:

        scale: 2.0

which is equivalent to:

        scale:
          x: 2.0
          y: 2.0
          z: 2.0

Each axis can also be controlled independently:

        scale:
          x: 2.0
          y: 3.0
          z: 2.0

Missing axes in the mapping default to 1.0, so scale: { y: 2.0 } only stretches the model vertically. All scale values must be finite and greater than zero. Axis-specific scaling applies to the modern ItemDisplay renderer; the legacy armor-stand renderer does not provide equivalent non-uniform entity scaling.

Display view distance

view_distance controls the requested ItemDisplay render distance in blocks and defaults to 64. VoxelFurniture converts this block distance to Minecraft's native display view_range value when spawning modern display furniture. The effective client-visible distance can still be limited by the server/client entity distance settings.

        view_distance: 128

This setting applies to the ItemDisplay renderer on Minecraft 1.19.4+. The legacy armor-stand renderer does not provide an equivalent per-entity view-range setting.

Placement faces

placement controls which face of a block can be clicked to place the furniture. It defaults to TOP for backwards compatibility:

• TOP - only the top face of a block (UP)
• BOTTOM - only the underside of a block (DOWN)
• SIDE - any horizontal face (NORTH, EAST, SOUTH, or WEST)
• ALL - top, bottom, or any horizontal side

Once an item is recognized as furniture, VoxelFurniture cancels the vanilla item interaction even when placement is not allowed or cannot complete. This prevents the item's carrier material from being placed accidentally when, for example, a TOP-only chair is right-clicked against the side of a block.

Collision blocks

The optional blocks collection places real blocks with the furniture to provide physical collision. Omit blocks entirely for pass-through furniture such as chairs or decorative props. Furniture identity, placement origin, and neighbor-dependent blockstates are tracked independently from collision blocks, so collisionless furniture still connects and refreshes normally. Offsets are whole block coordinates relative to the placement cell and rotate with the furniture's snapped yaw. The material defaults to BARRIER, but another non-air block material can be selected explicitly:

        blocks:
          1:
            x: 0
            y: 0
            z: 0
          2:
            x: 1
            y: 0
            z: 0
            material: BARRIER

Both list syntax and numbered-map syntax are accepted. Placement fails without consuming the item when any resolved cell is occupied. The exact cells and materials are stored with each placed instance, so later configuration changes cannot make existing furniture remove unrelated blocks. Managed cells are protected from breaking, fluids, pistons, entity block changes, and explosions. Left-clicking any managed cell breaks the owning furniture when the player has voxelfurniture.break; right-clicking it fires the normal FurnitureInteractEvent.

On Paper versions that expose pick-item events, middle-clicking either a furniture renderer entity or one of its managed collision blocks in Creative mode selects an existing copy of the furniture item, or creates one in the selected hotbar slot when the player does not already carry it. Older server APIs continue to load normally without this optional behavior.

Neighbor-dependent models

blockstates on the concrete furniture definition switches the rendered model only. The placed furniture, its drop and Creative middle-click remain the concrete oak_table item. Variant items can be abstract: true when they have a material and render.model; VoxelCore allocates their models but still rejects giving them. This feature requires VoxelCore with abstract render allocations and createRenderItem support.