SimplePlugin - Foundation

Overview

SimplePlugin is the core abstract class that your plugin should extend to leverage Foundation’s enhanced functionality. It extends Bukkit’s JavaPlugin and implements Listener for convenient event handling. Package: org.mineacademy.fo.plugin Inheritance: JavaPlugin → SimplePlugin

You must extend this class in your main plugin class and implement the abstract onPluginStart() method.

Lifecycle methods

Foundation provides several lifecycle hooks that are called at different stages of your plugin’s lifecycle.

onPluginLoad

protected void onPluginLoad()

Called before the plugin is started, equivalent to Bukkit’s onLoad(). Use this for early initialization tasks. Example:

@Override
protected void onPluginLoad() {
    // Register custom enchantments or world generators
}

onPluginStart

protected abstract void onPluginStart()

The main loading method called when the plugin is ready to start. This is where you initialize your plugin’s core functionality.

abstract

void

This method must be implemented in your plugin class.

Example:

@Override
protected void onPluginStart() {
    // Load configuration
    // Register commands
    // Initialize managers
    Common.log("Plugin started successfully!");
}

onReloadablesStart

protected void onReloadablesStart()

Register your commands, events, tasks, and files here. This is invoked when you start the plugin, call /reload, or the reload() method. Example:

@Override
protected void onReloadablesStart() {
    registerEvents(new PlayerListener());
    registerCommand(new MyCommand());
}

onPluginPreReload

protected void onPluginPreReload()

Invoked before settings are reloaded. Use this to prepare for configuration changes.

onPluginReload

protected void onPluginReload()

Invoked after settings are reloaded. Use this to apply new configuration values.

onPluginStop

protected void onPluginStop()

The main method called when the plugin is about to shut down. Clean up resources here. Example:

@Override
protected void onPluginStop() {
    // Save data
    // Close connections
    // Cancel tasks
}

Static accessors

These static methods provide quick access to plugin information.

getInstance

public static SimplePlugin getInstance()

Returns the instance of your plugin. It’s recommended to override this in your implementation for type safety. Returns: The plugin instance Example:

public static MyPlugin getInstance() {
    return (MyPlugin) SimplePlugin.getInstance();
}

hasInstance

public static final boolean hasInstance()

Checks if the plugin instance has been set. Returns: true if instance exists, false otherwise

getVersion

public static String getVersion()

Shortcut for getDescription().getVersion(). Returns: The plugin version string

getNamed

public static String getNamed()

Shortcut for getName(). Returns: The plugin name

getSource

public static File getSource()

Shortcut for getFile(). Returns: The plugin JAR file

getData

public static File getData()

Shortcut for getDataFolder(). Returns: The plugin’s data folder

isReloading

public static boolean isReloading()

Checks if the plugin is currently reloading. Returns: true if reloading, false otherwise

Registration methods

Convenient methods for registering various plugin components.

registerEvents

protected final void registerEvents(final Listener listener)

Registers an event listener. If called during onReloadablesStart(), the listener is automatically unregistered on reload.

listener

Listener

required

The Bukkit listener to register

Example:

registerEvents(new PlayerListener());

registerEvents (SimpleListener)

protected final void registerEvents(final SimpleListener<? extends Event> listener)

Registers a Foundation SimpleListener for a single event type.

listener

SimpleListener<? extends Event>

required

The SimpleListener to register

registerAllEvents

protected final <T extends Listener> void registerAllEvents(final Class<T> extendingClass)

Automatically registers all classes in your plugin that extend the given listener class. Classes must have a no-argument constructor.

extendingClass

Class<T>

required

The listener class to scan for

Set your Debug key in settings.yml to [“auto-register”] to see what gets registered.

Example:

registerAllEvents(MyBaseListener.class);

registerCommand

protected final void registerCommand(final Command command)

Registers a Bukkit command.

command

Command

required

The command to register

registerCommands

protected final void registerCommands(final SimpleCommandGroup group)

Registers a command group. Shortcut for calling group.register().

group

SimpleCommandGroup

required

The command group to register

registerAllCommands

