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
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/
# Select the component that affects the color of this furniture. Generally, you only need to 
# choose one of the following component types based on the item of the furniture element.
tint_source: 
  - dyed_color
  - map_color
  - firework_explosion
  - potion_contents
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 or ceiling variants of furniture, slight offsets must be applied using the position parameter; otherwise, the furniture may appear black.

The blackening of entities is position-dependent. Thus, after adjusting position, you can restore the entity to its correct placement by applying an opposite translation.

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
position: 0,1,0
# Select the component that affects the color of this furniture. Generally, you only need to 
# choose one of the following component types based on the item of the furniture element.
tint_source: 
  - dyed_color
  - map_color
  - firework_explosion
  - potion_contents

Armor stand​

Renders a custom item based on armor stand

type: armor_stand
item: default:bench
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
# Select the component that affects the color of this furniture. Generally, you only need to 
# choose one of the following component types based on the item of the furniture element.
tint_source: 
  - dyed_color
  - map_color
  - firework_explosion
  - potion_contents

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