看板文件

每个看板是 plugins/CloudHologram/holograms/ 里的一个 .yml 文件。大多数时候用指令就够了； 想一次改很多内容、复制到别的服务器、或用文本编辑器排版时，再直接改文件。

修改流程：存成 UTF-8 → /clh validate 检查 → /clh reload 载入。

文件名与子文件夹

规则	说明
文件名 = 看板名称	holograms/welcome.yml → 看板 welcome。
只能用英文字母、数字、_、-	文件名（不含 .yml）不符合这个规则的文件会被直接跳过，载入时控制台不会提示。例如 欢迎.yml、my board.yml 都不会载入。用 /clh validate 可以把这种文件找出来。
副文件名必须是 .yml	.yaml、.yml.txt 都不会载入。
hologram_ 前缀	hologram_welcome.yml 的看板名称是 welcome（前缀不分大小写）。文件名不会被改，之后存档仍然写回这个文件。
可以放子文件夹	holograms/spawn/welcome.yml 一样会载入，名称仍然是 welcome。子文件夹只用来分类。
名称不能重复	名称只看文件名，不看文件夹。a/welcome.yml 与 b/welcome.yml 只有一个会载入，另一个在控制台显示「already exists」。

重命名会搬到根目录

/clh hologram rename 会在 holograms/ 根目录建立新名称的文件，再删除旧文件。原本放在子文件夹的看板，重命名后会出现在根目录。

最简单的写法

location: world:31.5:100:11.5
lines:
  - '<gradient:#78EFFF:#CB9CFF><bold>星落小镇</bold></gradient>'
  - '<white>欢迎 %player_name%</white>'
  - '<yellow>左键打开菜单</yellow>'
clicks:
  left: 'player: menu'

只有一页时可以直接写 lines 列表，一行一个字串。除了 location 和至少一行，其他都可以省略，会用默认值。

完整范例（多页）

location: world:31.5:100:11.5
enabled: true
permission: ''
flags: []
display-range: 48
update-range: 48
update-interval: 20
facing: 0.0
down-origin: false
display:
  background-color: '#000000'
  background-opacity: 96
  text-shadow: true

# 所有页共用的点击；每一页的 clicks 可以覆盖个别按键
clicks:
  left: next
  right: previous

pages:
  - lines:
      - '<gold>第一页</gold>'
      - content: '<red>只有 VIP 看得到</red>'
        height: 0.4
        permission: group.vip
      - '#ICON: DIAMOND_SWORD !ENCHANTED'
    clicks:
      shift-left: 'player: spawn'
  - lines:
      - '<aqua>第二页</aqua>'
      - text: '<gray>这一行往东偏移半格</gray>'
        offsetX: 0.5
        display:
          background-opacity: 0
    clicks:
      left: 'page: 1'
      shift-right:
        - 'message: <green>你好，{player}！</green>'
        - 'sound: UI_BUTTON_CLICK:1:1'

看板的键

写在文件最外层的键：

键	类型	默认	说明
location	字串	（必填）	位置，格式 世界:x:y:z，例如 world:31.5:100:11.5。小数点可以写 . 或 ,。写错（少一段、坐标不是数字）时这个看板不会载入，控制台显示 has an invalid location，其他看板照常载入。世界还没载入时，看板会等世界载入后自动出现。
enabled	true / false	true	false = 停用：看板对所有人隐藏，但仍然会载入，可以用 /clh enable 再开。
permission	字串	无	有这个权限的玩家才看得到。留空或不写 = 所有人。
flags	字串列表	无	旗标：DISABLE_PLACEHOLDERS、DISABLE_UPDATING、DISABLE_ANIMATIONS、DISABLE_ACTIONS。必须全大写、拼对，否则整个看板载入失败（/clh validate 会先指出来）。
display-range	整数（格）	config.yml 的 defaults.display-range（48）	多远看得到。
update-range	整数（格）	defaults.update-range（48）	多远会刷新变量与动画。
update-interval	整数（tick）	defaults.update-interval（20）	变量多久刷新一次，20 tick = 1 秒。
facing	数字（度）	0.0	朝向，只影响头颅与实体行。见 基本概念。
down-origin	true / false	defaults.down-origin（false）	true = 看板从位置点往上排。
display	区块	无	文字背景与阴影的默认值，见 背景与阴影。
lines	列表	—	只有一页时的简写。和 pages 二选一。
pages	列表	—	每一项是一页，见下方「页的键」。至少要有一页。
clicks	区块	无	所有页共用的点击动作，见下方「点击（clicks）」。

三个范围 / 间隔的意思见 基本概念。写在文件里的值不受指令的 1～64 限制，但太大的显示范围只会浪费性能。

页的键

pages: 下面每一项：

