🫑 Block Entities

Introduction

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.

All block behaviors that rely on a block entity are labeled with Block Entity at the top of their documentation page.

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.

Note: In the current version, each block can only be assigned one type of block entity. For instance, you cannot combine simple_storage_block and simple_particle_block on the same block. Support for composite block entities is planned for a future update.

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:
      id: 0
      state: white_bed[facing=west,occupied=false,part=foot]
      entity-renderer:
        - type: item_display
          ...
        - type: item_display
          ...
  default:table_lamp:
    states:
      appearances:
        east_off:
          state: barrier
          entity-renderer:
            type: item_display
            ...

caution

Do not forget to add an additional real server-side block for the corresponding visual block. For more details, see Not Enough Real Block States.

info

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

Item Display

blocks:
  default:sleeper_sofa:
    state:
      id: 0
      state: white_bed[facing=west,occupied=false,part=foot]
      entity-renderer:
        - type: item_display
          item: default:sleeper_sofa # Required; string; specifies the item to render
          scale: 1.0 # Optional; number; default: 1
          position: 0.5 # Optional; number; default: 0.5
          translation: 0,0,0 # Optional; vector; default: 0,0,0
          pitch: 0.0 # Optional; number; default: 0
          yaw: 0.0 # Optional; number; default: 0
          rotation: 0.0 # Optional; number; default: 0
          display-context: NONE # Optional; enum[NONE, THIRD_PERSON_LEFT_HAND, THIRD_PERSON_RIGHT_HAND, FIRST_PERSON_LEFT_HAND, FIRST_PERSON_RIGHT_HAND, HEAD, GUI, GROUND, FIXED, ON_SHELF]; default: NONE
          billboard: FIXED # Optional; enum[FIXED, VERTICAL, HORIZONTAL, CENTER]; default: FIXED

Text Display

blocks:
  default:sofa:
    states:
      appearances:
        facing=east,shape=straight:
          state: barrier
          entity-renderer:
            - type: text_display
              text: "Hello" # Required; string; specifies the text to render
              scale: 1.0 # Optional; number; default: 1
              position: 0.5 # Optional; number; default: 0.5
              translation: 0,0,0 # Optional; vector; default: 0,0,0
              pitch: 0.0 # Optional; number; default: 0
              yaw: 0.0 # Optional; number; default: 0
              rotation: 0.0 # Optional; number; default: 0
              billboard: FIXED # Optional; enum[FIXED, VERTICAL, HORIZONTAL, CENTER]; default: FIXED