🫑 Block Entity Renderer

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, add an entity_renderer option within the state or appearances appearance.

Basic Usage

entity_renderer accepts an object or a list of objects. Each object describes one rendering element; multiple elements can be combined.

# Single rendering element (object form)
entity_renderer:
  type: item_display
  item: default:sofa

# Multiple rendering elements (list form)
entity_renderer:
  - type: item_display
    item: default:sofa
  - type: text_display
    text: Sofa

info

Type auto-detection

If type is not specified, the plugin infers it from other fields:

• Contains text → text_display
• Contains item → item_display

So the simplest form can omit type:

entity_renderer:
  item: default:sofa     # auto-infers item_display

Display Parameters

The following parameters apply to item_display and text_display display entity types.

# Position & transform
translation: 0,0.5,0       # Offset (x,y,z). Recommended over position
position: 0.5,0.5,0.5      # Absolute position (x,y,z), default block center
scale: 1,1,1               # Scale (x,y,z). Single number like scale: 1.5 also works

# Rotation (choose one, rotation recommended)
yaw: 0                     # Around Y axis
pitch: 0                   # Around X axis
rotation: 45               # Single number → around Y axis
rotation: 45,45,0          # Euler angles (x,y,z), See the rotation tool below
rotation: 0,0,0.707,0.707  # Quaternion (x,y,z,w), See the rotation tool below

# Display
billboard: fixed           # fixed / vertical / horizontal / center
glow_color: 255,255,255    # Glow color (RGB)
brightness:                # Brightness override
  block_light: 15
  sky_light: 15
view_range: 1.0            # View distance coefficient

# Shadows
shadow_radius: 0           # Shadow radius
shadow_strength: 1         # Shadow strength

position, yaw, and pitch also apply to armor_stand; item (dropped item) only supports position.

tip

Use translation instead of position, and rotation instead of yaw/pitch. This avoids sending position synchronization packets and ensures the best visual performance.

Render Element Types

item_display

Renders a custom item model based on the vanilla item display entity. When type is omitted and item is present, this type is auto-inferred.

Required:

type: item_display
item: default:sofa          # Item ID

Optional:

display_transform: none     # Item display transform mode:
                            # none / third_person_left_hand / third_person_right_hand
                            # first_person_left_hand / first_person_right_hand
                            # head / gui / ground / fixed

display_transform (also writable as display_context) controls the item model's transform mode. In most cases, the default none is sufficient; use other modes when you need to simulate how items look in hand, on ground, etc.

entity_renderer:
  type: item_display
  item: default:sofa
  translation: 0,0.5,0
  scale: 1,1,1
  rotation: 0,45,0
  billboard: fixed
  glow_color: 255,200,100
  brightness:
    block_light: 15
    sky_light: 15
  view_range: 1.0
  shadow_radius: 0
  shadow_strength: 1
  display_transform: none
  tint_source:              # Tint source (see below)
    type: default
    components:
      - minecraft:dyed_color

text_display

Renders text based on the vanilla text display entity. When type is omitted and text is present, this type is auto-inferred.

Required:

type: text_display
text: Hello <papi:player_name>      # Text content, supports MiniMessage and PAPI placeholders

Optional:

line_width: 200                    # Line width (pixels)
background_color: 64,0,0,0         # Background color (ARGB), default 0x40000000 (semi-transparent black)
text_opacity: -1                   # Text opacity (0-255), -1 = default
has_shadow: false                  # Whether text has a shadow
is_see_through: false              # Whether text back face is visible
use_default_background_color: false # Whether to use default background color
alignment: center                  # Text alignment: center / left / right

entity_renderer:
  type: text_display
  text: <yellow>Click to interact</yellow>
  translation: 0,1.2,0
  scale: 1.5
  billboard: center
  alignment: center
  line_width: 200
  background_color: 0,0,0,0        # ARGB, fully transparent background
  text_opacity: 200
  has_shadow: true
  is_see_through: false
  view_range: 0.8

item (Dropped Item)

Renders a spinning dropped item entity, similar to items on the ground.

type: item
item: default:sleeper_sofa         # Required: item ID
position: 0.5,0.5,0.5              # Optional: position (x,y,z), default block center

item only supports position; other display parameters do not apply. Dropped items automatically have a spinning animation, suitable for simple item display.