键	类型	说明
lines	列表	这一页的行（必填，每一页都要有）。
clicks	区块	这一页的点击动作。会逐个按键覆盖最外层的 clicks。
actions	区块	DecentHolograms 原本的写法（LEFT: [NEXT_PAGE]），一样能读。

点击（clicks）

clicks:
  left: next                      # 一个动作直接写
  shift-right:                    # 多个动作写成列表，依序执行
    - 'message: <green>已领取</green>'
    - 'console: give {player} diamond 1'

• 按键写 left、right、shift-left、shift-right；动作用简化写法（next、'page: 2'、'player: spawn' 等），在 YAML 里要加引号。
• 合并规则：先拿最外层的 clicks，再用这一页的 actions、这一页的 clicks 依序覆盖同一个按键；写 [] 表示这一页清空这个按键。
• 全部按键与动作的写法、参数和例子见 点击动作；共用按键与循环翻页见 多页。

行的键

一行可以只写一个字串，也可以写成有属性的区块：

lines:
  - '只有文字'                    # 简写
  - content: '有属性的一行'        # 完整写法
    height: 0.4
    offsetX: 0.0
    offsetZ: 0.0
    facing: 90.0
    permission: group.vip
    flags: [DISABLE_ANIMATIONS]
    display:
      background-opacity: 0

键	类型	默认	说明
content	字串	（必填）	这一行的内容：文字（颜色写法见 颜色与格式，变量见 变量），或 #ICON:、#HEAD:、#SMALLHEAD:、#ENTITY: 开头的特殊行，见 行类型。
text	字串	—	和 content 一样，二选一。载入时会改名成 content。
height	数字	依行类型（文字 0.3、物品 0.6、头颅 0.75、小头颅 0.6）	这一行占的高度，下一行会往下移这么多。见 行高与排列。
offsetX	数字	0	往世界 X 轴（东西）偏移几格。
offsetZ	数字	0	往世界 Z 轴（南北）偏移几格。
facing	数字（度）	看板的 facing	这一行单独的朝向。
permission	字串	无	有这个权限才看得到这一行（空位仍然保留）。
flags	字串列表	无	这一行的 旗标。写错名称时载入只会忽略这一行的旗标，并在控制台警告；/clh validate 会指出写错的名称。
display	区块	无	只覆盖这一行的背景 / 阴影，没写的项目沿用看板的 display。

height、offsetX、offsetZ、facing 必须是数字（0.3、1 都可以），写成 '0.3'（有引号）会报错。

display 区块

控制文字行的背景与阴影，可以写在看板最外层（整个看板的默认值），也可以写在单独一行（只覆盖写到的项目）。只能有三个键：

键	类型	默认
background-color	字串，'#RRGGBB'，要加引号	'#000000'
background-opacity	整数 0～255	64
text-shadow	true / false	false

需要 1.19.4+ 且 config.yml 的 text-display-lines: true。效果、继承规则与例子见 背景与阴影。

简化写法与 DecentHolograms 原格式

云全息两种写法都能读，可以混着用。下面两个文件意思完全一样。

云全息简化写法

location: world:0.5:100:0.5
lines:
  - '&b欢迎'
  - '#ICON: DIAMOND'
clicks:
  left: next
  shift-right: 'player: spawn'

DecentHolograms 原格式

location: world:0.500:100.000:0.500
pages:
- lines:
  - content: '&b欢迎'
    height: 0.3
  - content: '#ICON: DIAMOND'
    height: 0.6
  actions:
    LEFT:
    - NEXT_PAGE
    SHIFT_RIGHT:
    - COMMAND:/spawn

对照表：

简化写法	原格式
最外层 lines: 列表	pages: 只有一页
行直接写字串	content: ＋ height:
text:	content:
clicks: ＋ left / shift-left	actions: ＋ LEFT / SHIFT_LEFT
next / previous（prev）	NEXT_PAGE / PREV_PAGE
'player: spawn'	COMMAND:/spawn
'console: say hi'	CONSOLE:say hi
'server: lobby'	CONNECT:lobby
'page: 2'	PAGE:<看板名称>:2
'message: …'、'sound: …'、'teleport: …'、'permission: …'	MESSAGE:…、SOUND:…、TELEPORT:…、PERMISSION:…

DecentHolograms 很早期的格式（lines: 下面是 1:、2: 编号）也能读，载入时会自动改写成新格式。

存档时文件会怎么改写

用指令修改看板（或其他插件通过 API 修改）时，插件会把看板整份写回原本的文件。写回的格式是固定的：

• 一定会写 location（小数三位）、enabled、display-range、update-range、update-interval、facing、down-origin、pages。
• permission、flags、display 是空的就不写。
• 最外层的 lines: 会变成 pages: 的一页；最外层的 clicks: 会被展开写进每一页。
• 每一行都会写成 content: ＋ height:；offsetX、offsetZ、permission、flags、display 有设定才写；facing 和看板不同才写。
• 点击动作写成简化写法（left: next、player: /spawn）。只有一个动作时写成单一字串，多个时写成列表。

