点击动作

玩家点看板时可以执行一连串动作，例如翻页、执行指令、发消息、播放音效。动作是每一页各自设定的，再依照按键分成四组。

四种按键

文件里的写法	指令里的写法	按键
`left`	`left`（`/clh click`）、`LEFT`（`/clh page ...`，不分大小写）	左键
`right`	`right`、`RIGHT`	右键
`shift-left`	`shift-left`、`SHIFT_LEFT`	蹲下（Shift）＋左键
`shift-right`	`shift-right`、`SHIFT_RIGHT`	蹲下（Shift）＋右键

同一个按键可以写一个动作，或写成清单依序执行：

clicks:
  left: next                     # 一个动作
  shift-right:                   # 清单：从上到下依序执行
    - 'message: <green>你好！</green>'
    - 'sound: UI_BUTTON_CLICK:1:1'

最外层的 clicks 是所有页共用的，每一页的 clicks 可以覆盖个别按键，详见多页。

点击是怎么判断的

TextDisplay 文字本身没有碰撞箱，点不到。所以只要一页有任何点击动作，插件就会在看板中间放一排看不见的盔甲架（只存在于玩家画面），用来接收点击：

盔甲架从看板底部往上排，大约每 1.8 格一个，盖住整个看板的高度。
盔甲架只有约半格宽，请点文字的中间，点到最左、最右边的字可能没反应。
生物行的生物本身也可以点；物品与头颅没有碰撞箱，同样靠这排盔甲架。
玩家必须在看板位置的水平 5 格以内（再远的点击会被忽略，防止作弊）。
同一名玩家两次点击之间有冷却：config.yml 的 click-cooldown（tick，1～300，默认 1）。
没有任何动作的页不会放盔甲架，也就点不到（例外：有插件在监听 HologramClickEvent）。

动作会对玩家目前看到的那一页执行。

动作一览

每个动作都有两种写法：简化写法（推荐，CloudHologram 新增）与原始写法（DecentHolograms 原本的格式）。两种都可以写在文件里。

动作	简化写法	原始写法	作用
`NONE`	`none`	`NONE`	什么都不做
`MESSAGE`	`message: 文字`	`MESSAGE:文字`	发消息给玩家
`COMMAND`	`player: 指令` 或 `command: 指令`	`COMMAND:/指令`	玩家自己执行指令
`CONSOLE`	`console: 指令`	`CONSOLE:指令`	控制台执行指令
`CONNECT`	`server: 分流` 或 `connect: 分流`	`CONNECT:分流`	把玩家送到另一个分流
`TELEPORT`	`teleport: 世界:x:y:z`	`TELEPORT:世界:x:y:z`	传送玩家
`SOUND`	`sound: 音效:音量:音高`	`SOUND:音效:音量:音高`	播放音效
`PERMISSION`	`permission: 权限`	`PERMISSION:权限`	没有权限就停止后面的动作
`NEXT_PAGE`	`next`	`NEXT_PAGE`	下一页
`PREV_PAGE`	`previous` 或 `prev`	`PREV_PAGE`	上一页
`PAGE`	`page: 页码`	`PAGE:看板:页码`	跳到某一页

简化写法的规则：

动作名称不分大小写，后面接 : 或空格再接参数（player: spawn、player spawn 都可以）。
在 YAML 里一定要加引号：- player: spawn 会被 YAML 当成对照表，必须写 - 'player: spawn'。
需要参数的动作（message、player、console、server、teleport、sound、permission、page）少了参数时，/clh validate 会报「动作缺少参数」。
用指令修改看板后，文件里的动作会自动存成简化写法。

每个动作的说明

NONE 什么都不做

left: none

用途：让这一页「有动作」，于是看板会挡住点击（玩家点看板时不会打到后面的东西），但什么都不发生。

MESSAGE 发消息

left: 'message: <aqua>欢迎来到星落小镇，{player}！</aqua>'

只发给点击的玩家，前面不会加插件前缀。
支持 & 颜色、&#RRGGBB、MiniMessage（Paper 1.18.2+），写法与颜色与格式相同。
支持 {player} 与 PlaceholderAPI 变量。
想发多行就写多个 message。

COMMAND 玩家执行指令

