Development Setup (for devs)

Danger

BlazingGames is unfinished and we make breaking changes at every update. Avoid setting up a server or writing plugins integrating with it for now.

Caution

This hasn’t been tested yet, and may or may not work. We don’t even know if Paper works with Java services.

What is a feature?

Everything BlazingGames does is split into “features”. Each feature has its own data, which has a name, description, dependencies, lifecycle, and more.

Features can do just about anything, including acting as libraries. They can use all Paper APIs. For some feature examples, see the built-in features in the sidebar.

Tip

If a feature can act as a library, information about how to use it will be on the feature’s wiki page.

Configuring your plugin

Caution

Your plugin must be a Paper plugin. Spigot/Bukkit plugins are unsupported and BlazingGames also doesn’t load on those servers.

To begin, you want to add blazinggames as a dependency for both bootstrap and runtime. It should load after with a joined classpath.

For example:

paper-plugin.yml

name: example-plugin
dependencies:
  bootstrap:
    blazinggames:
      load: AFTER
      required: true
      join-classpath: true
  server:
    blazinggames:
      load: AFTER
      required: true
      join-classpath: true

You’ll also want to use BlazingGames as a library in your plugin. Please do not shade or bundle it, as it will be available at runtime.

Tip

We aren’t publishing the plugin anywhere yet, which is another reason why you shouldn’t do this yet. Once we do though, we’ll update this section, but for now figure it out yourself I guess.

Implementing FeatureLifecycle

Repeat this section for each feature you’d like to add. For this example, we’ll make a feature called “Walrus” for no reason in particular.

Code

First, make a class for it which extends FeatureLifecycle:

WalrusFeature.java

public class WalrusFeature extends FeatureLifecycle {

}

Now, we need to add a constructor. The super contructor takes the following values:

• key: This is the key/id of your feature. The namespace should be your plugin’s namespace, like Bukkit does it when you create a NamespacedKey with your Plugin instance.

  • Example: myawesomeplugin:walrus

• friendlyName: The name of your feature that users will see.

  • Example: Walrus

• description: Describe what your feature does.

  • Example: Adds walruses to the game!

• enabledByDefault: If the feature should be enabled by default when its configuration is generated. This is up to you to decide, but it will cause problems if not all of your dependencies are also enabled by default.

  • Example: false

• dependencies: A list of the keys of other FeatureLifecycles that this feature depends on. Assuming your dependencies also followed this guide they should have a key property with their key. (we’ll get to this in a minute)

  • Example: ContentLib.key, SocialCore.key (depend on built-in content and social)

WalrusFeature.java

public class WalrusFeature extends FeatureLifecycle {
    public WalrusFeature() {
        super(
            Key.key("myawesomeplugin", "walrus"),
            "Walrus",
            "Adds walruses to the game!",
            false,
            ContentLib.key, SocialCore.key
        );
    }

}

Next, your key should be public and static so that other features can depend on it.

WalrusFeature.java

public class WalrusFeature extends FeatureLifecycle {
    public static final Key key = Key.key("myawesomeplugin", "walrus");

    public WalrusFeature() {
        super(
            Key.key("myawesomeplugin", "walrus"),
            key,
            "Walrus",
            "Adds walruses to the game!",
            false,
            ContentLib.key, SocialCore.key
        );
    }

}

And that’s it for the code! You can now add your feature logic.

WalrusFeature.java

public class WalrusFeature extends FeatureLifecycle {
    ...

    @Override
    public void onInitialize(FileConfiguration config) {
        // This method allows you to load your configuration file. It will always
        // be called before any method here.
    }

    @Override
    public void onEnable(LifecycleContext context) {
        // Called during Bukkit's onEnable
    }

    @Override
    public void onDisable(BlazingGames plugin) {
        // Called during Bukkit's onDisable
    }
}

Configuration file

Your feature will fail to load if you do not have a default configuration file for it. Create a configtemplates folder in your plugin’s resources to store default configuration files.

A file with your feature’s key (without the namespace) and a .yml file extension is mandatory. Your feature your fail to load otherwise.

For example, if your feature is myawesomeplugin:walrus, you need a file at /configtemplates/walrus.yml.

This configuration file will be copied to /plugins/BlazingGames/configs/NAMESPACE/KEY.yml, regardless of what plugin registered it, and users can configure it there.

Example configuration file:

walrus.yml

# If the legendary blue walrus should be enabled.
blue-walrus: false

Caution

When copying your configuration file, BlazingGames will add a lot of comments at the start with your friendlyName and description and dependencies and such, along with an enabled: property, with the default being what you provided for enabledByDefault.

In other words, avoid describing your feature in its config file (unless the short description isn’t enough) and avoid adding a property named enabled.

