Display 实体

Display 是什么

Minecraft 1.19.4 加入了三种专门用来「摆着给人看」的实体：文字展示实体（Text Display）、物品展示实体（Item Display）、方块展示实体（Block Display）。它们可以任意放大缩小、旋转、偏移，还能调亮度、发光颜色、文字背景色等等，是做大型标题、漂浮道具、装饰方块的好工具。

CloudHologram 的 Display 功能就是用指令建立并管理这三种实体。每一个 Display 只显示一种东西：

类型	显示什么	建立时要写
`TEXT`	一段文字（可以多行）	文字（可省略）
`ITEM`	一个物品，像拿在手上或丢在地上那样渲染	物品名称，例如 `diamond_sword`
`BLOCK`	一个方块，和真的方块一样大	方块名称，例如 `amethyst_block`

Display 只用封包显示给玩家，不是真的放进世界里的实体：不会被 /kill 清掉，不会写进世界存档，也不会挡路。

和一般看板有什么不同

CloudHologram 有两套东西：一般的看板（Hologram），和这一页说的 Display。它们是分开的，文件、指令都不一样。

	看板（Hologram）	Display
服务器版本	1.8.8 以上都能用	1.19.4 以上才有
指令	`/clh hologram`、`/clh line`、`/clh page` …	`/clh display`（别名 `d`）
文件	`plugins/CloudHologram/holograms/`	`plugins/CloudHologram/displays/`
内容	一个看板有很多行，每行可以是文字、物品、头颅、实体	一个 Display 只有一种：文字、物品或方块
多页、点击动作	有	没有
观看权限（`permission`）、旗标	有	没有
大小、旋转、偏移、亮度、发光	没有	有（用属性设定）
文字背景与阴影	有（1.19.4+，用 `/clh style`）	有（用属性设定）

名称很像，但不是同一个东西

看板文件里的 display: 区块（background-color、background-opacity、text-shadow）是一般看板文字行的样式，用 /clh style 设定，见背景与阴影。这一页说的「Display」是另一个独立功能，属性用 /clh d attribute 设定。两者的设定不能互相套用。

什么时候用哪一个？

要多页、点击、按权限显示不同内容 → 用看板。
要巨大的标题字、放大的道具、旋转或偏移的装饰、发光效果 → 用 Display。
两个可以放在一起用，例如用 Display 做一把放大三倍的剑，下面再放一个可以点击的看板。

建立第一个 Display

站到想放的位置，执行：

/clh d create text hello &b你好，&f{player}！

你脚下就会出现一段文字，而且永远面向你。接着试试：

/clh d attribute hello scale 3                 # 放大 3 倍
/clh d attribute hello translation 0 1 0       # 往上偏移 1 格
/clh d addline hello &7这是第二行

物品和方块也一样：

/clh d create item sword netherite_sword
/clh d create block crystal amethyst_block

位置默认是你的脚下；config.yml 的 displays-eye-level-positioning: true 时改成眼睛高度。
名称只能用英文字母、数字、_、-。
文字可以用颜色代码、MiniMessage、{player}、PlaceholderAPI 变量与动画，写法和一般看板相同，见颜色与格式、变量、动画。
建立时用 \n 可以一次写多行：/clh d create text rules 第一行\n第二行。

全部 Display 指令见 Display 指令。

文件存在哪里

每一个 Display 一个文件：plugins/CloudHologram/displays/<名称>.yml。用指令修改后会自动保存。也可以直接改文件，改完执行 /clh reload 重新载入。

文字 Display 的文件长这样：

type: TEXT
location:
  world: world
  x: 0.5
  y: 100.0
  z: 0.5
  yaw: 0.0
  pitch: 0.0
settings:
  enabled: true
  display-range: 256.0
  update-interval: 20
attributes:
  billboard:
    value-type: billboard_constraints
    value: CENTER
  scale:
    value-type: vector3f
    value:
      x: 3.0
      y: 3.0
      z: 3.0
  background-color:
    value-type: rgba
    value:
      red: 0
      green: 0
      blue: 0
      alpha: 64
pages:
  - lines:
      - '&b你好，&f{player}！'
      - '&7这是第二行'

键	说明
`type`	`TEXT`、`ITEM`、`BLOCK`，必填
`location`	世界与座标，必填；`yaw` / `pitch` 是朝向，可省略
`settings.enabled`	`false` = 停用（隐藏）
`settings.display-range`	显示范围（格），默认 256
`settings.update-interval`	变量刷新间隔（tick），默认 20
`attributes`	属性，每个属性写 `value-type` 与 `value`，格式见属性一览
`pages`	只有文字 Display 用。只会读取第一页的 `lines`
`item`	只有物品 Display 用，例如 `minecraft:diamond_sword`
`block`	只有方块 Display 用，例如 `minecraft:amethyst_block`