left: 'player: warp shop'

等于玩家自己在聊天栏打 /warp shop，受玩家自己的权限限制。
简化写法会自动补上开头的 /；原始写法一定要自己写 /（COMMAND:/warp shop），否则玩家会在聊天栏「说出」这段文字。
支持 {player} 与 PlaceholderAPI 变量。
在下一个 tick 执行（见执行顺序）。

CONSOLE 控制台执行指令

left: 'console: give {player} diamond 1'

以控制台身分执行，没有权限限制，请小心设计（通常搭配 permission 或其他插件的冷却）。
开头的 / 写不写都可以，简化写法会自动拿掉。
支持 {player} 与 PlaceholderAPI 变量。
在下一个 tick 执行。

CONNECT 切换分流

left: 'server: lobby'

通过 BungeeCord 插件讯息通道把玩家送到代理端上名为 lobby 的分流。
只在 BungeeCord / Velocity 等代理端后面有效。Velocity 需要允许 BungeeCord 讯息通道（bungee-plugin-message-channel，默认开启）。
分流名称不支持变量。

TELEPORT 传送

left: 'teleport: world:100.5:64:200.5'          # 指定世界
right: 'teleport: 100.5:64:200.5:90:0'          # 玩家目前的世界，并设定面向（yaw:pitch）

格式	说明
`世界:x:y:z`	传送到指定世界
`世界:x:y:z:yaw:pitch`	同时设定面向
`x:y:z`	玩家目前所在的世界
`x:y:z:yaw:pitch`	玩家目前所在的世界，同时设定面向

小数点也可以写成逗号（100,5）。
世界不存在或格式错误时，后面的动作都不会执行。
不支持变量。在下一个 tick 执行。

SOUND 播放音效

left: 'sound: ENTITY_EXPERIENCE_ORB_PICKUP:1:1.5'

部分	说明
音效名称	Bukkit 的 `Sound` 名称（大写），例如 `UI_BUTTON_CLICK`、`ENTITY_PLAYER_LEVELUP`、`BLOCK_NOTE_BLOCK_PLING`
音量	一般写 `1`；大于 1 只是让更远的地方也听得到
音高	`0.5`（低）～`2`（高），`1` 是原本的音高

只有点击的玩家听得到，在他的位置播放。
音量和音高要一起写或一起省略；省略时都是 1。
音效名称在不同版本会改名（例如 1.8 是 CLICK、1.9 以上是 UI_BUTTON_CLICK）。名称写错不会有任何提示，只是没有声音。
不支持资源包的自定义音效名称（minecraft:xxx 这种）。

PERMISSION 权限检查

left:
  - 'permission: group.vip'
  - 'console: give {player} diamond 1'
  - 'message: <green>VIP 礼物已发放</green>'

玩家有这个权限 → 继续执行下面的动作。
玩家没有这个权限 → 停止，后面的动作都不执行，也不会显示任何提示。
可以放在清单中间：前面的动作照样执行，只挡住后面的。
没有「否则」的写法。想在没权限时给提示，只能把提示写在 permission 前面（有权限的人也会看到），或交给其他插件处理。

NEXT_PAGE 下一页

left: next

让点击的玩家看到这个看板的下一页。已经是最后一页时什么都不做。
写成 'next: shop' 会让另一个看板（shop）对这名玩家翻到下一页。

PREV_PAGE 上一页

right: previous

上一页。已经是第 1 页时什么都不做。也可以写 prev。
写成 'previous: shop' 会让看板 shop 对这名玩家翻到上一页。

PAGE 跳到某一页

left: 'page: 1'              # 这个看板的第 1 页
right: 'page: shop:2'        # 看板 shop 的第 2 页（对这名玩家）

页码从 1 开始。页码超出范围时什么都不做。
看板名称只能是英文字母、数字、_、-。
原始写法是 PAGE:看板:页码；只写 PAGE:2 也会当成这个看板。
常用来做循环翻页：最后一页的左键写 page: 1，见多页。

执行顺序与停止

同一个按键的动作由上到下依序执行。
遇到 permission 没权限、或 teleport 位置无效时，立刻停止，后面的不执行。其他动作不会中断清单。
message、sound、翻页会马上发生；player、console、teleport 排到下一个 tick 在主线程执行。所以清单里写在后面的 message，可能比写在前面的 console 指令结果还早出现。

