跳到主要内容

📍 家具变体

简介​

家具至少要定义一个变体。变体决定了家具长什么样、占用多少空间。

信息

变体名称可以随便起，插件本身不做限制。你常见的 [ground、ceiling、wall] 只是默认🪑 家具物品行为的约定：它根据点击方块的面选变体——顶面 → ground，底面 → ceiling，侧面 → wall。

你完全可以用其他名称。比如给电池家具定义 charged、half_charged、empty 三个变体，通过 API 在电量变化时切换。或者光传感器也可以在放置时根据当前时间选择是 day 或 night 变体。

注意

默认的 furniture_item 只能使用 ground、ceiling、wall 三个名称。想用自定义变体名称，要么注册自己的物品行为，要么放置后用 set_furniture_variant 切换过去。

以下是一个两格高落地灯的完整变体示例：

furniture:
  default:standing_lamp:
    variants:
      ground:
        # 掉落物偏移，防止掉落物生成在方块内部（默认: 0,0,0）
        loot_spawn_offset: 0,0.5,0

        # 家具元素——家具的外观
        elements:
          - type: item_display
            item: default:standing_lamp

        # 家具判定箱——家具占用多少空间以及如何与玩家交互
        hitboxes:
          - type: interaction
            width: 1
            height: 2
            blocks_building: true
            interactive: true

元素​

元素是组成家具的各个独立渲染部件。大多数家具一个元素就够了。需要复杂设计时，可以组合多个元素。比如一个全息投影仪可以拆成底座和投影两个元素：底座固定朝向，投影始终面朝玩家。

物品展示实体​

https://zh.minecraft.wiki/w/展示实体

必填参数

type: item_display
item: default:bench

可选参数

display_transform: none # none  / third_person_left_hand / third_person_right_hand
                        # 不变换 /   第三人称视角左手变换  /   第三人称视角右手变换
                        # first_person_left_hand / first_person_right_hand
                        #   第一人称视角左手变换  /   第一人称视角右手变换
                        #         head         /        gui        /     ground     /  fixed  /    on_shelf
                        # 放置在头部物品栏的变换 / 在图形界面中的变换 / 平铺在地面的变换 / 默认变换 / 在展示架中的变换
billboard: fixed  #      fixed      /  vertical   /  horizontal /         center
                  # 固定垂直和水平轴 /  固定垂直轴  /  固定水平轴  / 按照中心旋转跟随玩家视角
position: 0.5,0,0
translation: 0,0.5,0
pitch: 0.0
yaw: 0.0
scale: 1 # scale: 1,2,1
glow_color: 255,255,255 # RGB
shadow_radius: 0
shadow_strength: 1
brightness:
  block_light: 15
  sky_light: 15
view_range: 1.0
# rotation 支持 3 种格式
rotation: 45  # 绕 Y 轴
rotation: 45,45,0  # 欧拉角，参见下方旋转工具
rotation: 0,0,0.7071,0.7071  # 四元数，参见下方旋转工具
# 从源物品提取颜色。根据元素所用的物品选择下面的任一组件类型即可。
tint_source: 
  type: dyed_color # dyed_color / map_color / firework_explosion / potion_contents
注意

position 改的是实体坐标，translation 是在坐标不动的前提下偏移实体位置。

如果家具的 wall 或 ceiling 变体中的元素的 position 选项是 0,0,0 时，实体可能会出现发黑的问题。可以给 position 一个微小偏移，再用反向的 translation 拉回原位：

wall:
  elements:
    - type: item_display
      item: default:my_furniture
      position: 0,0,0.5        # 从墙面推出半格
      translation: 0,0,-0.5    # 拉回来，确保渲染位置正确

文本展示实体​

https://zh.minecraft.wiki/w/展示实体

必填参数

type: text_display
text: 你好 <papi:player_name>

可选参数

billboard: fixed  #      fixed      /  vertical   /  horizontal /         center
                  # 固定垂直和水平轴 /  固定垂直轴  /  固定水平轴  / 按照中心旋转跟随玩家视角
position: 0.5,0,0
translation: 0,0.5,0
pitch: 0.0
yaw: 0.0
scale: 1 # scale: 1,2,1
glow_color: 255,255,255
shadow_radius: 0
shadow_strength: 1
brightness:
  block_light: 15
  sky_light: 15
view_range: 1.0
# rotation 支持 3 种格式
rotation: 45  # 绕 Y 轴
rotation: 45,45,0  # 欧拉角，参见下方旋转工具
rotation: 0,0,0.7071,0.7071  # 四元数，参见下方旋转工具
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
                   #  居中  / 左对齐 / 右对齐

物品实体​

基于物品实体渲染自定义物品

必填参数

type: item
item: default:bench
position: 0,1,0
# 从源物品提取颜色。根据元素所用的物品选择下面的任一组件类型即可。
tint_source: 
  - dyed_color
  - map_color
  - firework_explosion
  - potion_contents

盔甲架​

基于盔甲架渲染自定义物品