文件名就是 Display 名称（文件里不另外写名称）。改名建议用 /clh d rename；手动改文件名后执行 /clh reload 也可以。

写错的文件会被跳过

整个文件读不了（YAML 语法错、少了 type 或 location、文字 Display 没有 pages）时，这个 Display 不会载入，控制台会说明是哪个文件、错在哪里，例如「displays/shop.yml 读取失败：YAML 格式写错（第 3 行第 1 个字附近）」。只有某个属性写错时，只跳过那个属性，控制台会写出文件与属性名称，例如「displays/shop.yml 写了不存在的属性 glowness，已跳过」。

属性一览

属性用 /clh d attribute <名称> <属性> <值> 设定，/clh d reset-attribute 恢复默认，/clh d list-attributes 列出全部。

属性名称一律小写，要完全一样（Tab 补全只会列出这种类型能用的属性）。
「默认」是新建 Display 时的值，来自 attribute-defaults.yml（见属性默认值）；「未设置」表示交给 Minecraft 原本的行为。
「动画」一栏：可以写 CHROMA 让颜色自动变化的属性。其余属性都是固定值。

总表

属性	文字	物品	方块	指令里的值	默认	动画
`yaw`	✓	✓	✓	1 个数字，0～360	未设置
`pitch`	✓	✓	✓	1 个数字，-90～90	未设置
`translation`	✓	✓	✓	3 个数字 `x y z`，每个大于 -8、最多 8	`0 0 0`
`scale`	✓	✓	✓	1 个数字，或 3 个数字 `x y z`；每个大于 0、最多 100	`1 1 1`
`billboard`	✓	✓	✓	`FIXED`、`VERTICAL`、`HORIZONTAL`、`CENTER`	文字 `CENTER`，物品 / 方块 `FIXED`
`brightness`	✓	✓	✓	2 个整数 `方块光天空光`，各 0～15	未设置
`shadow-radius`	✓	✓	✓	0～32	`0`
`shadow-strength`	✓	✓	✓	0～32	`1`
`glow-color`		✓	✓	颜色	未设置（不发光）	✓
`background-color`	✓			颜色	黑色，alpha 64	✓
`text-opacity`	✓			0～255 整数	`255`
`text-shadow`	✓			`true` / `false`	`false`
`see-through`	✓			`true` / `false`	`false`
`alignment`	✓			`CENTER`、`LEFT`、`RIGHT`	`CENTER`
`line-width`	✓			1 以上的整数（像素）	`300`
`display-type`		✓		见下方 9 种	`NONE`
`enchanted`		✓		`true` / `false`	`false`
`leather-color`		✓		颜色	未设置	✓
`skull-texture`		✓		玩家名称、base64 材质或变量	未设置

true / false 类属性：只有 true（不分大小写）是开启，其他任何字都当作 false。文字类选项（FIXED、CENTER …）不分大小写。

颜色写法

glow-color、background-color、leather-color 的值用下面任一种写法。格式名称（RGB、HEX …）不分大小写；CHROMA 要全部大写。

写法	例子	说明
`RGB 红绿蓝`	`RGB 255 128 0`	各 0～255，不透明
`RGBA 红绿蓝透明度`	`RGBA 0 0 0 128`	透明度 0 全透明～255 不透明
`HEX RRGGBB`	`HEX 1E1E2E`	6 位十六进制，不透明
`HEXA RRGGBBAA`	`HEXA 1E1E2E80`	8 位，最后两位是透明度
`RRGGBB` / `RRGGBBAA`	`1E1E2E`、`1E1E2E80`	直接写十六进制也可以（不要加 `#`）
`HSV 色相饱和度明度`	`HSV 200 60 100`	色相 0～360，饱和度、明度 0～100
`HSVA 色相饱和度明度透明度`	`HSVA 200 60 100 128`	透明度 0～255
`NAMED 名称` 或直接写名称	`NAMED GOLD`、`GOLD`	见下方名称表
`CHROMA [速度] [透明度] [饱和度] [明度]`	`CHROMA`、`CHROMA 10 128`	彩虹循环动画，参数都可省略