动作里的变量

动作	`{player}`	PlaceholderAPI
`message`	可以	可以
`player` / `command`	可以	可以
`console`	可以	可以
其他动作	不行	不行

{player} 是点击的玩家名称。{page}、{pages} 在动作里不会被替换。

用指令设定点击

/clh click

把某个按键的动作换成一个新的动作（原本的会被清掉）。

项目	内容
用法	`/clh click <看板> <页> <left\|right\|shift-left\|shift-right> <动作>`
权限	`dh.command.pages.addaction`
控制台	可以

动作用简化写法或原始写法都可以。

/clh click welcome 1 left next
/clh click welcome 2 left page: 1
/clh click welcome 1 shift-right player: spawn

/clh clickadd

在某个按键追加一个动作（排在最后）。用法、权限与 /clh click 相同。

/clh clickadd welcome 1 shift-left permission: group.vip
/clh clickadd welcome 1 shift-left console: give {player} diamond 1
/clh clickadd welcome 1 shift-left message: <green>已领取</green>

/clh clickclear

清掉某个按键的所有动作。

项目	内容
用法	`/clh clickclear <看板> <页> <按键>`
权限	`dh.command.pages.clearactions`

DecentHolograms 原本的指令

指令	权限	说明
`/clh page addaction <看板> <页> <按键> <原始写法>`	`dh.command.pages.addaction`	追加动作。只接受原始写法（`COMMAND:/spawn`），按键写 `LEFT`、`SHIFT_LEFT` 这种
`/clh page removeaction <看板> <页> <按键> <序号>`	`dh.command.pages.removeaction`	删掉第几个动作（从 1 开始）。别名 `remaction`
`/clh page clearactions <看板> <页> <按键>`	`dh.command.pages.clearactions`	清掉某个按键的所有动作
`/clh page actions <看板> <页> <按键> [列表页]`	`dh.command.pages.actions`	列出某个按键的动作（只能玩家执行）

/clh page addaction 与 /clh click、/clh clickadd 用的是同一个权限 dh.command.pages.addaction，已经包含在 dh.command.pages 里。各指令的详细说明见页指令。

暂时停用点击

给看板加上 DISABLE_ACTIONS 旗标：

/clh hologram addflag welcome DISABLE_ACTIONS

动作会保留在文件里，只是不执行，也不会放接收点击的盔甲架。要恢复就 removeflag。这个旗标要加在看板上，加在单一行上没有效果。

开发者：HologramClickEvent

其他插件可以监听 eu.decentsoftware.holograms.event.HologramClickEvent：

@EventHandler
public void onClick(HologramClickEvent event) {
    Player player = event.getPlayer();
    String hologram = event.getHologram().getName();
    ClickType click = event.getClick();          // LEFT / RIGHT / SHIFT_LEFT / SHIFT_RIGHT
    int page = event.getPage().getIndex() + 1;   // 页码（从 1 开始）
    if (hologram.equals("vip-only") && !player.hasPermission("group.vip")) {
        event.setCancelled(true);                // 取消后，这次点击的动作都不会执行
    }
}

这个事件是非同步的（不在主线程），要使用 Bukkit API 请用 Bukkit.getScheduler().runTask(...) 回到主线程。
事件在执行动作之前触发。
只要有任何插件监听这个事件，所有看板的每一页都会放接收点击的盔甲架（即使那一页没有动作）。
更多说明见开发者 API。

四种按键​

点击是怎么判断的​

动作一览​

每个动作的说明​

NONE 什么都不做​

MESSAGE 发消息​

COMMAND 玩家执行指令​

CONSOLE 控制台执行指令​

CONNECT 切换分流​

TELEPORT 传送​

SOUND 播放音效​

PERMISSION 权限检查​

NEXT_PAGE 下一页​

PREV_PAGE 上一页​

PAGE 跳到某一页​

执行顺序与停止​

动作里的变量​

用指令设定点击​

/clh click​

/clh clickadd​

/clh clickclear​

DecentHolograms 原本的指令​

暂时停用点击​

开发者：HologramClickEvent​