protected final <T extends Command> void registerAllCommands(final Class<T> extendingClass)

Automatically registers all command classes in your plugin that extend the given class. Classes must have a no-argument constructor.

extendingClass

Class<T>

required

The command class to scan for

registerBungeeCord

protected final void registerBungeeCord(@NonNull BungeeListener bungee)

Registers a custom BungeeCord listener for plugin messaging.

bungee

BungeeListener

required

The BungeeListener to register

Reload functionality

reload

public final void reload()

Attempts to reload the plugin. This method:

Detects debug mode
Unregisters reloadables
Reloads dependencies
Calls onPluginPreReload()
Reloads configuration files
Calls onPluginReload()
Calls onReloadablesStart()

Example:

SimplePlugin.getInstance().reload();

Configuration methods

These methods allow you to customize plugin behavior.

getMinimumVersion

public MinecraftVersion.V getMinimumVersion()

Return the minimum Minecraft version required to run your plugin. Foundation will prevent loading on older versions. Returns: Minimum version, or null for no restriction Example:

@Override
public MinecraftVersion.V getMinimumVersion() {
    return MinecraftVersion.V.v1_13;
}

getMaximumVersion

public MinecraftVersion.V getMaximumVersion()

Return the maximum Minecraft version for your plugin. Foundation will prevent loading on newer versions. Returns: Maximum version, or null for no restriction

getStartupLogo

protected String[] getStartupLogo()

Return a fancy ASCII logo to display on plugin startup. Returns: Array of strings for the logo, or null for none Example:

@Override
protected String[] getStartupLogo() {
    return new String[] {
        "&6  __  __       ____  _             _       ",
        "&6 |  \\/  |_   _|  _ \\| |_   _  __ _(_)_ __  ",
        "&6 | |\/| | | | | |_) | | | | |/ _` | | '_ \\ ",
        "&6 | |  | | |_| |  __/| | |_| | (_| | | | | |",
        "&6 |_|  |_|\\__, |_|   |_|\\__,_|\\__, |_|_| |_|",
        "&6         |___/                 |___/        "
    };
}

getUpdateCheck

public SpigotUpdater getUpdateCheck()

Return a SpigotUpdater instance to enable automatic update checking from SpigotMC. Returns: SpigotUpdater instance, or null to disable Example:

@Override
public SpigotUpdater getUpdateCheck() {
    return new SpigotUpdater(12345); // Your Spigot resource ID
}

getMetricsPluginId

public int getMetricsPluginId()

Return your bStats.org plugin ID to enable metrics tracking. Returns: Plugin ID from bStats, or -1 to disable Example:

@Override
public int getMetricsPluginId() {
    return 9876; // Your bStats plugin ID
}

getFoundedYear

public int getFoundedYear()

Return the year your plugin was founded, displayed in command help. Returns: The year, or -1 for no display

getMainCommand

@Nullable
public SimpleCommandGroup getMainCommand()

Returns the main command group if set via @AutoRegister. Returns: The main command group, or null

getRegexTimeout

public int getRegexTimeout()

Return the timeout in milliseconds for processing regular expressions. This prevents server freeze on malformed regex. Returns: Timeout in milliseconds Example:

@Override
public int getRegexTimeout() {
    return 100; // 100ms timeout
}

regexStripColors

public boolean regexStripColors()

Should colors be stripped from messages before checking against regex? Returns: true to strip colors (default)

regexCaseInsensitive

public boolean regexCaseInsensitive()

Should Pattern.CASE_INSENSITIVE be applied when compiling regex? Returns: true for case-insensitive matching (default)

regexUnicode

public boolean regexUnicode()

Should Pattern.UNICODE_CASE be applied when compiling regex? Returns: true for Unicode support (default)

regexStripAccents

public boolean regexStripAccents()

Should diacritical marks be removed before matching regex? Returns: true to strip accents (default)

areMenusEnabled

public boolean areMenusEnabled()

Should Foundation listen for Menu class clicking? Returns: true to enable menus (default)

Returning false will break the entire Foundation menu system.

areToolsEnabled

public boolean areToolsEnabled()