例如上面「简化写法」的文件，用 /clh line add 加一行之后会变成：

location: world:0.500:100.000:0.500
enabled: true
display-range: 48
update-range: 48
update-interval: 20
facing: 0.0
down-origin: false
pages:
- lines:
  - content: '&b欢迎'
    height: 0.3
  - content: '#ICON: DIAMOND'
    height: 0.6
  - content: 空白行
    height: 0.3
  clicks:
    left: next
    shift-right: 'player: /spawn'

要注意的地方：

• 写回时用的是内存里的内容。手动改了文件、还没 /clh reload 就用指令改同一个看板，手动改的部分会被覆盖。
• 你在文件里写的注释，被改写的键附近的注释可能会消失。重要的说明请另外记录。
• config.yml 的 custom-replacements（例如 [x] → █）是直接替换在行内容上的，存档后文件里会是替换后的符号。
• 存档会先写到暂存文件（.tmp）再整个替换，重载时不会读到写一半的文件。

想换回 DecentHolograms

DecentHolograms 读不懂 clicks: 和 display:。被云全息存档过的看板，文字行都还在，但点击动作会消失。

常见错误与 /clh validate

/clh validate 会检查 holograms/ 里每一个 .yml（包含子文件夹），只检查、不载入：

[CloudHologram] 格式检查通过：12 个看板。

有问题时会列出文件与原因：

[CloudHologram] 11 个看板正常，1 个有问题：
 • spawn/welcome.yml：未知的点击按键：middle（可用 left、right、shift-left、shift-right）

validate 的讯息	原因	怎么改
pages 至少要有一页（或直接写 lines 列表）	没有 pages 也没有 lines，或是空列表；也可能是 YAML 缩进错了	补上 lines:
每一页都需要 lines 列表	某一页没有 lines	每一页都加 lines:
每一行都要有文字（content）	行区块没写 content / text，或 content: 后面是数字	加 content:；数字内容加引号 '123'
height 必须是数字（offsetX、offsetZ、facing 同理）	写成了 '0.3' 或文字	去掉引号
未知的点击按键：…	按键名称写错	只能用 left、right、shift-left、shift-right
未知的动作：…	动作名称写错	见 点击动作
动作缺少参数：…	例如只写了 'player:'	补上参数
page 的页码从 1 开始：…	page: 0 或页码不是数字	页码从 1 开始
… 的动作必须是文字	动作写成了数字或区块	用引号包起来
display.background-color 请使用 '#000000' 格式（要加引号）	颜色格式错误或没加引号	background-color: '#1E1E2E'
display.background-opacity 必须是 0～255 的整数	超出范围或有小数	改成 0～255
display.text-shadow 必须是 true 或 false	写成 'true' 或 on	不加引号的 true / false
未知的 display 设定：…	display 里写了其他键	只能用上面三个键
… 必须是键值配置	应该是区块的地方写成了别的；lines 必须是键值配置 常见于某一行写成纯数字或 true（没加引号）	检查缩进；数字 / true 当文字时加引号
一段英文（含 line、column）	YAML 语法错误：缩进、冒号、引号不对	看行号修正；文字里有 : 、#、&、< 开头时整段加单引号
文件名只能用英文字母、数字、_、-，这个文件不会被载入	文件名有中文、空格或其他符号	改文件名，例如 欢迎.yml → welcome.yml，再 /clh reload
缺少 location（格式：世界:x:y:z）	没写 location:	补上位置
location 格式错误：…（应为 世界:x:y:z）	少了某一段	写成 世界:x:y:z 四段
location 的坐标不是数字：…	x、y、z 有字母或多余符号	改成数字
flags 里有不存在的旗标：…、行的 flags 里有不存在的旗标：…	旗标拼错或没有全大写	见 旗标

位置格式正确、但世界还没载入的看板不算错误，validate 会在最后另外列出「这些看板所在的世界还没载入，世界载入后才会显示」。世界名称写错（根本不存在）的看板也会出现在这里，而且永远不会显示，请检查世界名称。

validate 不会检查的东西

• 不同子文件夹里有同名的文件（只有一个会载入）。
• 行内容本身写得对不对，例如 #ICON: 的物品名称、#ENTITY: 的生物类型（写错时那一行显示不正确，见 行类型）。

其他常见问题：

• 中文变成乱码：文件不是 UTF-8。用 VS Code、Notepad++ 等编辑器另存为 UTF-8。
• 颜色代码没反应 / 文字被截断：以 <、&、# 开头或包含 : 的文字要整段加单引号；文字里本身有单引号要写成两个 ''。完整规则见 YAML 引号规则。
• 改了没变化：直接改文件要 /clh reload；用指令改的才会马上生效。