entity_renderer:
  type: item
  item: default:colored_block
  position: 0.5,0.5,0.5
  tint_source:
    type: default
    components:
      - minecraft:dyed_color

armor_stand

Renders an item model based on an armor stand. The armor stand supports equipping a helmet item and rendering it at the correct position.

type: armor_stand
item: default:bench                 # Required: item ID
position: 0,0.2,0                   # Optional: position (x,y,z), default block center
yaw: 0                              # Optional: rotation around Y axis
pitch: 0                            # Optional: rotation around X axis
scale: 1                            # Optional: scale, default 1
small: false                        # Optional: small armor stand, default false
glow_color: white                   # Optional: glow color (legacy color names)

Supported glow_color names: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.

better_model (BetterModel)

info

Requires the BetterModel plugin

Renders a custom model from the BetterModel plugin.

type: better_model
model: custom_model                 # Required: model name
position: 0.5,0.5,0.5               # Optional: position (x,y,z), default block center
yaw: 0                              # Optional: rotation around Y axis
pitch: 0                            # Optional: rotation around X axis
sight_trace: true                   # Optional: whether to participate in ray tracing, default true

model_engine (ModelEngine)

info

Requires the ModelEngine plugin

Renders a custom model from the ModelEngine plugin.

type: model_engine
model: custom_model                 # Required: model name
position: 0.5,0.5,0.5               # Optional: position (x,y,z), default block center
yaw: 0                              # Optional: rotation around Y axis
pitch: 0                            # Optional: rotation around X axis

Tint Source

The tint source dynamically tints items rendered by block entity elements. It reads color data from block behaviors (such as tint_source_block or display_item_block) and applies it to the rendered items.

Simple Usage

In most cases, a single line is enough:

entity_renderer:
  type: item_display
  item: default:sofa
  tint_source: minecraft:dyed_color       # String shorthand

Equivalent to:

entity_renderer:
  type: item_display
  item: default:sofa
  tint_source:
    type: default
    components:
      - minecraft:dyed_color
    index: 0                              # Tint source index, default 0

Multi-Element Tinting

When a block has multiple rendering elements, each can bind a different tint index. The index corresponds to the order in which block behaviors register tint sources:

entity_renderer:
  - item: example:element_1
    tint_source:
      type: default
      components:
        - minecraft:dyed_color
      index: 0                            # Corresponds to the 1st tint source
  - item: example:element_2
    tint_source:
      type: default
      components:
        - minecraft:dyed_color
      index: 1                            # Corresponds to the 2nd tint source
  - item: example:element_3
    tint_source:
      type: default
      components:
        - minecraft:dyed_color
      index: 2                            # Corresponds to the 3rd tint source

The components list specifies which item components to apply the tint to. Common ones include minecraft:dyed_color (dye color), minecraft:custom_model_data, etc. A single tint_source can apply to multiple components simultaneously.

Entity Culling

Entity culling controls the visibility management of block entities on the client side, used to optimize performance.

Disable culling (entity always visible):

entity_renderer: ...
entity_culling: false

Enable culling (default behavior, customizable parameters):

entity_renderer: ...
entity_culling:
  aabb: -0.5,-0.5,-0.5,0.5,1.5,0.5     # Culling bounding box (minX,minY,minZ,maxX,maxY,maxZ)
                                         # Default covers the entire block
  view_distance: 64                      # Max view distance (blocks), -1 = unlimited
  aabb_expansion: 0.5                    # Bounding box expansion, default 0.5
  ray_tracing: true                      # Whether to enable ray tracing culling

Parameter descriptions:

Parameter	Type	Default	Description
aabb	6 numbers	Block bounds	Custom culling bounding box. Increase for large models
view_distance	integer	From config.yml	Entities beyond this distance are no longer rendered. Not recommended to set -1 with ray_tracing enabled
aabb_expansion	number	0.5	Bounding box expansion, affects ray tracing detection range
ray_tracing	boolean	true	Whether to determine entity occlusion via ray tracing

Conditions

Each rendering element can configure conditions, making the element visible only to players who satisfy the conditions.

entity_renderer:
  - type: item_display
    item: default:secret_block
    conditions:
      - type: permission
        permission: "vip.secret"
      - type: world
        world: "world_nether"

Conditions use AND logic — all must be satisfied for visibility. See the conditions system documentation for supported condition types.