跳到主要内容

开发者 API

云全息内置完整的 DecentHolograms 2.10.1 核心，Java API 的套件名称与方法都和 DecentHolograms 相同（eu.decentsoftware.holograms.api）， 并在 plugin.yml 声明了 provides: [DecentHolograms]。

所以：

  • 已经支持 DecentHolograms 的插件，装在云全息上不用改任何东西。
  • 新写的插件，照 DecentHolograms 的 API 写就好，同时支持两边。

加入依赖​

编译时依赖 DecentHolograms 的 API（compileOnly / provided，不要打包进你的 jar）。

Gradle

repositories {
    maven { url = 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.decentsoftware-eu:decentholograms:2.10.1'
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.decentsoftware-eu</groupId>
        <artifactId>decentholograms</artifactId>
        <version>2.10.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

plugin.yml

softdepend: [DecentHolograms]   # 必须要有全息插件才能运作的话，改成 depend: [DecentHolograms]

写 DecentHolograms 就好，不需要写 CloudHologram：云全息会以 DecentHolograms 的身份满足这个依赖，你的插件会在它之后载入。

使用前确认 API 已经启动：

import eu.decentsoftware.holograms.api.DecentHologramsAPI;

if (!DecentHologramsAPI.isRunning()) {
    getLogger().warning("没有安装 DecentHolograms / CloudHologram，看板功能停用");
    return;
}

DecentHologramsAPI.get() 在 API 还没启动时会抛出 IllegalStateException。

云全息新增的功能不在 API 包里

背景颜色 / 阴影（display）、简化 YAML 等是云全息自己的功能，DecentHolograms 的 API 包里没有对应的方法。 想让看板有背景，可以先用 API 建立看板，再请服主用 /clh style 设定，或让看板存档后在文件里加 display:。

重要观念​

观念说明
索引从 0 开始API 的页码、行号从 0 开始（指令是从 1 开始）。getHologramPage(hologram, 0) 是第 1 页。
不带页码的方法 = 第 1 页例如 DHAPI.setHologramLine(hologram, 2, "…") 改的是第 1 页的第 3 行。
名称规则只能用 [a-zA-Z0-9_-]+，否则 createHologram 抛出 IllegalArgumentException。
存不存档createHologram(name, location) 默认不存档（重启就没了）；要存进 holograms/ 请用带 saveToFile = true 的版本。
API 看板不在指令列表里用 DHAPI.createHologram 建立的看板不会出现在 /clh list，也不能用 /clh 指令修改，/clh reload 也不会删掉它。存档过的看板，下次开服会从文件载入成一般看板。
找看板DHAPI.getHologram(name) 找得到所有看板，包含文件载入的和 API 建立的。
推荐写法
  • 每次开服由你的插件重建的看板（排行榜、商店标签……）：用 saveToFile = false，在 onEnable 建立、onDisable 删除。
  • 建一次就要永久保留的看板：先 DHAPI.getHologram(name)，找不到才 createHologram(..., true, ...)，避免重启后同名冲突。

存档过的 API 看板在执行 /clh reload 时，控制台会出现一行一般讯息「跳过：已经有同名看板」（因为同名看板已经在内存里），看板本身不受影响。

DHAPI 常用方法​

全部是 eu.decentsoftware.holograms.api.DHAPI 的静态方法。

建立与删除​

方法说明
createHologram(String name, Location location)建立空看板，不存档。
createHologram(String name, Location location, List<String> lines)建立并加入多行，不存档。
createHologram(String name, Location location, boolean saveToFile)指定是否存档。
createHologram(String name, Location location, boolean saveToFile, List<String> lines)指定是否存档并加入多行。
getHologram(String name)取得看板，找不到时回传 null。
moveHologram(String name, Location location) / moveHologram(Hologram, Location)移动看板（会存档）。
updateHologram(String name)强制所有观看者立刻刷新内容。
removeHologram(String name)删除看板，有存档的话连文件一起删除。

行​

方法说明
addHologramLine(Hologram, String content)在第 1 页最后加一行。
addHologramLine(Hologram, int pageIndex, String content)在指定页最后加一行。
addHologramLine(HologramPage, String content)在这一页最后加一行。
addHologramLine(Hologram / HologramPage, ItemStack 或 Material)加一个物品行（等于 #ICON:）。
insertHologramLine(Hologram, int lineIndex, String content)在第 1 页插入一行。
insertHologramLine(Hologram, int pageIndex, int lineIndex, String content)在指定页插入一行。
setHologramLine(Hologram, int lineIndex, String content)修改第 1 页某一行。
setHologramLine(Hologram, int pageIndex, int lineIndex, String content)修改指定页某一行。
setHologramLine(HologramLine line, String content)直接修改某一行。
setHologramLines(Hologram, List<String> lines)把第 1 页整个换成这些行（多的删掉、少的补上）。
setHologramLines(Hologram, int pageIndex, List<String> lines)同上，指定页。
removeHologramLine(Hologram, int lineIndex)删除第 1 页某一行。
removeHologramLine(Hologram, int pageIndex, int lineIndex)删除指定页某一行。
getHologramLine(HologramPage, int index)取得某一行。

content 的写法和指令完全相同：文字可以用 & 颜色、MiniMessage（Paper 1.18.2+）、PlaceholderAPI 变量；#ICON:、#HEAD:、#SMALLHEAD:、#ENTITY: 是特殊行，见 行类型。

页​

方法说明
addHologramPage(Hologram)在最后加一个空白页。
addHologramPage(Hologram, List<String> lines)加一页并放入多行。
insertHologramPage(Hologram, int index) / insertHologramPage(Hologram, int index, List<String> lines)插入一页。
removeHologramPage(Hologram, int index)删除一页，回传被删除的页。
getHologramPage(Hologram, int index)取得一页，超出范围回传 null。

范例​

建立、修改、删除​

import eu.decentsoftware.holograms.api.DHAPI;
import eu.decentsoftware.holograms.api.holograms.Hologram;
import org.bukkit.Location;
import java.util.Arrays;

Location location = player.getLocation().add(0, 2.5, 0);

// 建立（不存档，重启后消失）
Hologram hologram = DHAPI.createHologram("shop_label", location, Arrays.asList(
        "<gradient:#78EFFF:#CB9CFF><bold>杂货商店</bold></gradient>",
        "&7右键打开",
        "#ICON: EMERALD"
));

// 修改第 1 页第 2 行（索引从 0 开始）
DHAPI.setHologramLine(hologram, 1, "&a右键打开 &7| &f%player_name%");

// 在最后加一行
DHAPI.addHologramLine(hologram, "&8营业中");

// 整个换掉第 1 页
DHAPI.setHologramLines(hologram, Arrays.asList("&c休息中", "&7明天再来"));

// 移动、删除
DHAPI.moveHologram(hologram, location.clone().add(0, 1, 0));
DHAPI.removeHologram("shop_label");

永久看板（存档）​

Hologram board = DHAPI.getHologram("event_board");
if (board == null) {
    board = DHAPI.createHologram("event_board", location, true, Arrays.asList(
            "&6本周活动",
            "&f击败首领可获得奖励"
    ));
}

存档后文件在 plugins/CloudHologram/holograms/event_board.yml，服主可以照常用指令或文件修改。

多页与点击动作​

import eu.decentsoftware.holograms.api.actions.Action;
import eu.decentsoftware.holograms.api.actions.ClickType;
import eu.decentsoftware.holograms.api.holograms.HologramPage;

Hologram hologram = DHAPI.createHologram("guide", location, Arrays.asList("&b新手指南 1/2", "&7左键下一页"));
HologramPage page1 = DHAPI.getHologramPage(hologram, 0);
HologramPage page2 = DHAPI.addHologramPage(hologram, Arrays.asList("&b新手指南 2/2", "&7右键上一页"));

page1.addAction(ClickType.LEFT, new Action("NEXT_PAGE"));
page2.addAction(ClickType.RIGHT, new Action("PREV_PAGE"));
page2.addAction(ClickType.SHIFT_LEFT, new Action("COMMAND:/spawn"));
page2.addAction(ClickType.SHIFT_RIGHT, new Action("MESSAGE:&a欢迎，{player}！"));

hologram.save();     // 有存档的看板才需要；不存档的看板调用也没关系
hologram.showAll();  // 重新显示给附近玩家，让点击生效

Action 用 DecentHolograms 原本的格式 类型:内容：

写法作用
NEXT_PAGE / PREV_PAGE下一页 / 上一页（自动套用当前看板）
PAGE:看板名称:2跳到某个看板的第 2 页（这里页码从 1 开始）
COMMAND:/spawn玩家执行指令
CONSOLE:give {player} diamond 1控制台执行指令
MESSAGE:文字发送消息
SOUND:UI_BUTTON_CLICK:1:1播放音效
TELEPORT:world:0:100:0传送
CONNECT:lobby切换到 BungeeCord 分流
PERMISSION:权限没有权限就停止执行后面的动作
NONE什么都不做

动作类型写错时 new Action(...) 会抛出 IllegalArgumentException。各动作的详细说明见 点击动作。

切换某个玩家看到的页​

hologram.show(player, 1);   // 让这个玩家看第 2 页（索引从 0 开始）
int current = hologram.getPlayerPage(player);

只给特定玩家看​

import eu.decentsoftware.holograms.api.DecentHologramsAPI;

hologram.setDefaultVisibleState(false);   // 默认所有人都看不到
hologram.setShowPlayer(player);           // 只有这个玩家看得到
// hologram.setHidePlayer(other);         // 或：对某个玩家隐藏
// hologram.removeShowPlayer(player);     // 取消

// 插件每秒会自动套用；想立刻生效：
DecentHologramsAPI.get().getHologramManager().updateVisibility(player, hologram);

这些设定只存在内存里，不会写进文件，/clh reload、重启或玩家退出后要重新设定。

短暂出现的文字​

// 在位置上显示 "&c-5"，40 tick（2 秒）后自动消失，不存档
DecentHologramsAPI.get().getHologramManager()
        .spawnTemporaryHologramLine(location, "&c-5", 40L);

这就是伤害 / 治疗数字使用的方法；会显示给所有在线玩家。

其他常用方法​

方法（Hologram）说明
getName()、getLocation()、size()名称、位置、页数
getPage(int index)取得页（从 0 开始）
enable() / disable()启用 / 停用
setPermission(String)看板权限，null = 所有人
setDisplayRange(int)、setUpdateRange(int)、setUpdateInterval(int)范围与更新间隔
setFacing(float)、setDownOrigin(boolean)朝向、向下排列；改完调用 realignLines()
addFlags(EnumFlag...)、removeFlags(EnumFlag...)旗标
updateAll()、realignLines()刷新内容、重新排列行的位置
save()存档（不存档的看板什么都不做）
delete()删除看板（含文件）

用 Hologram 物件的 setter 改设定时不会自动存档，有需要请自己调用 save()。

事件​

全部在 eu.decentsoftware.holograms.event 套件，用一般的 Bukkit @EventHandler 监听。

事件什么时候触发可取消线程
HologramClickEvent玩家点击看板，在执行点击动作之前是：取消后不执行这次点击的动作一定是异步
HologramRegisterEvent看板加入插件的看板列表：开服 / 重载时从文件载入、/clh create、复制、转换否依呼叫的线程（开服与重载载入时是异步）
HologramUnregisterEvent看板离开看板列表：删除、重命名、/clh reload 前的清除否同上
HologramEnableEvent看板被启用（enable()、/clh enable、世界重新载入）否同上
HologramDisableEvent看板被停用（disable()、/clh disable、世界卸载，以及删除 / 重载时的清除）否同上
DecentHologramsReloadEvent/clh reload 完成后否异步

各事件可以取得的资料：

事件方法
HologramClickEventgetPlayer()、getHologram()、getPage()、getClick()（ClickType）、getEntityId()
其他看板事件getHologram()；停用原因用 getHologram().getDisableCause()（API、COMMAND、WORLD_UNLOAD）

注意：

  • DHAPI.createHologram 建立的看板不会触发 HologramRegisterEvent（它没有加入指令用的看板列表）。
  • 只要有任何插件监听 HologramClickEvent，所有看板都会变成可点击（每一页都会生成点击用的隐形实体），即使那一页没有设动作。
  • 授权版在开服时先启动、通过授权验证后才载入看板文件。想在看板载入后处理的话，监听 HologramRegisterEvent，不要在 onEnable 里马上 getHologram。

监听范例​

import eu.decentsoftware.holograms.api.actions.ClickType;
import eu.decentsoftware.holograms.event.HologramClickEvent;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class ShopListener implements Listener {

    private final MyPlugin plugin;

    public ShopListener(MyPlugin plugin) {
        this.plugin = plugin;
    }

    @EventHandler
    public void onClick(HologramClickEvent event) {
        if (!event.getHologram().getName().equals("shop_label")) {
            return;
        }
        if (event.getClick() != ClickType.RIGHT) {
            return;
        }
        event.setCancelled(true);              // 不执行看板本身设定的动作
        Player player = event.getPlayer();
        // 这个事件在异步线程，开菜单、给物品、传送等要切回主线程
        Bukkit.getScheduler().runTask(plugin, () -> plugin.openShop(player));
    }
}

注意事项​

  • 线程：HologramClickEvent 一定在异步线程触发，其他事件视情况。事件里要动到 Bukkit 的东西（菜单、物品、传送、方块、实体）一律用 runTask 切回主线程。DHAPI 的方法请在主线程调用。
  • 看板名称：只能用英文字母、数字、_、-，而且不能和现有看板重复（包含其他插件建立的）。建议加上自己插件的前缀，例如 myshop_label_1。
  • 点击冷却：玩家的点击受 config.yml 的 click-cooldown 限制，冷却中的点击不会触发事件。
  • 范围：玩家要在看板位置点水平 5 格内点击才会触发 HologramClickEvent。
  • 不要打包 API：把 DecentHolograms 的 API 打包进自己的 jar 会和云全息冲突，一定要用 compileOnly / provided。
最后于 更新