Skip to content
This repository was archived by the owner on Jan 23, 2025. It is now read-only.

PluginEntry Usage Guide

Jump to bottom
Lars edited this page Oct 18, 2024 · 4 revisions

Overview

PluginEntry is an abstract base class designed to simplify the creation of Bukkit/Spigot plugins by handling common functionalities like event management, metrics, update checking, and language file handling. By extending PluginEntry, developers can focus on building the core features of their plugins, while the framework manages standard tasks.

Table of Contents

Getting Started

To get started with PluginEntry, your plugin class should extend PluginEntry and provide the necessary parameters like id and packageName. This enables common features like logging, event handling, and update checking to work automatically.

class MyPlugin : PluginEntry(
    id = "myplugin",
    /**
     * This package name is used for event bus initialization and translation key detection.
     *
     * You should set the package name of the main class of your plugin.
     */
    packageName = "com.example.myplugin",
    isDebug = false,
    enableMetrics = true,
    serviceId = 12345,
    enableUpdateChecker = true,
    modrinthID = "abcd1234",
    availableLang = listOf("en", "jp")
) {
    // Custom plugin logic
}

Constructor Parameters

  • id: The unique identifier for your plugin.
  • packageName: The base package for event handling and other resources.
  • isDebug: Enables debug mode (optional, default is false).
  • enableMetrics: Whether to enable metrics tracking (optional, default is false).
  • serviceId: Service ID for metrics tracking (required if enableMetrics is true).
  • enableUpdateChecker: Enables automatic update checking via Modrinth (optional, default is true).
  • modrinthID: The Modrinth project ID for your plugin.
  • availableLang: List of available language files (optional).

Plugin Lifecycle

Instead of directly overriding onLoad, onEnable, and onDisable, PluginEntry allows you to work with events that represent different stages in the plugin lifecycle. This approach provides a cleaner separation of concerns, where you can react to lifecycle events in a modular way.

Event-Driven Lifecycle

  • PluginLoadEvent.Pre: Fired before the plugin is loaded.
  • PluginLoadEvent.Post: Fired after the plugin has been loaded.
  • PluginEnableEvent.Pre: Fired before the plugin is enabled.
  • PluginEnableEvent.Post: Fired after the plugin has been enabled.
  • PluginDisableEvent.Pre: Fired before the plugin is disabled.
  • PluginDisableEvent.Post: Fired after the plugin has been disabled.

By using these events, you can avoid overriding lifecycle methods like onEnable() or onDisable() directly, and instead handle specific events that are triggered during those stages.

Example: Plugin Load Event

class MyPlugin : PluginEntry(
    id = "myplugin",
    packageName = "com.example.myplugin"
), IEventHandler {

    // Handle plugin load event (before loading)
    val onPreLoad = handler<PluginLoadEvent.Pre> {
        logger.info("MyPlugin is about to load!")
    }

    // Handle plugin load event (after loading)
    val onPostLoad = handler<PluginLoadEvent.Post> {
        logger.info("MyPlugin has finished loading.")
    }
}

Example: Plugin Enable Event

class MyPlugin : PluginEntry(
    id = "myplugin",
    packageName = "com.example.myplugin"
), IEventHandler {

    // Handle plugin enable event (before enabling)
    val onPreEnable = handler<PluginEnableEvent.Pre> {
        logger.info("MyPlugin is about to be enabled!")
    }

    // Handle plugin enable event (after enabling)
    val onPostEnable = handler<PluginEnableEvent.Post> {
        logger.info("MyPlugin has been enabled.")
    }
}

Event Handling

PluginEntry leverages an event bus to simplify event management. To handle events, you can use the handler<T>() function. The syntax is clean and minimal:

val onEnable = handler<PluginEnableEvent.Pre> {
    // Code to run before the plugin is enabled
}

This event system is flexible, allowing you to handle plugin lifecycle events or any custom events you define. The IEventHandler interface allows classes to declare that they want to handle events.

For more information, it is recommended to read the Beacon Wiki.

Example

Here’s an example of handling a custom event within the plugin:

class MyPlugin : PluginEntry(
    id = "myplugin",
    packageName = "com.example.myplugin"
), IEventHandler {

    val onCustomEvent = handler<MyCustomEvent> {
        // Actions to perform when MyCustomEvent is triggered
        logger.info("Handling custom event!")
    }
}

Update Checking

PluginEntry provides built-in support for checking if a new version of the plugin is available on Modrinth. When enableUpdateChecker is set to true and modrinthID is provided, the framework will automatically check for updates and notify the user.

You can customize the update check process by overriding the following methods:

  • onAllVersionsRetrieved(versionCount: Int): Called when all available versions have been retrieved.
  • onNewVersionFound(latestVersion: String, newerVersionCount: Int): Called when a newer version is found.
  • onNoNewVersionFound(): Called when no new version is found.
  • onUpdateCheckFailed(responseCode: Int): Called when the update check fails.
  • onUpdateCheckError(e: Exception): Called when an error occurs during the update check.

Example

override fun onNewVersionFound(latestVersion: String, newerVersionCount: Int) {
    logger.info("A new version $latestVersion is available with $newerVersionCount newer versions.")
}

Metrics

PluginEntry integrates with bStats to provide tracking of plugin usage. By setting enableMetrics = true and providing a serviceId, your plugin will automatically report metrics.

Example

class MyPlugin : PluginEntry(
    id = "myplugin",
    packageName = "com.example.myplugin",
    enableMetrics = true,
    serviceId = 12345
) {
    // Plugin logic here
}

Language File Management

PluginEntry provides built-in support for loading and updating language files. You can specify available languages using the availableLang parameter, and the framework will automatically manage these files.

Language files are stored in the lang directory and are automatically updated if a newer version is available within the plugin’s resources.

Clone this wiki locally