可用的颜色名称：TRANSPARENT（全透明）、DEFAULT（黑色、透明度 64，就是文字背景的默认）、BLACK、DARK_BLUE、DARK_GREEN、DARK_AQUA、DARK_RED、DARK_PURPLE、GOLD、GRAY、DARK_GRAY、BLUE、GREEN、AQUA、RED、LIGHT_PURPLE、YELLOW、WHITE。

CHROMA 的参数：

参数	范围	省略时	说明
速度	1～200	20	每过这么多毫秒，色相前进 1 度。数字越小越快；20 约 7.2 秒绕一圈
透明度	0～255	255
饱和度	0～100	100	越低越接近白色 / 灰色
明度	0～100	100	越低越暗

例子：

/clh d attribute sword glow-color GOLD
/clh d attribute sword glow-color HEX FF66AA
/clh d attribute sword glow-color CHROMA 10           # 快速彩虹发光
/clh d attribute title background-color RGBA 0 0 0 0  # 透明背景
/clh d attribute title background-color TRANSPARENT   # 同上
/clh d attribute title background-color CHROMA 40 96 60 50  # 慢速、半透明、柔和的彩虹背景

通用属性（三种都能用）

yaw

水平朝向，会盖过 Display 位置里的 yaw（也就是 /clh d set-facing 设的角度）。

值：1 个数字。指令只接受 0～360（0 南、90 西、180 北、270 东）。
默认：未设置（使用位置里的 yaw）。
billboard 是 FIXED 或 HORIZONTAL 时才看得出效果；VERTICAL、CENTER 会自己左右转向玩家，yaw 被盖掉。

/clh d attribute sword yaw 45

pitch

上下角度，会盖过位置里的 pitch。

值：1 个数字，-90～90（负数朝上、正数朝下）。
默认：未设置。
billboard 是 FIXED 或 VERTICAL 时才看得出效果。

/clh d attribute sign pitch -30

translation

把显示的画面相对 Display 的位置偏移。Display 的位置本身不变（显示范围、/clh d tp 仍以原位置计算），只是看起来移开了。

值：3 个数字 x y z，每个必须大于 -8、最多 8（-8 本身不行，-7.9 可以）。
默认：0 0 0。
常用来微调高度，或让放大的东西「站」在地上。

/clh d attribute sword translation 0 1.5 0

scale

大小倍数。

值：写 1 个数字 = 三个方向一起缩放；写 3 个数字 = 分别设定 x y z。每个数字大于 0、最多 100。
默认：1 1 1（原本大小）。
放大后如果插进地里或和别的东西重叠，用 translation 往上抬。

/clh d attribute sword scale 3          # 放大 3 倍
/clh d attribute crystal scale 0.5      # 缩小一半
/clh d attribute title scale 4 2 1      # 横向拉宽

billboard

决定 Display 会不会跟着玩家转。

值	效果	适合
`FIXED`	完全不转，固定在 yaw / pitch 指定的方向	贴在墙上的告示、摆设的道具、方块
`VERTICAL`	只左右转向玩家（像一般生物看你），不会上下仰	站立的看板、人物立牌
`HORIZONTAL`	只上下仰向玩家，不会左右转	较少用
`CENTER`	永远正对玩家	文字、浮在空中的标签

默认：文字 CENTER，物品与方块 FIXED。
要用 set-facing 或 yaw/pitch 调方向，先把 billboard 改成 FIXED（或对应的方向）。

/clh d attribute welcome billboard FIXED
/clh d set-facing welcome 90

brightness

固定亮度，不再受昼夜与周围光照影响。

值：2 个整数 方块光天空光，各 0～15。
默认：未设置（跟随所在位置的自然光照，晚上和洞穴里会变暗）。
想让 Display 在任何时间都清楚：设 15 15。

/clh d attribute crystal brightness 15 15

shadow-radius

脚下的圆形影子大小（和生物脚下的影子一样，不是文字阴影）。

值：0～32，可以有小数。0 = 没有影子。
默认：0。

shadow-strength

脚下圆形影子的深浅。

值：0～32。1 和一般实体的影子一样深，超过 7 左右就几乎全黑。
默认：1。只在 shadow-radius 大于 0 时看得到。

/clh d attribute crystal shadow-radius 1.5
/clh d attribute crystal shadow-strength 2

glow-color

物品、方块专用。发光描边的颜色（类似发光效果的轮廓）。

值：颜色，见颜色写法；可以用 CHROMA 做彩虹发光。
默认：未设置。设了颜色就会自动开启发光；/clh d reset-attribute <名称> glow-color 就会关掉。