Example generated file

walrus.yml

#
# Walrus
# Adds walruses to the game!
# Dependencies:
# - Content (../content.yml)
# - Social Core (../social.yml)
#
# View the wiki of the plugin providing this feature for more information.
# If this file is out of date, you can delete it to regenerate it with newer configuration values.
#
# Technical Details:
# > Feature ID: myawesomeplugin:walrus
# > Provided by: com.example.awesomesauce.MyFeatureProvider
# > Generated at: 16:07, 2026-01-31
#

enabled: true

# The configuration options are present below:

# If the legendary blue walrus should be enabled.
blue-walrus: false

Tip

You can also create a .overrides.yml file in the same directory if you want to customize the configuration in unit tests, if you are writing any. You do not need to set the enabled property.

Tip: LifecycleContext methods

Here’s a brief overview of what you can do with the LifecycleContext given in onEnable:

// Listen to an event
context.registerEvent(PlayerInteractEvent.class, new WalrusInteractHandler());

// Register a timer
context.registerTimer(new WalrusBukkitRunnable(), 0, 20);

// Just do something else entirely, some other features act as libraries
ResourcePackManager.installHook(new WalrusHook(this));

Tip

Your IDE is very smart and can tell you all the methods that a certain class has. This is just a brief overview of what you’d usually do.

Implementing FeatureProvider

This is how BlazingGames gets the list of features to get from your plugin. Just like before, let’s start with a class:

MyFeatureProvider.java

public class MyFeatureProvider implements FeatureProvider {

}

Then, register it as a Java service (with Java’s SPI).

No idea what this means? Just add Google’s AutoService as a dependency and annotate your FeatureProvider implementation like this:

MyFeatureProvider.java

@AutoService(FeatureProvider.class)
public class MyFeatureProvider implements FeatureProvider {

}

Now, we need to implement getFeatures. There are plenty of ways to do this, so do it however you’d like. A few examples:

Feature instances on the FeatureProvider

This is the easiest to implement, but it might accidentally allow other plugins to initalize your feature (unless the lifecycle is package-private, which is impractical depending on your code organization).

MyFeatureProvider.java

@AutoService(FeatureProvider.class)
public class MyFeatureProvider implements FeatureProvider {
    public static final WalrusFeature walrus = new WalrusFeature();

    @Override
    public List<FeatureLifecycle> getFeatures() {
        return List.of(walrus);
    }
}

Feature instances on their FeatureLifecycle

This is probably the cleanest solution, but requires a bit more effort. Other plugins will be unable to initalize stuff they shouldn’t.

First, in each feature’s lifecycle:

WalrusFeature.java

public class WalrusFeature extends FeatureLifecycle {
    public static final WalrusFeature instance = new WalrusFeature();
    public static final Key key = Key.key("myawesomeplugin", "walrus");

    public WalrusFeature() {
    private WalrusFeature() {
        super(
            key,
            "Walrus",
            "Adds walruses to the game!",
            false,
            ContentLib.key, SocialCore.key
        );
    }

    ...
}

Then, in your feature provider:

MyFeatureProvider.java

@AutoService(FeatureProvider.class)
public class MyFeatureProvider implements FeatureProvider {
    @Override
    public List<FeatureLifecycle> getFeatures() {
        return List.of(WalrusFeature.instance);
    }
}

Tip

These are just examples, organize your code however you’d like!

Testing your feature

Launch a Paper server however you usually do it to test. If you’d like, you can also read the admin setup guide for some important information.

Server Setup (for admins)

It doesn’t work

Make sure BlazingGames is loaded, because it loads your feature and crashes if it fails to. If it isn’t, check your server logs for any stacktraces, and make sure BlazingGames detects your feature in the first place.

A few common problems you might encouter are documented below:

No stacktrace in console

Feature or FeatureProvider wasn’t detected at discovery time

Was your FeatureProvider registered as a Java SPI service? If you’re using AutoService, is it also in your annotation processor classpath?

Make sure the FeatureProvider also has a public no-args constructor.

If it worked, you should see a file in META-INF in your jar somewhere with the full class name of FeatureProvider containing a line with the full class name of your implementation. Otherwise, it didn’t register.

Feature was detected, but didn’t load

Is your feature enabledByDefault? If not, you’ll need to enable it yourself at /plugins/BlazingGames/configs/NAMESPACE/KEY.yml by setting enabled to true.

Weird stacktrace in console

Bukkit/Server isn’t initialized or something exception

During construction of your FeatureProvider and FeatureLifecycles, along with onInitialize and onBootstrap, the server doesn’t yet exist. Check the stacktrace to see what tried to use a Bukkit API.