Open API

KaLogin exposes its authentication events (login, registration, password change, logout) to other plugins, so an integration can react to authentication state without touching the database.

Note: KaLogin's authentication callbacks are not Bukkit Event subclasses. Implement them through the KaLoginListener interface — @EventHandler will not work. The single exception is the Bukkit event PlayerAuthenticationReadyEvent used for cross-server arrivals, described below.

Adding the dependency#

Depend on KaLogin as a soft dependency instead of shading it into your plugin:

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

Add the soft dependency to your plugin's plugin.yml:

softdepend:
  - KaLogin

Getting the API instance#

KaLoginAPI is a lazy singleton: getInstance() never returns null, use isEnabled() to check availability.

val api = KaLoginAPI.getInstance()
if (api != null && api.isEnabled()) {
    // KaLogin is enabled
}

Registering a listener#

Register in onEnable() and unregister in 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} logged in")
    }

    override fun onPlayerProxyRestore(event: PlayerProxyRestoreEvent) {
        plugin.logger.info("${event.player.name} was restored from a group session")
    }
}

Listener callbacks#

Every method of KaLoginListener has an empty default implementation, so override only what you need.

Callback	Fired when
onPlayerLoginSuccess	The password check passed and the player logged in.
onPlayerLoginFailed	A wrong password failed the current login attempt.
onPlayerAutoLogin	A same-IP automatic login succeeded.
onPlayerProxyRestore	The login state was restored on this backend through a KaProxy group session.
onPlayerRegisterSuccess	Registration succeeded.
onPlayerRegisterFailed	Registration failed.
onPlayerChangePasswordSuccess	Changing the password succeeded.
onPlayerChangePasswordFailed	Changing the password failed.
onPlayerLogout	The player logged out.
onPlayerUnregister	The player deleted their own account.
onPlayerAdminUnregister	An administrator deleted a player's account.

Event objects#

Event	Fields
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

Authentication ready event (for cross-server arrivals)#

PlayerAuthenticationReadyEvent is a regular Bukkit event. It is fired once authentication is finalized (including any local last-seen application) and is meant for plugins that wait for authentication before teleporting:

class MyArrivalListener : Listener {

    @EventHandler
    fun onAuthenticationReady(event: PlayerAuthenticationReadyEvent) {
        val player = event.player
        // Authentication is complete, it is safe to teleport now
    }
}

It fires for the built-in mode, the AuthMe mode, manual login, automatic login and cross-server restore, and also when last-seen is disabled.

The event only means that authentication on this backend has finished. It does not guarantee that a later asynchronous proxy-side last-seen transfer has completed; cross-server arrivals still need their own acknowledgement.

Frequently used API methods#

Method	Description
isPlayerLoggedIn(player: Player)	Whether the player has passed authentication; in AuthMe mode the AuthMe session decides.
isPlayerLoggedIn(playerName: String)	Same, by player name.
logout(player: Player, kickMessage: Component? = null)	Performs a logout: fires the logout event, disables same-IP auto login, and in group mode lets the proxy disconnect the whole group; when the proxy does not handle it, the player is kicked from this backend.
registerListener(plugin, listener) / unregisterListener(plugin, listener)	Register and unregister listeners.
getListenerCount()	Number of currently registered listeners.
isEnabled()	Whether KaLogin is enabled.

Notes#

• The authentication callbacks run on the player thread; do not perform slow database or network work inside them.
• The events.login action queue and the KaLoginListener callbacks are two separate mechanisms: the former is driven by the events section of config.yml, the latter is called from code. Whether the queue runs on a same-IP automatic login is controlled by login.execute-events-on-auto-login, and whether it is replayed on a cross-server restore by proxy.replay-login-actions.
• A cross-server restore and a same-IP automatic login are different events: the former is onPlayerProxyRestore, the latter is onPlayerAutoLogin.