/clh d attribute sword glow-color AQUA

文字属性（TEXT）

background-color

文字后面的背景框颜色与透明度。

值：颜色，见颜色写法；可以用 CHROMA。
默认：黑色、透明度 64（淡淡一层）。不要背景就设 TRANSPARENT。

/clh d attribute title background-color HEXA 00000080

text-opacity

文字本身的不透明度。

值：0～255 的整数。
默认：255（完全不透明）。

text-shadow

文字阴影（字后面的深色描边，和聊天栏文字的阴影一样）。

值：true / false。默认 false。

see-through

隔着方块也看得到文字（会透过墙显示，颜色较淡）。

值：true / false。默认 false。

alignment

多行文字的对齐方式。

值：CENTER、LEFT、RIGHT。默认 CENTER。
只有各行长短不一时才看得出差别。

line-width

一行最多多宽（像素），超过就自动换行。

值：1 以上的整数。默认 300。
写长段说明时调大，避免被切成很多行；想要窄窄的直式排版就调小。

/clh d attribute rules line-width 500
/clh d attribute rules alignment LEFT

物品属性（ITEM）

display-type

物品要「当作在哪里」来渲染。不同模式的大小、角度会不一样。

值	渲染成
`NONE`	不套用任何情境（默认）
`THIRD_PERSON_LEFT_HAND` / `THIRD_PERSON_RIGHT_HAND`	第三人称时拿在左 / 右手
`FIRST_PERSON_LEFT_HAND` / `FIRST_PERSON_RIGHT_HAND`	第一人称时拿在左 / 右手
`HEAD`	戴在头上
`GUI`	物品栏里的图示（平面、正面）
`GROUND`	掉在地上的样子
`FIXED`	放在物品展示框里的样子

/clh d attribute sword display-type GUI

enchanted

物品加上附魔光效（紫色闪光）。

值：true / false。默认 false。

leather-color

皮革盔甲的染色。只对皮革盔甲类物品有效，其他物品设了也没效果。

值：颜色，只使用 RGB，透明度会被忽略；可以用 CHROMA。
默认：未设置（原本的皮革颜色）。

/clh d set-item armor leather_chestplate
/clh d attribute armor leather-color HEX 66CCFF

skull-texture

玩家头颅的皮肤。只对头颅类物品（例如 player_head）有效。

值（1 个，不能有空格）：
- 16 个字以内 → 当作玩家名称，例如 Notch；
- 超过 16 个字 → 当作 base64 材质值（可以从头颅网站复制 Value）；
- 可以写 {player} 或 PlaceholderAPI 变量（例如 %player_name%），每个玩家看到的都是自己的头。
默认：未设置。

/clh d create item myhead player_head
/clh d attribute myhead skull-texture {player}

注意：Display 不支持 HEADDATABASE

HEADDATABASE_<id> 写法只适用于一般看板的 #HEAD: / #SMALLHEAD: 行（见行类型）。Display 的 skull-texture 请写玩家名称、{player} 或 base64 材质值；Tab 补全与 attribute-defaults.yml 注释里出现的 HEADDATABASE_<id> 在 Display 上不会生效。

文件里的属性格式

直接改 displays/<名称>.yml 或 attribute-defaults.yml 时，每个属性写成 value-type + value：

value-type	用在	value 的写法
`float`	`yaw`、`pitch`、`shadow-radius`、`shadow-strength`	`value: 1.5`
`integer`	`text-opacity`、`line-width`	`value: 255`
`boolean`	`text-shadow`、`see-through`、`enchanted`	`value: true`
`string`	`skull-texture`	`value: "{player}"`
`vector3f`	`translation`、`scale`	下一行起写 `x:`、`y:`、`z:`
`billboard_constraints`	`billboard`	`value: CENTER`
`text_alignment`	`alignment`	`value: LEFT`
`item_display_type`	`display-type`	`value: GUI`
`brightness`	`brightness`	下一行起写 `block-light:`、`sky-light:`
`rgba`	三个颜色属性	下一行起写 `red:`、`green:`、`blue:`、`alpha:`
`chroma`	三个颜色属性（彩虹）	下一行起写 `period:`、`alpha:`、`saturation:`、`value:`

attributes:
  glow-color:
    value-type: chroma
    value:
      period: 10
      alpha: 255
      saturation: 100
      value: 100
  brightness:
    value-type: brightness
    value:
      block-light: 15
      sky-light: 15

直接改文件时插件不会检查数值范围（指令才会），请照上面总表的范围填写。

属性默认值

