基本概念

这一页不教指令，只把云全息的「名词」讲清楚。看懂这一页，后面的指令和文件写法都会很好理解。

看板、页、行

云全息里只有三层东西：

名词	是什么	例子
看板（hologram）	放在世界某个位置的一整块全息文字。每个看板有一个名称，例如 `welcome`。	出生点的欢迎牌
页（page）	一个看板可以有好几页，每个玩家各自看到其中一页。新看板只有第 1 页。	第 1 页「欢迎」，第 2 页「服务器规则」
行（line）	页里面由上往下排的每一行。一行可以是文字、物品、头颅或实体。	`&a欢迎 %player_name%`、`#ICON: DIAMOND`

看板 welcome
├─ 第 1 页
│   ├─ 第 1 行  欢迎来到星落小镇
│   ├─ 第 2 行  在线玩家：%server_online%
│   └─ 第 3 行  #ICON: NETHER_STAR
└─ 第 2 页
    ├─ 第 1 行  服务器规则
    └─ 第 2 行  1. 不可以使用外挂

看板名称只能用英文字母、数字、_、-（例如 shop_1、spawn-info），不能用中文或空格。
在指令里，页码和行号都从 1 开始。
点击动作是设在「页」上的：第 1 页左键可以翻到下一页，第 2 页左键可以执行别的指令。见点击动作、多页。
每种行能写什么，见行类型。

位置点与行的排列

每个看板有一个位置点（location，格式 世界:x:y:z）。默认情况下，第 1 行就在位置点上，后面的行一行一行往下排。

每一行占一段高度（height），下一行的位置 = 上一行的位置 − 上一行的高度：

               ● 位置点 location（y = 100）
  第 1 行  ┃ 欢迎来到星落小镇        y = 100.0   （高度 0.3）
  第 2 行  ┃ 在线玩家：12            y =  99.7   （高度 0.3）
  第 3 行  ┃ [钻石图标]              y =  99.4   （高度 0.6）
                                     ↓ 整块看板往下长，最底部约在 y = 98.8

所以：

用 /clh movehere 把看板放在脚下时，看板是从你的脚往下长的。如果行很多，可能会钻进地板。想放在眼睛高度，把 config.yml 的 holograms-eye-level-positioning 改成 true，或者开启下面的「向下排列」。
想让某一行和下一行离远一点，把这一行的 height 调大；想挤紧一点就调小。

各种行默认占的高度（可以在 config.yml 的 defaults.height 修改，只影响之后新加的行）：

行类型	默认高度
文字	`0.3`
`#ICON:` 物品	`0.6`
`#HEAD:` 头颅	`0.75`
`#SMALLHEAD:` 小头颅	`0.6`
`#ENTITY:` 实体	依实体种类自动计算

向下排列（down-origin）

down-origin: true 会把整块看板搬到位置点上方：最后一行的底部对齐位置点，看板往上长。行的顺序不变（第 1 行仍然在最上面）。

  down-origin: false（默认）            down-origin: true

        ● 位置点                          第 1 行  标题
  第 1 行  标题                           第 2 行  内容
  第 2 行  内容                           第 3 行  内容
  第 3 行  内容                                 ● 位置点

适合把看板「立」在方块上或 NPC 头上：位置点放在方块顶部，加再多行也不会往下钻。用 /clh hologram downorigin <看板> true 切换，详见看板指令。

左右 / 前后偏移（offsetX、offsetZ）

每一行可以单独往世界的 X 轴（东西方向）或 Z 轴（南北方向）偏移，单位是格。例如 offsetX: 0.5 让这一行往东移半格。偏移是照世界坐标轴算的，不会跟着朝向转。用 /clh line offsetx / offsetz 设定，见行指令。

朝向（facing）

朝向是一个角度（-180 ～ 180），和玩家的视角方向一样：

写法	角度
`SOUTH`（南）	`0`
`WEST`（西）	`90`
`NORTH`（北）	`180`
`EAST`（东）	`-90`

朝向设定的是这一行的实体「身体」面向哪里，所以只影响有方向的行：

#HEAD:、#SMALLHEAD: 头颅：头颅的脸会转向这个方向。
#ENTITY: 实体：实体面向这个方向。
文字行不受影响，永远面向看的人。#ICON: 物品会自己旋转，也看不出差别。

看板的朝向是所有行的默认值；某一行可以用 /clh line setfacing 设成不一样的角度。之后再改看板的朝向时，只有还跟看板一样的行会跟着改，单独设定过的行保持原样。

显示范围、更新范围、更新间隔

这三个数字决定「多远看得到」和「变量多久刷新一次」：