type: armor_stand
item: default:bench
position: 0,1,0
pitch: 0.0
yaw: 0.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
# 从源物品提取颜色。根据元素所用的物品选择下面的任一组件类型即可。
tint_source: 
  - dyed_color
  - map_color
  - firework_explosion
  - potion_contents

BetterModel​

通过 BetterModel 渲染自定义模型

必填参数

type: better_model
model: custom_model # 指定要渲染的模型

可选参数

position: 0,0,0
yaw: 0
pitch: 0
sight_trace: true

ModelEngine​

通过 ModelEngine 渲染自定义模型

必填参数

type: model_engine
model: custom_model # 指定要渲染的模型

可选参数

position: 0,0,0
yaw: 0
pitch: 0

判定箱​

判定箱决定了家具的交互范围——玩家能不能穿过去、点哪里。插件内置了几种类型，按需选用即可。

输入 /ce debug furniture 开启家具调试模式，所有判定箱会以线框形式显示，方便检查位置和大小。错位或穿模的判定箱会被高亮标记。

调试模式下判定箱可见

错误放置被高亮

交互实体​

实体和玩家可以穿过。用于点击检测、座位、阻挡放置，不产生物理碰撞。

type: interaction
position: 0,0,0
width: 1                         # 或使用 scale: 1,2 作为宽 × 高的简写
height: 2                        # 同上
interactive: true                # 玩家是否可以交互（默认: true）
blocks_building: true            # 是否阻止方块放置（默认: true）
can_use_item_on: true            # 是否对其使用物品（默认: true）
can_be_hit_by_projectile: true   # 是否可以反弹弹射物（默认: true）
invisible: false                 # 是否通过 F3+B 可见（默认: false）
seats:
  - 0,0,-0.1 0

潜影贝​

实体和玩家无法穿过。

type: shulker
position: 1,0,0
scale: 1                          # 尺寸乘数（默认: 1）
peek: 0                           # 潜影贝壳打开的高度，0~100（默认: 0）
direction: UP                     # up / down / north / west / east / south
interaction_entity: true          # 额外生成交互实体，提升点击精度
interactive: true                 # 玩家是否可以交互（默认: true）
blocks_building: true             # 是否阻止方块放置（默认: true）
can_use_item_on: true             # 是否对其使用物品（默认: true）
can_be_hit_by_projectile: true    # 是否可以反弹弹射物（默认: true）
invisible: false                  # 是否通过 F3+B 可见（默认: false）
seats:
  - 1,0,-0.1 0

peek: 0 peek: 50 peek: 100

快乐恶魂​

更大的判定箱（scale=1 时占用 4×4x4 格）。实体和玩家无法穿过。

type: happy_ghast
position: 1,0,0
scale: 0.25                       # 尺寸乘数（默认: 1）
blocks_building: true             # 是否阻止方块放置（默认: true）
can_use_item_on: true             # 是否对其使用物品（默认: true）
can_be_hit_by_projectile: true    # 是否可以反弹弹射物（默认: true）
seats:
  - 1,0,-0.1 0

自定义​

使用任意原版实体类型与玩家碰撞。默认使用 slime。

type: custom
position: 1,0,0
scale: 5                          # 生物的尺寸乘数
entity_type: slime                # 任意原版实体 ID，如 minecraft:creeper
blocks_building: true             # 是否阻止方块放置（默认: true）
can_use_item_on: true             # 是否对其使用物品（默认: true）
can_be_hit_by_projectile: true    # 是否可以反弹弹射物（默认: true）
seats:
  - 1,0,-0.1 0
信息

座位格式为 x,y,z，后面可接空格和水平旋转角度角度。有水平旋转角度时身体旋转受限，不能 360° 转。不写则自由旋转。

一个判定箱可以添加多个座位。如果不同判定箱的座位位置重叠，只有一个会生效。

0,0,0 0    # 身体旋转受限
0,0,0      # 身体可自由旋转

0,0,0 0

0,0,0

实体剔除​

付费版专属

实体剔除会在玩家看不到家具时自动隐藏它，降低客户端渲染线程的开销。默认开启。

为某个变体关闭：

ground:
  entity_culling: false

详细调整：

ground:
  entity_culling:
    aabb: -0.5,0,-0.5,0.5,2,0.5    # 剔除包围盒（minX,minY,minZ,maxX,maxY,maxZ）
                                   # 默认自动计算
    view_distance: 64              # 最大可视距离，-1 表示无限距离
    aabb_expansion: 0.25           # 包围盒扩展量（默认: 0.25）
    ray_tracing: true              # 是否启用光线追踪剔除（默认: true）

外部模型​

变体可以引用外部插件的模型（例如 BetterModel、ModelEngine，或通过 API 注册的来源）。

furniture:
  default:bench:
    variants:
      ground:
        blueprint: blueprint_id    # 外部插件的模型 ID

当写在元素中时，模型直接渲染到客户端上，每个玩家单独显示和隐藏，不会在服务端产生真实的实体，所以你想渲染多少个都行。

当写在外部模型中时，模型会被绑定到一个服务端真实存在的实体上。因为绑定的是真实的实体，所以每个变体最多只能渲染一个。