Working With Plugins

Plugins

ServerPackCreator gives you the ability to use plugins, which can enhance your experience in a limited amount of ways.

Any given plugin has the chance to do various things:

Before a server pack is generated
After a server pack was generated, but BEFORE the ZIP-archive is created
After a server pack and its ZIP-archive were generated
Adding extra tabs to the GUI, in which more additional features can then be added
Adding custom configuration checks
Adding custom elements to the server pack configuration tab

For a list of plugins, check out the ServerPackCreator Addons Overview

Installing a plugin

If you have a plugin you would like to enhance your ServerPackCreator-experience with, simply download it and put it into the plugins-directory which resides in the base-directory of ServerPackCreator.

ServerPackCreator
├── lang
├── logs
│   └── archive
├── plugins <--------- 
├── server-packs
│   ├── Survive Create Prosper 4 custom (1)
│   └── World of Dragons II
├── server_files
└── work
    ├── modpacks
    └── temp

Disabling a plugin

In order to deactivate any installed plugins, edit the disabled.txt-file in the plugins-directory. If these don't exist, create them.

ServerPackCreator
├── lang
├── logs
├── plugins
│   ├── ExamplePlugin-3.0.5.jar
│   └── disabled.txt <------
├── server-packs
├── server_files
└── work
    └── ...

Then, find the plugin ID of the installed plugins. This can be mentioned in the pluginss repository, but can also be found in the pluginss manifest.

SomePlugin-3.0.5.jar\META-INF\MANIFEST.MF. Look for the entry Plugin-Id:, for example: Plugin-Id: example-plugin

Then, in your disabled.txt, add a new line containing example-plugin, or rather, whatever ID of any plugins you want to deactivate:

########################################
# - Load all plugins except these.   - #
# - Add one plugin-id per line.      - #
########################################
example-plugin

Important: If ServerPackCreator was running during the disabling of an plugins, you need to restart it in order for the plugins to become disabled.

Example plugin for ServerPackCreator

This repository contains an example plugin. Available at Example Plugin

ServerPackCreator provides several extension endpoints for pf4j plugins, to add additional functionality. This example plugin demonstrates an implementation for all available extension endpoints of ServerPackCreator.

The example plugin demonstrates how extension for ServerPackCreator are implemented, one small example for every extension point available in ServerPackCreator.

Available Extensions

Configuration Panel Extension

The configuration panel is intended to let you add a panel in which you, or the user of your plugin, may configure something for any of the extensions added by your plugin.

The above example lets you configure four text-fields, one for each extension point used during server pack configuration checking and server pack generation. More on this in Configuration Check Extension.

Extension configurations are saved to the serverpackcreator.conf of the server pack and re-loaded along with everything else, like the Minecraft version, modloader and modloader version etc.

Tab Extension

Tab extensions allow you to add whole tabs to the GUI of ServerPackCreator. These additional tabs are intended to let you add text-fields and such, which allow you to configure your global plugin configuration. You may add anything you want to it. The sky is the limit!

The above example adds a button which, when pressed, opens a minimalistic Tetris game in a new window. It's not supposed to be actually that entertaining, but rather to demonstrate that you can do what you want inside your tab.

Below the big button are some text-fields which allow you to change some values of the global plugin-wide configuration. Global plugin-configurations are handed to you by ServerPackCreator when the tab is instantiated.

Global plugin-configurations are passed to every extension, along with any available extension-specific configuration, automatically, so you don't have to worry about anything other than actually saving changes you made in the tab.

Maybe have a timer auto-save every few seconds? Your tab, your choice! 😁

Configuration Check Extension

The configuration check extension point allows you to run your own config checks, be that on any of the already available data from the server pack config tab, or your own data from the configuration panel, or your own tab, or whatever else you may want to check.

The above example simply checks whether the string in text of the passed CommentedConfig in a list of passed configs contains text. If it does, then we add a custom error message to the list of errors encountered during configuration checks. That list is then displayed to the user after the configurations checks have all run.

Make use of this extension point in combination with the Configuration Panel Extension and/or Tab Extension in order to check user input for any errors!

Pre Server Pack Generation Extension

The Pre Server Pack Generation extensions run, as the name implies, right before the generation of a server pack really begins. You may use this to prepare the environment for any of the tailing extensions.

