[RD] LockLogin - LockLogin

感谢以下贡献者

• Watherfoxx
• Bastaboii
• RxF
• ElGuerrero
• Katana6951
• El_PerroSandia

请注意：LockLogin 插件即将停止维护，请关注其后续版本 LockLogin2 以获取更多信息。

LockLogin 的 API 通常不直接对插件开放，但通过其独特的 API 卡片（或称 API 桥接卡片）系统，开发者可以在模块与插件之间建立安全的通信桥梁。本文档将详细介绍如何创建和使用这些卡片来实现双向数据交互。

💡核心概念

API 卡片（APICard）是 LockLogin 模块与外部插件之间进行安全通信的载体。模块负责创建并“发出”卡片，插件则负责“监听”并“消费”这些卡片，从而实现事件驱动的数据传递。

关键要点

• 通信必须通过一个 LockLogin 模块 作为桥梁。
• 插件不能直接访问 LockLogin 的核心 API。
• 卡片通过事件队列机制传递，确保了线程安全与数据一致性。

🎮创建 API 卡片（模块端）

要在模块中创建一个自定义的 API 卡片，你需要继承 APICard 类并实现其方法。

代码示例：TeleportCard

以下是一个名为 TeleportCard 的卡片示例，它用于传递玩家对象。

public class TeleportCard extends APICard<ModulePlayer> {
    private ModulePlayer player;

    /**
     * 初始化传送卡片
     *
     * @param module 拥有此卡片的模块
     * @param client 此卡片管理的客户端
     */
    public TeleportCard(final PluginModule module, final ModulePlayer client) {
        super(module, "teleport");
        player = client;
    }

    /**
     * 更新卡片对象
     *
     * @param update 更新值
     */
    @Override
    protected final void update(final ModulePlayer update) {
        if (CurrentPlatform.getServer().isValid(update)) {
            player = update;
        }
    }

    /**
     * 获取卡片值
     *
     * @return 卡片值
     */
    @Override
    public final ModulePlayer get() {
        return player;
    }
}

🔧发送 API 卡片（模块端）

创建卡片后，你需要在模块的事件监听器中将其放入队列，以便插件接收。

代码示例：在事件中排队卡片

public final class Listener implements EventListener {
    private final PluginModule module;

    public Listener(final PluginModule owner) {
        module = owner;
    }

    public void onAuth(UserAuthenticateEvent e) {
        ModulePlayer player = e.getPlayer();
        TeleportCard card = new TeleportCard(module, player);
        module.queueCard(card); // 将卡片加入队列
    }
}

✨接收 API 卡片（插件端）

在你的插件中，你需要设置监听器来捕获并处理已排队的卡片。正确消费卡片至关重要，以避免内存泄漏和错误。

方法一：使用事件监听器（推荐）

这是最清晰的方式，通过监听 CardConsumedEvent 来处理已被消费的卡片。

public class Main extends JavaPlugin {
    @Override
    public void onEnable() {
        APICard.addCardListener(new CardAdapter() {
            /**
             * 当一张卡片被完全消费后触发
             *
             * @param event 卡片消费事件包装器
             */
            @Override
            public void cardPostQueued(CardConsumedEvent event) {
                PluginModule module = event.getModule(); // 卡片所有者模块
                PluginModule container = event.getContainer(); // 卡片存储容器（通常与所有者相同）
                String identifier = event.getIdentifier(); // 卡片标识符

                APICard<ModulePlayer> card = container.getCard(module, identifier);
                UUID id = card.get().getUUID();
                Player player = getServer().getPlayer(id);
                player.teleport(/* 目标地点 */);
            }
        });
    }
}

方法二：主动轮询消费

你也可以在异步任务中主动检查并消费特定标识符的卡片。

// 定义要监听的卡片标识符
String[] identifiers = new String[]{"teleport", "another_example"};

// 在异步任务中循环消费卡片
while (true) {
    for (String str : identifiers) {
        if (module.consumeCard(str)) { // 消费卡片并将其移出队列
            APICard<ModulePlayer> card = module.getCard(str);
            // 处理卡片数据...
        }
    }
}

❓重要注意事项

• 必须消费卡片：使用 PluginModule#consumeCard(String) 方法将卡片从队列移至临时字段，然后通过 PluginModule#getCard(String) 获取。不这样做会导致卡片堆积，引发高内存使用和潜在错误。
• 标识符匹配：发送和接收时使用的卡片标识符（如 "teleport"）必须完全一致。
• 模块依赖：整个通信流程依赖于一个正常工作的 LockLogin 模块（如 LockLoginManager）作为中介。