Should Foundation handle Tool clicking events automatically? Returns: true to enable tools (default)

areRegionsEnabled

public boolean areRegionsEnabled()

Should the region system be enabled? Loads DiskRegion.loadRegions(). Returns: false by default

getConsoleFilter

public Set<String> getConsoleFilter()

Return a list of console messages to filter out (using startsWith or contains matching). Returns: Set of filter strings Example:

@Override
public Set<String> getConsoleFilter() {
    return new HashSet<>(Arrays.asList(
        "[ViaVersion]",
        "Can't keep up!"
    ));
}

filterInsecureChat

public boolean filterInsecureChat()

Remove the [Not Secure] message from console chat. Returns: true to filter (default)

Utility methods

getJavaVersion

public static int getJavaVersion()

Return the major Java version (e.g., 8 for Java 1.8, 17 for Java 17). Returns: Major Java version number Example:

int javaVersion = SimplePlugin.getJavaVersion();
if (javaVersion < 11) {
    Common.log("Warning: Java 11 or higher is recommended!");
}

Complete example

package com.example.myplugin;

import org.mineacademy.fo.plugin.SimplePlugin;
import org.mineacademy.fo.MinecraftVersion;
import org.mineacademy.fo.model.SpigotUpdater;

public final class MyPlugin extends SimplePlugin {

    @Override
    protected void onPluginStart() {
        Common.log("Starting MyPlugin...");
        
        // Initialize your plugin
    }

    @Override
    protected void onReloadablesStart() {
        // Register events
        registerEvents(new PlayerListener());
        
        // Register commands
        registerCommand(new MyCommand());
    }

    @Override
    protected void onPluginStop() {
        Common.log("Stopping MyPlugin...");
    }

    @Override
    public MinecraftVersion.V getMinimumVersion() {
        return MinecraftVersion.V.v1_13;
    }

    @Override
    public int getMetricsPluginId() {
        return 12345; // Your bStats ID
    }

    @Override
    public int getFoundedYear() {
        return 2024;
    }

    public static MyPlugin getInstance() {
        return (MyPlugin) SimplePlugin.getInstance();
    }
}

Plugin

Commands

Menus

Database

NBT

Models

Core Utilities

​Overview

​Lifecycle methods

​onPluginLoad

​onPluginStart

​onReloadablesStart

​onPluginPreReload

​onPluginReload

​onPluginStop

​Static accessors

​getInstance

​hasInstance

​getVersion

​getNamed

​getSource

​getData

​isReloading

​Registration methods

​registerEvents

​registerEvents (SimpleListener)

​registerAllEvents

​registerCommand

​registerCommands

​registerAllCommands

​registerBungeeCord

​Reload functionality

​reload

​Configuration methods

​getMinimumVersion

​getMaximumVersion

​getStartupLogo

​getUpdateCheck

​getMetricsPluginId

​getFoundedYear

​getMainCommand

​getRegexTimeout

​regexStripColors

​regexCaseInsensitive

​regexUnicode

​regexStripAccents

​areMenusEnabled

​areToolsEnabled

​areRegionsEnabled

​getConsoleFilter

​filterInsecureChat

​Utility methods

​getJavaVersion

​Complete example

Build docs developers (and LLMs) love

Overview

Lifecycle methods

onPluginLoad

onPluginStart

onReloadablesStart

onPluginPreReload

onPluginReload

onPluginStop

Static accessors

getInstance

hasInstance

getVersion

getNamed

getSource

getData

isReloading

Registration methods

registerEvents

registerEvents (SimpleListener)

registerAllEvents

registerCommand

registerCommands

registerAllCommands

registerBungeeCord

Reload functionality

reload

Configuration methods

getMinimumVersion

getMaximumVersion

getStartupLogo

getUpdateCheck

getMetricsPluginId

getFoundedYear

getMainCommand

getRegexTimeout

regexStripColors

regexCaseInsensitive

regexUnicode

regexStripAccents

areMenusEnabled

areToolsEnabled

areRegionsEnabled

getConsoleFilter

filterInsecureChat

Utility methods

getJavaVersion

Complete example