KeyCard API - 门禁卡系统接口

简介

KeyCard 是一个卡牌扫描 API 插件。你可以创建未配对的钥匙卡和扫描器，将它们配对后，即可在扫描器处刷卡，并通过其他附属插件实现各种交互功能。

💡前置需求

• Java 8
• RecipesRedone (用于物品合成)

✨附属插件

如果你想将自己的附属插件加入此列表，请联系作者。

• KeyCardRedstone - 刷卡时发出红石脉冲信号。
• KeyCardChests - 刷卡可以打开上锁的箱子。

🎮物品与合成

所有物品默认都通过 /kc craft 命令打开 RecipesRedone 合成界面进行制作。

• 未配对的钥匙卡
• 未配对的扫描器

🔧用户使用教程

第一步：放置扫描器

将你的扫描器放置在地上。请注意，不同的附属插件可能会使用自己专属的扫描器，如果你想使用某个附属插件的功能，请确保制作的是对应的扫描器，而不是默认的。

第二步：配对钥匙卡与扫描器

手持未配对的钥匙卡，右键点击已放置的扫描器，即可将它们配对。

第三步：为钥匙卡命名

配对后，你将获得一张未命名的钥匙卡。使用命令 /kc name <名称> 为其命名。

• 注意：名称中不能包含空格。

第四步：开始使用

现在钥匙卡和扫描器已经成功链接！右键点击扫描器即可刷卡，并使用各种附属插件提供的功能。

复制钥匙卡

如果你想为朋友或其他玩家复制钥匙卡，请按以下步骤操作：

• 手持你想要复制的已配对钥匙卡。
• 确保你的背包中有未配对的钥匙卡。
• 执行命令 /kc duplicate。此命令将消耗一张未配对的钥匙卡，生成一张与你手中完全相同的副本。

⭐开发者 API 教程

如果你想开发一个使用此 API 的插件，请务必先编辑你的 plugin.yml 文件。

添加依赖

在你的 plugin.yml 中，必须添加依赖项：

depend: [KeyCard]

同时，请将 KeyCard.jar 添加到你的项目构建路径中。

创建自定义扫描器

首先，你需要创建你希望作为扫描器的 ItemStack 对象。用户教程中使用的是石质按钮，你可以将其替换为任何物品。

示例代码：

APIUtils.registerScannerItem(scannerItemStack);
// 将一个 ItemStack 注册为可配对的扫描器

监听 ScannerPairEvent 事件

你可以像监听其他 Bukkit 事件一样监听此事件。当一个未配对的钥匙卡和任意插件的扫描器成功配对时，此事件会被触发。建议在处理前，先检查事件中的扫描器物品是否与你自定义的扫描器匹配。

示例代码：

@EventHandler
public void onScannerPair(ScannerPairEvent e) {
    if (e.getScannerItem().isSimilar(scannerItemStack)) {
        // 执行操作，例如将扫描器位置保存到文件
    }
}

监听 KeyCardScanEvent 事件

此事件在玩家使用已配对的钥匙卡扫描扫描器时触发。推荐的做法是：在 ScannerPairEvent 事件中将扫描器位置保存到文件，然后在 KeyCardScanEvent 事件中检查扫描位置是否与文件中保存的某个自定义扫描器位置一致。

示例代码：

@EventHandler
public void onScan(KeyCardScanEvent e) {
    /*
     * 此处逻辑：扫描保存了扫描器位置的文件，检查正在被扫描的是否是我的自定义扫描器。
     * 如果是，则收集信息并执行自定义操作。
     */
    List<String> locStrings = this.scannerFile.contains("data") ? this.scannerFile.getStringList("data") : new ArrayList();
    if (locStrings.contains(StringUtils.toLocString(e.getFrame().getLocation()))) {
        // StringUtils 是作者使用的私有库
        Location loc = e.getFrame().getLocation();
        ItemFrame frame = e.getFrame();
        BlockFace face = frame.getAttachedFace();
        Block b = loc.add(face.getModX(), face.getModY(), face.getModZ()).getBlock();
        // 至此，你应该获得了足够的信息来执行任何需要的操作
    }
}