The above example shows the run of a PreGen extension, with the global plugin configuration as well as the extension-specific extension passed to it by ServerPackCreator.

Pre Server Pack ZIP-archive Creation Extension

The Pre Server Pack ZIP-archive Creation extensions run, as the name implies, right before the creation of the server packs ZIP-archive is, or would be, started. Want to add any files to the ZIP-archive? Or make sure some file doesn't make it into the ZIP-archive?

The above example shows the run of a PreZip extension, with the global plugin configuration as well as the extension-specific extension passed to it by ServerPackCreator.

Post Server Pack Generation Extension

The Post Server Pack Generation extensions run, as the name implies, after the generation of a server pack has finished. Want to add any files to the server pack, but don't want them to end up in the ZIP-archive? Maybe download, install and configure DynMap with some render-data? This would be the place to do that!

The above example shows the run of a PreGen extension, with the global plugin configuration as well as the extension-specific extension passed to it by ServerPackCreator.

Listeners

In addition to extensions you may also register a variety of listeners to run your own code. Adding those listeners is easier than writing extensions, but they're also more restricted in the values you get to work with.

Here's a very basic example, just to give you an idea how much easier the listeners are, compared to the extensions:

        val genericListener = object : SPCGenericListener {
            override fun run() {
                println("Helloooooo. I'm a SPCGenericListener!")
                println("Helloooooo. I'm a SPCGenericListener!")
                println("Helloooooo. I'm a SPCGenericListener!")
            }

        }
        val configListener = object : SPCConfigCheckListener {
            override fun run(packConfig: PackConfig, configCheck: ConfigCheck) {
                println("Helloooooo. I'm a SPCConfigCheckListener!")
                println(packConfig.modpackDir)
            }

        }
        val preServerPackListener = object : SPCPreServerPackGenerationListener {
            override fun run(packConfig: PackConfig, serverPackPath: Path) {
                println("Helloooooo. I'm a SPCPreServerPackGenerationListener!")
                println(packConfig.modpackDir)
                println(serverPackPath.toString())
            }

        }
        val preZipListener = object : SPCPreServerPackZipListener {
            override fun run(packConfig: PackConfig, serverPackPath: Path) {
                println("Helloooooo. I'm a SPCPreServerPackZipListener!")
                println(packConfig.modpackDir)
                println(serverPackPath.toString())
            }

        }
        val postGenListener = object : SPCPostGenListener {
            override fun run(packConfig: PackConfig, serverPackPath: Path) {
                println("Helloooooo. I'm a SPCPostGenListener!")
                println(packConfig.modpackDir)
                println(serverPackPath.toString())
            }

        }

        ApiWrapper.api().configurationHandler.addEventListener(genericListener)
        ApiWrapper.api().configurationHandler.addEventListener(configListener)
        ApiWrapper.api().serverPackHandler.addEventListener(genericListener)
        ApiWrapper.api().serverPackHandler.addEventListener(preServerPackListener)
        ApiWrapper.api().serverPackHandler.addEventListener(preZipListener)
        ApiWrapper.api().serverPackHandler.addEventListener(postGenListener)

See now why the ConfigPanel, ConfigCheck and Tab extensions are so nice to have? The possibilities are (almost) endless !😁

The reason for allowing ServerPackCreator to run plugins:

Some people need additional functionality for their server packs, or have some additional wishes for them. Some of those things may not fit into the core functionality of ServerPackCreator itself.

It may also be that it is such a niche feature, that I either don't have the time to code it in, or simply don't want to. Maybe it doesn't fit into the overall design of ServerPackCreator, too. Who knows, it could be any of those reasons or another.

Hence, the plugin functionality.

This allows people to write their own plugins to expand the functionality of ServerPackCreator with their own features as they see fit.

Adding your own

A curated list of officially acknowledged plugins can be found here (redirects to GitHub Pages)

How to get your own plugin into this list:

If you have written your own plugin for ServerPackCreator and you would like to see it added here, please open an issue over at ServerPackCreator, using the Documentation template.

For a plugin to be accepted, you must at least provide:

The name of and link to the repository, and therefore the plugin.
The owner of the repository, and therefore the plugin.
The branch of the repository where the main code resides in.
A description of the plugin.

Last modified: 25 July 2024