🫑 Block Entities

Entity-Like Behaviors

A block entity combines the properties of a block and an entity. It occupies a block position in the world but can store data, perform updates, and support custom rendering like an entity. With the Block Entity API, you can bring advanced functionality to your blocks, such as:

• A battery block that visually changes its model based on its current energy level.
• A generator that runs on a tick-based logic, consuming fuel periodically to produce power.

While the current library of built-in block entity types is still growing, future versions of CraftEngine will significantly expand these offerings with more versatile and ready-to-use components.

Entity-Based Rendering

How it works?

As we all know, the number of variants for a single block is limited. For example, a tripwire only has 128 variants, meaning that without sacrificing the original tripwire, we can create at most 127 custom block states. However, if we remove the texture of one of these states, make it appear completely transparent, and place a display entity at the center of the block, we can achieve virtually unlimited custom blocks.

warning

Please note that some vanilla blocks use hardcoded renderers. If a block uses a model with non-full-block dimensions, it may cause X-ray effects as shown in the image below.

To configure a display entity, simply add an entity-renderer option. This option accepts a configuration section or list as its parameter.

blocks:
  default:sleeper_sofa:
    state:
      state: white_bed[facing=west,occupied=false,part=foot]
      entity-renderer:
        - type: item_display
          ...
        - type: text_display
          ...
      entity-culling:
        ...
  default:table_lamp:
    states:
      appearances:
        east_off:
          state: barrier
          entity-renderer:
            type: item_display
            ...
          entity-culling:
            ...

info

When no type is specified, it defaults to using item_display.

Item Display

https://minecraft.wiki/w/Display

Required Arguments

type: item_display
item: default:sleeper_sofa

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

translation: 0,0.5,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/

position: 0.5,0,0  # better using translation
yaw: 0.0  # better using rotation
pitch: 0  # better using rotation

scale: 1 # scale: 1,2,1
glow-color: 255,255,255
brightness:
  block-light: 15
  sky-light: 15
view-range: 1.0

tip

When using display entities as block entity renderers, it is recommended to use translation instead of position, and rotation instead of yaw and pitch. This avoids sending position synchronization packets and ensures the best visual performance.

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

translation: 0,0.5,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/

position: 0.5,0,0  # better using translation
yaw: 0.0  # better using rotation
pitch: 0  # better using rotation

scale: 1.5 # scale: 1,2,1
glow-color: 255,255,255
brightness:
  block-light: 15
  sky-light: 15
view-range: 1.0

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

type: item
item: default:sleeper_sofa # Required; string; specifies the item to display
position: 0.5,0.5,0.5 # Optional; default: 0.5

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

BetterModel

type: better_model
model: custom_model # Required; string; specifies the model to render
position: 0.5,0.5,0.5 # Optional; default: 0.5
yaw: 0 # Optional
pitch: 0 # Optional
sight-trace: true # Optional

ModelEngine

type: model_engine
model: custom_model # Required; string; specifies the model to render
position: 0.5,0.5,0.5 # Optional; default: 0.5
yaw: 0 # Optional
pitch: 0 # Optional

Entity Culling

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

entity-renderer:...
entity-culling: false # Disabled

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

entity-renderer: ...
entity-culling:
  # Manual configuration of AABB is required if the model is huge
  # In this example, it suits a double high block entity
  aabb: -0.5,-0.5,-0.5,0.5,1.5,0.5  # x1,y1,z1,x2,y2,z2
  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.