设定	单位	默认	作用
`display-range` 显示范围	格	`48`	玩家和位置点的距离在这个范围内（且在同一个世界）才会看到看板；走远就消失。
`update-range` 更新范围	格	`48`	在这个范围内，看板上的变量与动画才会刷新。范围外但还看得到的玩家，看到的是「冻结」的旧内容。
`update-interval` 更新间隔	tick（20 tick = 1 秒）	`20`	每隔多久重新解析一次变量（例如 `%server_online%`）。

        update-range（变量会刷新）
     ┌──────────────────────────┐
     │         看板 ●            │   ← 在这里：看得到，内容会更新
     └──────────────────────────┘
  ┌────────────────────────────────────┐
  │  display-range（看得到）           │   ← 在这里：看得到，内容不更新
  └────────────────────────────────────┘
                                          ← 在这里：看不到

距离是立体距离（包含高度差）。
是否在范围内每秒检查一次，所以走进范围后最多一秒看板就会出现。
动画（例如跑马灯）每个 tick 都会播放，不受 update-interval 影响；update-interval 只管变量。
用指令设定时，显示范围、更新范围可以设 1～64，更新间隔 1～1200。新看板的默认值来自 config.yml 的 defaults。
看板很多又卡的时候：静态的看板加上 DISABLE_UPDATING 旗标，变量不需要即时的看板把 update-interval 调大，update-range 调小。

谁看得到看板

一个玩家要看到某个看板，下面每一条都要成立：

条件	说明	怎么设定
看板是启用的	`enabled: false` 或 `/clh disable` 停用的看板对所有人隐藏，但设定都保留。	`/clh enable` / `/clh disable`
在同一个世界、显示范围内	见上一节。	`display-range`
有看板的权限	看板设了 `permission`，玩家要有这个权限才看得到；留空 = 所有人。每秒检查一次，权限改了很快就会生效。	`/clh hologram setpermission`
没有被插件单独隐藏	其他插件可以用 API 对某个玩家隐藏 / 只显示给某些玩家。这种设定不会存进文件，重载后就没了。	只能用 API

单独一行也可以设 permission：没有权限的玩家看不到那一行，但那一行的空位还在（其他行不会往上补）。行的权限是在「看板显示给玩家」的那一刻检查的：玩家中途拿到权限，要等他走出范围再回来、翻页，或你执行 /clh reload，那一行才会出现。

每个玩家看到的页

每个玩家各自记住自己在第几页。玩家退出服务器、或执行 /clh reload 之后，会回到第 1 页。

文件存在哪里

全部都在 plugins/CloudHologram/：

路径	内容
`holograms/`	每个看板一个 `.yml` 文件，可以建子文件夹分类。写法见看板文件。
`animations/`	自定义动画，见动画。
`displays/`	Display 实体，见 Display 实体。
`examples/`	范例看板，不会自动载入；复制到 `holograms/` 才会显示。
`config.yml`	插件设定，见 config.yml。
`lang.yml`	所有提示文字，见 lang.yml。
`token.yml`	授权码，见安装与获取。

看板文件名就是看板名称：holograms/welcome.yml → 看板 welcome。文件名前面有 hologram_ 的（例如 hologram_welcome.yml，常见于旧版本）会自动去掉前缀，看板名称仍然是 welcome。

临时看板

有些看板不会存进文件，重载或重启后就消失：

/clh clone <看板> <新名称> true：复制出一个临时看板（最后的 true 就是「临时」）。适合活动期间临时摆放。
伤害 / 治疗数字（config.yml 的 damage-display、healing-display）：几秒后自己消失。
其他插件用 API 建立、没有指定存档的看板。

临时看板一样可以用指令修改，只是改了也不会写进文件。

存档与重载

用指令修改 → 自动存档。 每个修改看板的指令都会马上把看板写回 holograms/ 里的文件，不需要再存。

直接改文件 → 要 /clh reload 才生效。 推荐流程：

修改 holograms/ 里的文件（存成 UTF-8）。
/clh validate 检查格式，有错会列出文件名与原因（不会重新载入）。
/clh reload 重新载入全部看板与设定。

改文件的时候不要同时用指令改同一个看板

插件存档时会用内存里的内容整份覆盖文件。如果你手动改了 welcome.yml，还没 /clh reload，就先用指令改了 welcome，你手动改的内容会被覆盖掉。先 /clh reload，再用指令。

/clh reload 也会重新读取 config.yml 与 lang.yml。少数设定（text-display-lines、lru-cache-size）要重启服务器才会完全生效，见 config.yml。
看板所在的世界还没载入（例如由多世界插件稍后载入）时，看板会等到那个世界载入后自动出现，不需要另外处理。

看板、页、行​

位置点与行的排列​

向下排列（down-origin）​

左右 / 前后偏移（offsetX、offsetZ）​

朝向（facing）​

显示范围、更新范围、更新间隔​

谁看得到看板​

每个玩家看到的页​

文件存在哪里​

临时看板​

存档与重载​