离渊系列插件Wiki

开发接口 ​

LyDragonBlock 在插件主模块中定义了 LyDragonBlockAPI 接口，用于操作插件记录的龙核方块。当前接口只包含设置方块和移除方块两个方法，其中只有移除方法提供了实际逻辑。

接口状态 ​

项目当前状态
接口类Ly.dragon.block.client.plugin.api.LyDragonBlockAPI
实现类Ly.dragon.block.server.api.LyDragonBlockAPIServer
API 获取方法Start#getApi()
API 注入方法Start#setApi(LyDragonBlockAPI api)
setBlock已定义，但当前实现为空
removeBlock已实现

警告

当前项目代码中存在 API 字段、Getter、Setter 和实现类，但没有发现将 LyDragonBlockAPIServer 注入插件实例的初始化代码。因此，Start#getApi() 在当前代码构建中可能返回 null，调用前必须检查。

接口定义 ​

java
package Ly.dragon.block.client.plugin.api;

import org.bukkit.Location;
import org.bukkit.entity.Player;

public interface LyDragonBlockAPI {
    void setBlock(Location loc, Player placer, String dragonId, String matchId);
    void removeBlock(Location loc);
}

方法说明 ​

方法参数返回值当前行为
setBlock(Location loc, Player placer, String dragonId, String matchId)方块位置、放置者、龙核方块 ID、龙核匹配值无当前实现为空，不会放置方块，也不会创建或保存方块数据
removeBlock(Location loc)需要移除的方块位置无检查指定位置是否为插件已记录的头颅方块，符合条件时删除记录并将方块设为空气

获取 API ​

插件主类为 Ly.dragon.block.client.license.Start，其中提供了 getApi() 方法。接入插件应先声明对 LyDragonBlock 的依赖，并在调用前检查插件实例和 API 实例。

yaml
name: YourPlugin
main: your.package.YourPlugin
version: '1.0.0'
depend:
  - LyDragonBlock
java
import Ly.dragon.block.client.license.Start;
import Ly.dragon.block.client.plugin.api.LyDragonBlockAPI;
import org.bukkit.Bukkit;
import org.bukkit.plugin.Plugin;

Plugin plugin = Bukkit.getPluginManager().getPlugin("LyDragonBlock");
if (!(plugin instanceof Start) || !plugin.isEnabled()) {
    return;
}

LyDragonBlockAPI api = ((Start) plugin).getApi();
if (api == null) {
    return;
}

如果 LyDragonBlock 只是可选依赖，可以将 depend 改为 softdepend，但必须自行处理插件未安装、未启用或 API 未初始化的情况。

移除方块 ​

java
api.removeBlock(location);

removeBlock 会按以下顺序处理指定位置：

  1. 通过 Location 获取当前位置的 Bukkit 方块。
  2. 使用世界名称和方块坐标生成存储 ID。
  3. 检查方块不是空气。
  4. 检查方块类型为 Material.SKULL。
  5. 检查该位置存在于 LyDragonBlock 的方块缓存中。
  6. 从内存缓存中移除方块记录。
  7. 尝试删除 plugins/LyDragonBlock/data/ 下对应的数据文件。
  8. 将当前位置的方块类型设为 Material.AIR。

存储 ID 的格式为：

text
世界名称_X坐标_Y坐标_Z坐标

例如：

text
world_100_64_-20

不会执行移除的情况 ​

出现以下任一情况时，removeBlock 不会修改方块和保存数据：

  • 指定位置为空气。
  • 指定位置不是 Material.SKULL 类型的头颅方块。
  • 指定位置没有对应的 LyDragonBlock 缓存记录。
  • 方块数据尚未完成加载，缓存中暂时不存在该位置。

该方法没有返回值，无法直接判断是否成功移除。调用方如果需要确认结果，应在调用前后自行检查方块状态。

设置方块 ​

接口中定义了以下方法：

java
api.setBlock(location, player, dragonId, matchId);

参数含义如下：

参数类型说明
locLocation目标方块位置
placerPlayer方块放置者
dragonIdString龙核方块 ID，对应方块配置文件的顶级配置键
matchIdString龙核方块配置中的匹配值

危险

当前 LyDragonBlockAPIServer#setBlock 方法体为空。调用该方法不会生成头颅方块、写入 dragon_id NBT、创建缓存或保存数据，不能用于程序化放置龙核方块。

需要发放可正常放置的方块物品时，应通过 /ldb open 打开方块总览并获取插件生成的物品。插件生成的物品会写入用于识别方块配置的 dragon_id NBT。

线程要求 ​

removeBlock 会读取和修改 Bukkit 世界方块，同时操作插件缓存和数据文件。应在 Bukkit 主线程调用，不要直接从异步任务中执行。

如果当前代码处于异步线程，可以切换到主线程：

java
Bukkit.getScheduler().runTask(yourPlugin, () -> {
    LyDragonBlockAPI api = ((Start) Bukkit.getPluginManager().getPlugin("LyDragonBlock")).getApi();
    if (api != null) {
        api.removeBlock(location);
    }
});

调用时还应确保：

  • Location 不为 null。
  • Location#getWorld() 不为 null。
  • 对应世界已经加载。
  • LyDragonBlock 已经启用并完成方块数据加载。

数据处理说明 ​

每个已放置方块会在内存中保存一份 BlockCache，并在以下目录保存独立的数据文件：

text
plugins/LyDragonBlock/data/

记录的数据包括：

数据说明
location方块所在世界和坐标
placer-uuid放置者 UUID
placer-name放置者名称
dragon-match方块使用的龙核匹配值
dragon-id对应的方块配置 ID
origin-item放置时使用的原始物品数据

调用 removeBlock 时，只有方块类型和缓存记录均符合要求才会清理这些数据。直接通过 Bukkit 将方块设为空气不会自动调用 LyDragonBlock API，可能留下缓存和数据文件。

接口限制 ​

当前公开接口未提供以下能力：

  • 查询指定位置是否为 LyDragonBlock 方块。
  • 获取方块 ID、放置者或原始物品。
  • 获取方块配置或事件列表。
  • 判断移除操作是否成功。
  • 通过 API 创建并保存新的龙核方块。
  • 注册方块放置、交互或移除回调。

不要直接修改插件内部的 BlockCache.caches 或 DragonConfigCache.caches。这些字段虽然在当前代码中公开，但属于内部实现，绕过现有流程可能导致内存缓存、世界方块和数据文件不同步。