开放 API

文档版本: v1.5.2页面更新: 2026-10-19

KaLogin 向其他插件开放登录、注册、改密、登出等认证事件，供接入方在不直接操作数据库的前提下感知认证状态。

注意：KaLogin 的认证回调不是 Bukkit Event 子类，必须通过 KaLoginListener 接口实现，不能使用 @EventHandler。唯一的例外是跨服落点用的 Bukkit 事件 PlayerAuthenticationReadyEvent，见下文。

引入方式#

把 KaLogin 作为软依赖引入，不要打包进你的插件：

dependencies {
    compileOnly(fileTree("libs") { include("KaLogin-1.5.2.jar") })
}

在你的插件的 plugin.yml 中添加软依赖：

softdepend:
  - KaLogin

获取 API 实例#

KaLoginAPI 是惰性单例，getInstance() 永远不返回 null；是否可用请用 isEnabled() 判断：

val api = KaLoginAPI.getInstance()
if (api != null && api.isEnabled()) {
    // KaLogin 已启用
}

注册监听器#

在 onEnable() 中注册，在 onDisable() 中注销：

class MyPlugin(private val plugin: Plugin) : Listener {
    private var listener: MyKaLoginListener? = null

    override fun onEnable() {
        val api = KaLoginAPI.getInstance() ?: return
        if (!api.isEnabled()) return
        listener = MyKaLoginListener(plugin)
        api.registerListener(this, listener!!)
    }

    override fun onDisable() {
        val api = KaLoginAPI.getInstance() ?: return
        listener?.let { api.unregisterListener(this, it) }
    }
}

class MyKaLoginListener(private val plugin: Plugin) : KaLoginListener {
    override fun onPlayerLoginSuccess(event: PlayerLoginSuccessEvent) {
        plugin.logger.info("玩家 ${event.player.name} 登录成功")
    }

    override fun onPlayerProxyRestore(event: PlayerProxyRestoreEvent) {
        plugin.logger.info("玩家 ${event.player.name} 通过群组会话恢复登录")
    }
}

监听器回调#

KaLoginListener 的所有方法都有默认空实现，只覆写你需要的即可。

回调	触发时机
`onPlayerLoginSuccess`	密码校验通过、登录成功
`onPlayerLoginFailed`	密码错误导致本次登录失败
`onPlayerAutoLogin`	同 IP 自动登录成功
`onPlayerProxyRestore`	通过 KaProxy 群组会话在目标服免密恢复登录态
`onPlayerRegisterSuccess`	注册成功
`onPlayerRegisterFailed`	注册失败
`onPlayerChangePasswordSuccess`	修改密码成功
`onPlayerChangePasswordFailed`	修改密码失败
`onPlayerLogout`	玩家登出
`onPlayerUnregister`	玩家注销自己的账户
`onPlayerAdminUnregister`	管理员注销玩家账户

事件对象#

事件	字段
`PlayerLoginSuccessEvent`	`player`、`ip`、`isAutoLogin`
`PlayerLoginFailedEvent`	`player`、`remainingAttempts`
`PlayerAutoLoginEvent`	`player`、`ip`
`PlayerProxyRestoreEvent`	`player`、`ip`
`PlayerRegisterSuccessEvent`	`player`、`ip`
`PlayerRegisterFailedEvent`	`player`、`reason`
`PlayerChangePasswordSuccessEvent`	`player`
`PlayerChangePasswordFailedEvent`	`player`、`reason`
`PlayerLogoutEvent`	`player`
`PlayerUnregisterEvent`	`player`
`PlayerAdminUnregisterEvent`	`playerName`

认证就绪事件（跨服落点用）#

PlayerAuthenticationReadyEvent 是标准的 Bukkit 事件，在认证收尾（含可选的上次位置本地应用）完成后触发，适合跨服落点、传送类插件等待认证结束：

class MyArrivalListener : Listener {

    @EventHandler
    fun onAuthenticationReady(event: PlayerAuthenticationReadyEvent) {
        val player = event.player
        // 此时认证已完成，可以安全执行传送等操作
    }
}

它在内置模式、AuthMe 模式、手动登录、自动登录与跨服恢复五种情况下都会触发，未启用 last-seen 时同样触发。

该事件只表示本服认证收尾完成，不保证代理端异步的 last-seen 后续切服已结束；跨服落点仍需各自的确认机制。

常用 API 方法#

方法	说明
`isPlayerLoggedIn(player: Player)`	判断玩家是否已通过认证；AuthMe 模式下按 AuthMe 的登录态判断
`isPlayerLoggedIn(playerName: String)`	同上，按玩家名判断
`logout(player: Player, kickMessage: Component? = null)`	执行登出：触发登出事件、关闭同 IP 自动登录、在群组模式下由代理断开整组连接，未被代理接管时在本服踢出玩家
`registerListener(plugin, listener)` / `unregisterListener(plugin, listener)`	注册与注销监听器
`getListenerCount()`	当前已注册的监听器数量
`isEnabled()`	KaLogin 是否处于启用状态

注意事项#

认证回调在玩家线程触发，回调里不要执行耗时数据库或网络操作。
events.login 动作队列与 KaLoginListener 回调是两套机制：前者由 config.yml 的 events 配置驱动，后者供代码调用；是否执行同 IP 自动登录的动作由 login.execute-events-on-auto-login 决定，是否重放跨服恢复的动作由 proxy.replay-login-actions 决定。
跨服恢复与同 IP 自动登录是两个不同事件：前者是 onPlayerProxyRestore，后者是 onPlayerAutoLogin。