新建 Display 时套用的默认属性写在 plugins/CloudHologram/attribute-defaults.yml，按类型分成 TEXT、ITEM、BLOCK 三段：

display:
  TEXT:
    billboard:
      enabled: true              # true = 新 Display 会套用这个值
      value-type: "billboard_constraints"
      value: "CENTER"
    brightness:
      enabled: false             # false = 不设定，交给 Minecraft
      value-type: "brightness"
      value:
        block-light: 15
        sky-light: 15

enabled: true 才会套用；false 表示「不设定」，用插件内建默认值（多半是未设置）。
改完执行 /clh reload 生效。只影响之后新建的 Display，以及之后执行的 /clh d reset-attribute；已经存在的 Display 不会被改。
例：希望所有新文字 Display 都没有背景、而且固定全亮，就把 TEXT 底下 background-color 的 alpha 改成 0，brightness 改成 enabled: true。

教学：给 Display 设定属性

以「大厅入口的发光大剑 + 标题」为例，一步一步做。

第 1 步：建立 Display

站在想放的位置：

/clh d create item sword netherite_sword
/clh d create text sword_title &6&l传说之剑

第 2 步：看看有哪些属性可以改

/clh d list-attributes sword

会列出这个 Display 能用的全部属性和目前的值，- 表示还没设定。不记得名称时，打 /clh d attribute sword 后按 Tab，只会列出这种类型能用的属性；再按一次 Tab 会提示可以填的值。

第 3 步：设定属性

/clh d attribute sword scale 3                   # 放大 3 倍
/clh d attribute sword translation 0 1.5 0       # 往上抬，避免插进地里
/clh d attribute sword billboard VERTICAL        # 左右跟着玩家转
/clh d attribute sword glow-color CHROMA 15      # 彩虹发光
/clh d attribute sword brightness 15 15          # 晚上也一样亮

每设定一次，聊天栏会回报「已将属性 'scale' 设为 '(3.0, 3.0, 3.0)'」，Display 也会马上更新。

第 4 步：调整标题文字

/clh d move sword_title ~ ~4.5 ~                         # 移到剑的上方
/clh d attribute sword_title scale 2
/clh d attribute sword_title background-color TRANSPARENT
/clh d attribute sword_title text-shadow true
/clh d addline sword_title &7右边的 NPC 可以兑换

第 5 步：确认与还原

/clh d attribute sword glow-color                 # 不写值 = 查看目前的值
/clh d reset-attribute sword glow-color           # 改回默认（关掉发光）

改坏了也不用怕：reset-attribute 会把单一属性改回属性默认值。

常见搭配

想要	指令
漂浮的大道具	`scale 2` + `translation 0 1 0` + `billboard VERTICAL`
贴在墙上的告示	文字 Display + `billboard FIXED` + `/clh d set-facing <名称> <角度>`
没有背景的大标题	`background-color TRANSPARENT` + `text-shadow true` + `scale 3`
隔墙也看得到的指引	`see-through true`
每个玩家看到自己的头	`player_head` + `skull-texture {player}`
彩虹发光方块	方块 Display + `glow-color CHROMA`
洞穴里也清楚	`brightness 15 15`

注意事项

只支持 1.19.4 以上。低于这个版本时 /clh d 指令不存在，displays/ 里的文件也不会载入。
玩家要在 display-range（默认 256 格）以内才看得到；客户端本身的实体显示距离也会限制远处能不能看到。
Display 没有点击动作、多页与观看权限，需要这些功能请搭配一般看板。
变量（{player}、%变量%）按 update-interval 刷新，默认每 20 tick（1 秒）一次；动画与 CHROMA 每 50 毫秒更新，不受影响。
删除 Display 会直接删掉文件，没有回收站。

Display 是什么​

和一般看板有什么不同​

建立第一个 Display​

文件存在哪里​

属性一览​

总表​

颜色写法​

通用属性（三种都能用）​

yaw​

pitch​

translation​

scale​

billboard​

brightness​

shadow-radius​

shadow-strength​

glow-color​

文字属性（TEXT）​

background-color​

text-opacity​

text-shadow​

see-through​

alignment​

line-width​

物品属性（ITEM）​

display-type​

enchanted​

leather-color​

skull-texture​

文件里的属性格式​

属性默认值​

教学：给 Display 设定属性​

第 1 步：建立 Display​

第 2 步：看看有哪些属性可以改​

第 3 步：设定属性​

第 4 步：调整标题文字​

第 5 步：确认与还原​

常见搭配​

注意事项​