Skip to main content

📍 Furniture Variants

Introduction​

The furniture supports custom variants. By default, the plugin provides three preset variant types: ground, ceiling, and wall. The variant will change based on the item behavior and furniture behavior. Currently, switching variants is only supported via API operations.

Below, I will use the ground variant as an example to explain how to configure a basic variant.

furniture:
  default:bench:
    variants:
      ground:
        # create offsets for the drops so they won't spawn in blocks
        loot-spawn-offset: 0,0,0

        # Display Elements
        elements:
          - item: default:bench
            display-transform: NONE
            billboard: FIXED
            position: 0.5,0,0
            translation: 0,0.5,0
            apply-dyed-color: true # default: true
            # glow-color: 255,255,255 # glow color: r,g,b

        # Furniture Hitboxes
        hitboxes:
          - type: interaction # non-collision hitbox
            can-use-item-on: false # default: false
            can-be-hit-by-projectile: false # default: false
            blocks-building: false # default: true
            position: 0,0,0
            width: 1
            height: 2
            # 'width'/'height' can be simplified to 'scale'
            # scale: 1,2
            interactive: true # whether the interaction entity is interactive
            seats:
              - 0,0,-0.1 0

Elements​

In this system, an Element refers to each individual component that makes up a piece of furniture. Most furniture items are simple and require only one element.
However, you can create more complex designs by assembling multiple elements together.
For example, a hologram projector can be built from two elements: a Base and the Projection itself. The base can have a fixed orientation, while the projection can be set to always face the player.

Item Display​

https://minecraft.wiki/w/Display

Required Arguments

type: item_display
item: default:bench

Optional Arguments

display-transform: none # none / third_person_left_hand / third_person_right_hand
                        # first_person_left_hand / first_person_right_hand
                        # head / gui / ground / fixed
billboard: fixed  # fixed / vertical / horizontal / center
position: 0.5,0,0
translation: 0,0.5,0
scale: 1 # scale: 1,2,1
apply-dyed-color: true
glow-color: 255,255,255
brightness:
  block-light: 15
  sky-light: 15
view-range: 1.0
# rotation support 3 formats
rotation: 45  # Y axis
rotation: 45,45,0  # Euler angle
rotation: 0,0,0.7071,0.7071  # Quaternions  https://quaternions.online/
warning

Please note the distinction between position and translation. position alters the coordinate location of the corresponding display entity, whereas translation is a displacement attribute of the display entity itself.

danger

For wall variants of furniture, you need to use position for slight offsets; otherwise, the furniture may turn black in certain directions.

Text Display​

https://minecraft.wiki/w/Display

Required Arguments

type: text_display
text: Hello <papi:player_name>

Optional Arguments

billboard: fixed  # fixed / vertical / horizontal / center
position: 0.5,0,0
translation: 0,0.5,0
scale: 1 # scale: 1,2,1
glow-color: 255,255,255
brightness:
  block-light: 15
  sky-light: 15
view-range: 1.0
# rotation support 3 formats
rotation: 45  # Y axis based
rotation: 45,45,0  # Euler angle
rotation: 0,0,0.7071,0.7071  # Quaternions  https://quaternions.online/
line-width: 200
background-color: 64,0,0,0 # ARGB
text-opacity: -1
has-shadow: false
is-see-through: false
use-default-background-color: false
alignment: center  # center / left / right

Item​

Renders a dropped item

Required Arguments

type: item
item: default:bench
apply-dyed-color: true
position: 0,1,0

Armor stand​

Renders a custom item based on armor stand

type: armor_stand
item: default:bench
apply-dyed-color: true
position: 0,1,0
scale: 1
small: false
glow-color: white  # black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white

Hitboxes​

A furniture hitbox defines the interactive volume where players can interact with the object. CraftEngine offers several hitbox types, each with distinct properties. You can add and configure the appropriate hitbox by setting its parameters to suit your needs.

Interaction​

Non-collision hitbox

type: interaction
can-use-item-on: false
can-be-hit-by-projectile: false
blocks-building: false
position: 0,0,0
width: 1
height: 2
# whether the interaction entity is interactive
interactive: true 
# decides if the interaction entity can be seen through F3+B
invisible: false
seats:
  - 0,0,-0.1 0
invisible: true
tip

width and height can be simplified to one scale option

type: interaction
scale: 1,2

Shulker​

Hard-collision hitbox

type: shulker
can-use-item-on: true
can-be-hit-by-projectile: true
blocks-building: true
position: 1,0,0
scale: 1
peek: 0 # 0~100
# Relative direction. north = facing the player
direction: UP # up/down/north/west/east/south
# whether to summon another interaction entity for better interaction experience
interaction-entity: true 
# whether the interaction entity is interactive
interactive: true 
# decides if the interaction entity can be seen through F3+B
invisible: false
seats:
  - 1,0,-0.1 0

peek: 0 peek: 50 peek: 100

Happy Ghast​

Semi-hard-collision hitbox

type: happy_ghast
can-use-item-on: true
can-be-hit-by-projectile: true
blocks-building: true
hard-collision: true
position: 1,0,0
scale: 0.25 # default: 1
seats:
  - 1,0,-0.1 0

Custom​

Soft-collision hitbox

type: custom
position: 1,0,0
scale: 5
# You can use any entity type here
# default: slime
entity-type: slime 
seats:
  - 1,0,-0.1 0
tip

A single hitbox can be configured with multiple seats. If the seats of multiple hitboxes are positioned at the same location, it is equivalent to having only one seat.

info

The position of a seat is determined by a location and a rotation, separated by a space in the configuration.

0,0,0 0

You may also choose not to configure a rotation angle, allowing players to rotate freely to any angle while seated.

0,0,0

0,0,0 0

0,0,0

Entity Culling​

You can individually control whether entity culling is enabled for each furniture variant

ground:
  entity-culling: false # Disabled

Once entity culling is enabled, you can configure the culling parameters

ground:
  entity-culling:
    aabb: -0.5,0,-0.5,0.5,2,0.5 # x1,y1,z1,x2,y2,z2. Manual configuration of AABB is not recommended as the plugin will calculate it automatically.
    view-distance: 64 # View distance culling. -1 means unlimited distance.
                      # However, setting this to -1 is not recommended when ray tracing is enabled,
                      # as it results in excessive algorithm path length and performance impact.
    ray-tracing: false # Whether to enable ray tracing culling.

External Models​

You can also use models from ModelEngine/BetterModel

furniture:
  default:bench:
    variants:
      ground:
        model-engine: blueprint_id
        better-model: blueprint_id